Модуль CPAN: Mail::IMAPClient
На модерации
Отложенный
Mail::IMAPClient - An IMAP Client API
NAME
Mail::IMAPClient - An IMAP Client API
DESCRIPTION
This module provides methods implementing the IMAP protocol. It allows perl scripts to interact with IMAP message stores.
The module is used by constructing or instantiating a new IMAPClient object via the the new manpage constructor method. Once the object has been instantiated, the the connect manpage method is either implicitly or explicitly called. At that point methods are available that implement the IMAP client commands as specified in RFC2060. When processing is complete, the logoff object method should be called.
This documentation is not meant to be a replacement for RFC2060, and the wily programmer will have a copy of that document handy when coding IMAP clients.
Note that this documentation uses the term folder in place of RFC2060's use of mailbox. This documentation reserves the use of the term mailbox to refer to the set of folders owned by a specific IMAP id.
RFC2060 defines four possible states for an IMAP connection: not authenticated, authenticated, selected, and logged out. These correspond to the IMAPClient constants <code>Connected</code>, <code>Authenticated</code>, <code>Selected</code>, and <code>Unconnected</code>, respectively. These constants are implemented as class methods, and can be used in conjunction with the the Status manpage method to determine the status of an IMAPClient object and its underlying IMAP session. Note that an IMAPClient object can be in the <code>Unconnected</code> state both before a server connection is made and after it has ended. This differs slightly from RFC2060, which does not define a pre-connection status. For a discussion of the methods available for examining the IMAPClient object's status, see the section labeled Status Methods, below.
Advanced Authentication Mechanisms
RFC2060 defines two commands for authenticating to an IMAP server: LOGIN for plain text authentication and AUTHENTICATE for more secure authentication mechanisms. Currently Mail::IMAPClient supports CRAM-MD5 and plain text authentication. There are also a number of methods and parameters that you can use to build your own authentication mechanism. Since this topic is a source of many questions, I will provide a quick overview here. All of the methods and parameters discussed here are described in more detail elsewhere in this document; this section is meant to help you get started.
First of all, if you just want to do plain text authentication and your server is okay with that idea then you don't even need to read this section.
Second of all, the intent of this section is to help you implement the authentication mechanism of your choice, but you will have to understand how that mechanism works. There are lots of authentication mechanisms and most of them are not available to me to test with for one reason or another. Even if this section does not answer all of your authentication questions it does contain all the answers that I have, which I admit are scant.
Third of all, if you manage to get any advanced authentication mechanisms to work then please consider donating them to this module. I don't quite have a framework visualized for how different authentication mechanisms could ``plug in'' to this module but I would like to eventually see this module distributed with a number of helper modules to implement various authentication schemes.
The Mail::IMAPClient's support for add-on authentication mechanisms is pretty straight forward and is built upon several assumptions. Basically you create a callback to be used to provide the response to the server's challenge. The Authcallback parameter contains a reference to the callback, which can be an anonymous subroutine or a named subroutine. Then, you identify your authentication mechanism, either via the Authmechanism parameter or as an argument to the authenticate manpage.
You may also need to provide a subroutine to encrypt (or whatever) data before it is sent to the server. The Prewritemethod parameter must contain a reference to this subroutine. And, you will need to decrypt data from the server; a reference to the subroutine that does this must be stored in the Readmethod parameter.
This framework is based on the assumptions that a) the mechanism you are using requires a challenge-response exchange, and b) the mechanism does not fundamentally alter the exchange between client and server but merely wraps the exchange in a layer of encryption. It particularly assumes that the line-oriented nature of the IMAP conversation is preserved; authentication mechanisms that break up messages into blocks of a predetermined size may still be possible but will certainly be more difficult to implement.
Alternatively, if you have access to imtest, a utility included in the Cyrus IMAP distribution, you can use that utility to broker your communications with the IMAP server. This is quite easy to implement. An example, imtestExample.pl in the examples manpage, can be found in the <code>examples</code> subdirectory of the source distribution.
The following list summarizes the methods and parameters that you may find useful in implementing advanced autentication:
<dl>
authenticate methodThis method implements the AUTHENTICATE IMAP client command as documented in RFC2060. If you have set the Authmechanism parameter then the the login manpage method will call the authenticate manpage instead of doing a clear text login, which is its normal behavior. If you don't want login to call authenticate on your behalf then you can call it yourself. Instead of setting an Authmechanism you can just pass the authmechanism as the first argument to AUTHENTICATE.Socket ParameterThe Socket parameter holds a reference to the socket connection. Normally this is set for you by the the connect manpage method, but if you are implementing an advanced authentication technique you may choose to set up your own socket connection and then set this parameter manually, bypassing the connect method completely.State, Server, Password, and User ParametersIf you need to make your own connection to the server and perform your authentication manually, then you can set these parameters to keep your Mail::IMAPClient object in sync with its actual status. Of these, only the State parameter is always necessary. The others need to be set only if you think your program will need them later.AuthmechanismSet this to the value that AUTHENTICATE should send to the server as the authentication mechanism. If you are brokering your own authentication then this parameter may be less useful. It is also not needed by the the authenticate manpage method. It exists solely so that you can set it when you call the new manpage to instantiate your object. The new method will call the connect manpage, who will call the login manpage. If login sees that you've set an Authmechanism then it will call authenticate, using your Authmechanism and Authcallback parameters as arguments.AuthcallbackThe Authcallback parameter, if set, should contain a pointer to a subroutine. The the login manpage method will use this as the callback argument to the authenticate method if the Authmechanism and Authcallback parameters are both set. If you set Authmechanism but not Authcallbackthen the default callback for your mechanism will be used. Unfortunately only the CRAM-MD5 authentication mechanism has a default callback; in every other case not supplying the callback results in an error.
Most advanced authentication mechanisms require a challenge-response exchange. After the the authenticate manpage method sends ``<tag> AUTHENTICATE <Authmechanism>\r\n'' to the IMAP server, the server replies with a challenge. The authenticate method then invokes the code whose reference is stored in the Authcallback parameter as follows:
<pre> $Authcallback->($challenge,$imap)</pre>
where <code>$Authcallback</code> is the code reference stored in the Authcallback parameter, <code>$challenge</code> is the challenge received from the IMAP server, and <code>$imap</code> is a pointer to the Mail::IMAPClient object. The return value from the Authcallback routine should be the response to the challenge, and that return value will be sent by the the authenticate manpage method to the server.
ReadmethodThe Readmethod parameter points to a routine that will read data from the socket connection. This read method will replace the sysread that would otherwise be performed by Mail::IMAPClient. The replacement method is called with five arguments. The first is a pointer to the Mail::IMAPClient object; the rest are the four arguments required by the sysread function. Note the third argument (which corresponds to the second argument to sysread) is a buffer to read into; this will be a pointer to a scalar. So for example if your Readmethod were just going to replace sysread without any intervening processing (which would be silly but this is just an example after all) then you would set your Readmethodlike this:
<pre> $imap->Readmethod(
sub {
my($self) = shift;
my($handle,$buffer,$count,$offset) = @_;
return sysread( $handle, $$buffer, $count, $offset);
}
);</pre>
Note particularly the double dollar signs in <code>$$buffer</code> in the sysread call; this is not a typo!
PrewritemethodThe Prewritemethod, if defined, should contain a pointer to a subroutine. It is called immediately prior to writing to the socket connection. It is called by Mail::IMAPClient with two arguments: a reference to the Mail::IMAPClient object and the ASCII text string to be written. It should return another string that will be the actual string sent to the IMAP server. The idea here is that your Prewritemethod will do whatever encryption is necessary and then return the result to the caller so it in turn can be sent to the server.</dl>
Errors
If you attempt an operation that results in an error, then you can retrieve the text of the error message by using the LastError method. However, since the LastError method is an object method (and not a class method) you will only be able to use this method if you've successfully created your object. Errors in the the new manpage method can prevent your object from ever being created. Additionally, if you supply the Server, User, and Password parameters to the new manpage, it will attempt to call connect and login, either of which could fail and cause your the new manpage method call to return <code>undef</code> (in which case your object will have been created but its reference will have been discarded before ever having been returned to you).
If this happens to you, you can always check <code>$@</code>. Mail::IMAPClient will populate that variable with something useful if either of the the new manpage, the connect manpage, or the login manpage methods fail. In fact, as of version 2, the <code>$@</code> variable will always contain error info from the last error, so you can print that instead of calling LastError if you wish.
If you run your script with warnings turned on (which I'm sure you'll do at some point because it's such a good idea) then any error message that gets placed into the LastError slot (and/or in <code>$@</code>) will automatically generate a warning.
Transactions
RFC2060 requires that each line in an IMAP conversation be prefixed with a tag. A typical conversation consists of the client issuing a tag-prefixed command string, and the server replying with one of more lines of output. Those lines of output will include a command completion status code prefixed by the same tag as the original command string.
The IMAPClient module uses a simple counter to ensure that each client command is issued with a unique tag value. This tag value is referred to by the IMAPClient module as the transaction number. A history is maintained by the IMAPClient object documenting each transaction. The the Transaction manpage method returns the number of the last transaction, and can be used to retrieve lines of text from the object's history.
The Clear parameter is used to control the size of the session history so that long-running sessions do not eat up unreasonable amounts of memory. See the discussion of Clear under Parameters for more information.
The the Report manpage transaction returns the history of the entire IMAP session since the initial connection or for the last Clear transactions. This provides a record of the entire conversation, including client command strings and server responses, and is a wonderful debugging tool as well as a useful source of raw data for custom parsing.
CLASS METHODS
There are a couple of methods that can be invoked as class methods. Generally they can be invoked as an object method as well, as a convenience to the programmer. (That is, as a convenience to the programmer who wrote this module, as well as the programmers using it. It's easier not to enforce a class method's classiness.) Note that if the the new manpage method is called as an object method, the object returned is identical to what have would been returned if the new manpage had been called as a class method. It doesn't give you a copy of the original object or anything like that.
new
Example:
<pre> Mail::IMAPClient->new(%args) or die "Could not new: $@\n";</pre>
The the new manpage method creates a new instance of an IMAPClient object. If the Server parameter is passed as an argument to new, then new will implicitly call the the connect manpage method, placing the new object in the Connected state. If User and Password values are also provided, then the connect manpage will in turn call the login manpage, and the resulting object will be returned from new in the Authenticated state.
If the Server parameter is not supplied then the IMAPClient object is created in the Unconnected state.
If the new method is passed arguments then those arguments will be treated as a list of key=>value pairs. The key should be one of the parameters as documented under Parameters, below.
Here are some examples:
<pre> use Mail::IMAPClient;</pre>
<pre> # returns an unconnected Mail::IMAPClient object:
my $imap = Mail::IMAPClient->new;
# ...
# intervening code using the 1st object, then:
# (returns a new, authenticated Mail::IMAPClient object)
$imap = Mail::IMAPClient->new(
Server => $host,
User => $id,
Password=> $pass,
Clear => 5, # Unnecessary since '5' is the default
# ... # Other key=>value pairs go here
) or die "Cannot connect to $host as $id: $@";</pre>
See also Parameters, below, and connect and login for information on how to manually connect and login after new.
Authenticated
Example:
<pre> $Authenticated = $imap->Authenticated();
# or:
$imap->Authenticated($new_value); # But you'll probably never need to do this</pre>
returns a value equal to the numerical value associated with an object in the Authenticated state. This value is normally maintained by the Mail::IMAPClient module, so you typically will only query it and won't need to set it.
NOTE: For a more programmer-friendly idiom, see the IsUnconnected, IsConnected, IsAuthenticated, and IsSelected object methods. You will usually want to use those methods instead of one of the above.
Connected
Example:
<pre> $Connected = $imap->Connected();
# or:
$imap->Connected($new_value); # But you'll probably never need to do this</pre>
returns a value equal to the numerical value associated with an object in the Connected state. This value is normally maintained by the Mail::IMAPClient module, so you typically will only query it and won't need to set it.
NOTE: For a more programmer-friendly idiom, see the IsUnconnected, IsConnected, IsAuthenticated, and IsSelected object methods. You will usually want to use those methods instead of one of the above.
Quote
Example:
<pre> $imap->search(HEADER => 'Message-id' => $imap->Quote($msg_id));</pre>
The Quote method accepts a value as an argument. It returns its argument as a correctly quoted string or a literal string.
Note that you should not use this on folder names, since methods that accept folder names as an argument will quote the folder name arguments appropriately for you. (Exceptions to this rule are methods that come with IMAP extensions that are not explicitly supported by Mail::IMAPClient.)
If you are getting unexpected results when running methods with values that have (or might have) embedded spaces, double quotes, braces, or parentheses, then you may wish to call Quote to quote these values. You should not use this method with foldernames or with arguments that are wrapped in quotes or parens if those quotes or parens are there because the RFC2060 spec requires them. So, for example, if RFC requires an argument in this format:
<pre> ( argument )</pre>
and your argument is (or might be) ``pennies (from heaven)'', then you could just use:
<pre> $argument = "(" . $imap->Quote($argument) . ")"</pre>
and be done with it.
Of course, the fact that sometimes these characters are sometimes required delimiters is precisely the reason you must quote them when they are not delimiting. For example:
<pre> $imap->Search('SUBJECT',"(no subject)");
# WRONG! Sends this to imap server:
#<TAG> Search SUBJECT (no subject)\r\n
</pre>
<pre> $imap->Search('SUBJECT',$imap->Quote("(no subject)"));
# Correct! Sends this to imap server:
#<TAG> Search SUBJECT "(no subject)"\r\n</pre>
On the other hand:
<pre> $imap->store('+FLAGS',$imap->Quote("(\Deleted)"));
# WRONG! Sends this to imap server:
#<TAG> [UID] STORE +FLAGS "(\Deleted)"\r\n
</pre>
<pre> $imap->store($imap->Quota('+FLAGS'),"(\Deleted)");
# CORRECT! Sends this to imap server:
#<TAG> [UID] STORE +FLAGS (\Deleted)\r\n</pre>
In the above, I had to abandon the many methods available to Mail::IMAPClient programmers (such as the delete_message manpage and all-lowercase the search manpage) for the sake of coming up with an example. However, there are times when unexpected values in certain places will force you to Quote. An example is RFC822 Message-id's, which usually don't contain quotes or parens. So you don't worry about it, until suddenly searches for certain message-id's fail for no apparent reason. (A failed search is not simply a search that returns no hits; it's a search that flat out didn't happen.) This normally happens to me at about 5:00 pm on the one day when I was hoping to leave on time. (By the way, my experience is that any character that can possibly find its way into a Message-Id eventually will, so when dealing with these values take proactive, defensive measures from the very start. In fact, as I was typing the above, a buddy of mine came in to ask advice about a logfile parsing routine he was writing in which the fields were delimited by colons. One of the fields was a Message Id, and, you guessed it, some of the message id's in the log had (unescaped!) colons embedded in them and were screwing up his <code>split()</code>. So there you have it, it's not just me. This is everyone's problem.)
Range
Example:
<pre> my %parsed = $imap->parse_headers(
$imap->Range($imap->messages),
"Date",
"Subject"
);</pre>
The Range method will condense a list of message sequence numbers or message UID's into the most compact format supported by RFC2060. It accepts one or more arguments, each of which can be:
<dl>
a) a message number,b) a comma-separated list of message numbers,c) a colon-separated range of message numbers (i.e. ``$begin:$end'')d) a combination of messages and message ranges, separated by commas (i.e. 1,3,5:8,10), ore) a reference to an array whose elements are like a) through d).</dl>
The Range method returns a reference to a Mail::IMAPClient::MessageSet object. The object has all kinds of magic properties, one of which being that if you treat it as if it were just a string it will act like it's just a string. This means you can ignore its objectivity and just treat it like a string whose value is your message set expressed in compact format.
You may want to use this method if you find that fetch operations on large message sets seem to take a really long time, or if your server rejects these requests with the claim that the input line is too long. You may also want to use this if you need to add or remove messages to your message set and want an easy way to manage this.
For more information on the capabilities of the returned object reference, see the Mail::IMAPClient::MessageSet manpage.
Rfc2060_date
Example:
<pre> $Rfc2060_date = $imap->Rfc2060_date($seconds);
# or:
$Rfc2060_date = Mail::IMAPClient->Rfc2060_date($seconds);</pre>
The Rfc2060_date method accepts one input argument, a number of seconds since the epoch date. It returns an RFC2060 compliant date string for that date (as required in date-related arguments to SEARCH, such as ``since'', ``before'', etc.).
Rfc822_date
Example:
<pre> $Rfc822_date = $imap->Rfc822_date($seconds);
# or:
$Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);</pre>
The Rfc822_date method accepts one input argument, a number of seconds since the epoch date. It returns an RFC822 compliant date string for that date (without the 'Date:' prefix). Useful for putting dates in message strings before calling the append manpage, the search manpage, etcetera.
Selected
Example:
<pre> $Selected = $imap->Selected();
# or:
$imap->Selected($new_value); # But you'll probably never need to do this</pre>
returns a value equal to the numerical value associated with an object in the Selected state. This value is normally maintained by the Mail::IMAPClient module, so you typically will only query it and won't need to set it.
NOTE: For a more programmer-friendly idiom, see the IsUnconnected, IsConnected, IsAuthenticated, and IsSelected object methods. You will usually want to use those methods instead of one of the above.
Strip_cr
Example:
<pre> $Strip_cr = $imap->Strip_cr();
# or:
$imap->Strip_cr($new_value);</pre>
The Strip_cr method strips carriage returns from IMAP client command output. Although RFC2060 specifies that lines in an IMAP conversation end with <CR><LF>, it is often cumbersome to have the carriage returns in the returned data. This method accepts one or more lines of text as arguments, and returns those lines with all <CR><LF> sequences changed to <LF>. Any input argument with no carriage returns is returned unchanged. If the first argument (not counting the class name or object reference) is an array reference, then members of that array are processed as above and subsequent arguments are ignored. If the method is called in scalar context then an array reference is returned instead of an array of results.
Taken together, these last two lines mean that you can do something like:
<pre> my @list = $imap->some_imap_method ;
@list = $imap->Strip_cr(@list) ;
# or:
my $list = [ $imap->some_imap_method ] ; # returns an array ref
$list = $imap->Strip_cr($list);</pre>
NOTE: Strip_cr does not remove new line characters.
Unconnected
Example:
<pre> $Unconnected = $imap->Unconnected();
# or:
$imap->Unconnected($new_value);</pre>
returns a value equal to the numerical value associated with an object in the Unconnected state. This value is normally maintained by the Mail::IMAPClient module, so you typically will only query it and won't need to set it.
NOTE: For a more programmer-friendly idiom, see the IsUnconnected, IsConnected, IsAuthenticated, and IsSelected object methods. You will usually want to use those methods instead of one of the above.
OBJECT METHODS
Object methods must be invoked against objects created via the the new manpage method. They cannot be invoked as class methods, which is why they are called ``object methods'' and not ``class methods''.
There are basically two types of object methods--mailbox methods, which participate in the IMAP session's conversation (i.e. they issue IMAP client commands) and object control methods, which do not result in IMAP commands but which may affect later commands or provide details of previous ones. This latter group can be further broken down into two types, Parameter accessor methods, which affect the behavior of future mailbox methods, and Status methods, which report on the affects of previous mailbox methods.
Methods that do not result in new IMAP client commands being issued (such as the the Transaction manpage, the Status manpage, and the History manpage methods) all begin with an uppercase letter, to distinguish them from methods that do correspond to IMAP client commands. Class methods and eponymous parameter methods likewise begin with an uppercase letter because they also do not correspond to an IMAP client command.
As a general rule, mailbox control methods return <code>undef</code> on failure and something besides <code>undef</code> when they succeed. This rule is modified in the case of methods that return search results. When called in a list context, searches that do not find matching results return an empty list. When called in a scalar context, searches with no hits return 'undef' instead of an array reference. If you want to know why you received no hits, you should check <code>$@</code>, which will be empty if the search was successful but had no matching results but populated with an error message if the search encountered a problem (such as invalid parameters).
A number of IMAP commands do not have corresponding Mail::IMAPClient methods. Instead, they are implemented via a default method and Perl's AUTOLOAD facility. If you are looking for a specific IMAP client command (or IMAP extension) and do not see it documented in this pod, then that does not necessarily mean you can not use Mail::IMAPClient to issue the command. In fact, you can issue almost any IMAP client command simply by pretending that there is a corresponding Mail::IMAPClient method. See the section on Other IMAP Client Commands and the Default Object Method below for details on the default method.
Mailbox Control Methods
append
Example:
<pre> my $uid = $imap->append($folder,$msg_text)
or die "Could not append: $@\n";</pre>
The append method adds a message to the specified folder. It takes two arguments, the name of the folder to append the message to, and the text of the message (including headers). Additional arguments are added to the message text, separated with <CR><LF>.
The append method returns the UID of the new message (a true value) if successful, or <code>undef</code> if not, if the IMAP server has the UIDPLUS capability. If it doesn't then you just get true on success and undef on failure.
Note that many servers will get really ticked off if you try to append a message that contains ``bare newlines'', which is the titillating term given to newlines that are not preceded by a carrage return. To protect against this, append will insert a carrage return before any newline that is ``bare''. If you don't like this behavior then you can avoid it by not passing naked newlines to append.
Note that append does not allow you to specify the internal date or initial flags of an appended message. If you need this capability then use the append_string manpage, below.
append_file
Example:
<pre> my $new_msg_uid = $imap->append_file(
$folder,
$filename
[ , $input_record_separator ] # optional (not arrayref)
) or die "Could not append_file: $@\n";</pre>
The append_file method adds a message to the specified folder. It takes two arguments, the name of the folder to append the message to, and the file name of an RFC822-formatted message.
An optional third argument is the value to use for <code>input_record_separator</code>. The default is to use ``'' for the first read (to get the headers) and ``\n'' for the rest. Any valid value for <code>$/</code> is acceptable, even the funky stuff, like <code>\1024</code>. (See perlvar for more information on <code>$/</code>). (The brackets in the example indicate that this argument is optional; they do not mean that the argument should be an array reference.)
The append_file method returns the UID of the new message (a true value) if successful, or <code>undef</code> if not, if the IMAP server has the UIDPLUS capability. If it doesn't then you just get true on success and undef on failure. If you supply a filename that doesn't exist then you get an automatic <code>undef</code>. The LastError method will remind you of this if you forget that your file doesn't exist but somehow manage to remember to check LastError.
In case you're wondering, append_file is provided mostly as a way to allow large messages to be appended without having to have the whole file in memory. It uses the <code>-s</code> operator to obtain the size of the file and then reads and sends the contents line by line (or not, depending on whether you supplied that optional third argument).
append_string
Example:
<pre> # brackets indicate optional arguments (not array refs):</pre>
<pre> my $uid = $imap->append_string( $folder, $text [ , $flags [ , $date ] ])
or die "Could not append_string: $@\n";</pre>
The append_string method adds a message to the specified folder. It requires two arguments, the name of the folder to append the message to, and the text of the message (including headers). The message text must be included in a single string (unlike the append manpage, above).
You can optionally specify a third and fourth argument to append_string. The third argument, if supplied, is the list of flags to set for the appended message. The list must be specified as a space-separated list of flags, including any backslashes that may be necessary. The enclosing parentheses that are required by RFC2060 are optional for append_string. The fourth argument, if specified, is the date to set as the internal date. It should be in the format described for date_time fields in RFC2060, i.e. ``dd-Mon-yyyy hh:mm:ss +0000''.
If you want to specify a date/time but you don't want any flags then specify undef as the third argument.
The append_string method returns the UID of the new message (a true value) if successful, or <code>undef</code> if not, if the IMAP server has the UIDPLUS capability. If it doesn't then you just get true on success and undef on failure.
Note that many servers will get really ticked off if you try to append a message that contains ``bare newlines'', which is the titillating term given to newlines that are not preceded by a carrage return. To protect against this, append_string will insert a carrage return before any newline that is ``bare''. If you don't like this behavior then you can avoid it by not passing naked newlines to append_string.
authenticate
Example:
<pre> $imap->authenticate($authentication_mechanism, $coderef)
or die "Could not authenticate: $@\n";</pre>
The authenticate method accepts two arguments, an authentication type to be used (ie CRAM-MD5) and a code or subroutine reference to execute to obtain a response. The authenticate method assumes that the authentication type specified in the first argument follows a challenge-response flow. The authenticate method issues the IMAP Client AUTHENTICATE command and receives a challenge from the server. That challenge (minus any tag prefix or enclosing '+' characters but still in the original base64 encoding) is passed as the only argument to the code or subroutine referenced in the second argument. The return value from the 2nd argument's code is written to the server as is, except that a <CR><NL> sequence is appended if neccessary.
If one or both of the arguments are not specified in the call to authenticate but their corresponding parameters have been set (Authmechanism and Authcallback, respectively) then the parameter values are used. Arguments provided to the method call however will override parameter settings.
If you do not specify a second argument and you have not set the Authcallback parameter, then the first argument must be one of the authentication mechanisms for which Mail::IMAPClient has built in support. Currently there is only built in support for CRAM-MD5, but I hope to add more in future releases.
If you are interested in doing NTLM authentication then please see Mark Bush's the Authen::NTLM manpage, which can work with Mail::IMAPClient to provide NTLM authentication.
See also the the login manpage method, which is the simplest form of authentication defined by RFC2060.
before
Example:
<pre> my @msgs = $imap->before($Rfc2060_date)
or warn "No messages found before $Rfc2060_date.\n";</pre>
The before method works just like the since method, below, except it returns a list of messages whose internal system dates are before the date supplied as the argument to the before method.
body_string
Example:
<pre> my $string = $imap->body_string($msgId)
or die "Could not body_string: $@\n";</pre>
The body_string method accepts a message sequence number (or a message UID, if the Uid parameter is set to true) as an argument and returns the message body as a string. The returned value contains the entire message in one scalar variable, without the message headers.
bodypart_string
Example:
<pre> my $string=$imap->bodypart_string( $msgid, $part_number ,
$length ,$offset
) or die "Could not get bodypart string: $@\n";</pre>
The bodypart_string method accepts a message sequence number (or a message UID, if the Uid parameter is set to true) and a body part as arguments and returns the message part as a string. The returned value contains the entire message part (or, optionally, a portion of the part) in one scalar variable.
If an optional third argument is provided, that argument is the number of bytes to fetch. (The default is the whole message part.) If an optional fourth argument is provided then that fourth argument is the offset into the part at which the fetch should begin. The default is offset zero, or the beginning of the message part.
If you specify an offset without specifying a length then the offset will be ignored and the entire part will be returned.
bodypart_string will return <code>undef</code> if it encounters an error.
capability
Example:
<pre> my @features = $imap->capability
or die "Could not determine capability: $@\n";</pre>
The capability method returns an array of capabilities as returned by the CAPABILITY IMAP Client command, or a reference to an array of capabilities if called in scalar context. If the CAPABILITY IMAP Client command fails for any reason then the capability method will return <code>undef</code>.
close
Example:
<pre> $imap->close or die "Could not close: $@\n";</pre>
The close method is implemented via the default method and is used to close the currently selected folder via the CLOSE IMAP client command. According to RFC2060, the CLOSE command performs an implicit EXPUNGE, which means that any messages that you've flagged as \Deleted (say, with the the delete_message manpage method) will now be deleted. If you haven't deleted any messages then close can be thought of as an ``unselect''.
Note again that this closes the currently selected folder, not the IMAP session.
See also the delete_message manpage, the expunge manpage, and your tattered copy of RFC2060.
connect
Example:
<pre> $imap->connect or die "Could not connect: $@\n";</pre>
The connect method connects an imap object to the server. It returns <code>undef</code> if it fails to connect for any reason. If values are available for the User and Password parameters at the time that connect is invoked, then connect will call the the login manpage method after connecting and return the result of the the login manpage method to connect's caller. If either or both of the User and Password parameters are unavailable but the connection to the server succeeds then connect returns a pointer to the IMAPClient object.
The Server parameter must be set (either during the new manpage method invocation or via the the Server manpage object method) before invoking connect. If the the Server manpage parameter is supplied to the the new manpage method then connect is implicitly called during object construction.
The connect method sets the state of the object to <code>connected</code> if it successfully connects to the server. It returns <code>undef</code> on failure.
copy
Example:
<pre> # Here brackets indicate optional arguments:
my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ])
or die "Could not copy: $@\n";</pre>
Or:
<pre> # Now brackets indicate an array ref!
my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ])
or die "Could not copy: $@\n";</pre>
The copy method requires a folder name as the first argument, and a list of one or more messages sequence numbers (or messages UID's, if the UID parameter is set to a true value). The message sequence numbers or UID's should refer to messages in the currenly selected folder. Those messages will be copied into the folder named in the first argument.
The copy method returns <code>undef</code> on failure and a true value if successful. If the server to which the current Mail::IMAPClient object is connected supports the UIDPLUS capability then the true value returned by copy will be a comma separated list of UID's, which are the UID's of the newly copied messages in the target folder.
create
Example:
<pre> $imap->create($new_folder)
or die "Could not create $new_folder: $@\n";</pre>
The create method accepts one argument, the name of a folder (or what RFC2060 calls a ``mailbox'') to create. If you specifiy additional arguments to the create method and your server allows additional arguments to the CREATE IMAP client command then the extra <code>argument(s)</code> will be passed to your server.
If you specifiy additional arguments to the create method and your server does not allow additional arguments to the CREATE IMAP client command then the extra <code>argument(s)</code> will still be passed to your server and the create will fail, so don't do that.
create returns a true value on success and <code>undef</code> on failure, as you've probably guessed.
date
Example:
<pre> my $date = $imap->date($msg);</pre>
The date method accepts one argument, a message sequence number (or a message UID if the Uid parameter is set to a true value). It returns the date of message as specified in the message's RFC822 ``Date: '' header, without the ``Date: '' prefix.
The date method is a short-cut for:
<pre> my $date = $imap->get_header($msg,"Date");</pre>
delete
Example:
<pre> $imap->delete($folder) or die "Could not delete $folder: $@\n";</pre>
The delete method accepts a single argument, the name of a folder to delete. It returns a true value on success and <code>undef</code> on failure.
delete_message
Example:
<pre> my @msgs = $imap->seen;
scalar(@msgs) and $imap->delete_message(\@msgs)
or die "Could not delete_message: $@\n";</pre>
The above could also be rewritten like this:
<pre> # scalar context returns array ref
my $msgs = scalar($imap->seen);</pre>
<pre> scalar(@$msgs) and $imap->delete_message($msgs)
or die "Could not delete_message: $@\n";</pre>
Or, as a one-liner:
<pre> $imap->delete_message( scalar($imap->seen) )
or warn "Could not delete_message: $@\n";
# just give warning in case failure is
# due to having no 'seen' msgs in the 1st place!</pre>
The delete_message method accepts a list of arguments. If the Uid parameter is not set to a true value, then each item in the list should be either:
<dl>
> a message sequence number,> a comma-separated list of message sequence numbers,> a reference to an array of message sequence numbers, or</dl>
If the Uid parameter is set to a true value, then each item in the list should be either:
<dl>
> a message UID,> a comma-separated list of UID's, or> a reference to an array of message UID's.</dl>
The messages identified by the sequence numbers or UID's will be deleted. If successful, delete_message returns the number of messages it was told to delete. However, since the delete is done by issuing the +FLAGS.SILENT option of the STORE IMAP client command, there is no guarantee that the delete was successful for every message. In this manner the delete_message method sacrifices accuracy for speed. Generally, though, if a single message in a list of messages fails to be deleted it's because it was already deleted, which is what you wanted anyway so why worry about it? If there is a more severe error, i.e. the server replies ``NO'', ``BAD'', or, banish the thought, ``BYE'', then delete_message will return <code>undef</code>.
If you must have guaranteed results then use the IMAP STORE client command (via the default method) and use the +FLAGS (\Deleted) option, and then parse your results manually.
Eg:
<pre> $imap->store($msg_id,'+FLAGS (\Deleted)');
my @results = $imap->History($imap->Transaction);
... # code to parse output goes here</pre>
(Frankly I see no reason to bother with any of that; if a message doesn't get deleted it's almost always because it's already not there, which is what you want anyway. But 'your milage may vary' and all that.)
The IMAPClient object must be in <code>Selected</code> status to use the delete_message method.
NOTE: All the messages identified in the input <code>argument(s)</code> must be in the currently selected folder. Failure to comply with this requirement will almost certainly result in the wrong <code>message(s)</code> being deleted. This would be a crying shame.
NOTE SOME MORE: In the grand tradition of the IMAP protocol, deleting a message doesn't actually delete the message. Really. If you want to make sure the message has been deleted, you need to expunge the folder (via the the expunge manpage method, which is implemented via the default method). Or at least the close manpage it. This is generally considered a feature, since after deleting a message, you can change your mind and undelete it at any time before your the expunge manpage or the close manpage.
See also: The the delete manpage method, to delete a folder, the the expunge manpage method, to expunge a folder, the the restore_message manpage method to undelete a message, and the the close manpage method (implemented here via the default method) to close a folder. Oh, and don't forget about RFC2060.
deny_seeing
Example:
<pre> # Reset all read msgs to unread
# (produces error if there are no seen msgs):
$imap->deny_seeing( scalar($imap->seen) )
or die "Could not deny_seeing: $@\n" ;</pre>
The deny_seeing method accepts a list of one or more message sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then unsets the ``\Seen'' flag for those messages (so that you can ``deny'' that you ever saw them). Of course, if the Uid parameter is set to a true value then those message sequence numbers should be unique message id's.
Note that specifying <code>$imap->deny_seeing(@msgs)</code> is just a shortcut for specifying <code>$imap->unset_flag("Seen",@msgs)</code>.
disconnect
Example:
<pre> $imap->disconnect or warn "Could not disconnect: $@\n";</pre>
Disconnects the IMAPClient object from the server. Functionally equivalent to the the logout manpage method. (In fact it's actually a synonym for the logout manpage.)
done
Example:
<pre> my $idle = $imap->idle or warn "Couldn't idle: $@\n";
&goDoOtherThings;
$imap->done($idle) or warn "Error from done: $@\n";</pre>
The done method tells the IMAP server that the connection is finished idling. See the idle manpage for more information. It accepts one argument, which is the transaction number you received from the previous call to the idle manpage.
If you pass the wrong transaction number to done then your perl program will probably hang. If you don't pass any transaction number to done then it will try to guess, and if it guesses wrong it will hang.
If you call done without previously having called the idle manpage then your server will mysteriously respond with * BAD Invalid tag.
If you try to run any other mailbox method after calling the idle manpage but before calling the done manpage, then that method will not only fail but also take you out of the IDLE state. This means that when you eventually remember to call done you will just get that * BAD Invalid tag thing again.
examine
Example:
<pre> $imap->examine($folder) or die "Could not examine: $@\n";</pre>
The examine method selects a folder in read-only mode and changes the object's state to ``Selected''. The folder selected via the examine method can be examined but no changes can be made unless it is first selected via the the select manpage method.
The examine method accepts one argument, which is the name of the folder to select.
exists
Example:
<pre> $imap->exists($folder) or warn "$folder not found: $@\n";</pre>
Accepts one argument, a folder name. Returns true if the folder exists or false if it does not exist.
expunge
Example:
<pre> $imap->expunge($folder) or die "Could not expunge: $@\n";</pre>
The expunge method accepts one optional argument, a folder name. It expunges the folder specified as the argument, or the currently selected folder if no argument is supplied.
Although RFC2060 does not permit optional arguments (like a folder name) to the EXPUNGE client command, the the expunge manpage method does, which is especially interesting given that the the expunge manpage method doesn't technically exist. In case you're curious, expunging a folder deletes the messages that you thought were already deleted via the delete_message manpage but really weren't, which means you have to use a method that doesn't exist to delete messages that you thought didn't exist. (Seriously, I'm not making any of this stuff up.)
Or you could use the the close manpage method, which de-selects as well as expunges and which likewise doesn't technically exist. As with any IMAP client command, that fact that these methods don't exist will not stop them from working anyway. This is a feature of the Mail::IMAPClient module. (See Other IMAP Client Commands and the Default Object Method if you still don't believe me.)
fetch
Example:
<pre> my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";</pre>
The fetch method implements the FETCH IMAP client command. It accepts a list of arguments, which will be converted into a space-delimited list of arguments to the FETCH IMAP client command. If no arguments are supplied then fetch does a FETCH ALL. If the Uid parameter is set to a true value then the first argument will be treated as a UID or list of UID's, which means that the UID FETCH IMAP client command will be run instead of FETCH. (It would really be a good idea at this point to review RFC2060.)
If called in array context, fetch will return an array of output lines. The output lines will be returned just as they were received from the server, so your script will have to be prepared to parse out the bits you want. The only exception to this is literal strings, which will be inserted into the output line at the point at which they were encountered (without the {nnn} literal field indicator). See RFC2060 for a description of literal fields.
If fetch is called in a scalar context, then a reference to an array (as described above) is returned instead of the entire array.
fetch returns <code>undef</code> on failure. Inspect LastError or <code>$@</code> for an explanation of your error.
fetch_hash
| Example: |
| |
my $hashref = {} ; |
| |
$imap-><code>fetch_hash(``RFC822.SIZE'',$hashref)</code> ; |
| |
print ``Msg #$m is $hashref->{$m} bytes\n'' foreach my $m (keys %$hashref); |
The fetch_hash method accepts a list of message attributes to be fetched (as described in RFC2060). It returns a hash whose keys are all the messages in the currently selected folder and whose values are key-value pairs of fetch keywords and the message's value for that keyword (see sample output below).
If fetch_hash is called in scalar context, it returns a reference to the hash instead of the hash itself. If the last argument is a hash reference, then that hash reference will be used as the place where results are stored (and that reference will be returned upon successful completion). If the last argument is not a reference then it will be treated as one of the FETCH attributes and a new hash will be created and returned (either by value or by reference, depending on the context in which fetch_hash was called).
For example, if you have a folder with 3 messages and want the size and internal date for each of them, you could do the following:
<pre> use Mail::IMAPClient;
use Data::Dumper;
# ... other code goes here
$imap->select($folder);
my $hash = $imap->fetch_hash("RFC822.SIZE","INTERNALDATE");
# (Same as:
# my $hash = $imap->fetch_hash("RFC822.SIZE");
# $imap->fetch_hash("INTERNALDATE",$hash);
# ).
print Data::Dumper->Dumpxs([$hash],['$hash']);</pre>
This would result in the Data::Dumper manpage output similar to the following:
<pre> $hash = {
'1' => {
'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
'RFC822.SIZE' => '1586',
},
'2' => {
'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
'RFC822.SIZE' => '1945',
},
'3' => {
'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
'RFC822.SIZE' => '134314',
}
};</pre>
You can specify BODY[HEADER.FIELDS ($fieldlist) as an argument, but you should keep the following in mind if you do:
1. You can only specify one argument of this type per call. If you need multiple fields, then you'll have to call fetch_hashref multiple times, each time specifying a different FETCH attribute but the same.
2. Fetch operations that return RFC822 message headers return the whole header line, including the field name and the colon. For example, if you do a <code>$imap->fetch_hash("BODY[HEADER.FIELDS (Subject)]")</code>, you will get back subject lines that start with ``Subject: ''.
By itself this method may be useful for, say, speeding up programs that want the size of every message in a folder. It issues one command and receives one (possibly long!) response from the server. However, it's true power lies in the as-yet-unwritten methods that will rely on this method to deliver even more powerful result hashes (and which may even remove the restrictions mentioned in 1 and 2, above). Look for more new function in later releases.
This method is new with version 2.2.3 and is thus still experimental. If you decide to try this method and run into problems, please see the section on REPORTING BUGS.
flags
Example:
<pre> my @flags = $imap->flags($msgid)
or die "Could not flags: $@\n";</pre>
The flags method implements the FETCH IMAP client command to list a single message's flags. It accepts one argument, a message sequence number (or a message UID, if the Uid parameter is true), and returns an array (or a reference to an array, if called in scalar context) listing the flags that have been set. Flag names are provided with leading backslashes.
As of version 1.11, you can supply either a list of message id's or a reference to an array of of message id's (which means either sequence number, if the Uid parameter is false, or message UID's, if the Uid parameter is true) instead of supplying a single message sequence number or UID. If you do, then the return value will not be an array or array reference; instead, it will be a hash reference, with each key being a message sequence number (or UID) and each value being a reference to an array of flags set for that message.
For example, if you want to display the flags for every message in the folder where you store e-mail related to your plans for world domination, you could do something like this:
<pre> use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new( Server => $imaphost,
User => $login,
Password=> $pass,
Uid => 1, # optional
);</pre>
<pre> $imap->select("World Domination");
# get the flags for every message in my 'World Domination' folder
$flaghash = $imap->flags( scalar($imap->search("ALL"))) ;</pre>
<pre> # pump through sorted hash keys to print results:
for my $k (sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash) {
# print: Message 1: \Flag1, \Flag2, \Flag3
print "Message $k:\t",join(", ",@{$flaghash->{$k}}),"\n";
}</pre>
folders
Example:
<pre> $imap->folders or die "Could not list folders: $@\n";</pre>
The folders method returns an array listing the available folders. It will only be successful if the object is in the Authenticated or Selected states.
The folders argument accepts one optional argument, which is a prefix. If a prefix is supplied to the folders method, then only folders beginning with the prefix will be returned.
For example:
<pre> print join(", ",$imap->folders),".\n";
# Prints:
# INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
print join(", ",$imap->folders("Projects"),".\n";
# Prints:
# Projects, Projects/Completed, Projects/Ongoing, Projects Software.
print join(", ",$imap->folders("Projects" . $imap->separator),".\n";
# Prints:
# Projects/Completed, Projects/Ongoing</pre>
Notice that if you just want to list a folder's subfolders (and not the folder itself), then you need to include the hierarchy separator character (as returned by the the separator manpage method).
has_capability
Example:
<pre> my $has_feature = $imap->has_capability($feature)
or die "Could not do has_capability($feature): $@\n";</pre>
Returns true if the IMAP server to which the IMAPClient object is connected has the capability specified as an argument to has_capability.
idle
Example:
<pre> my $idle = $imap->idle or warn "Couldn't idle: $@\n";
&goDoOtherThings;
$imap->done($idle) or warn "Error from done: $@\n";</pre>
The idle method places the IMAP connection in an IDLE state. Your server must support the IMAP IDLE extension to use this method. (See RFC2177 for a discussion of the IDLE IMAP extension.) The idle method accepts no arguments and returns a transaction number. This transaction number must be supplied as the argument for the done manpage when the the done manpage method is later called.
Use the the done manpage method to tell the IMAP server that the connection is finished idling.
If you attempt to use the idle method against a server that does not have the IDLE capability then the idle method will return <code>undef</code>. If you then attempt to use the idle method a second time the idle method will return <code>undef</code> again.
If you successfully run the idle method, then you must use the the done manpage method to stop idling (or to continue, in the parlance of RFC2177). Failure to do so will only encourage your server to call you BAD and to rant about a Bogus IDLE continuation.
If you try to run any other mailbox method after calling the idle manpage but before calling the done manpage, then that method will not only fail but also take you out of the IDLE state. This means that when you eventually remember to call done you will just get an * BAD Invalid tag message.
imap4rev1
Example:
<pre> $imap->imap4rev1 or die "Could not imap4rev1: $@\n";</pre>
Returns true if the IMAP server to which the IMAPClient object is connected has the IMAP4REV1 capability.
internaldate
Example:
<pre> my $msg_internal_date = $imap->internaldate($msgid)
or die "Could not internaldate: $@\n";</pre>
internaldate accepts one argument, a message id (or UID if the Uid parameter is true), and returns that message's internal date.
get_bodystructure
Example:
<pre> my $bodyStructObject = $imap->get_bodystructure($msgid)
or die "Could not get_bodystructure: $@\n";</pre>
The get_bodystructure method accepts one argument, a message sequence number or, if Uid is true, a message UID. It obtains the message's body structure and returns a parsed the Mail::IMAPClient::BodyStructure manpage object for the message.
get_envelope
Example:
<pre> my $envObject = $imap->get_envelope(@args)
or die "Could not get_envelope: $@\n";</pre>
The get_envelope method accepts one argument, a message sequence number or, if Uid is true, a message UID. It obtains the message's envelope and returns a Mail::IMAPClient::BodyStructure::Envelope object for the envelope, which is just a version of the envelope that's been parsed into a perl object.
For more information on how to use this object once you've gotten it, see the the Mail::IMAPClient::BodyStructure manpage documention. (As of this writing there is no separate pod document for Mail::IMAPClient::BodyStructure::Envelope.)
getacl
Example:
<pre> my $hash = $imap->getacl($folder)
or die "Could not getacl for $folder: $@\n";</pre>
getacl accepts one argument, the name of a folder. If no argument is provided then the currently selected folder is used as the default. It returns a reference to a hash. The keys of the hash are userids that have access to the folder, and the value of each element are the permissions for that user. The permissions are listed in a string in the order returned from the server with no whitespace or punctuation between them.
get_header
Example:
<pre> my $messageId = $imap->get_header($msg, "Message-Id") ;</pre>
The get_header method accepts two arguments, a message sequence number or UID and the name of an RFC822 header (without the trailing colon). It returns the value for that header in the message whose sequence number or UID was passed as the first argument. If no value can be found it returns <code>undef</code>; if multiple values are found it returns the first one. Its return value is always a scalar. get_header uses case insensitive matching to get the value, so you do not have to worry about the case of your second argument.
The get_header method is a short-cut for:
<pre> my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];</pre>
is_parent
Example:
<pre> my $hasKids = $imap->is_parent($folder) ;</pre>
The is_parent method accepts one argument, the name of a folder. It returns a value that indicates whether or not the folder has children. The value it returns is either 1) a true value (indicating that the folder has children), 2) 0 if the folder has no children at this time, or 3) <code>undef</code> if the folder is not permitted to have children.
Eg:
<pre> my $parenthood = $imap->is_parent($folder);
if (defined($parenthood)) {
if ($parenthood) {
print "$folder has children.\n" ;
} else {
print "$folder is permitted children, but has none.\n";
}
} else {
print "$folder is not permitted to have children.\n";
}</pre>
list
Example:
<pre> my @raw_output = $imap->list(@args)
or die "Could not list: $@\n";</pre>
The list method implements the IMAP LIST client command. Arguments are passed to the IMAP server as received, separated from each other by spaces. If no arguments are supplied then the default list command <code>tag LIST "" '*'</code> is issued.
The list method returns an array (or an array reference, if called in a scalar context). The array is the unadulterated output of the LIST command. (If you want your output adulterated then see the the folders manpage method, above.)
listrights
Example:
<pre> $imap->listrights($folder,$user)
or die "Could not listrights: $@\n";</pre>
The listrights method implements the IMAP LISTRIGHTS client command (RFC2086). It accepts two arguments, the foldername and a user id. It returns the rights the specified user has for the specified folder. If called in a scalar context then the rights are returned a strings, with no punction or whitespace or any nonsense like that. If called in array context then listrights returns an array in which each element is one right.
login
Example:
<pre> $imap->login or die "Could not login: $@\n";</pre>
The login method uses the IMAP LOGIN client command (as defined in RFC2060) to log into the server. The User and Password parameters must be set before the login method can be invoked. If successful, the login method returns a pointer to the IMAPClient object and sets the object status to Authenticated. If unsuccessful, it returns undef. See the the new manpage method for more information on how login can be called automatically from the new manpage.
login is sometimes called automatically by the connect manpage, which in turn is sometimes called automatically by the new manpage. You can predict this behavior once you've read the section on the the new manpage method.
logout
Example:
<pre> $imap->logout or die "Could not logout: $@\n";</pre>
The logout method issues the LOGOUT IMAP client commmand. Since the LOGOUT IMAP client command causes the server to end the connection, this also results in the IMAPClient client entering the Unconnected state. This method does not, however, destroy the IMAPClient object, so a program can re-invoke the the connect manpage and the login manpage methods if it wishes to reestablish a session later in the program.
According to the standard, a well-behaved client should log out before closing the socket connection. Therefore, Mail::IMAPClient will attempt to log out of the server during DESTROY processing if the object being destroyed is in the Connected state.
lsub
Example:
<pre> $imap->lsub(@args) or die "Could not lsub: $@\n";</pre>
The lsub method implements the IMAP LSUB client command. Arguments are passed to the IMAP server as received, separated from each other by spaces. If no arguments are supplied then the default lsub command <code>tag LSUB "" '*'</code> is issued.
The lsub method returns an array (or an array reference, if called in a scalar context). The array is the unaltered output of the LSUB command. If you want an array of subscribed folders then see the the subscribed manpage method, below.
mark
Example:
<pre> $imap->mark(@msgs) or die "Could not mark: $@\n";</pre>
The mark method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then sets the ``\Flagged'' flag for those message(s). Of course, if the Uid parameter is set to a true value then those message sequence numbers had better be unique message id's.
Note that specifying <code>$imap->see(@msgs)</code> is just a shortcut for specifying <code>$imap->set_flag("Flagged",@msgs)</code>.
Massage
Example:
<pre> $imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));</pre>
The Massage method accepts a value as an argument and, optionally, a second value that, when true, indicates that the first argument is not the name of an existing folder.
It returns its argument as a correctly quoted string or a literal string.
Note that you should rarely use this on folder names, since methods that accept folder names as an argument will call Massage for you. In fact, it was originally developed as an undocumented helper method meant for internal Mail::IMAPClient methods only.
You may also want to see the Quote method, which is related to this method.
message_count
Example:
<pre> my $msgcount = $imap->message_count($folder);
defined($msgcount) or die "Could not message_count: $@\n";</pre>
The message_count method accepts the name of a folder as an argument and returns the number of messages in that folder. Internally, it invokes the the status manpage method (see above) and parses out the results to obtain the number of messages. If you don't supply an argument to message_count then it will return the number of messages in the currently selected folder (assuming of course that you've used the the select manpage or the examine manpage method to select it instead of trying something funky). Note that RFC2683 contains warnings about the use of the IMAP STATUS command (and thus the the status manpage method and therefore the message_count method) against the currenlty selected folder. You should carefully consider this before using message_count on the currently selected folder. You may be better off using the search manpage or one of its variants (especially the messages manpage), and then counting the results. On the other hand, I regularly violate this rule on my server without suffering any dire consequences. Your milage may vary.
message_string
Example:
<pre> my $string = $imap->message_string($msgid)
or die "Could not message_string: $@\n";</pre>
The message_string method accepts a message sequence number (or message UID if Uid is true) as an argument and returns the message as a string. The returned value contains the entire message in one scalar variable, including the message headers. Note that using this method will set the message's ``\Seen'' flag as a side effect, unless Peek is set to a true value.
message_to_file
Example:
<pre> $imap->message_to_file($file,@msgs)
or die "Could not message_to_file: $@\n";</pre>
The message_to_file method accepts a filename or file handle and one or more message sequence numbers (or message UIDs if Uid is true) as arguments and places the message <code>string(s)</code> (including RFC822 headers) into the file named in the first argument (or prints them to the filehandle, if a filehandle is passed). The returned value is true on succes and <code>undef</code> on failure.
If the first argument is a reference, it is assumed to be an open filehandle and will not be closed when the method completes, If it is a file, it is opened in append mode, written to, then closed.
Note that using this method will set the message's ``\Seen'' flag as a side effect. But you can use the the deny_seeing manpage method to set it back, or set the the Peek manpage parameter to a true value to prevent setting the ``\Seen'' flag at all.
This method currently works by making some basic assumptions about the server's behavior, notably that the message text will be returned as a literal string but that nothing else will be. If you have a better idea then I'd like to hear it.
message_uid
Example:
<pre> my $msg_uid = $imap->message_uid($msg_seq_no)
or die "Could not get uid for $msg_seq_no: $@\n";</pre>
The message_uid method accepts a message sequence number (or message UID if Uid is true) as an argument and returns the message's UID. Yes, if Uid is true then it will use the IMAP UID FETCH UID client command to obtain and return the very same argument you supplied. This is an IMAP feature so don't complain to me about it.
messages
Example:
<pre> # Get a list of messages in the current folder:
my @msgs = $imap->messages or die "Could not messages: $@\n";
# Get a reference to an array of messages in the current folder:
my $msgs = $imap->messages or die "Could not messages: $@\n";</pre>
If called in list context, the messages method returns a list of all the messages in the currenlty selected folder. If called in scalar context, it returns a reference to an array containing all the messages in the folder. If you have the Uid parameter turned off, then this is the same as specifying <code>1 ... $imap->message_count</code>; if you have UID set to true then this is the same as specifying <code>$imap->search("ALL")</code>.
migrate
Example:
<pre> $imap->migrate($imap_2, "ALL", $targetFolder )
or die "Could not migrate: $@\n";</pre>
The migrate method copies the indicated messages from the currently selected folder to another Mail::IMAPClient object's session. It requires these arguments:
- a reference to the target Mail::IMAPClient object (not the calling object, which is connected to the source account);
- the <code>message(s)</code> to be copied, specified as either a) the message sequence number (or message UID if the UID parameter is true) of a single message, b) a reference to an array of message sequence numbers (or message UID's if the UID parameter is true) or c) the special string ``ALL'', which is a shortcut for the results of <code>search("ALL")</code>.
- the folder name of a folder on the target mailbox to receive the message(s). If this argument is not supplied or if undef is supplied then a folder with the same name as the currently selected folder on the calling object will be created if necessary and used. If you specify something other then undef for this argument, even if it's '$imap1->Folder' or the name of the currently selected folder, then that folder will only be used if it exists on the target object's mailbox; if it does not exist then migrate will fail.
The target Mail::IMAPClient object should not be the same as the source. The source object is the calling object, i.e. the one whose migrate method will be used. It cannot be the same object as the one specified as the target, even if you are for some reason migrating between folders on the same account (which would be silly anyway, since the copy manpage can do that much more efficiently). If you try to use the same Mail::IMAPClient object for both the caller and the reciever then they'll both get all screwed up and it will be your fault because I just warned you and you didn't listen.
migrate will download messages from the source in chunks to minimize memory usage. The size of the chunks can be controlled by changing the source Mail::IMAPClient object's the Buffer parameter. The higher the Buffer value, the faster the migration, but the more memory your program will require. TANSTAAFL. (See the Buffer parameter and eponymous accessor method, described above under the Parameters section.)
The migrate method uses Black Magic to hardwire the I/O between the two Mail::IMAPClient objects in order to minimize resource consumption. If you have older scripts that used the message_to_file manpage and the append_file manpage to move large messages between IMAP mailboxes then you may want to try this method as a possible replacement.
move
Example:
<pre> my $newUid = $imap->move($newFolder, $oldUid)
or die "Could not move: $@\n";
$imap->expunge;</pre>
The move method moves messages from the currently selected folder to the folder specified in the first argument to move. If the Uid parameter is not true, then the rest of the arguments should be either:
<dl>
>a message sequence number,>a comma-separated list of message sequence numbers, or>a reference to an array of message sequence numbers.</dl>
If the Uid parameter is true, then the arguments should be:
<dl>
>a message UID,>a comma-separated list of message UID's, or>a reference to an array of message UID's.</dl>
If the target folder does not exist then it will be created.
If move is sucessful, then it returns a true value. Furthermore, if the Mail::IMAPClient object is connected to a server that has the UIDPLUS capability, then the true value will be the comma-separated list of UID's for the newly copied messages. The list will be in the order in which the messages were moved. (Since move uses the copy method, the messages will be moved in numerical order.)
If the move is not successful then move returns <code>undef</code>.
Note that a move really just involves copying the message to the new folder and then setting the \Deleted flag. To actually delete the original message you will need to run the expunge manpage (or the close manpage).
namespace
Example:
<pre> my @refs = $imap->namespace
or die "Could not namespace: $@\n";</pre>
The namespace method runs the NAMESPACE IMAP command (as defined in RFC 2342). When called in a list context, it returns a list of three references. Each reference looks like this:
<pre> [ [ $prefix_1, $separator_1 ] ,
[ $prefix_2, $separator_2 ],
[ $prefix_n , $separator_n]
]</pre>
The first reference provides a list of prefices and separator charactors for the available personal namespaces. The second reference provides a list of prefices and separator charactors for the available shared namespaces. The third reference provides a list of prefices and separator charactors for the available public namespaces.
If any of the three namespaces are unavailable on the current server then an 'undef' is returned instead of a reference. So for example if shared folders were not supported on the server but personal and public namespaces were both available (with one namespace each), the returned value might resemble this:
<pre> ( [ "", "/" ] , undef, [ "#news", "." ] ) ;</pre>
If the namespace method is called in scalar context, it returns a reference to the above-mentioned list of three references, thus creating a single structure that would pretty-print something like this:
<pre> $VAR1 = [
[
[ $user_prefix_1, $user_separator_1 ] ,
[ $user_prefix_2, $user_separator_2],
[ $user_prefix_n , $user_separator_n]
] , # or undef
[
[ $shared_prefix_1, $shared_separator_1 ] ,
[ $shared_prefix_2, $shared_separator_2],
[ $shared_prefix_n , $shared_separator_n]
] , # or undef
[
[ $public_prefix_1, $public_separator_1 ] ,
[ $public_prefix_2, $public_separator_2],
[ $public_prefix_n , $public_separator_n]
] , # or undef
];</pre>
Or, to look at our previous example (where shared folders are unsupported) called in scalar context:
<pre> $VAR1 = [
[
[
"" ,
"/",
],
],</pre>
<pre> undef,</pre>
<pre> [
[
"#news",
"."
],
],
];</pre>
on
Example:
<pre> my @msgs = $imap->on($Rfc2060_date)
or warn "Could not find messages sent on $Rfc2060_date: $@\n";</pre>
The on method works just like the the since manpage method, below, except it returns a list of messages whose internal system dates are the same as the date supplied as the argument.
parse_headers
Example:
<pre> my $hashref = $imap->parse_headers($msg||@msgs, "Date", "Subject")
or die "Could not parse_headers: $@\n";</pre>
The parse_headers method accepts as arguments a message sequence number and a list of header fields. It returns a hash reference in which the keys are the header field names (without the colon) and the values are references to arrays of values. A picture would look something like this:
<pre> $hashref = $imap->parse_headers(1,"Date","Received","Subject","To");
$hashref = {
"Date" => [ "Thu, 09 Sep 1999 09:49:04 -0400" ] ,
"Received" => [ q/
from mailhub ([111.11.111.111]) by mailhost.bigco.com
(Netscape Messaging Server 3.6) with ESMTP id AAA527D for
<bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
/, q/
from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
(ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
/, q/
from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473)
with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
18 Jun 1999 16:29:05 +0000 (GMT)
/] ,
"Subject" => [ qw/ Help! I've fallen and I can't get up!/ ] ,
"To" => [ "Big Shot <big.shot@bigco.com> ] ,
} ;</pre>
The text in the example for the ``Received'' array has been formated to make reading the example easier. The actual values returned are just strings of words separated by spaces and with newlines and carriage returns stripped off. The Received header is probably the main reason that the parse_headers method creates a hash of lists rather than a hash of values.
If the second argument to parse_headers is 'ALL' or if it is unspecified then all available headers are included in the returned hash of lists.
If you're not emotionally prepared to deal with a hash of lists then you can always call the the fetch manpage method yourself with the appropriate parameters and parse the data out any way you want to. Also, in the case of headers whose contents are also reflected in the envelope, you can use the the get_envelope manpage method as an alternative to the parse_headers manpage.
If the Uid parameter is true then the first argument will be treated as a message UID. If the first argument is a reference to an array of message sequence numbers (or UID's if Uid is true), then parse_headers will be run against each message in the array. In this case the return value is a hash, in which the key is the message sequence number (or UID) and the value is a reference to a hash as described above.
An example of using parse_headers to print the date and subject of every message in your smut folder could look like this:
<pre> use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new( Server => $imaphost,
User => $login,
Password=> $pass,
Uid => 1, # optional
);</pre>
<pre> $imap->select("smut");</pre>
<pre> for my $h (</pre>
<pre> # grab the Subject and Date from every message in my (fictional!) smut folder;
# the first argument is a reference to an array listing all messages in the folder
# (which is what gets returned by the $imap->search("ALL") method when called in
# scalar context) and the remaining arguments are the fields to parse out</pre>
<pre> # The key is the message number, which in this case we don't care about:
values %{$imap->parse_headers( scalar($imap->search("ALL")) , "Subject", "Date")}
) {
# $h is the value of each element in the hash ref returned from parse_headers,
# and $h is also a reference to a hash.
# We'll only print the first occurance of each field because we don't expect more
# than one Date: or Subject: line per message.
print map { "$_:\t$h->{$_}[0]\n"} keys %$h ;
}</pre>
recent
Example:
<pre> my @recent = $imap->recent or warn "No recent msgs: $@\n";</pre>
The recent method performs an IMAP SEARCH RECENT search against the selected folder and returns an array of sequence numbers (or UID's, if the Uid parameter is true) of messages that are recent.
recent_count
Example:
<pre> my $count = 0;
defined($count = $imap->recent_count($folder))
or die "Could not recent_count: $@\n";</pre>
The recent_count method accepts as an argument a folder name. It returns the number of recent messages in the folder (as returned by the IMAP client command ``STATUS folder RECENT''), or <code>undef</code> in the case of an error. The recent_count method was contributed by Rob Deker (deker@ikimbo.com)
rename
Example:
<pre> $imap->rename($oldname,$nedwname)
or die "Could not rename: $@\n";</pre>
The rename method accepts two arguments: the name of an existing folder, and a new name for the folder. The existing folder will be renamed to the new name using the RENAME IMAP client command. rename will return a true value if successful, or <code>undef</code> if unsuccessful.
restore_message
Example:
<pre> $imap->restore_message(@msgs) or die "Could not restore_message: $@\n";</pre>
The restore_message method is used to undo a previous the delete_message manpage operation (but not if there has been an intervening the expunge manpage or the close manpage). The IMAPClient object must be in Selected status to use the restore_message method.
The restore_message method accepts a list of arguments. If the Uid parameter is not set to a true value, then each item in the list should be either:
<dl>
>a message sequence number,>a comma-separated list of message sequence numbers,>a reference to an array of message sequence numbers, or</dl>
If the Uid parameter is set to a true value, then each item in the list should be either:
<dl>
>a message UID,>a comma-separated list of UID's, or>a reference to an array of message UID's.</dl>
The messages identified by the sequence numbers or UID's will have their \Deleted flags cleared, effectively ``undeleting'' the messages. restore_message returns the number of messages it was able to restore.
Note that restore_messages is similar to calling <code>unset_flag("\Deleted",@msgs)</code>, except that restore_messages returns a (slightly) more meaningful value. Also it's easier to type.
run
Example:
<pre> $imap->run(@args) or die "Could not run: $@\n";</pre>
Like Perl itself, the Mail::IMAPClient module is designed to make common things easy and uncommon things possible. The run method is provided to make those uncommon things possible.
The run method excepts one or two arguments. The first argument is a string containing an IMAP Client command, including a tag and all required arguments. The optional second argument is a string to look for that will indicate success. (The default is <code>/OK.*/</code>). The run method returns an array of output lines from the command, which you are free to parse as you see fit.
The run method does not do any syntax checking, other than rudimentary checking for a tag.
When run processes the command, it increments the transaction count and saves the command and responses in the History buffer in the same way other commands do. However, it also creates a special entry in the History buffer named after the tag supplied in the string passed as the first argument. If you supply a numeric value as the tag then you may risk overwriting a previous transaction's entry in the History buffer.
If you want the control of run but you don't want to worry about the damn tags then see tag_and_run, below.
search
Example:
<pre> my @msgs = $imap->search(@args) or warn "search: None found\n";
if ($@) {
warn "Error in search: $@\n";
}</pre>
The search method implements the SEARCH IMAP client command. Any argument supplied to search is prefixed with a space and appended to the SEARCH IMAP client command. This method is another one of those situations where it will really help to have your copy of RFC2060 handy, since the SEARCH IMAP client command contains a plethora of options and possible arguments. I'm not going to repeat them here.
Remember that if your argument needs quotes around it then you must make sure that the quotes will be preserved when passing the argument. I.e. use <code>qq/"$arg"/</code> instead of <code>"$arg"</code>. When in doubt, use the Quote method.
The search method returns an array containing sequence numbers of messages that passed the SEARCH IMAP client command's search criteria. If the Uid parameter is true then the array will contain message UID's. If search is called in scalar context then a pointer to the array will be passed, instead of the array itself. If no messages meet the criteria then search returns an empty list (when in list context) or <code>undef</code> (in scalar context).
Since a valid, successful search can legitimately return zero matches, you may wish to distinguish between a search that correctly returns zero hits and a search that has failed for some other reason (i.e. invalid search parameters). Therefore, the <code>$@</code> variable will always be cleared before the SEARCH command is issued to the server, and will thus remain empty unless the server gives a BAD or NO response to the SEARCH command.
see
Example:
<pre> $imap->see(@msgs) or die "Could not see: $@\n";</pre>
The see method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then sets the \Seen flag for those message(s). Of course, if the Uid parameter is set to a true value then those message sequence numbers had better be unique message id's, but then you already knew that, didn't you?
Note that specifying <code>$imap->see(@msgs)</code> is just a shortcut for specifying <code>$imap->set_flag("Seen",@msgs)</code>.
seen
Example:
<pre> my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";</pre>
The seen method performs an IMAP SEARCH SEEN search against the selected folder and returns an array of sequence numbers of messages that have already been seen (ie their \Seen flag is set). If the Uid parameter is true then an array of message UID's will be returned instead. If called in scalar context than a reference to the array (rather than the array itself) will be returned.
select
Example:
<pre> $imap->select($folder) or die "Could not select: $@\n";</pre>
The select method selects a folder and changes the object's state to Selected. It accepts one argument, which is the name of the folder to select.
selectable
Example:
<pre> foreach my $f ( grep($imap->selectable($_),$imap->folders ) ) {
$imap->select($f) ;
}</pre>
The selectable method accepts one value, a folder name, and returns true if the folder is selectable or false if it is not selectable.
sentbefore
Example:
<pre> my @msgs = $imap->sentbefore($Rfc2060_date)
or warn "Could not find any msgs sent before $Rfc2060_date: $@\n";</pre>
The sentbefore method works just like sentsince, below, except it searches for messages that were sent before the date supplied as an argument to the method.
senton
Example:
<pre> my @msgs = $imap->senton($Rfc2060_date)
or warn "Could not find any messages sent on $Rfc2060_date: $@\n";</pre>
The senton method works just like sentsince, below, except it searches for messages that were sent on the exact date supplied as an argument to the method.
sentsince
Example:
<pre> my @msgs = $imap->sentsince($Rfc2060_date)
or warn "Could not find any messages sent since $Rfc2060_date: $@\n";</pre>
The sentsince method accepts one argument, a date in either epoch time 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 the argument. It uses the RFC822 Date: header to determine the sentsince date. (Actually, it the server that uses the Date: header; this documentation just assumes that the date is coming from the Date: header because that's what RFC2060 dictates.)
In the case of arguments supplied as a number of seconds, the returned result list will include items sent on or after that day, regardless of whether they arrived before the specified time on that day. The IMAP protocol does not support searches at a granularity finer than a day, so neither do I. On the other hand, the only thing I check for in a date_text argument is that it matches the pattern <code>/\d\d-\D\D\D-\d\d\d\d/</code> (notice the lack of anchors), so if your server lets you add something extra to a date_text string then so will Mail::IMAPClient.
If you'd like, you can use the Rfc2060_date method to convert from epoch time (as returned by time) into an RFC2060 date specification.
separator
Example:
<pre> my $sepChar = $imap->separator(@args)
or die "Could not get separator: $@\n";</pre>
The separator method returns the character used as a separator character in folder hierarchies. On unix-based servers, this is often but not necessarily a forward slash (/). It accepts one argument, the name of a folder whose hierarchy's separator should be returned. If no folder name is supplied then the separator for the INBOX is returned, which probably is good enough.
If you want your programs to be portable from IMAP server brand X to IMAP server brand Y, then you should never use hard-coded separator characters to specify subfolders. (In fact, it's even more complicated than that, since some server don't allow any subfolders at all, some only allow subfolders under the ``INBOX'' folder, and some forbid subfolders in the inbox but allow them ``next'' to the inbox. Furthermore, some server implementations do not allow folders to contain both subfolders and mail messages; other servers allow this.)
set_flag
Example:
<pre> $imap->set_flag("Seen",@msgs)
or die "Could not set flag: $@\n";</pre>
The set_flag method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then sets the flag specified for those message(s). Of course, if the Uid parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect.
Note that when specifying the flag in question, the preceding backslash (\) is entirely optional. (For you, that is. Mail::IMAPClient still has remember to stick it in there before passing the command to the server if the flag is one of the reserved flags specified in RFC2060. This is in fact so important that the method checks its argument and adds the backslash when necessary, which is why you don't have to worry about it overly much.)
setacl
Example:
<pre> $imap->setacl($folder,$userid,$authstring)
or die "Could not set acl: $@\n";</pre>
The setacl method accepts three input arguments, a folder name, a user id (or authentication identifier, to use the terminology of RFC2086), and an access rights modification string. See RFC2086 for more information. (This is somewhat experimental and its implementation may change.)
since
Example:
<pre> my @msgs = $imap->since($date)
or warn "Could not find any messages since $date: $@\n";</pre>
The since method accepts a date in either epoch format (seconds since 1/1/1970, or as output by time in the perlfunc manpage and as accepted by localtime in the perlfunc manpage) 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 whose internal dates are on or after the day whose date is provided as the argument. It uses the internal system date for a message to determine if that message was sent since the given date.
In the case of arguments supplied as a number of seconds, the returned result list will include items whose internal date is on or after that day, regardless of whether they arrived before the specified time on that day.
If since is called in a list context then it will return a list of messages meeting the SEARCH SINCE criterion, or an empty list if no messages meet the criterion.
If since is called in a scalar context then it will return a reference to an array of messages meeting the SEARCH SINCE criterion, or <code>undef</code> if no messages meet the criterion.
Since since is a front-end to the search manpage, some of the same rules apply. For example, the <code>$@</code> variable will always be cleared before the SEARCH command is issued to the server, and will thus remain empty unless the server gives a BAD or NO response to the SEARCH command.
size
Example:
<pre> my $size = $imap->size($msgId)
or die "Could not find size of message $msgId: $@\n";</pre>
The size method accepts one input argument, a sequence number (or message UID if the Uid parameter is true). It returns the size of the message in the currently selected folder with the supplied sequence number (or UID). The IMAPClient object must be in a Selected state in order to use this method.
sort
Example:
<pre> my @msgs = $imap->sort(@args) ;
if ($@ ) {
warn "Error in sort: $@\n";
}</pre>
The sort method is just like the the search manpage method, only different. It implements the SORT extension as described in http://search.ietf.org/internet-drafts/draft-ietf-imapext-sort-10.txt. It would be wise to use the the has_capability manpage method to verify that the SORT capability is available on your server before trying to use the sort method. If you forget to check and you're connecting to a server that doesn't have the SORT capability then sort will return undef. LastError will then say you are ``BAD''. If your server doesn't support the SORT capability then you'll have to use the search manpage and then sort the results yourself.
The first argument to sort is a space-delimited list of sorting criteria. The Internet Draft that describes SORT requires that this list be wrapped in parentheses, even if there is only one sort criterion. If you forget the parentheses then the sort method will add them. But you have to forget both of them, or none. This isn't CMS running under VM!
The second argument is a character set to use for sorting. Different character sets use different sorting orders, so this argument is important. Since all servers must support UTF-8 and US-ASCII if they support the SORT capability at all, you can use one of those if you don't have some other preferred character set in mind.
The rest of the arguments are searching criteria, just as you would supply to the the search manpage method. These are all documented in RFC2060. If you just want all of the messages in the currently selected folder returned to you in sorted order, use ALL as your only search criterion.
The sort method returns an array containing sequence numbers of messages that passed the SORT IMAP client command's search criteria. If the Uid parameter is true then the array will contain message UID's. If sort is called in scalar context then a pointer to the array will be passed, instead of the array itself. The message sequence numbers or unique identifiers are ordered according to the sort criteria specified. The sort criteria are nested in the order specified; that is, items are sorted first by the first criterion, and within the first criterion they are sorted by the second criterion, and so on.
The sort method will clear <code>$@</code> before attempting the SORT operation just as the the search manpage method does.
status
Example:
<pre> my @rawdata = $imap->status($folder,qw/(Messages)/)
or die "Error obtaining status: $@\n";</pre>
The status method accepts one argument, the name of a folder (or mailbox, to use RFC2060's terminology), and returns an array containing the results of running the IMAP STATUS client command against that folder. If additional arguments are supplied then they are appended to the IMAP STATUS client command string, separated from the rest of the string and each other with spaces.
If status is not called in an array context then it returns a reference to an array rather than the array itself.
The status method should not be confused with the Status method (with an uppercase 'S'), which returns information about the IMAPClient object. (See the section labeled Status Methods, below).
store
Example:
<pre> $imap->store(@args) or die "Could not store: $@\n";</pre>
The store method accepts a message sequence number or comma-separated list of message sequence numbers as a first argument, a message data item name, and a value for the message data item. Currently, data items are the word ``FLAGS'' followed by a space and a list of flags (in parens). The word ``FLAGS'' can be modified by prefixing it with either a ``+'' or a ``-'' (to indicate ``add these flags'' or ``remove these flags'') and by suffixing it with ``.SILENT'' (which reduces the amount of output from the server; very useful with large message sets). Normally you won't need to call store because there are oodles of methods that will invoke store for you with the correct arguments. Furthermore, these methods are friendlier and more flexible with regards to how you specify your arguments. See for example the see manpage, the deny_seeing manpage, the delete_message manpage, and the restore_message manpage. Or the mark manpage, the unmark manpage, the set_flag manpage, and the unset_flag manpage.
subject
Example:
<pre> my $subject = $imap->subject($msg);</pre>
The subject method accepts one argument, a message sequence number (or a message UID, if the Uid parameter is true). The text in the ``Subject'' header of that message is returned (without the ``Subject: '' prefix). This method is a short-cut for:
<pre> my $subject = $imap->get_header($msg, "Subject");</pre>
subscribed
Example:
<pre> my @subscribedFolders = $imap->subscribed
or warn "Could not find subscribed folders: $@\n";</pre>
The subscribed method works like the folders method, above, except that the returned list (or array reference, if called in scalar context) contains only the subscribed folders.
Like the folders manpage, you can optionally provide a prefix argument to the subscribed method.
tag_and_run
Example:
<pre> my @output = $imap->tag_and_run(@args)
or die "Could not tag_and_run: $@\n";</pre>
The tag_and_run method accepts one or two arguments. The first argument is a string containing an IMAP Client command, without a tag but with all required arguments. The optional second argument is a string to look for that will indicate success (without pattern delimiters). The default is <code>OK.*</code>.
The tag_and_run method will prefix your string (from the first argument) with the next transaction number and run the command. It returns an array of output lines from the command, which you are free to parse as you see fit. Using this method instead of run (above) will free you from having to worry about handling the tags (and from worrying about the side affects of naming your own tags).
uidnext
Example:
<pre> my $nextUid = $imap->uidnext($folder) or die "Could not uidnext: $@\n";</pre>
The uidnext method accepts one argument, the name of a folder, and returns the numeric string that is the next available message UID for that folder.
thread
Example:
<pre> my $thread = $imap->thread($algorythm, $charset, @search_args ) ;</pre>
The thread method accepts zero to three arguments. The first argument is the threading algorythm to use, generally either ORDEREDSUBJECT or REFERENCES. The second argument is the character set to use, and the third argument is the set of search arguments to use.
If the algorythm is not supplied, it defaults to REFERENCES if available, or ORDEREDSUBJECT if available. If neither of these is available then the thread method returns undef.
If the character set is not specified it will default to UTF-8.
If the search arguments are not specified, the default is ALL.
If thread is called for an object connected to a server that does not support the THREADS extension then the thread method will return <code>undef</code>.
The threads method will issue the THREAD command as defined in http://www.ietf.org/internet-drafts/draft-ietf-imapext-thread-11.txt. It returns an array of threads. Each element in the array is either a message id or a reference to another array of (sub)threads.
If the Uid parameter is set to a true value then the message id's returned in the thread structure will be message UID's. Otherwise they will be message sequence numbers.
uidvalidity
Example:
<pre> my $validity = $imap->uidvalidity($folder)
or die "Could not uidvalidity: $@\n";</pre>
The uidvalidity method accepts one argument, the name of a folder, and returns the numeric string that is the unique identifier validity value for the folder.
unmark
Example:
<pre> $imap->unmark(@msgs) or die "Could not unmark: $@\n";</pre>
The unmark method accepts a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its argument(s). It then unsets the \Flagged flag for those message(s). Of course, if the Uid parameter is set to a true value then those message sequence numbers should really be unique message id's.
Note that specifying <code>$imap->unmark(@msgs)</code> is just a shortcut for specifying <code>$imap->unset_flag("Flagged",@msgs)</code>.
Note also that the \Flagged flag is just one of many possible flags. This is a little confusing, but you'll have to get used to the idea that among the reserved flags specified in RFC2060 is one name \Flagged. There is no specific meaning for this flag; it means whatever the mailbox owner (or delegate) wants it to mean when it is turned on.
unseen
Example:
<pre> my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";</pre>
The unseen method performs an IMAP SEARCH UNSEEN search against the selected folder and returns an array of sequence numbers of messages that have not yet been seen (ie their \Seen flag is not set). If the Uid parameter is true then an array of message UID's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned.
Note that when specifying the flag in question, the preceding backslash (\) is entirely optional.
unseen_count
Example:
<pre> foreach my $f ($imap->folders) {
print "The $f folder has ",
$imap->unseen_count($f)||0,
" unseen messages.\n";
}</pre>
The unseen_count method accepts the name of a folder as an argument and returns the number of unseen messages in that folder. If no folder argument is provided then it returns the number of unseen messages in the currently selected Folder.
unset_flag
Example:
<pre> $imap->unset_flag("\Seen",@msgs)
or die "Could not unset_flag: $@\n";</pre>
The unset_flag method accepts the name of a flag as its first argument and a list of one or more messages sequence numbers, or a single reference to an array of one or more message sequence numbers, as its next argument(s). It then unsets the flag specified for those message(s). Of course, if the Uid parameter is set to a true value then those message sequence numbers had better be unique message id's, just as you'd expect.
Other IMAP Client Commands and the Default Object Method
IMAP Client Commands not otherwise documented have been implemented via an AUTOLOAD hack and use a default method.
If a program calls a method that is not defined (or inherited) by the IMAPClient module then the IMAPClient module will assume that it is an IMAP client command. It will prefix the command with the next available transaction number (or tag value), and append to it the space-delimited list of arguments supplied to the unimplemented method (if any). It will then read lines of output from the imap session until it finds a line containing the strings ``OK'' and ``Completed'', and return an array containing all of the lines of output (or, if called in scalar context, an array reference). If it finds ``BAD'' or ``NO'' instead of ``OK'' it returns <code>undef</code>.
Eg:
<pre> my @results = $imap->FOO("bar","an example","of the default");</pre>
results in:
<pre> 99 FOO bar an example of the default\r\n</pre>
being sent to the IMAP server (assuming that 99 is the current transaction number).
Notice that we used an uppercase method name ``FOO'' so as not to conflict with future implementations of that IMAP command. If you run your script with warnings turned on (always a good idea, at least during testing), then you will receive warnings whenever you use a lowercase method name that has not been implemented. An exception to this is when you use certain common (yet unimplemented) methods that, if ever explicitly implemented, are guaranteed to behave just like the default method. To date, those methods are either documented in the section labeled OBJECT METHODS, above, or listed here:
Mail::IMAPClient's default method adds enormous flexibility and built-in extensibility but it is not psychic. It can handle almost any extension and truthfully tell you if the server successfully performed your request. But it cannot predict how the command's output should be handled, beyond returning a true value on success and <code>undef</code> on failure. So if you are running a command because you want the output then you may need to parse that output yourself. If you develop code that extends Mail::IMAPClient in a way that you feel may be useful to others then please consider donating the code. Many of the methods in Mail::IMAPClient were contributed by other programmers such as yourself. Their contributions are listed in the Changes file as they occur.
<code>copy($msg,$folder)</code>
Copy a message from the currently selected folder in the the folder whose name is in <code>$folder</code>
<code>subscribe($folder)</code>
Subscribe to a folder
CAUTION: Once again, remember to quote your quotes (or use the Quote method) if you want quotes to be part of the IMAP command string.
You can also use the default method to override the behavior of implemented IMAP methods by changing the case of the method name, preferably to all-uppercase so as not to conflict with the Class method and accessor method namespace. For example, if you don't want the the search manpage method's behavior (which returns a list of message numbers) but would rather have an array of raw data returned from your the search manpage operation, you can issue the following snippet:
<pre> my @raw = $imap->SEARCH("SUBJECT","Whatever...");</pre>
which is slightly more efficient than the equivalent:
<pre> $imap->search("SUBJECT","Whatever...");</pre>
<pre> my @raw = $imap->Results;</pre>
Of course you probably want the search results tucked nicely into a list for you anyway, in which case you might as well use the the search manpage method.
Parameters
There are several parameters that influence the behavior of an IMAPClient object. Each is set by specifying a named value pair during new method invocation as follows:
<pre> my $imap = Mail::IMAPClient->new ( parameter => "value",
parameter2 => "value",
...
);</pre>
Parameters can also be set after an object has been instantiated by using the parameter's eponymous accessor method like this:
<pre> my $imap = Mail::IMAPClient->new;
$imap->parameter( "value");
$imap->parameter2("value");</pre>
The eponymous accessor methods can also be used without arguments to obtain the current value of the parameter as follows:
<pre> my $imap = Mail::IMAPClient->new;
$imap->parameter( "value");
$imap->parameter2("value");</pre>
<pre> ... # A whole bunch of awesome perl code,
# omitted for brevity</pre>
<pre> my $forgot = $imap->parameter;
my $forgot2 = $imap->parameter2;</pre>
Note that in these examples I'm using 'parameter' and 'parameter2' as generic parameter names. The IMAPClient object doesn't actually have parameters named 'parameter' and 'parameter2'. On the contrary, the available parameters are:
Authmechanism
Example:
<pre> $imap->Authmechanism("CRAM-MD5");
# or
my $authmech = $imap->Authmechanism();</pre>
If specified, the Authmechanism causes the specified authentication mechanism to be used whenever Mail::IMAPClient would otherwise invoke login. If the value specified for the Authmechanism parameter is not a valid authentication mechanism for your server then you will never ever be able to log in again for the rest of your perl script, probably. So you might want to check, like this:
<pre> my $authmech = "CRAM-MD5";
$imap->has_capability($authmech) and $imap->Authmechanism($authmech);</pre>
Of course if you know your server supports your favorite authentication mechanism then you know, so you can then include your Authmechanism with your new call, as in:
<pre> my $imap = Mail::IMAPClient->new(
User => $user,
Passord => $passord,
Server => $server,
Authmechanism => $authmech,
%etc
);</pre>
If Authmechanism is supplied but Authcallback is not then you had better be supporting one of the authentication mechanisms that Mail::IMAPClient supports ``out of the box'' (such as CRAM-MD5).
Authcallback
Example:
<pre> $imap->Authcallback( \&callback );</pre>
This specifies a default callback to the default authentication mechanism (see Authmechanism, above). Together, these two methods replace automatic calls to login with automatic calls that look like this (sort of):
<pre> $imap->authenticate($imap->Authmechanism,$imap->Authcallback) ;</pre>
If Authmechanism is supplied but Authcallback is not then you had better be supporting one of the authentication mechanisms that Mail::IMAPClient supports ``out of the box'' (such as CRAM-MD5).
Buffer
Example:
<pre> $Buffer = $imap->Buffer();
# or:
$imap->Buffer($new_value);</pre>
The Buffer parameter sets the size of a block of I/O. It is ignored unless Fast_io, below, is set to a true value (the default), or unless you are using the the migrate manpage method. It's value should be the number of bytes to attempt to read in one I/O operation. The default value is 4096.
When using the the migrate manpage method, you can often achieve dramatic improvements in throughput by adjusting this number upward. However, doing so also entails a memory cost, so if set too high you risk losing all the benefits of the the migrate manpage method's chunking algorythm. Your program can thus terminate with an ``out of memory'' error and you'll have no one but yourself to blame.
Note that, as hinted above, the Buffer parameter affects the behavior of the the migrate manpage method regardless of whether you have Fast_io turned on. Believe me, you don't want to go around migrating tons of mail without using buffered I/O!
Clear
Example:
<pre> $Clear = $imap->Clear();
# or:
$imap->Clear($new_value);</pre>
The name of this parameter, for historical reasons, is somewhat misleading. It should be named Wrap, because it specifies how many transactions are stored in the wrapped history buffer. But it didn't always work that way; the buffer used to actually get cleared. The name though remains the same in the interests of backwards compatibility. Also I'm too lazy to change it.
Clear specifies that the object's history buffer should be wrapped after every n transactions, where n is the value specified for the Clear parameter. Calling the eponymous Clear method without an argument will return the current value of the Clear parameter but will not cause clear the history buffer to wrap.
Setting Clear to 0 turns off automatic history buffer wrapping, and setting it to 1 turns off the history buffer facility (except for the last transaction, which cannot be disabled without breaking the IMAPClient module). Setting Clear to 0 will not cause an immediate clearing of the history buffer; setting it to 1 (or any other number) will (except of course for that inevitable last transaction).
The default Clear value is set to five in order to conserve memory.
Debug
Example:
<pre> $Debug = $imap->Debug();
# or:
$imap->Debug($true_or_false);</pre>
Sets the debugging flag to either a true or false value. Can be supplied with the the new manpage method call or separately by calling the Debug object method. Use of this parameter is strongly recommended when debugging scripts and required when reporting bugs.
Debug_fh
Example:
<pre> $Debug_fh = $imap->Debug_fh();
# or:
$imap->Debug_fh($fileHandle);</pre>
Specifies the filehandle to which debugging information should be printed. It can either a filehandle object reference or a filehandle glob. The default is to print debugging info to STDERR.
For example, you can:
<pre> use Mail::IMAPClient;
use IO::File;
# set $user, $pass, and $server here
my $dh = IO::File->new(">debugging.output")
or die "Can't open debugging.output: $!\n";
my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass,
Server=>$server, Debug=> "yes, please",
Debug_fh => $dh
);</pre>
which is the same as:
<pre> use Mail::IMAPClient;
use IO::File;
# set $user, $pass, and $server here
my $imap = Mail::IMAPClient->new( User =>$user,
Password=>$pass,
Server =>$server,
Debug => "yes, please",
Debug_fh=> IO::File->new(">debugging.output") ||
die "Can't open debugging.output: $!\n"
);</pre>
You can also:
<pre> use Mail::IMAPClient;
# set $user, $pass, and $server here
open(DBG,">debugging.output")
or die "Can't open debugging.output: $!\n";
my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass,
Server=>$server, Debug=> 1,
Debug_fh => *DBG
);</pre>
Specifying this parameter is not very useful unless the Debug manpage is set to a true value.
EnableServerResponseInLiteral
Example:
<pre> $EnableServerResponseInLiteral = $imap->EnableServerResponseInLiteral();
# or:
$imap->EnableServerResponseInLiteral($new_value);</pre>
The EnableServerResponseInLiteral parameter tells Mail::IMAPClient to expect server responses to be embedded in literal strings. Usually literal strings contain only message data, not server responses. I have seen at least one IMAP server implementation though that includes the final <tag> OK response in the literal data. If your server does this then your script will hang whenever you try to read literal data, such as message text, or even output from the the folders manpage method if some of your folders have special characters such as double quotes or sometimes spaces in the name.
I am pretty sure this behavior is not RFC2060 compliant so I am dropping it by default. In fact, I encountered the problem a long time ago when still new to IMAP and may have imagined the whole thing. However, if your scripts hang running certain methods you may want to at least try enabling this parameter by passing the eponymous method a true value.
Fast_io
Example:
<pre> $Fast_io = $imap->Fast_io();
# or:
$imap->Fast_io($true_or_false);</pre>
The Fast_io parameter controlls whether or not your Mail::IMAPClient object will attempt to use buffered (i.e. ``Fast'') I/O. It is turned on by default. If you turn it off you will definately slow down your program, often to a painfull degree. However, if you are experience problems you may want to try this just to see if it helps. If it does then that means you have found a bug and should report it immediately (by following the instructions in the section on REPORTING BUGS). Even if it doesn't fix the problem, testing with both Fast_io turned on and with it turned off will often aid in identifying the source of the problem. (If it doesn't help you, it may help me when you report it!)
Lately there have not been any bugs associated with Fast_io so this parameter may become deprecated in the future.
Folder
Example:
<pre> $Folder = $imap->Folder();
# or:
$imap->Folder($new_value);</pre>
The Folder parameter returns the name of the currently-selected folder (in case you forgot). It can also be used to set the name of the currently selected folder, which is completely unnecessary if you used the the select manpage method (or the select manpage's read-only equivalent, the the examine manpage method) to select it.
Note that setting the Folder parameter does not automatically select a new folder; you use the the select manpage or the examine manpage object methods for that. Generally, the Folder parameter should only be queried (by using the no-argument form of the Folder method). You will only need to set the Folder parameter if you use some mysterious technique of your own for selecting a folder, which you probably won't do.
Maxtemperrors
Example:
<pre> $Maxtemperrors = $imap->Maxtemperrors();
# or:
$imap->Maxtemperrors($new_value);</pre>
The Maxtemperrors parameter specifies the number of times a write operation is allowed to fail on a ``Resource Temporarily Available'' error. These errors can occur from time to time if the server is too busy to empty out its read buffer (which is logically the ``other end'' of the client's write buffer). By default, Mail::IMAPClient will retry an unlimited number of times, but you can adjust this behavior by setting Maxtemperrors. Note that after each temporary error, the server will wait for a number of seconds equal to the number of consecutive temporary errors times .25, so very high values for Maxtemperrors can slow you down in a big way if your ``temporary error'' is not all that temporary.
You can set this parameter to ``UNLIMITED'' to ignore ``Resource Temporarily Unavailable'' errors. This is the default.
Password
Example:
<pre> $Password = $imap->Password();
# or:
$imap->Password($new_value);</pre>
Specifies the password to use when logging into the IMAP service on the host specified in the Server parameter as the user specified in the User parameter. Can be supplied with the new method call or separately by calling the Password object method.
If Server, User, and Password are all provided to the the new manpage method, then the newly instantiated object will be connected to the host specified in Server (at either the port specified in Port or the default port 143) and then logged on as the user specified in the User parameter (using the password provided in the Password parameter). See the discussion of the new method, below.
Peek
Example:
<pre> $Peek = $imap->Peek();
# or:
$imap->Peek($true_or_false);</pre>
Setting Peek to a true value will prevent the the body_string manpage, the message_string manpage and the message_to_file manpage methods from automatically setting the \Seen flag. Setting Peek to 0 (zero) will force body_string, message_string, message_to_file, and parse_headers to always set the \Seen flag.
The default is to set the seen flag whenever you fetch the body of a message but not when you just fetch the headers. Passing undef to the eponymous Peek method will reset the Peek parameter to its pristine, default state.
Port
Example:
<pre> $Port = $imap->Port();
# or:
$imap->Port($new_value);</pre>
Specifies the port on which the IMAP server is listening. The default is 143, which is the standard IMAP port. Can be supplied with the the new manpage method call or separately by calling the Port object method.
Prewritemethod
Specifies a method to call if your authentication mechanism requires you to to do pre-write processing of the data sent to the server. If defined, then the Prewritemethod parameter should contain a reference to a subroutine that will do Special Things to data before it is sent to the IMAP server (such as encryption or signing).
This method will be called immediately prior to sending an IMAP client command to the server. Its first argument is a reference to the Mail::IMAPClient object and the second argument is a string containing the command that will be sent to the server. Your Prewritemethod should return a string that has been signed or encrypted or whatever; this returned string is what will actually be sent to the server.
Your Prewritemethod will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the Mail::IMAPClient object itself.
Note that this method should not actually send anything over the socket connection to the server; it merely converts data prior to sending.
If you need a Prewritemethod then you probably need a Readmethod as well.
Ranges
Example:
<pre> $imap->Ranges(1);
# or:
my $search = $imap->search(@search_args);
if ( $imap->Ranges) { # $search is a MessageSet object
print "This is my condensed search result: $search\n";
print "This is every message in the search result: ",
join(",",@$search),"\n;
}</pre>
If set to a true value, then the the search manpage method will return a the Mail::IMAPClient::MessageSet manpage object if called in a scalar context, instead of the array reference that fetch normally returns when called in a scalar context. If set to zero or if undefined, then search will continue to return an array reference when called in scalar context.
This parameter has no affect on the search method when search is called in a list context.
Readmethod
This parameter, if supplied, should contain a reference to a subroutine that will replace sysreads. The subroutine will be passed the following arguments:
<pre>=over 4</pre>
1. imap_object_ref - a reference to the current imap object
2. scalar_ref - a reference to a scalar variable into which data is read. The data place in here should be ``finished data'', so if you are decrypting or removing signatures then be sure to do that before you place data into this buffer.
3. read_length - the number of bytes requested to be read
4. offset - the offset into <code>scalar_ref</code> into which data should be read. If not supplied it should default to zero.
Note that this method completely replaces reads from the connection to the server, so if you define one of these then your subroutine will have to actually do the read. It is for things like this that we have the the Socket manpage parameter and eponymous accessor method.
Your Readmethod will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the Mail::IMAPClient object itself.
If you need a Readmethod then you probably need a Prewritemethod as well.
Server
Example:
<pre> $Server = $imap->Server();
# or:
$imap->Server($hostname);</pre>
Specifies the hostname or IP address of the host running the IMAP server. If provided as part of the the new manpage method call, then the new IMAP object will automatically be connected at the time of instantiation. (See the the new manpage method, below.) Can be supplied with the the new manpage method call or separately by calling the Server object method.
Showcredentials
Normally debugging output will mask the login credentials when the plain text login mechanism is used. Setting Showcredentials to a true value will suppress this, so that you can see the string being passed back and forth during plain text login. Only set this to true when you are debugging problems with the IMAP LOGIN command, and then turn it off right away when you're finished working on that problem.
Example:
<pre> print "This is very risky!\n" if $imap->Showcredentials();
# or:
$imap->Showcredentials(0); # mask credentials again</pre>
Socket
Example:
<pre> $Socket = $imap->Socket();
# or:
$imap->Socket($socket_fh);</pre>
The Socket method can be used to obtain the socket handle of the current connection (say, to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (perhaps an SSL handle, for example).
If you supply a socket handle yourself, either by doing something like:
<pre> $imap=Mail::IMAPClient->new(Socket=>$sock, User => ... );</pre>
or by doing something like:
<pre> $imap=Mail::IMAPClient->new(User => $user, Password => $pass, Server => $host);
# blah blah blah
$imap->Socket($ssl);</pre>
then it will be up to you to establish the connection AND to authenticate, either via the the login manpage method, or the fancier the authenticate manpage, or, since you know so much anyway, by just doing raw I/O against the socket until you're logged in. If you do any of this then you should also set the the State manpage parameter yourself to reflect the current state of the object (i.e. Connected, Authenticated, etc).
Timeout
Example:
<pre> $Timeout = $imap->Timeout();
# or:
$imap->Timeout($new_value);</pre>
Specifies the timeout value in seconds for reads. Specifying a true value for Timeout will prevent Mail::IMAPClient from blocking in a read.
Since timeouts are implemented via the perl select operator, the Timeout parameter may be set to a fractional number of seconds. Not supplying a Timeout, or (re)setting it to zero, disables the timeout feature.
Uid
Example:
<pre> $Uid = $imap->Uid();
# or:
$imap->Uid($true_or_false);</pre>
If Uid is set to a true value (i.e. 1) then the behavior of the the fetch manpage, the search manpage, the copy manpage, and the store manpage methods (and their derivatives) is changed so that arguments that would otherwise be message sequence numbers are treated as message UID's and so that return values (in the case of the the search manpage method and its derivatives) that would normally be message sequence numbers are instead message UID's.
Internally this is implemented as a switch that, if turned on, causes methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH, or UID COPY, respectively. The main difference between message sequence numbers and message UID's is that, according to RFC2060, UID's must not change during a session and should not change between sessions, and must never be reused. Sequence numbers do not have that same guarantee and in fact may be reused right away.
Since foldernames also have a unique identifier (UIDVALIDITY), which is provided when the folder is the select manpageed or the examine manpaged or by doing something like ``$imap->status($folder,''UIDVALIDITY``), it is possible to uniquely identify every message on the server, although normally you won't need to bother.
The methods currently affected by turning on the Uid flag are:
<pre> copy fetch
search store
message_string message_uid
body_string flags
move size
parse_headers thread</pre>
Note that if for some reason you only want the Uid parameter turned on for one command, then you can choose between the following two snippets, which are equivalent:
Example 1:
<pre> $imap->Uid(1);
my @uids = $imap->search('SUBJECT',"Just a silly test"); #
$imap->Uid(0);</pre>
Example 2:
<pre> my @uids;
foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
chomp $r;
$r =~ s/\r$//;
$r =~ s/^\*\s+SEARCH\s+// or next;
push @uids, grep(/\d/,(split(/\s+/,$r)));
}</pre>
In the second example, we used the default method to issue the UID IMAP Client command, being careful to use an all-uppercase method name so as not to inadvertently call the Uid accessor method. Then we parsed out the message UIDs manually, since we don't have the benefit of the built-in the search manpage method doing it for us.
Please be very careful when turning the Uid parameter on and off throughout a script. If you loose track of whether you've got the Uid parameter turned on you might do something sad, like deleting the wrong message. Remember, like all eponymous accessor methods, the Uid method without arguments will return the current value for the Uid parameter, so do yourself a favor and check. The safest approach is probably to turn it on at the beginning (or just let it default to being on) and then leave it on. (Remember that leaving it turned off can lead to problems if changes to a folder's contents cause resequencing.)
By default, the Uid parameter is turned on.
User
Example:
<pre> $User = $imap->User();
# or:
$imap->User($userid);</pre>
Specifies the userid to use when logging into the IMAP service. Can be supplied with the the new manpage method call or separately by calling the User object method.
Parameters can be set during the new manpage method invocation by passing named parameter/value pairs to the method, or later by calling the parameter's eponymous object method.
Status Methods
There are several object methods that return the status of the object. They can be used at any time to check the status of an IMAPClient object, but are particularly useful for determining the cause of failure when a connection and login are attempted as part of a single the new manpage method invocation. The status methods are:
Escaped_results
| Example: |
| |
my @results = $imap->Escaped_results ; |
The Escaped_results method is almost identical to the History method. Unlike the History method, however, server output transmitted literally will be wrapped in double quotes, with all of the parentheses, double quotes, backslashes, newlines, and carrage returns escaped. If called in a scalar context, Escaped_results returns an array reference rather than an array.
Escaped_results is useful if you are retrieving output and processing it manually, and you are depending on the above special characters to delimit the data. It is not useful when retrieving message contents; use message_string or body_string for that.
History
Example:
<pre> my @history = $imap->History;</pre>
The History method is almost identical to the the Results manpage method. Unlike the the Results manpage method, however, the IMAP command that was issued to create the results being returned is not included in the returned results. If called in a scalar context, History returns an array reference rather than an array.
IsUnconnected
returns a true value if the object is currently in an Unconnected state.
IsConnected
returns a true value if the object is currently in either a Connected, Authenticated, or Selected state.
IsAuthenticated
returns a true value if the object is currently in either an Authenticated or Selected state.
IsSelected
returns a true value if the object is currently in a Selected state.
LastError
Internally LastError is implemented just like a parameter (as described in Parameters, above). There is a LastError attribute and an eponymous accessor method which returns the LastError text string describing the last error condition encountered by the server.
Note that some errors are more serious than others, so LastError's value is only meaningful if you encounter an error condition that you don't like. For example, if you use the the exists manpage method to see if a folder exists and the folder does not exist, then an error message will be recorded in LastError even though this is not a particularly serious error. On the other hand, if you didn't use the exists manpage and just tried to the select manpage a non-existing folder, then the select manpage would return <code>undef</code> after setting LastError to something like <code>NO SELECT failed: Can't open mailbox "mailbox": no such mailbox</code>. At this point it would be useful to print out the contents of LastError as you die.
LastIMAPCommand
New in version 2.0.4, LastIMAPCommand returns the exact IMAP command string to be sent to the server. Useful mainly in constructing error messages when LastError just isn't enough.
Report
The Report method returns an array containing a history of the IMAP session up to the point that Report was called. It is primarily meant to assist in debugging but can also be used to retrieve raw output for manual parsing. The value of the Clear parameter controls how many transactions are in the report. (See the discussion of Clear in Parameters, above.)
Results
The Results method returns an array containing the results of one IMAP client command. It accepts one argument, the transaction number of the command whose results are to be returned. If transaction number is unspecified then Results returns the results of the last IMAP client command issued. If called in a scalar context, Results returns an array reference rather than an array.
State
The State method returns a numerical value that indicates the current status of the IMAPClient object. If invoked with an argument, it will set the object's state to that value. If invoked without an argument, it behaves just like the Status manpage, below.
Normally you will not have to invoke this function. An exception is if you are bypassing the Mail::IMAPClient module's the connect manpage and/or the login manpage modules to set up your own connection (say, for example, over a secure socket), in which case you must manually do what the the connect manpage and the login manpage methods would otherwise do for you.
Status
The Status method returns a numerical value that indicates the current status of the IMAPClient object. (Not to be confused with the the status manpage method, all lower-case, which is the implementation of the STATUS IMAP client command.)
Transaction
The Transaction method returns the tag value (or transaction number) of the last IMAP client command.
Undocumented Methods and Subroutines
There are two types of undocumented subroutines and methods. The first are methods that are not documented because they don't exist, even though they work just fine. Some of my favorite Mail::IMAPClient methods don't exist but I use them all the time anyway. You can too, assuming you have your copy of RFC2060 and its extension RFC's handy. (By the way, you do have them handy because I gave them to you. They're bundled with the Mail::IMAPClient distribution in the docs/ subdirectory.) You should feel free to use any of these undocumented methods.
These undocumented methods all use what this document refers to as the ``default method''. See Other IMAP Client Commands and the Default Object Method, above, for more information on the default method.
There are also some undocumented methods and subroutines that actually do exist. Don't use these! If they aren't documented it's for a reason. They are either experimental, or intended for use by other Mail::IMAPClient methods only, or deprecated, or broken, or all or none of the above. In no cases can you write programs that use these methods and assume that these programs will work with the next version of Mail::IMAPClient. I never try to make these undocumented methods and subroutines backwards compatible because they aren't part of the documented API.
Occasionally I will add a method and forget to document it; in that case it's a bug and you should report it. (See REPORTING BUGS, below.) It is sometimes hard to tell the difference; if in doubt you may submit a bug report and see what happens! However, don't bothering submitting bug reports for missing documentation for any method or subroutine that begins with an underscore (_) character. These methods are always private and will never be part of the documented interface.
REPORTING BUGS
Please feel free to e-mail the author at <code>bug-Mail-IMAPClient@rt.cpan.org</code> if you encounter any strange behaviors. Don't worry about hurting my feelings or sounding like a whiner or anything like that; if there's a problem with this module you'll be doing me a favor by reporting it. However, I probably won't be able to do much about it if you don't include enough information, so please read and follow these instructions carefully.
When reporting a bug, please be sure to include the following:
- As much information about your environment as possible. I especially need to know which version of Mail::IMAPClient you are running and the type/version of IMAP server to which you are connecting. Your OS and perl verions would be helpful too.
- As detailed a description of the problem as possible. (What are you doing? What happens? Have you found a work-around?)
- An example script that demonstrates the problem (preferably with as few lines of code as possible!) and which calls the Mail::IMAPClient's the new manpage method with the the Debug manpage parameter set to ``1''. (If this generates a ridiculous amount of output and you're sure you know where the problem is, you can create your object with debugging turned off and then turn it on later, just before you issue the commands that recreate the problem. On the other hand, if you can do this you can probably also reduce the program rather than reducing the output, and this would be the best way to go under most circumstances.)
- Output from the example script when it's running with the Debug parameter turned on. You can edit the output to remove (or preferably to ``X'' out) sensitive data, such as hostnames, user names, and passwords, but PLEASE do not remove the text that identifies the TYPE of IMAP server to which you are connecting. Note that in most versions of Mail::IMAPClient, debugging does not print out the user or password from the login command line. However, if you use some other means of authenticating then you may need to edit the debugging output with an eye to security.
- If something worked in a previous release and doesn't work now, please tell me which release did work. You don't have to test every intervening release; just let me know it worked in version x but doesn't work in version (x+n) or whatever.
- Don't be surprised if I come back asking for a trace of the problem. To provide this, you should create a file called .perldb in your current working directory and include the following line of text in that file:
<code>&parse_options("NonStop=1 LineInfo=mail_imapclient_db.out");</code>
For your debugging convenience, a sample .perldb file, which was randomly assigned the name sample.perldb, is provided in the distribution.
Next, without changing your working directory, debug the example script like this: <code>perl -d example_script.pl [ args ]</code>
Note that in these examples, the script that demonstrates your problem is named ``example_script.pl'' and the trace output will be saved in ``mail_imapclient_db.out''. You should either change these values to suit your needs, or change your needs to suit these values.
Bug reports should be mailed to:
<pre> bug-Mail-IMAPClient@rt.cpan.org</pre>
Please remember to place a SHORT description of the problem in the subject of the message. Please try to be a bit specific; things like ``Bug in Mail::IMAPClient'' or ``Computer Problem'' won't exactly expedite things on my end.
REPORTING THINGS THAT ARE NOT BUGS
If you have suggestions for extending this functionality of this module, or if you have a question and you can't find an answer in any of the documentation (including the RFC's, which are included in this distribution for a reason), then you can e-mail me at the following address:
<pre> DJKERNEN@cpan.org</pre>
Please note that this address is for questions, suggestions, and other comments about Mail::IMAPClient. It's not for reporting bugs, it's not for general correspondence, and it's especially not for selling porn, mortgages, Viagra, penis enlargment pills, DVD copying software, or anything else.
AUTHOR
<pre> David J. Kernen
The Kernen Consulting Group, Inc
DJKERNEN@cpan.org</pre>
COPYRIGHT
<pre> Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
All rights reserved.</pre>
This program is free software; you can redistribute it and/or modify it under the terms of either:
<dl>
a) the ``Artistic License'' which comes with this Kit, orb) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.</dl>
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. All your base are belong to us.
|
Mail::IMAPClient - An IMAP Client API
|
Комментарии