Revision history for Perl extension IMAPClient.
Changes in version 1.09
-----------------------
Changed login method so that values for the User parameter that do not start and end with quotes
will be quoted when sent to the server. This is to support user id's with embedded spaces, which
are legal on some platforms.
Changed name of test input file created by perl Makefile.PL and used by 'make test' from .test to
test.txt to support weird, offbeat OS platforms that cannot handle filenames beginning with a dot.
Fixed bugs in seen, unseen, and recent methods. (These are almost the same method anyway; they
are dynamically created at compile time from the same code, with variable substitution filling in
the places where "seen", "unseen", or "recent" belong.) The bug caused these methods to return the
transaction number of the search as if it were the last message sequence number (or message uid) in
the result set.
Added the 'since' method, which accepts a date in either standard perl format (seconds since 1/1/1970, or
as output by time and as accepted by localtime) or in the date_text format as defined in RFC2060
(dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). It searches
for items in the currently selected folder for messages sent since the day whose date is provided as
an argument.
Added 'sentsince', 'senton', 'sentbefore', 'on', and 'before' methods which are totally 100% just
like the 'since' method, except that they run different searches. (Did I mention that it's useful
to have RFC2060 handy when writing IMAP clients?)
Added two new methods, run and tag_and_run, to allow IMAP client programmers finer control over
the IMAP conversation. These methods allow the programmer to compose the entire IMAP command string
and pass it as-is to the IMAP server. The difference between these two methods is that the run
method requires that the string include the tag while the tag_and_run method requires that it does not.
To a similar end, the pre-existing Socket parameter and eponymous accessor method has been
documented to allow direct access to the IMAP socket handle and to allow the socket handle to
be replaced with some other file handle, presumably one derived from a more interesting technology
(such as SSL).
Fixed a bug that caused blank lines to be removed from 'literal' output (as defined in RFC2060)
when fast_io was not used. This bug was especially likely to show up in routines that fetched a
message's body text. The fact that this bug did not occur in the newer fast_io code may
indicate that I've learned something, but on the other hand we shouldn't jump to rash conclusions.
I've run benchmarks on the fast_io code to determine whether or not it is faster and, if so, under
what circumstances. It appears that the fast_io code is quite faster, except when reading large
'literal' strings (i.e. message bodies), in which case it appears to take the same amount of time
as the older i/o code but at the cost of more cpu cycles (which means it may actually be slower
on cpu-constrained systems). The reason for this is that reads of literal strings are by their
nature already optimized, but without the overhead of fcntl calls. So if you expect to be doing
lots of message text (or multipart message body parts) fetching you should not use fast_io, but in
pretty much any other case you should go ahead and use it. In any event, a number of people have
tested fast_io so I no longer consider it experimental, unless you're running perl on NT or CP/M
or something funky like that, in which case let me know how you make out!
Changes in version 1.08
-----------------------
Maintenance release 1.08a fixes a bug in the folders method when supplying the optional argument
(see "Enhanced folders method..." below) with some IMAP servers.
Added option to build_ldif.pl (in the examples subdirectory) to allow new options and to better
handle quoted comments in e-mail addresses. Thanks to Jeffrey Fiedl, whose book _Mastering
Regular Expressions_ (O'Reilly) helped me to figure out a good way to do this.
Fixed documentation error that failed to mention constraints on when the append method will
return the uid of the appended message. (This feature only works with servers that have the
UIDPLUS capability.)
Added/improved documentation somewhat.
The copy method now returns a comma-separated list of uids if successful and if the IMAP server
supports UIDPLUS extentions. The move method now works similarly.
Added new method uidnext, which accepts the name of a folder as an argument and returns the next
available message UID for that folder.
The exists and append methods now will handle unquoted foldernames with embedded spaces or quotes
or whatever. Including quotes as part of the argument string is no longer required but is still
supported for backwards compatibility reasons. In other words, $imap->exists(q("Some Folder")) is
now no longer necessary (but will still work). $imap->exists(some folder) is good enough.
Mail::IMAPClient has been tested successfully on Mirapoint 2.0.2. (Thanks to Jim Hickstein.)
I've now installed the UW imapd IMAP4rev1 v12.264 on one of my machines so I'm better able to
certify that platform. All the tests in 'make test' work there (or are at least gently skipped).
Fixed bug in getacl in which folder names were quoted twice. (Thanks to Albert Chin for
squashing this bug.) Similar bugs existed in the other ACL methods and were similarly
fixed.
Fixed a bug in message_uid that basically caused it to not work. Muchos gracias to Luvox (aka
fluvoxamine hydrochloride) for providing me with just the help I needed to discover and fix this
bug.
Enhanced folders method to allow an argument. If an argument is supplied, then the folders method
will restrict its results to subfolders of the supplied argument (which should be the name of a
parent folder, IMHO). This is implemented by supplying arguments to the LIST IMAP Client command
so we are optimizing network I/O at the expense of possible server incompatibilities. If you
find server incompatibilities with this then please let me know, and in the meantime you can
always grep(/^parent/,$imap->folders) or something. Or re-implement the folders method yourself.
Changes in version 1.07
-----------------------
Added a new parameter, Fast_io, which, if set to a true value, will attempt to implement a faster
I/O engine. USE THIS AT YOUR OWN RISK. It is alpha code. I don't even know yet if it even helps.
Added support for spaces in folder names for the autoloaded subscribe method.
Added new methods setacl, getacl, deleteacl, and listrights. These methods are not yet fully
tested and should be considered beta for this release.
Enhanced support for the myrights method (which is implemented via the default method).
Fixed bug in append method that caused it to hang if server replied to original APPEND with
a NO (because, say, the mailbox's quota has been exceeded).
Removed the autodiscovery of the folder hierarchy from the login method. This will speed up
logging in but may delay certain other methods later (but see the next item, below).
Updated the exists method to issue a "STATUS" IMAP Client command, rather than depend on the
folder hierarchy being discovered via 'LIST "" "*"'. Apparently this speeds things up a lot for
some configurations, although the difference will be negligable to many.
Updated Makefile.PL to support the PREFIX=~/ directive. Thanks to Henry C. Barta (hbarta@wwa.com)
for this fix.
Added the Timeout parameter and eponymous accessor method, which, if set to a true value,
causes reads to time out after the number of seconds specified in the Timeout parameter. The
value can be in fractions of a second. This has not been fully tested though, so use of this parameter
is strictly "Beta".
Enhanced support for the UID IMAP client command. Setting the new Uid parameter to a true value
will now cause the object to treat all message numbers as message UID numbers rather than message
sequence numbers. Setting the Uid parameter to a false value will turn off this behavior again.
Updated test suite to handle servers that cannot do UIDPLUS and to add tests for the Uid parameter.
Incorporated bug fixes for recent_count and message_count in which some servers are sticking in
extra \r's, and updated DESTROY to remove spurious warning messages under some versions of perl
(thanks to Scott Wilson for catching and killing these bugs).
Changes in version 1.06
-----------------------
Changed folders method so that it correctly handles mail folders whose names start and end
with quotes.
Changed append method so that it returns the uid of the newly appended message if
successful. Since the uid is a "true" value this should not affect the behavior of
existing scripts, although it may enhance the behavior of new scripts ;-)
Fixed bug in parse_headers that could cause script to die if there were no headers of
the type requested and if there was a space on the blank line returned from FETCH.
(Some blank lines are blanker than others...)
Added the "flags" method, which returns an array (or array reference if called in scalar
context) containing the flags that have been set for the message whose sequence number has
been provided as the argument to the method.
Added the "message_string" method, which accepts a message sequence number as an argument and
returns the contents of the message (including RFC822 headers) as a single string.
Added the "body_string" method, which accepts a message sequence number as an argument and
returns the contents of the message (not including RFC822 headers) as a single string.
Changes in version 1.05
-----------------------
Patched the 'make test' basic test to work correctly on systems that do not
support double quotes in folder names. Thanks to Rex Walters for this fix.
Added a new example script, build_dist.pl, that rumages through a folder
(specified on the command line) and collects the "From:" address, and then
appends a message to that folder with all those addresses in both the To: field
and the text, to facilitate cuting and pasting (or dragging and dropping)
into address books and so forth. (Note that the message doesn't actually get
sent to all those people; it just kind of looks that way.)
Also added another example, build_ldif.pl, that is similar to build_dist.pl
except that instead of listing addresses in the message text, it creates a
MIME attachment and attaches a text file in LDIF format, which can then be
imported into any address book that supports LDIF as an import file format.
This example requires the MIME::Lite module. MIME::Lite was written by Eryq
(okay, Erik Dorfman is his legal name), and is totally available on CPAN.
This distribution has now been tested on Mirapoint Message Server Appliances
(versions 1.6.1 and 1.7.1). Many thanks to Rex Walters for certifying this
platform and for providing a test account for future releases.
Changes in version 1.04
-----------------------
Fixed situation in which servers that include the "<tag> <COMMAND> OK\r\n" line
as part of a literal (i.e. text delivered via {<length>}\r\n<length> bytes\r\n)
caused the module to hang. This situation is pretty rare; I've only run across
one server that does it (UW-IMAP). I'm sure it's a bug; I'm not sure whose. ;-}
Many thanks to Thomas Stromberg for 1) pointing out this bug and 2) providing
me with facilities to find and fix it!
Fixed potential bug in I/O engine that could cause module to hang when reading
a literal if the first read did not capture the entire literal.
Cleaned up some unnecessary runtime warnings when a script is executed with
the -w switch.
Added new tests to 'make test'. I just can't keep my hands off it! ;-)
Enhanced the append method and several tests in 'make test' to be more widely
compatible. Successfully tested on UW-IMAP, Cyrus v1.5.19, Netscape Messenger
4.1, and Netscape Messenger v3.6. If you know of others please add them to
the list!
Fixed a bug in the separator method (new in 1.03) that caused it to fail if
'inbox' was specified in lowercase characters as the method's argument.
Added a new example, imap_to_mbox.pl, contributed by Thomas Stromberg. This
example converts a user's IMAP folders on an IMAP server into mbox format.
Changes in version 1.03
-----------------------
Reworked several methods to support double-quote characters within folder
names. This was kind of hard. This has been successfully tested with create,
delete, select, and folders, to name the ones that come to mind.
Reworked the undocumented method that reads the socket to accept and handle
more gracefully lines ending in {nnn}\r\n ( where nnn is a number of
characters to read). This seems to be part of the IMAP protocol although I
am at a total loss as to where it's explained, other than a brief description
of a "literal's" bnf syntax, which hardly counts.
Added separator object method, which returns the separator character in use
by the current server.
Added is_parent method, which returns 1, 0, or undef depending on whether a
folder has children, has no children, or is not permitted to have children.
Added tests to 'make test' to test new function. Also changed 'make test' to
support IMAP systems that allow folders to be created only in the user's INBOX
(which is the exact opposite of what my IMAP server allows...oh, well).
Fixed a bug that caused search to return an array of one undef'ed element
rather than undef if there were no hits.
Changes in version 1.02
-----------------------
Fixed bugs in search and folders methods.
Fixed bug in new method that ignored Clear => 0 when specified as arguments to
new.
Changes in version 1.01
-----------------------
Fixed a bug in test.pl that caused tests to fail if the extended tests were not used.
Added method 'parse_headers' to parse the header fields of a message in the
IMAP store into a perl data structure.
Changes in version 1.00
-----------------------
Made cosmetic changes to documentation.
Fixed a bug introduced into the 'folders' method in .99.
Changed 'new' method so that it returns undef if an implicit connection or
login is attempted but fails. Previous releases returned a Mail::IMAPClient
object that was not connected or not logged in, depending on what failed.
Changed installation script so that it reuses the parameter file for test.pl
if it finds one. Installation can be run in the background if the test.txt file
exists. Touching it is good enough to prevent prompts; having a correctly
formatted version (as described in test_template.txt) is even better, as it will
allow you to do a thorough 'make test'.
Changes in version .99
----------------------
Added the Rfc822_date class method to create RFC822-compliant date fields in
messages being appended with the append method.
Added the recent, seen, and unseen methods to return an array of sequence
numbers from a SEARCH RECENT, SEARCH SEEN, or SEARCH UNSEEN method call.
These methods are shortcuts to $imap->search("RECENT"), etc.
Added the recent_count method to return the number of RECENT messages in a
folder. Contributed by Rob Deker.
Added 'use strict' compliance, courtesy of Mihai Ibanescu.
Fixed a bug in the search method that resulted in a list with one empty member
being returned if a search had no hits. The search method now returns undef
if there are no hits.
Added 'authenticate' method to provide very crude support for the IMAP
AUTHENTICATE command. The previous release didn't support AUTHENTICATE at all,
unless you used very low-level (and undocumented) methods. With the
'authenticate' method, the programmer still has to figure out how to
respond to the server's challenge. I hope to make it friendlier in the
next release. Or maybe the one after that. This method is at least a start,
albeit a pretty much untested one.
Added Rfc822_date class method to facilitate creation of "Date:" header
field when creating text for the "append" method, although the method may
come in handy whenever you're creating a Date: header, even if it's not
in conjuction with an IMAP session.
Added more tests, which will optionally run at 'make test' time, provided all
the necessary data (like username, hostname, password for testing an IMAP
session) are available.
Changes in version 0.09
-----------------------
Thu Aug 26 14:10:03 1999 - original version; created by h2xs 1.19
# $Id: Changes,v 19991216.12 2000/03/10 16:04:22 dkernen Exp $