Author: as
Date: Wed Jul 4 11:29:52 2007
New Revision: 5681
Log:
- Some documentation updates for the IMAP transport.
Modified:
trunk/Mail/docs/tutorial/tutorial_imap.php
trunk/Mail/docs/tutorial/tutorial_imap_extra.php
trunk/Mail/src/transports/imap/imap_set.php
trunk/Mail/src/transports/imap/imap_transport.php
Modified: trunk/Mail/docs/tutorial/tutorial_imap.php
==============================================================================
--- trunk/Mail/docs/tutorial/tutorial_imap.php [iso-8859-1] (original)
+++ trunk/Mail/docs/tutorial/tutorial_imap.php [iso-8859-1] Wed Jul 4 11:29:52
2007
@@ -40,10 +40,14 @@
// See the function description for a list of supported flags
$set = $imap->fetchByFlag( "DELETED" );
- // Fetch a range of messages sorted by a criteria
+ // Fetch a range of messages sorted by Date
// Use this to page through a mailbox
// See the function description for a list of criterias and for how to
sort ascending or descending
$set = $imap->sortFromOffset( 1, 10, "Date" );
+
+ // Sort the specified messages by Date
+ // See the function description for a list of criterias and for how to
sort ascending or descending
+ $set = $imap->sortMessages( "1,2,3,4,5", "Date" );
// Fetch messages which match the specified criteria.
// See the section 6.4.4. of RFC 1730 or 2060 for a list of criterias
Modified: trunk/Mail/docs/tutorial/tutorial_imap_extra.php
==============================================================================
--- trunk/Mail/docs/tutorial/tutorial_imap_extra.php [iso-8859-1] (original)
+++ trunk/Mail/docs/tutorial/tutorial_imap_extra.php [iso-8859-1] Wed Jul 4
11:29:52 2007
@@ -43,10 +43,4 @@
// Use this with a "Sent" or "Drafts" mailbox
$imap->append( "Sent", $mail );
-// Create a new mail parser object
-$parser = new ezcMailParser();
-
-// Parse the set of messages retrieved from the server earlier
-$mail = $parser->parseMail( $set );
-
?>
Modified: trunk/Mail/src/transports/imap/imap_set.php
==============================================================================
--- trunk/Mail/src/transports/imap/imap_set.php [iso-8859-1] (original)
+++ trunk/Mail/src/transports/imap/imap_set.php [iso-8859-1] Wed Jul 4
11:29:52 2007
@@ -1,6 +1,6 @@
<?php
/**
- * File containing the ezcMailImapSet class
+ * File containing the ezcMailImapSet class.
*
* @package Mail
* @version //autogen//
@@ -10,9 +10,9 @@
/**
* ezcMailImapSet is an internal class that fetches a series of mail
- * from the imap server.
+ * from the IMAP server.
*
- * The imap set works on an existing connection and a list of the messages that
+ * The IMAP set works on an existing connection and a list of the messages that
* the user wants to fetch. The user must accept all the data for each mail for
* correct behaviour.
*
@@ -70,16 +70,15 @@
private $currentTag = 'A0000';
/**
- * Constructs a new imap parser set that will fetch the messages with the
- * id's.
- *
- * $connection must hold a valid connection to a imap server that is ready
to retrieve
- * the messages.
+ * Constructs a new imap parser set that will fetch the messages with the
IDs.
+ *
+ * $connection must hold a valid connection to a imap server that is ready
+ * to retrieve the messages.
*
* If $deleteFromServer is set to true the messages will be deleted after
retrieval.
*
* @throws ezcMailTransportException
- * if the server send a negative response.
+ * if the server send a negative response
* @param ezcMailTransportConnection $connection
* @param array(int) $messages
* @param bool $deleteFromServer
@@ -152,7 +151,7 @@
* False is returned if there are no more mail in the set.
*
* @throws ezcMailTransportException
- * if the server sent a negative response.
+ * if the server sent a negative response
* @return bool
*/
public function nextMail()
@@ -198,24 +197,30 @@
}
/**
- * Reads the responses from the server until encountering $tag.
- *
- * In IMAP, each command sent by the client is prepended with a
- * alphanumeric tag like 'A1234'. The server sends the response
- * to the client command as lines, and the last line in the response
- * is prepended with the same tag, and it contains the status of
- * the command completion ('OK', 'NO' or 'BAD').
- * Sometimes the server sends alerts and response lines from other
- * commands before sending the tagged line, so this method just
- * reads all the responses until it encountering $tag.
- * It returns the tagged line to be processed by the calling method.
- * If $response is specified, then it will not read the response
- * from the server before searching for $tag in $response.
- *
- * @param string $tag
- * @param string $response
- * @return string
- */
+ * Reads the responses from the server until encountering $tag.
+ *
+ * In IMAP, each command sent by the client is prepended with a
+ * alphanumeric tag like 'A1234'. The server sends the response
+ * to the client command as lines, and the last line in the response
+ * is prepended with the same tag, and it contains the status of
+ * the command completion ('OK', 'NO' or 'BAD').
+ *
+ * Sometimes the server sends alerts and response lines from other
+ * commands before sending the tagged line, so this method just
+ * reads all the responses until it encounters $tag.
+ *
+ * It returns the tagged line to be processed by the calling method.
+ *
+ * If $response is specified, then it will not read the response
+ * from the server before searching for $tag in $response.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established.
+ *
+ * @param string $tag
+ * @param string $response
+ * @return string
+ */
private function getResponse( $tag = null, $response = null )
{
if ( is_null( $response ) )
@@ -235,19 +240,24 @@
}
/**
- * Generates the next IMAP tag to prepend to client commands.
- *
- * The structure of the IMAP tag is Axxxx, where
- * A is a letter (uppercase for conformity, it can be lowercase also)
- * x is a digit from 0 to 9
- * example of generated tag: T5439
- * It uses the class variable [EMAIL PROTECTED] $this->currentTag}.
- * Everytime it is called, the tag increases by 1.
- * If it reaches the last tag, it wraps around to the first tag.
- * By default, the first tag is A0001.
- *
- * @return string
- */
+ * Generates the next IMAP tag to prepend to client commands.
+ *
+ * The structure of the IMAP tag is Axxxx, where:
+ * - A is a letter (uppercase for conformity)
+ * - x is a digit from 0 to 9
+ *
+ * example of generated tag: T5439
+ *
+ * It uses the class variable $this->currentTag.
+ *
+ * Everytime it is called, the tag increases by 1.
+ *
+ * If it reaches the last tag, it wraps around to the first tag.
+ *
+ * By default, the first generated tag is A0001.
+ *
+ * @return string
+ */
private function getNextTag()
{
$tagLetter = substr( $this->currentTag, 0, 1 );
@@ -268,7 +278,7 @@
}
/**
- * Returns whether the set has mails
+ * Returns whether the set has mails.
*
* @return bool
*/
@@ -280,7 +290,7 @@
/**
* Returns message numbers for current set.
*
- * @return array(int=>int)
+ * @return array(int)
*/
public function getMessageNumbers()
{
Modified: trunk/Mail/src/transports/imap/imap_transport.php
==============================================================================
--- trunk/Mail/src/transports/imap/imap_transport.php [iso-8859-1] (original)
+++ trunk/Mail/src/transports/imap/imap_transport.php [iso-8859-1] Wed Jul 4
11:29:52 2007
@@ -1,6 +1,6 @@
<?php
/**
- * File containing the ezcMailImapTransport class
+ * File containing the ezcMailImapTransport class.
*
* @package Mail
* @version //autogen//
@@ -9,11 +9,98 @@
*/
/**
- * ezcMailImapTransport implements IMAP for mail retrieval.
+ * The class ezcMailImapTransport implements functionality for handling IMAP
+ * mail servers.
*
- * The implementation supports most of the basic commands specified in
- * http://www.faqs.org/rfcs/rfc1730.html (IMAP4) and
- * http://www.faqs.org/rfcs/rfc2060.html (IMAP4rev1)
+ * The implementation supports most of the commands specified in:
+ * - [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc1730.html} (IMAP4)
+ * - [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc2060.html} (IMAP4rev1)
+ *
+ * Each user account on the IMAP server has it's own folders (mailboxes).
+ * Mailboxes can be created, renamed or deleted. All accounts have a special
+ * mailbox called Inbox which cannot be deleted or renamed.
+ *
+ * Messages are organized in mailboxes, and are identified by a message number
+ * (which can change over time) and a unique ID (which does not change under
+ * normal circumstances). Commands which handle messages usually use message
+ * numbers to identify messages.
+ *
+ * Messages are marked by certain flags (SEEN, DRAFT, etc). Deleting a message
+ * actually sets it's DELETED flag, and a later call to [EMAIL PROTECTED]
expunge()} will
+ * delete all the messages marked with the DELETED flag.
+ *
+ * Most IMAP commands require that a connection is established and a user
+ * is authenticated. Certain commands require in addition that a mailbox is
+ * selected.
+ *
+ * The IMAP transport class allows developers to interface with an IMAP server.
+ *
+ * Basic commands:
+ * - connect to an IMAP server ([EMAIL PROTECTED] __construct()})
+ * - authenticate a user with a username and password ([EMAIL PROTECTED]
authenticate()})
+ * - select a mailbox ([EMAIL PROTECTED] selectMailbox()})
+ * - disconnect from an IMAP server ([EMAIL PROTECTED] disconnect()})
+ *
+ * Work with mailboxes:
+ * - get the list of mailboxes of the user ([EMAIL PROTECTED]
listMailboxes()})
+ * - create a mailbox ([EMAIL PROTECTED] createMailbox()}
+ * - rename a mailbox ([EMAIL PROTECTED] renameMailbox()}
+ * - delete a mailbox ([EMAIL PROTECTED] deleteMailbox()}
+ * - append a message to a mailbox ([EMAIL PROTECTED] append()}
+ * - select a mailbox ([EMAIL PROTECTED] selectMailbox()})
+ * - get the status of messages in the current mailbox ([EMAIL PROTECTED]
status()})
+ * - get the number of messages with a certain flag ([EMAIL PROTECTED]
countByFlag()}
+ *
+ * Work with message numbers (on the currently selected mailbox):
+ * - get the message numbers and sizes of all the messages ([EMAIL PROTECTED]
listMessages()})
+ * - get the message numbers and IDs of all the messages ([EMAIL PROTECTED]
listUniqueIdentifiers()})
+ * - get the message numbers of a range of sorted messages ([EMAIL PROTECTED]
sortMessages()})
+ * - get the headers of a certain message ([EMAIL PROTECTED] top()})
+ * - copy messages to another mailbox ([EMAIL PROTECTED] copyMessages()})
+ * - delete a message ([EMAIL PROTECTED] delete()} and [EMAIL PROTECTED]
expunge()})
+ *
+ * Work with ezcMailImapSet sets (parseable with ezcMailParser) (on the
+ * currently selected mailbox):
+ * - create a set from all messages ([EMAIL PROTECTED] fetchAll()})
+ * - create a set from a certain message ([EMAIL PROTECTED]
fetchByMessageNr()})
+ * - create a set from a range of messages ([EMAIL PROTECTED]
fetchFromOffset()})
+ * - create a set from messages with a certain flag ([EMAIL PROTECTED]
fetchByFlag()})
+ * - create a set from a sorted range of messages ([EMAIL PROTECTED]
sortFromOffset()})
+ * - create a set from a sorted list of messages ([EMAIL PROTECTED]
sortMessages()})
+ * - create a set from a free-form search ([EMAIL PROTECTED] searchMailbox()})
+ *
+ * Work with flags (on the currently selected mailbox):
+ * - get the flags of the specified messages ([EMAIL PROTECTED] fetchFlags()})
+ * - set a flag on the specified messages ([EMAIL PROTECTED] setFlag()})
+ * - clear a flag from the specified messages ([EMAIL PROTECTED] clearFlag()})
+ *
+ * Miscellaneous commands:
+ * - get the capabilities of the IMAP server ([EMAIL PROTECTED] capability()})
+ * - get the hierarchy delimiter (useful for nested mailboxes) ([EMAIL
PROTECTED] getHierarchyDelimiter()})
+ * - issue a NOOP command to keep the connection alive ([EMAIL PROTECTED]
noop()})
+ *
+ * The usual operation with an IMAP server is illustrated by this example:
+ * <code>
+ * // Create a new IMAP transport object by specifying the server name,
optional port
+ * // and optional SSL mode
+ * $imap = new ezcMailImapTransport( 'imap.example.com', null, array( 'ssl' =>
true ) );
+ *
+ * // Authenticate to the IMAP server
+ * $imap->authenticate( 'username', 'password' );
+ *
+ * // Select a mailbox (here 'Inbox')
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * // issue commands to the IMAP server
+ * // for example get the number of RECENT messages
+ * $recent = $imap->countByFlag( 'RECENT' );
+ *
+ * // see the above list of commands or consult the online documentation for
+ * // the full list of commands you can issue to an IMAP server and examples
+ *
+ * // disconnect from the IMAP server
+ * $imap->disconnect();
+ * </code>
*
* @todo ignore messages of a certain size?
* @todo // support for signing?
@@ -114,11 +201,13 @@
/**
* Basic flags are used by [EMAIL PROTECTED] setFlag()} and [EMAIL
PROTECTED] clearFlag()}
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message has marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - SEEN Message has been read
+ *
+ * Basic flags:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - SEEN - message has been read
*
* @var array(string)
*/
@@ -126,16 +215,26 @@
/**
* Extended flags are used by [EMAIL PROTECTED] searchByFlag()}
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message has marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - RECENT Message is recent (cannot be set)
- * - SEEN Message has been read
- * - UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
- * Opposites of the above flags
- * - NEW Equivalent to RECENT + UNSEEN
- * - ALL All the messages
+ *
+ * Basic flags:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - RECENT - message is recent
+ * - SEEN - message has been read
+ *
+ * Opposites of the above flags:
+ * - UNANSWERED
+ * - UNDELETED
+ * - UNDRAFT
+ * - UNFLAGGED
+ * - OLD
+ * - UNSEEN
+ *
+ * Composite flags:
+ * - NEW - equivalent to RECENT + UNSEEN
+ * - ALL - all the messages
*
* @var array(string)
*/
@@ -168,14 +267,14 @@
protected $selectedMailbox = null;
/**
- * The connection to the IMAP server.
+ * Holds the connection to the IMAP server.
*
* @var ezcMailTransportConnection
*/
protected $connection = null;
/**
- * Options for an IMAP transport connection.
+ * Holds the options for an IMAP transport connection.
*
* @var ezcMailImapTransportOptions
*/
@@ -188,7 +287,17 @@
* 993 (for SSL connections) or 143 (for plain connections). Use the
$options
* parameter to specify an SSL connection.
*
- * See [EMAIL PROTECTED] ezcMailImapTransportOptions} for options you can
specify for IMAP.
+ * See ezcMailImapTransportOptions for options you can specify for
+ * IMAP.
+ *
+ * Example of creating an IMAP transport:
+ * <code>
+ * // replace with your IMAP server address
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ *
+ * // if you want to use SSL:
+ * $imap = new ezcMailImapTransport( 'imap.example.com', null, array(
'ssl' => true ) );
+ * </code>
*
* @throws ezcMailTransportException
* if it was not possible to connect to the server
@@ -230,7 +339,7 @@
}
/**
- * Sets the property $name to $value.
+ * Sets the value of the property $name to $value.
*
* @throws ezcBasePropertyNotFoundException
* if the property $name does not exist
@@ -321,14 +430,22 @@
*
* This method should be called directly after the construction of this
* object.
- * If authentication does not succeed, an ezcMailTransportException is
- * thrown.
- * If the server is waiting for authentication process to respond, the
+ *
+ * If the server is waiting for the authentication process to respond, the
* connection with the IMAP server will be closed, and false is returned,
* and it is the application's task to reconnect and reauthenticate.
*
- * @throws ezcMailTransportException
- * if there was no connection to the server
+ * Example of creating an IMAP transport and authenticating:
+ * <code>
+ * // replace with your IMAP server address
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ *
+ * // replace the values with your username and password for the IMAP
server
+ * $imap->authenticate( 'username', 'password' );
+ * </code>
+ *
+ * @throws ezcMailTransportException
+ * if already authenticated
* or if the provided username/password combination did not work
* @param string $user
* @param string $password
@@ -368,26 +485,37 @@
}
/**
- * Lists the available mailboxes on the IMAP server.
- *
- * Before listing the mailboxes, the connection state ($state) must
- * be at least [EMAIL PROTECTED] STATE_AUTHENTICATED} or [EMAIL PROTECTED]
STATE_SELECTED} or
- * [EMAIL PROTECTED] STATE_SELECTED_READONLY}.
+ * Returns an array with the names of the available mailboxes for the user
+ * currently authenticated on the IMAP server.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
*
* For more information about $reference and $mailbox, consult
- * the IMAP RFC document (http://www.faqs.org/rfcs/rfc1730.html).
+ * the IMAP RFCs documents ([EMAIL PROTECTED]
http://www.faqs.org/rfcs/rfc1730.html}
+ * or [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc2060.html}, section
7.2.2.).
+ *
* By default, $reference is "" and $mailbox is "*".
+ *
* The array returned contains the mailboxes available for the connected
* user on this IMAP server. Inbox is a special mailbox, and it can be
* specified upper-case or lower-case or mixed-case. The other mailboxes
- * should be specified as they are (to the selectMailbox() method).
+ * should be specified as they are (to the [EMAIL PROTECTED]
selectMailbox()} method).
+ *
+ * Example of listing mailboxes:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ *
+ * $mailboxes = $imap->listMailboxes();
+ * </code>
*
* @throws ezcMailMailTransportException
* if $state is not accepted
* or if the server sent a negative response
* @param string $reference
* @param string $mailbox
- * @return array(int=>string)
+ * @return array(string)
*/
public function listMailboxes( $reference = '', $mailbox = '*' )
{
@@ -428,23 +556,23 @@
* Returns the hierarchy delimiter of the IMAP server, useful for handling
* nested IMAP folders.
*
- * Example:
- * <code>
- * $imap = new ezcMailImapTransport( 'imap.example.com' );
- * $imap->authenticate( 'username', 'password' );
- * $delimiter = $imap->getDelimiter();
- * </code>
- *
- * After running the above code, $delimiter should be something like "/".
- *
- * Before returning the hierarchy delimiter, the connection state ($state)
- * must be at least [EMAIL PROTECTED] STATE_AUTHENTICATED} or [EMAIL
PROTECTED] STATE_SELECTED}
- * or [EMAIL PROTECTED] STATE_SELECTED_READONLY}.
- *
* For more information about the hierarchy delimiter, consult the IMAP
RFCs
* [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc1730.html} or
* [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc2060.html}, section 6.3.8.
*
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
+ *
+ * Example of returning the hierarchy delimiter:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ *
+ * $delimiter = $imap->getDelimiter();
+ * </code>
+ *
+ * After running the above code, $delimiter should be something like "/".
+ *
* @throws ezcMailMailTransportException
* if $state is not accepted
* or if the server sent a negative response
@@ -484,18 +612,24 @@
}
/**
- * Selects the mailbox $mailbox.
+ * Selects the mailbox $mailbox, which will be the active mailbox for the
+ * subsequent commands until it is changed.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
+ *
+ * Inbox is a special mailbox and can be specified with any case.
*
* This method should be called after authentication, and before fetching
* any messages.
- * Before selecting the mailbox, the connection state ($state) must
- * be at least [EMAIL PROTECTED] STATE_AUTHENTICATED}, [EMAIL PROTECTED]
STATE_SELECTED} or
- * or [EMAIL PROTECTED] STATE_SELECTED_READONLY}.
- * If the selecting of the mailbox fails (with "NO" or "BAD" response
- * from the server), $state revert to STATE_AUTHENTICATED.
- * After successfully selecting a mailbox, $state will be STATE_SELECTED
- * or STATE_SELECTED_READONLY.
- * Inbox is a special mailbox and can always be specified.
+ *
+ * Example of selecting a mailbox:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ *
+ * $imap->selectMailbox( 'Reports 2006' );
+ * </code>
*
* @throws ezcMailMailTransportException
* if $state is not accepted
@@ -513,6 +647,9 @@
}
$tag = $this->getNextTag();
+
+ // if the mailbox selection will be successful, $state will be
STATE_SELECTED
+ // or STATE_SELECTED_READONLY, depending on the $readOnly parameter
if ( $readOnly !== true )
{
$this->connection->sendData( "{$tag} SELECT \"{$mailbox}\"" );
@@ -523,6 +660,9 @@
$this->connection->sendData( "{$tag} EXAMINE \"{$mailbox}\"" );
$state = self::STATE_SELECTED_READONLY;
}
+
+ // if the selecting of the mailbox fails (with "NO" or "BAD" response
+ // from the server), $state reverts to STATE_AUTHENTICATED
$response = trim( $this->getResponse( $tag ) );
if ( $this->responseType( $response ) == self::RESPONSE_OK )
{
@@ -539,6 +679,11 @@
/**
* Creates the mailbox $mailbox.
+ *
+ * Inbox cannot be created.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
*
* @throws ezcMailTransportException
* if $state is not accepted
@@ -570,6 +715,9 @@
*
* Inbox cannot be renamed.
*
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
+ *
* @throws ezcMailTransportException
* if $state is not accepted
* or if trying to rename the currently selected mailbox
@@ -605,7 +753,10 @@
/**
* Deletes the mailbox $mailbox.
*
- * Inbox cannot be deleted.
+ * Inbox and the the currently selected mailbox cannot be deleted.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
*
* @throws ezcMailTransportException
* if $state is not accepted
@@ -639,12 +790,29 @@
}
/**
- * Copies message(s) from the selected mailbox to mailbox $destination.
+ * Copies message(s) from the currently selected mailbox to mailbox
+ * $destination.
*
* $messages can be:
- * - a single message number (eg: 1)
- * - a message range (eg. 1:4)
- * - a message list (eg. 1,2,4)
+ * - a single message number (eg: '1')
+ * - a message range (eg. '1:4')
+ * - a message list (eg. '1,2,4')
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected (the mailbox from which messages will be copied).
+ *
+ * Example of copying 3 messages to a mailbox:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $imap->copyMessages( '1,2,4', 'Reports 2006' );
+ * </code>
+ *
+ * The above code will copy the messages with numbers 1, 2 and 4 from Inbox
+ * to Reports 2006.
*
* @throws ezcMailTransportException
* if $state is not accepted
@@ -675,11 +843,25 @@
/**
* Returns a list of the not deleted messages in the current mailbox.
*
- * It returns only the messages with the flag \Deleted not set.
- * The format of the returned array is array(message_id => size).
- * Eg: ( 2 => 1700, 5 => 1450, 6 => 21043 )
+ * It returns only the messages with the flag DELETED not set.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * The format of the returned array is
+ * <code>
+ * array( message_id => size );
+ * </code>
+ *
+ * Example:
+ * <code>
+ * array( 2 => 1700, 5 => 1450, 6 => 21043 );
+ * </code>
+ *
* If $contentType is set, it returns only the messages with
* $contentType in the Content-Type header.
+ *
* For example $contentType can be "multipart/mixed" to return only the
* messages with attachments.
*
@@ -687,7 +869,7 @@
* if a mailbox is not selected
* or if the server sent a negative response
* @param string $contentType
- * @return array(int=>int)
+ * @return array(int)
*/
public function listMessages( $contentType = null )
{
@@ -753,13 +935,29 @@
}
/**
- * Returns information about messages in the selected mailbox.
- *
- * The information returned through parameters is:
- * - $numMessages = number of not deleted messages in the selected mailbox
- * - $sizeMessages = sum of the not deleted messages sizes
- * - $recent = number of recent and not deleted messages
- * - $unseen = number of unseen and not deleted messages
+ * Returns information about the messages in the current mailbox.
+ *
+ * The information returned through the parameters is:
+ * - $numMessages = number of not deleted messages in the selected mailbox
+ * - $sizeMessages = sum of the not deleted messages sizes
+ * - $recent = number of recent and not deleted messages
+ * - $unseen = number of unseen and not deleted messages
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example of returning the status of the currently selected mailbox:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $imap->status( $numMessages, $sizeMessages, $recent, $unseen );
+ * </code>
+ *
+ * After running the above code, $numMessages, $sizeMessages, $recent
+ * and $unseen will be populated with values.
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -789,12 +987,17 @@
}
/**
- * Deletes the message with the message number $msgNum from the server.
- *
- * The message number must be a valid identifier fetched with e.g.
- * listMessages().
- * The message is not physically deleted, but has its \Deleted flag set,
- * and can be later undeleted by clearing its \Deleted flag
+ * Deletes the message with the message number $msgNum from the current
mailbox.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * The message number $msgNum must be a valid identifier fetched with e.g.
+ * [EMAIL PROTECTED] listMessages()}.
+ *
+ * The message is not physically deleted, but has its DELETED flag set,
+ * and can be later undeleted by clearing its DELETED flag with
* [EMAIL PROTECTED] clearFlag()}.
*
* @throws ezcMailTransportException
@@ -823,10 +1026,40 @@
/**
* Returns the headers and the first characters from message $msgNum,
- * without setting the \Seen flag.
+ * without setting the SEEN flag.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
*
* If the command failed or if it was not supported by the server an empty
* string is returned.
+ *
+ * This method is useful for retrieving the headers of messages from the
+ * mailbox as strings, which can be later parsed with ezcMailParser
+ * and ezcMailVariableSet. In this way the retrieval of the full
+ * messages from the server is avoided when building a list of messages.
+ *
+ * Example of listing the mail headers of all the messages in the current
+ * mailbox:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $parser = new ezcMailParser();
+ * $messages = $imap->listMessages();
+ * foreach ( $messages as $messageNr => $size )
+ * {
+ * $set = new ezcMailVariableSet( $imap->top( $messageNr ) );
+ * $mail = $parser->parseMail( $set );
+ * $mail = $mail[0];
+ * echo "From: {$mail->from}, Subject: {$mail->subject}, Size:
{$size}\n";
+ * }
+ * </code>
+ *
+ * For a more advanced example see the "Mail listing example" in the online
+ * documentation.
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -881,16 +1114,28 @@
}
/**
- * Returns the unique identifiers messages on the IMAP server.
- *
- * You can fetch the unique identifier for a specific message only by
+ * Returns the unique identifiers for the messages from the current
mailbox.
+ *
+ * You can fetch the unique identifier for a specific message by
* providing the $msgNum parameter.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
*
* The unique identifier can be used to recognize mail from servers
* between requests. In contrast to the message numbers the unique
- * numbers assigned to an email never changes.
- *
- * The format of the returned array is array(message_num=>unique_id)
+ * numbers assigned to an email usually never changes.
+ *
+ * The format of the returned array is:
+ * <code>
+ * array( message_num => unique_id );
+ * </code>
+ *
+ * Example:
+ * <code>
+ * array( 1 => 216, 2 => 217, 3 => 218, 4 => 219 );
+ * </code>
*
* @todo add UIVALIDITY value to UID (like in POP3) (if necessary).
*
@@ -898,7 +1143,7 @@
* if a mailbox is not selected
* or if the server sent a negative response
* @param int $msgNum
- * @return array(int=>string)
+ * @return array(string)
*/
public function listUniqueIdentifiers( $msgNum = null )
{
@@ -949,10 +1194,33 @@
}
/**
- * Returns a parserset with all the messages on the server.
- *
- * If $deleteFromServer is set to true the mail will be removed from the
- * server after retrieval. If not it will be left.
+ * Returns an ezcMailImapSet with all the messages from the current
mailbox.
+ *
+ * If $deleteFromServer is set to true the mail will be marked for deletion
+ * after retrieval. If not it will be left intact.
+ *
+ * The set returned can be parsed with ezcMailParser.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $set = $imap->fetchAll();
+ *
+ * // parse $set with ezcMailParser
+ * $parser = new ezcMailParser();
+ * $mails = $parser->parseMail( $set );
+ * foreach ( $mails as $mail )
+ * {
+ * // process $mail which is an ezcMail object
+ * }
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -968,12 +1236,28 @@
/**
* Returns an ezcMailImapSet containing only the $number -th message in
- * the mailbox.
- *
- * If $deleteFromServer is set to true the mail will be removed from the
- * server after retrieval. If not it will be left.
+ * the current mailbox.
+ *
+ * If $deleteFromServer is set to true the mail will be marked for deletion
+ * after retrieval. If not it will be left intact.
+ *
* Note: for IMAP the first message is 1 (so for $number = 0 an exception
* will be thrown).
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $set = $imap->fetchByMessageNr( 1 );
+ *
+ * // $set can be parsed with ezcMailParser
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -998,11 +1282,27 @@
}
/**
- * Returns an ezcMailImapSet with $count messages starting from $offset.
+ * Returns an ezcMailImapSet with $count messages starting from $offset
from
+ * the current mailbox.
*
* Fetches $count messages starting from the $offset and returns them as a
* ezcMailImapSet. If $count is not specified or if it is 0, it fetches
* all messages starting from the $offset.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'Inbox' );
+ *
+ * $set = $imap->fetchFromOffset( 1, 10 );
+ *
+ * // $set can be parsed with ezcMailParser
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1040,7 +1340,7 @@
/**
* Returns an ezcMailImapSet containing the messages which match the
- * provided $criteria.
+ * provided $criteria from the current mailbox.
*
* See [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc1730.html} - 6.4.4.
(or
* [EMAIL PROTECTED] http://www.faqs.org/rfcs/rfc1730.html} - 6.4.4.) for
criterias
@@ -1050,6 +1350,10 @@
* If $criteria is null or empty then it will default to 'ALL' (returns all
* messages in the mailbox).
*
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
* Examples:
* <code>
* $imap = new ezcMailImapTransport( 'imap.example.com' );
@@ -1066,6 +1370,8 @@
* // return an ezcMailImapSet containing messages flagged as 'SEEN' and
* // with 'release' in their Subject
* $set = $imap->searchMailbox( 'SEEN SUBJECT "release"' );
+ *
+ * // $set can be parsed with ezcMailParser
* </code>
*
* @throws ezcMailTransportException
@@ -1112,12 +1418,32 @@
}
/**
- * Fetches $count messages from $offset sorted by $sortCriteria.
+ * Returns an ezcMailImapSet containing $count messages starting from
$offset
+ * sorted by $sortCriteria from the current mailbox.
+ *
+ * It is useful for paging through a mailbox.
*
* Fetches $count messages starting from the $offset and returns them as a
* ezcMailImapSet. If $count is is 0, it fetches all messages starting from
* the $offset.
- * $sortCriteria is an email header like: Subject, To, From, Date, Sender.
+ *
+ * $sortCriteria is an email header like: Subject, To, From, Date, Sender,
etc.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * // Fetch a range of messages sorted by Date
+ * $set = $imap->sortFromOffset( 1, 10, "Date" );
+ *
+ * // $set can be parsed with ezcMailParser
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1158,17 +1484,37 @@
}
/**
- * Fetches messages $messages sorted by $sortCriteria.
+ * Returns an ezcMailImapSet containing messages $messages sorted by
+ * $sortCriteria from the current mailbox.
*
* $messages is an array of message numbers, for example:
- * array( 1, 2, 4 );
- * $sortCriteria is an email header like: Subject, To, From, Date, Sender.
+ * <code>
+ * array( 1, 2, 4 );
+ * </code>
+ *
+ * $sortCriteria is an email header like: Subject, To, From, Date, Sender,
etc.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * // Fetch the list of messages sorted by Date
+ * $set = $imap->sortMessages( 1, 10, "Date" );
+ *
+ * // $set can be parsed with ezcMailParser
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
* or if the server sent a negative response
* or if array $messages is empty
- * @param array(int=>int) $messages
+ * @param array(int) $messages
* @param string $sortCriteria
* @param bool $reverse
* @return ezcMailImapSet
@@ -1180,19 +1526,46 @@
}
/**
- * Fetches messages by a certain flag.
+ * Returns an ezcMailImapSet containing messages with a certain flag from
+ * the current mailbox.
*
* $flag can be one of:
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - RECENT Message is recent
- * - SEEN Message has been read
- * - UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
- * Opposites of the above flags
- * - NEW Equivalent to RECENT + UNSEEN
- * - ALL All the messages
+ *
+ * Basic flags:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - RECENT - message is recent
+ * - SEEN - message has been read
+ *
+ * Opposites of the above flags:
+ * - UNANSWERED
+ * - UNDELETED
+ * - UNDRAFT
+ * - UNFLAGGED
+ * - OLD
+ * - UNSEEN
+ *
+ * Composite flags:
+ * - NEW - equivalent to RECENT + UNSEEN
+ * - ALL - all the messages
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * // Fetch the messages marked with the RECENT flag
+ * $set = $imap->fetchByFlag( 'RECENT' );
+ *
+ * // $set can be parsed with ezcMailParser
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1211,16 +1584,30 @@
* Wrapper function to fetch count of messages by a certain flag.
*
* $flag can be one of:
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - RECENT Message is recent
- * - SEEN Message has been read
- * - UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
- * Opposites of the above flags
- * - NEW Equivalent to RECENT + UNSEEN
- * - ALL All the messages
+ *
+ * Basic flags:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - RECENT - message is recent
+ * - SEEN - message has been read
+ *
+ * Opposites of the above flags:
+ * - UNANSWERED
+ * - UNDELETED
+ * - UNDRAFT
+ * - UNFLAGGED
+ * - OLD
+ * - UNSEEN
+ *
+ * Composite flags:
+ * - NEW - equivalent to RECENT + UNSEEN
+ * - ALL - all the messages
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1240,17 +1627,35 @@
* Fetches IMAP flags for messages $messages.
*
* $messages is an array of message numbers, for example:
- * array( 1, 2, 4 );
+ * <code>
+ * array( 1, 2, 4 );
+ * </code>
+ *
* The format of the returned array is:
- * array( message_number => array( flags ) )
+ * <code>
+ * array( message_number => array( flags ) )
+ * </code>
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
* Example:
- * - for
- * $messages = array( 1, 2, 4 );
- * - the returned flags are
- * array( 1 => array( '\Seen' ),
- * 2 => array( '\Seen' ),
- * 4 => array( '\Seen', 'NonJunk' )
- * );
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * $flags = $imap->fetchFlags( array( 1, 2, 4 ) );
+ * </code>
+ *
+ * The returned array $flags will be something like:
+ * <code>
+ * array( 1 => array( '\Seen' ),
+ * 2 => array( '\Seen' ),
+ * 4 => array( '\Seen', 'NonJunk' )
+ * );
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1295,17 +1700,32 @@
* Sets $flag on $messages.
*
* $messages can be:
- * - a single message number (eg. 1)
- * - a message range (eg. 1:4)
- * - a message list (eg. 1,2,4)
+ * - a single message number (eg. 1)
+ * - a message range (eg. 1:4)
+ * - a message list (eg. 1,2,4)
+ *
* $flag can be one of:
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - SEEN Message has been read
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - SEEN - message has been read
+ *
* This function automatically adds the '\' in front of the flag when
* calling the server command.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * $imap->setFlag( '1:4', 'DRAFT' );
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1344,17 +1764,32 @@
* Clears $flag from $messages.
*
* $messages can be:
- * - a single message number (eg. 1)
- * - a message range (eg. 1:4)
- * - a message list (eg. 1,2,4)
+ * - a single message number (eg. '1')
+ * - a message range (eg. '1:4')
+ * - a message list (eg. '1,2,4')
+ *
* $flag can be one of:
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - SEEN Message has been read
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - SEEN - message has been read
+ *
* This function automatically adds the '\' in front of the flag when
* calling the server command.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
+ * Example:
+ * <code>
+ * $imap = new ezcMailImapTransport( 'imap.example.com' );
+ * $imap->authenticate( 'username', 'password' );
+ * $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
+ *
+ * $imap->clearFlag( '1:4', 'DRAFT' );
+ * </code>
*
* @throws ezcMailTransportException
* if a mailbox is not selected
@@ -1390,26 +1825,46 @@
}
/**
- * Finds messages in the selected mailbox by a certain flag.
+ * Returns an array of message numbers from the selected mailbox which
have a
+ * certain flag set.
*
* $flag can be one of:
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - RECENT Message is recent
- * - SEEN Message has been read
- * - UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
- * Opposites of the above flags
- * - NEW Equivalent to RECENT + UNSEEN
- * - ALL All the messages
+ *
+ * Basic flags:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - RECENT - message is recent
+ * - SEEN - message has been read
+ *
+ * Opposites of the above flags:
+ * - UNANSWERED
+ * - UNDELETED
+ * - UNDRAFT
+ * - UNFLAGGED
+ * - OLD
+ * - UNSEEN
+ *
+ * Composite flags:
+ * - NEW - equivalent to RECENT + UNSEEN
+ * - ALL - all the messages
+ *
+ * The returned array is something like this:
+ * <code>
+ * array( 0 => 1, 1 => 5 );
+ * </code>
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
*
* @throws ezcMailTransportException
* if a mailbox is not selected
* or if the server sent a negative response
* or if $flag is not valid
* @param string $flag
- * @return array(int=>int)
+ * @return array(int)
*/
protected function searchByFlag( $flag )
{
@@ -1451,6 +1906,9 @@
/**
* Sends a NOOP command to the server, use it to keep the connection alive.
*
+ * Before calling this method, a connection to the IMAP server must be
+ * established.
+ *
* @throws ezcMailTransportException
* if there was no connection to the server
* or if the server sent a negative response
@@ -1477,6 +1935,17 @@
/**
* Returns an array with the capabilities of the IMAP server.
*
+ * The returned array will be something like this:
+ * <code>
+ * array( 'IMAP4rev1', 'SASL-IR SORT', 'THREAD=REFERENCES',
'MULTIAPPEND',
+ * 'UNSELECT', 'LITERAL+', 'IDLE', 'CHILDREN', 'NAMESPACE',
+ * 'LOGIN-REFERRALS'
+ * );
+ * </code>
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established.
+ *
* @throws ezcMailTransportException
* if there was no connection to the server
* or if the server sent a negative response
@@ -1516,7 +1985,11 @@
* Sends an EXPUNGE command to the server.
*
* This method permanently deletes the messages marked for deletion by
- * the method delete().
+ * the method [EMAIL PROTECTED] delete()}.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
*
* @throws ezcMailTransportException
* if a mailbox was not selected
@@ -1545,13 +2018,19 @@
* Draft.
*
* $flags is an array of flags to be set to the $mail (if provided):
- * - ANSWERED Message has been answered
- * - DELETED Message is marked to be deleted by later EXPUNGE
- * - DRAFT Message is marked as a draft
- * - FLAGGED Message is "flagged" for urgent/special attention
- * - SEEN Message has been read
+ *
+ * $flag can be one of:
+ * - ANSWERED - message has been answered
+ * - DELETED - message is marked to be deleted by later EXPUNGE
+ * - DRAFT - message is marked as a draft
+ * - FLAGGED - message is "flagged" for urgent/special attention
+ * - SEEN - message has been read
+ *
* This function automatically adds the '\' in front of each flag when
* calling the server command.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully.
*
* @throws ezcMailTransportException
* if user is not authenticated
@@ -1626,18 +2105,26 @@
* Sorts message numbers array $messages by the specified $sortCriteria.
*
* $messages is an array of message numbers, for example:
- * array( 1, 2, 4 );
+ * <code>
+ * array( 1, 2, 4 );
+ * </code>
+ *
* $sortCriteria is an email header like: Subject, To, From, Date, Sender.
+ *
* The sorting is done with the php function natcasesort().
*
+ * Before calling this method, a connection to the IMAP server must be
+ * established and a user must be authenticated successfully, and a mailbox
+ * must be selected.
+ *
* @throws ezcMailTransportException
* if a mailbox is not selected
* or if the server sent a negative response
* or if the array $messages is empty
- * @param array(int=>int) $messages
+ * @param array(int) $messages
* @param string $sortCriteria
* @param bool $reverse
- * @return array(int=>string)
+ * @return array(string)
*/
protected function sort( $messages, $sortCriteria, $reverse = false )
{
@@ -1757,12 +2244,18 @@
* to the client command as lines, and the last line in the response
* is prepended with the same tag, and it contains the status of
* the command completion ('OK', 'NO' or 'BAD').
+ *
* Sometimes the server sends alerts and response lines from other
* commands before sending the tagged line, so this method just
* reads all the responses until it encounters $tag.
+ *
* It returns the tagged line to be processed by the calling method.
+ *
* If $response is specified, then it will not read the response
* from the server before searching for $tag in $response.
+ *
+ * Before calling this method, a connection to the IMAP server must be
+ * established.
*
* @param string $tag
* @param string $response
@@ -1789,13 +2282,18 @@
/**
* Generates the next IMAP tag to prepend to client commands.
*
- * The structure of the IMAP tag is Axxxx, where
+ * The structure of the IMAP tag is Axxxx, where:
* - A is a letter (uppercase for conformity)
* - x is a digit from 0 to 9
+ *
* example of generated tag: T5439
- * It uses the class variable [EMAIL PROTECTED] $this->currentTag}.
+ *
+ * It uses the class variable $this->currentTag.
+ *
* Everytime it is called, the tag increases by 1.
+ *
* If it reaches the last tag, it wraps around to the first tag.
+ *
* By default, the first generated tag is A0001.
*
* @return string
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
