Hunny Software Home || Hunny MIME++ Home || Hunny Mail++ Home

Main Page | Namespace List | Class Hierarchy | Class List | Namespace Members | Class Members

Imap4Client Class Reference

List of all members.

Detailed Description

Imap4Client is a class that represents an IMAP4 client connection.

The IMAP4 client commands are described in the IMAP4rev1 specification, RFC 3501. All commands have straightforward translations into member functions in the Imap4Client class. RFC 3501 also describes the possible server responses. All server responses have straightforward translations into subclasses of Response. Brief descriptions of some of the client commands are included in this documentation. However, RFC 3501 is authoritative on the IMAP4rev1 protocol, so it's a good idea to refer to it frequently.

To use the Imap4Client class, first create an instance of the class. Then call the Connect() member function to connect to the IMAP4 server. After you have connected, you may invoke member functions of Imap4Client to send client commands to the IMAP4 server. After each command, you must process the responses received from the IMAP4 server. When you are finished invoking commands, call Logout() to log out from the session, followed by Disconnect() to close the connection to the server.

After invoking a client command, you must process the server's responses, which are collected by the Imap4Client object. The client command member functions are synchronous, which means that when you call one of the functions, it does not return until it has received a success or failure response from the IMAP4 server. An IMAP4 server can send any number of responses following a client command. To see how many responses were received, call the NumResponses() member function. Once you know how many responses there are, you may call ResponseAt() to iterate through them or to access them randomly. The collection of responses is cleared at the beginning of each client command, so pointers to any Response objects become invalid when you invoke a function that sends a client command.

When you invoke an IMAP4 client command, you must be prepared to handle errors. If a network error occurs, the member function returns -1. Your program should always check the return value. To get more specific information about a network error, you may call the member functions ErrorCode() and ErrorMessage(). In addition to network errors, your code should be prepared to handle IMAP4 server errors. After you invoke a client command, you should check the responses from the server. A tagged OK response from the server indicates no error. A tagged NO or BAD response indicates an error. You may get more information about the error from the response code or response text. (See NoResponse and BadResponse.) You may call the convenience member function CommandStatus() to get the OK, NO, or BAD status result of the last command.

As with any network protocol, it is possible for a connection to stop responding. This could happen, for example, if a network element were to stop functioning or if the server stopped responding. To recover from this situation, the Imap4Client class provides a Cancel() member function. You can call Cancel() safely from another thread to terminate the network connection and unblock the thread that is blocked on a client command execution. After you call Cancel(), all client command functions return an error, which is the normal behavior when there is no connection to an IMAP4 server. To continue with the recovery, you must call Connect() again to re-establish the connection to the server.

See also:
RFC 3501: Internet Message Access Protocol - Version 4rev1


Public Member Functions

 Imap4Client ()
 Default constructor.
virtual ~Imap4Client ()
 Destructor.
void SetTraceOutput (TraceOutput *out, bool takeOwnership)
 Sets a Trace Output instance.
void SetTimeout (int secs)
 Sets the timeout value for network send and receive operations.
void SetReceiveTimeout (int secs)
 Sets the timeout value for network receive operations.
void SetSendTimeout (int secs)
 Sets the timeout value for network send operations.
void Cancel ()
 Cancels a currently executing command.
int Connect (const char *address, int port=143, bool wait=true)
 Opens a connection to an IMAP4 server.
int ConnectTls (const char *serverHostName, bool wait=false)
 Establishes a TLS connection over an existing TCP connection.
int ConnectTlsOpenSSL (const char *serverHostName, void *ssl, bool wait=false)
 Establishes a TLS connection over an existing TCP connection.
void Disconnect ()
 Closes the connection to the IMAP4 server.
CommandStatusCode CommandStatus () const
 Indicates if the last command succeeded.
int Capability ()
 Sends the CAPABILITY command.
int Noop ()
 Sends the NOOP command.
int Logout ()
 Sends the LOGOUT command.
int Starttls ()
 Sends the STARTTLS command.
int AuthenticatePlain (const char *user, const char *password, const char *authorizeUser=0)
 Sends the AUTHENTICATE PLAIN command.
int AuthenticateCramMd5 (const char *user, const char *password)
 Sends the AUTHENTICATE CRAM-MD5 command.
int AuthenticateNtlm (const char *user, const char *password)
 Sends the AUTHENTICATE NTLM command.
int Login (const char *name, const char *password)
 Sends the LOGIN command.
int Select (const char *mailboxName)
 Sends the SELECT command.
int Examine (const char *mailboxName)
 Sends the EXAMINE command.
int Create (const char *mailboxName)
 Sends the CREATE command.
int Delete (const char *mailboxName)
 Sends the DELETE command.
int Rename (const char *oldName, const char *newName)
 Sends the RENAME command.
int Subscribe (const char *mailboxName)
 Sends the SUBSCRIBE command.
int Unsubscribe (const char *mailboxName)
 Sends the UNSUBSCRIBE command.
int List (const char *reference, const char *mailboxName)
 Sends the LIST command.
int Lsub (const char *reference, const char *mailboxName)
 Sends the LSUB command.
int Status (const char *mailboxName, const char *items)
 Sends the STATUS command.
int Append (const char *mailboxName, const char *flags, const char *date, const char *message)
 Sends the APPEND command.
int Append (const char *mailboxName, const char *flags, const char *date, StreamBuffer &sbuf)
 Sends the APPEND command.
int Check ()
 Sends the CHECK command.
int Close ()
 Sends the CLOSE command.
int Expunge ()
 Sends the EXPUNGE command.
int Search (const char *charset, const char *criteria)
 Sends the SEARCH command.
int Fetch (int msgNum, const char *items)
 Sends the FETCH command with a single message sequence number.
int Fetch (int firstMsgNum, int lastMsgNum, const char *items)
 Sends the FETCH command with a range of message sequence numbers.
int Fetch (const char *set, const char *items)
 Sends the FETCH command with a message sequence number set.
int Store (int msgNum, const char *item, const char *value)
 Sends the STORE command with a single message sequence number.
int Store (int firstMsgNum, int lastMsgNum, const char *item, const char *value)
 Sends the STORE command with a range of message sequence numbers.
int Store (const char *set, const char *item, const char *value)
 Sends the STORE command with a message sequence number set.
int Copy (int msgNum, const char *mailboxName)
 Sends the COPY command with a single message sequence number.
int Copy (int firstMsgNum, int lastMsgNum, const char *mailboxName)
 Sends the COPY command with a range of message sequence numbers.
int Copy (const char *set, const char *mailboxName)
 Sends the COPY command with a message sequence number set.
int UidFetch (int uid, const char *items)
 Sends the UID FETCH command with a single message UID.
int UidFetch (int firstUid, int lastUid, const char *items)
 Sends the UID FETCH command with a range of message UIDs.
int UidFetch (const char *set, const char *items)
 Sends the UID FETCH command with a message UID set.
int UidStore (int uid, const char *item, const char *value)
 Sends the UID STORE command with a single message UID.
int UidStore (int firstUid, int lastUid, const char *item, const char *value)
 Sends the UID STORE command with a range of message UIDs.
int UidStore (const char *set, const char *item, const char *value)
 Sends the UID STORE command with a message UID set.
int UidCopy (int uid, const char *mailboxName)
 Sends the UID COPY command with a single message UID.
int UidCopy (int firstUid, int lastUid, const char *mailboxName)
 Sends the UID COPY command with a range of message UIDs.
int UidCopy (const char *set, const char *mailboxName)
 Sends the UID COPY command with a message UID set.
int UidSearch (const char *charset, const char *criteria)
 Sends the UID SEARCH command.
int SetQuota (const char *quotaRoot, const char *resourceList)
 Sends the SETQUOTA command.
int GetQuota (const char *quotaRoot)
 Sends the GETQUOTA command.
int GetQuotaRoot (const char *mailboxName)
 Sends the GETQUOTAROOT command.
int Namespace ()
 Sends the NAMESPACE command.
int ProxyAuth (const char *userName)
 Sends the PROXYAUTH command.
int NumResponses () const
 Gets the number of responses received from the server.
const Response & ResponseAt (int index) const
 Gets the response at the specified position.
Error ErrorCode () const
 Gets the platform-independent error code of last error.
int OsErrorCode () const
 Gets the platform-specific error code of last error.
const char * ErrorMessage () const
 Gets the error message associated with last error.

Constructor & Destructor Documentation

Imap4Client (   ) 
 

Default constructor.

~Imap4Client (   )  [virtual]
 

Destructor.

The destructor performs all necessary clean-up. If the connection to the server is open, the destructor closes it.

Member Function Documentation

int Append (  const char *  mailboxName,
const char *  flags,
const char *  date,
StreamBuffer &  sbuf
) 
 

Sends the APPEND command.

The APPEND command requests the server to add a new message to a mail folder (called a "mailbox" in the IMAP4 specification). The APPEND command can optionally set flags for the message and the internal date of the message. The message must be in a format compatible with RFC 2822 or MIME -- that is, in the standard Internet email format.

This version of the Append member function takes the message as a StreamBuffer. An alternative version, Append(const char*, const char*, const char*, const char*) takes the message as a NUL-terminated char array.

Example:
 void foo(Imap4Client& client, StreamBuffer& message) {
     const char* mailboxName = "INBOX";
     const char* flags = "(\Draft)";
     const char* date = 0;
     client.Append(mailboxName, flags, date, message);
 }
Parameters:
mailboxName the name of the mailbox to append the message to
flags if not NULL, contains a parenthesized list of flags to set for this message
date if not NULL, contains a date in RFC 3501 format for the message's internal date
sbuf the message to append to the mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
APPEND command in the IMAP4 specification

int Append (  const char *  mailboxName,
const char *  flags,
const char *  date,
const char *  message
) 
 

Sends the APPEND command.

The APPEND command requests the server to add a new message to a mail folder (called a "mailbox" in the IMAP4 specification). The APPEND command can optionally set flags for the message and the internal date of the message. The message must be in a format compatible with RFC 2822 or MIME -- that is, in the standard Internet email format.

This version of the Append member function takes the message as a NUL-terminated char array. An alternative version, Append(const char*, const char*, const char*, StreamBuffer&) takes the message as a StreamBuffer.

Example:
 void foo(Imap4Client& client, const char* message) {
     const char* mailboxName = "INBOX";
     const char* flags = "(\Draft)";
     const char* date = 0;
     client.Append(mailboxName, flags, date, message);
 }
Parameters:
mailboxName the name of the mailbox to append the message to
flags if not NULL, contains a parenthesized list of flags to set for this message
date if not NULL, contains a date in RFC 3501 format for the message's internal date
message the message to append to the mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
APPEND command in the IMAP4 specification

int AuthenticateCramMd5 (  const char *  user,
const char *  password
) 
 

Sends the AUTHENTICATE CRAM-MD5 command.

The AUTHENTICATE CRAM-MD5 command authenticates a user to the IMAP4 server.

If the authentication succeeds, the server sends a tagged OK response. If the authentication fails, the server sends a tagged NO response.

CRAM-MD5 is the name of a registered SASL authentication mechanism, which is supplied as a parameter to the generic AUTHENTICATE command. (SASL, described in RFC 2222, means "Simple Authentication and Security Layer".) The CRAM-MD5 authentication mechanism is described in RFC 2195.

CRAM-MD5 is more secure than the PLAIN authentication mechanism because the password is not sent across the network.

Note:
Not all IMAP4 servers support the CRAM-MD5 authentication mechanism. If the server supports CRAM-MD5 authentication, it returns AUTH=CRAM-MD5 as a capability in its CAPABILITY response.
Parameters:
user user name for the authentication
password password for the authentication
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::AuthenticatePlain(), Imap4Client::AuthenticateNtlm()

RFC 2222: Simple Authentication and Security Layer (SASL)

RFC 2195: IMAP/POP AUTHorize Extension for Simple Challenge/Response

int AuthenticateNtlm (  const char *  user,
const char *  password
) 
 

Sends the AUTHENTICATE NTLM command.

The AUTHENTICATE NTLM command authenticates a user to the IMAP4 server.

If the authentication succeeds, the server sends a tagged OK response. If the authentication fails, the server sends a tagged NO response.

NTLM is the name of a registered SASL authentication mechanism, which is supplied as a parameter to the generic AUTHENTICATE command. (SASL, described in RFC 2222, means "Simple Authentication and Security Layer".) The NTLM authentication mechanism is used to authenticate users in a Microsoft Windows environment, and is a popular option for authentication with Microsoft Exchange Server.

CRAM-MD5 is considered to be more secure than the NTLM authentication mechanism. You can use the AuthenticateCramMd5() member function to send the AUTHENTICATE CRAM-MD5 command.

Note:
Not all IMAP4 servers support the NTLM authentication mechanism. If the server supports NTLM authentication, it returns AUTH=NTLM as a capability in its CAPABILITY response.
Parameters:
user user name for the authentication
password password for the authentication
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::AuthenticateCramMd5(), Imap4Client::AuthenticatePlain()

RFC 2222: Simple Authentication and Security Layer (SASL)

int AuthenticatePlain (  const char *  user,
const char *  password,
const char *  authorizeID = 0
) 
 

Sends the AUTHENTICATE PLAIN command.

The AUTHENTICATE PLAIN command authenticates a user to the IMAP4 server.

If the authentication succeeds, the server sends a tagged OK response. If the authentication fails, the server sends a tagged NO response.

PLAIN is the name of a registered SASL authentication mechanism, which is supplied as a parameter to the generic AUTHENTICATE command. (SASL, described in RFC 2222, means "Simple Authentication and Security Layer".) The PLAIN authentication mechanism is described in RFC 2595.

PLAIN is the least secure of all the SASL authentication mechanisms, since the password is sent unencrypted across the network. The CRAM-MD5 authentication mechanism is much more secure. You can use the AuthenticateCramMd5() member function to send the AUTHENTICATE CRAM-MD5 command.

The AuthenticatePlain() member function takes a user name and password as required parameters, and an authorization ID as an optional parameter. The function sends the user name and password to the server for authentication, that is, for login. If you provide an authorization ID, the function sends it to the server for authorization, which allows the authenticated user to act on another user's account. (Normally, this kind of authorization requires special privileges for the authenticated user.)

Note:
Not all IMAP4 servers support the PLAIN authentication mechanism. If the server supports PLAIN authentication, it returns AUTH=PLAIN as a capability in its CAPABILITY response.
Parameters:
user user name for the authentication
password password for the authentication
authorizeID ID for the authorization, with default value NULL
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::AuthenticateCramMd5(), Imap4Client::AuthenticateNtlm()

RFC 2222: Simple Authentication and Security Layer (SASL)

PLAIN SASL mechanism in RFC 2595

void Cancel (   ) 
 

Cancels the currently executing command.

Since it is possible for a network connection to stop responding, an interactive application must be able to cancel a command that is waiting on a network operation (connect, send, or receive). For this reason, the Imap4Client class provides a Cancel() member function, which promptly terminates any currently executing client command.

Cancel() is the only member function that is safe to call from another thread. In a typical situation, you have one thread that executes IMAP4 commands, and another thread that serves the user interface. A user action to cancel is serviced by the user interface thread, which calls Cancel() on the Imap4Client object to cancel a command. The command function that the IMAP4 client thread was executing at the time may return an error. (It will return an error if the cancel operation occurred before the command was completed.)

Because it is difficult to recover the client/server state after a cancel operation, the library closes the connection whenever you call the Cancel() member function. You must call Connect() again to reconnect to the IMAP4 server. Note: You should not call the Connect() function from the same thread thread that called Cancel().

Note:
Since all network operations will timeout, you do not need to use Cancel() in non-interactive applications. Instead, you can just let the timeout timer stop any stalled network operation.

int Capability (   ) 
 

Sends the CAPABILITY command.

The CAPABILITY command requests the server to send a list of features (that is, capabilities) that it supports. In response to the CAPABILITY command, the IMAP4 server sends a CAPABILITY response.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
CapabilityResponse

CAPABILITY command in the IMAP4 specification

int Check (   ) 
 

Sends the CHECK command.

The CHECK command requests the server to establish a checkpoint for the currently selected mailbox. The actions that occur to establish a checkpoint are server-dependent. If any failures occur after a checkpoint, it should be possible for the server to reliably return to the state at the time of the checkpoint.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
CHECK command in the IMAP4 specification

int Close (   ) 
 

Sends the CLOSE command.

The CLOSE command requests the server to close the currently selected mailbox. When the server closes a mailbox, it permanently deletes (expunges) all messages in the mailbox that are marked with the \Deleted flag. After a CLOSE command, the server is no longer in the SELECTED state (that is, no mailbox is selected).

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
CLOSE command in the IMAP4 specification

Imap4Client::CommandStatusCode CommandStatus (   )  const
 

Indicates if the last command succeeded.

This convenience function examines the responses from the server and indicates if the last command succeeded. Normally, you call this function after every command to learn if the command succeeded or failed at the server.

Failures can happen at different layers and for different reasons. At the network layer, communication with the server can fail. At the application layer, command execution at the server can fail. If the command succeeds, the server returns a tagged OK response. If the command fails, the server returns either a tagged NO response or a tagged BAD response. If communication with the server fails, the client receives no response from the server.

You may call this function to learn the status of the most recent command. If the command succeeded at the server and the server sent a tagged OK response, the function returns Imap4Client::OK. If the command failed and the server sent a tagged NO response or a tagged BAD response, the function returns Imap4Client::NO or Imap4Client::BAD, respectively. If the client did not receive a tagged OK, NO, or BAD response from the server, the function returns Imap4Client::ERR.

Returns:
status code that indicates OK, NO, or BAD

int Connect (  const char *  address,
int  port = 143,
bool  wait = true
) 
 

Opens a connection to an IMAP4 server.

This member function opens a connection to the host at network address address and TCP port port. The address parameter may be a hostname ("imap4.example.com"), an IP address in dotted decimal form ("192.168.2.25"), or an IPv6 address in hexadecimal form ("2002:458c:68f7:0:203:baff:fe0b:74ba"). The default value for port is 143, the well-known TCP port number for IMAP4.

If the client connects to the server successfully, then Connect() returns 0. If the client fails to connect to the server -- for example, if the host is not found or some other network error occurs -- then Connect() returns -1. If Connect() returns 0, then you should also check the responses from the server. The server sends an untagged OK response if it is ready to process commands. You can check the server's responses by calling the NumResponses() and ResponseAt() member functions.

You may call the Cancel() member function from another thread to cancel this operation.

If the optional parameter wait is true, it causes the client to wait for the server's greeting. In the IMAP4 protocol, the server always begins the dialog with its initial greeting. However, if you need to establish a TLS connection to the server, you may set wait to false. Then, the function returns immediately after the TCP connection is established without waiting for the server's initial greeting.

Note:
The cancel operation will not have an immediate effect if the connect operation is waiting on a hostname lookup. Failed hostname lookups always time out. (In a future implementation, the library may provide the capability to cancel a hostname lookup, as well.)
Parameters:
address hostname or IP address of the IMAP4 server
port TCP port number of the IMAP4 server (default = 143)
wait after the TCP connection is established, the client should wait for the server's greeting (default = true)
Returns:
0 if communication between client and server succeeded; otherwise -1

int ConnectTls (  const char *  serverHostName,
bool  wait = false
) 
 

Opens a TLS connection over an existing TCP connection.

Transport Layer Security (TLS) provides server authentication and private communication over a TCP connection. TLS is the successor to Secure Sockets Layer (SSL), and individuals often use the term SSL even if the actual protocol is TLS. TLS is a standards track protocol developed by the IETF and described in RFC 2246.

Before you call ConnectTls(), you must have established a TCP connection to the server. You must also have configured the TlsConfig object. Normally, you configure the TlsConfig object when you initialize your application.

ConnectTls() starts a dialog between client and server, called a TLS handshake, to negotiate security parameters for the secure connection and to authenticate the server. If the handshake succeeds, a secure TLS connection is established between client and server.

During the TLS handshake, the server sends a certificate to the client, and the client examines the certificate to verify the identity of the server. The certificate must be valid, and it must contain the host name of the server. When you call ConnectTls(), you provide the server's host name in the serverHostName parameter. The library tries to match serverHostName with the host name in the certificate. If the match fails, but the handshake otherwise succeeds, then the function returns -1, and the error code is BAD_CERTIFICATE_NAME_ERROR. In many applications, a BAD_CERTIFICATE_NAME_ERROR is not automatically treated as a fatal error; rather, the application presents an alert to the user and allows the user the choice to abort the connection or to continue and ignore the failure. Therefore, BAD_CERTIFICATE_NAME_ERROR should be treated as a severe warning: the server authentication failed but the secure connection succeeded. You should treat any other error that occurs during the handshake as a fatal error and close the TCP connection.

If the optional parameter wait is true, it causes the client to wait for the server's greeting. It is important to set the correct value for this parameter. There are two cases: In the first case, you call Connect() to connect to a special secure IMAP4 port (TCP port 993) and then immediately call ConnectTls() to create a TLS connection. In this case, you call Connect() with wait false and you call ConnectTls() with wait true. In the second case, you call Connect() to connect to the standard IMAP4 port (TCP port 143). Then you call Starttls() to indicate to the server that you want to begin a TLS handshake. Then you call ConnectTls() create a TLS connection. In this case, you call Connect() with wait true (the default), and you call ConnectTls() with wait false (also the default).

The function returns 0 on success and -1 on failure. To check the error code after a failure, call ErrorCode().

Note:
You must have Hunny Secure Mail++ to use this member function. In standard Hunny Mail++, the function returns -1.
Parameters:
serverHostName host name of the server for server authentication
wait after the TLS connection is established, the client should wait for the server's greeting (default = false)
Returns:
0 if successful; otherwise -1
See also:
RFC 2246 The TLS Protocol Version 1.0

int ConnectTlsOpenSSL (  const char *  serverHostName,
void *  ssl,
bool  wait = false
) 
 

Opens a TLS connection over an existing TCP connection, using a specified SSL struct.

For simple use of TLS, you may use the ConnectTls() member function.

For advanced use, you may use this member function, which allows you to create an SSL struct and pass it to the library to use. Examples of situations where you may choose to use the ConnectTlsOpenSSL() function include:

  • You want to get the server's certificate.
  • You want to install a verify callback to override the default certificate verification procedure.
  • You want to override certain default options in the SSL struct.

To use ConnectTlsOpenSSL(), you must call the OpenSSL function SSL_new(SSL_CTX*) to create an SSL struct. After you configure the SSL struct, you pass it as the ssl parameter to ConnectTlsOpenSSL().

The Imap4Client destructor calls SSL_free(SSL*) to free the SSL struct. However, OpenSSL uses a reference counting mechanism, and you may use that mechanism to prevent the Imap4Client destructor from freeing the SSL struct. To prevent the Imap4Client's destructor from freeing the SSL struct, increment the reference count before you pass the struct to the Imap4Client, like so:

     CRYPTO_add(&ssl->references, 1, CRYPTO_LOCK_SSL);

Parameters:
serverHostName host name of the server for server authentication
ssl OpenSSL SSL struct
wait after the TLS connection is established, the client should wait for the server's greeting (default = false)
Returns:
0 if successful; otherwise -1
See also:
ConnectTls()

int Copy (  const char *  set,
const char *  mailboxName
) 
 

Sends the COPY command.

The COPY command requests the server to copy one or more messages from the currently selected mailbox to a different mailbox.

This version of the overloaded member function allows multiple messages to be copied, as specified by a set of message sequence numbers. The set parameter should specify a set of message sequence numbers in the syntax given in RFC 3501. In this syntax, individual sequence numbers or sequence number ranges are separated by commas, and ranges are indicated using a colon.

Example:
 // Copy messages 2, 4, and 6-10 to "saved" mailbox
 const char* set = "2,4,6:10";
 const char* mailboxName = "saved";
 client.Copy(set, mailboxName);
Parameters:
set string that specifies a set of message sequence numbers
mailboxName name of the destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
COPY command in the IMAP4 specification

int Copy (  int  firstMsgNum,
int  lastMsgNum,
const char *  mailboxName
) 
 

Sends the COPY command.

The COPY command requests the server to copy one or more messages from the currently selected mailbox to a different mailbox.

This version of the overloaded member function allows multiple messages to be copied, as specified by a range of message sequence numbers. The parameter firstMsgNum should be the sequence number of the first message in the range, and lastMsgNum should be the sequence number of the last message in the range. The range in inclusive.

Parameters:
firstMsgNum starting message sequence number for a range of messages
lastMsgNum ending message sequence number for a range of messages
mailboxName name of the destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
COPY command in the IMAP4 specification

int Copy (  int  msgNum,
const char *  mailboxName
) 
 

Sends the COPY command.

The COPY command requests the server to copy one or more messages from the currently selected mailbox to a different mailbox.

This version of the overloaded member function allows one message to be copied. The parameter msgNum should be the sequence number of a single message to copy.

Parameters:
msgNum sequence number of the message to copy
mailboxName name of the destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
COPY command in the IMAP4 specification

int Create (  const char *  mailboxName  ) 
 

Sends the CREATE command.

The CREATE command requests the server to create a new mailbox (sometimes called a mail folder). The mailboxName parameter should contain the name of the new mailbox.

Parameters:
mailboxName name of the new mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
CREATE command in the IMAP4 specification

int Delete (  const char *  mailboxName  ) 
 

Sends the DELETE command.

The DELETE command requests the server to delete an existing mailbox. The mailboxName parameter should contain the name of the mailbox to be deleted.

Parameters:
mailboxName name of the mailbox to delete
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
DELETE command in the IMAP4 specification

void Disconnect (   ) 
 

Closes the connection to the IMAP4 server.

The correct way to end an IMAP4 session is to send a LOGOUT command, which causes the server to perform any necessary closing operations and close the connection. Therefore you should almost always call Logout() just before you call Disconnect().

You may safely call this method even if the client is not connected.

See also:
Imap4Client::Logout()

Error ErrorCode (   )  const
 

Gets the platform-independent error code for the last error.

The error codes are enumerated in the file mailpp/Error.h. Note that they are defined in the mailpp namespace.

The ErrorMessage() member function returns a textual description of the platform-independent error.

If the error code is SYSTEM_ERROR, you may call OsErrorCode() to get more detailed information about the error.

Returns:
platform-independent error code
See also:
Imap4Client::ErrorMessage()

const char * ErrorMessage (   )  const
 

Gets the error message for the last error.

This function returns a textual description of the platform-independent error code.

Returns:
platform-independent error message
See also:
Imap4Client::ErrorCode()

int Examine (  const char *  mailboxName  ) 
 

Sends the EXAMINE command.

The EXAMINE command is similar to a SELECT command with one difference: EXAMINE selects the mailbox read-only.

Parameters:
mailboxName name of the mailbox to select
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Select()

EXAMINE command in the IMAP4 specification

int Expunge (   ) 
 

Sends the EXPUNGE command.

The EXPUNGE command causes the server to permanently delete the messages in the currently selected mailbox that have the \Deleted flag set. The server sends an EXPUNGE response for each message deleted.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
ExpungeResponse

EXPUNGE command in the IMAP4 specification

int Fetch (  const char *  set,
const char *  items
) 
 

Sends the FETCH command.

The FETCH command requests the server to return one or more messages, parts of messages, or message attributes. The server sends one or more FETCH responses that contain the requested information.

This version of the overloaded member function allows information for multiple messages to be fetched, as specified by a set of message sequence numbers. The set parameter should specify a set of message sequence numbers in the syntax given in RFC 3501. In this syntax, individual sequence numbers or sequence number ranges are separated by commas, and ranges are indicated using a colon.

Example:
 void foo(Imap4Client& client)
 {
     // fetch the FLAGS, INTERNALDATE, RFC822.SIZE, and ENVELOPE
     const char* set = "1:2,5";
     // Note: "ALL" is a macro, so it does not go in parentheses
     const char* items = "ALL";
     client.Fetch(set, items);
     // process the responses
     // [...]
     // fetch the UID and message body
     items = "(UID BODY.PEEK[TEXT])";
     client.Fetch(set, items);
     // process the responses
     // [...]
 }
Note:
Some data items that can be fetched can be very large, as, for example, an entire message. If a data item is very large, it is a good idea to fetch it in several fragments. For example, to fetch a message with sequence number 3 that is 200K in size, you could do it with these two FETCH commands, which fetch the message in two 100,000 byte fragments: 
     1 FETCH 3 (BODY[]<0.100000>)
     2 FETCH 3 (BODY[]<100000.100000>)
By fetching the message in fragments, you can also provide feedback to a user on the progress of the fetch operation.
Parameters:
set string that specifies a set of message sequence numbers
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

FETCH command in the IMAP4 specification

int Fetch (  int  firstMsgNum,
int  lastMsgNum,
const char *  items
) 
 

Sends the FETCH command.

The FETCH command requests the server to return one or more messages, parts of messages, or message attributes. The server sends one or more FETCH responses that contain the requested information.

This version of the overloaded member function allows information for multiple messages to be fetched, as specified by a range of message sequence numbers. The parameter firstMsgNum should be the sequence number of the first message in the range, and lastMsgNum should be the sequence number of the last message in the range. The range in inclusive.

Parameters:
firstMsgNum starting message sequence number for a range of messages
lastMsgNum ending message sequence number for a range of messages
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

FETCH command in the IMAP4 specification

int Fetch (  int  msgNum,
const char *  items
) 
 

Sends the FETCH command.

The FETCH command requests the server to return one or more messages, parts of messages, or message attributes. The server sends one or more FETCH responses that contain the requested information.

This version of the overloaded member function allows information for a single message to be fetched. The parameter msgNum should be the sequence number of the message.

Parameters:
msgNum message sequence number
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

FETCH command in the IMAP4 specification

int GetQuota (  const char *  quotaRoot  ) 
 

Sends the GETQUOTA command.

An IMAP4 client may send the GETQUOTA command to get information about resource usage and limits, such as the amount of storage used and the storage limit. The GETQUOTA command takes a quota root name as a parameter. (You may send the GETQUOTAROOT command to get a list of quota roots for a particular mailbox.) In response to the GETQUOTA command, the server sends a QUOTA response that reports resource usage and limits.

The GETQUOTA command is an optional IMAP4 command. An IMAP4 server that supports the GETQUOTA command returns the QUOTA keyword in its CAPABILITY response.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
GetQuotaRoot

QuotaResponse

GETQUOTA command in RFC 2087

int GetQuotaRoot (  const char *  mailboxName  ) 
 

Sends the GETQUOTAROOT command

An IMAP4 client may send the GETQUOTAROOT command to get a list of quota roots that apply to a mailbox. A quota root may be shared by many mailboxes, which allows all the mailboxes to share the same resource limits. In response to the GETQUOTAROOT command, the server sends a QUOTAROOT response that lists all the quota roots, plus a QUOTA response for each quota root.

The GETQUOTAROOT command is an optional IMAP4 command. An IMAP4 server that supports the GETQUOTAROOT command returns the QUOTA keyword in its CAPABILITY response.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
GetQuota

QuotaRootResponse

QuotaResponse

GETQUOTAROOT command in RFC 2087

int List (  const char *  reference,
const char *  mailboxName
) 
 

Sends the LIST command.

The LIST command requests the server to return a list of all names that match a specified pattern. In response, the server sends zero or more LIST responses.

Note:
The names that the server returns are not necessarily the names of valid mailboxes. Some servers will list all the files in a directory whether or not those files are valid mailbox files. You must check the \noselect and \noinferiors flags to learn if a name is not a valid mailbox name.
Warning:
If the command contains a "*" wildcard, the server could potentially send a very large number of responses. It is safer to use the "%" wildcard, instead of the "*" wildcard, and to traverse one level of hierarchy per command.
Parameters:
reference context in which the mailbox name is interpreted
mailboxName mailbox name or wildcard pattern
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
ListResponse

LIST command in the IMAP4 specification

int Login (  const char *  name,
const char *  password
) 
 

Sends the LOGIN command.

The LOGIN command sends a user name and password for client authentication.

LOGIN may not be secure, because it sends the user name and password across the network. It is safe to use LOGIN after you have established a TLS connection. However, if you do not use TLS, you should consider using AUTHENTICATE CRAM-MD5 for authentication, since AUTHENTICATE CRAM-MD5 does not send the password over the network.

Parameters:
name user name for the authentication
password password for the authentication
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
LOGIN command in the IMAP4 specification

int Logout (   ) 
 

Sends the LOGOUT command.

The LOGOUT command ends the current IMAP4 session. In response to the LOGOUT command, the IMAP4 server sends a BYE response and then closes the connection. Therefore, after you call Logout, you must call Connect again to reconnect to the server before you can call any member functions that send commands.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
ByeResponse

LOGOUT command in the IMAP4 specification

int Lsub (  const char *  reference,
const char *  mailboxName
) 
 

Sends the LSUB command.

The LSUB command is similar to the LIST command, except that the server returns only names that are in the list of subscribed mailboxes.

Parameters:
reference context in which the mailbox name is interpreted
mailboxName mailbox name or wildcard pattern
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
LsubResponse

LSUB command in the IMAP4 specification

int Namespace (   ) 
 

Sends the NAMESPACE command.

The NAMESPACE command is an optional IMAP4 command, which is not supported by all IMAP4 servers. If an IMAP4 server supports the NAMESPACE command, then it sends the NAMESPACE keyword in its CAPABILITIES response.

If the IMAP4 server accepts the NAMESPACE command, then it sends a NAMESPACE response with information about mailbox namespaces. See the introduction to the NamespaceResponse class for more information about the NAMESPACE command.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
NamespaceResponse

NAMESPACE command in RFC 2342

int Noop (   ) 
 

Sends the NOOP command.

The NOOP command is typically used to obtain notification responses, such as the RECENT response, from the IMAP4 server. (The RECENT response notifies the client that new mail has arrived.) The NOOP command is also used sometimes to keep the connection open for a long period of time. (Most IMAP4 servers will close the connection after a long period of inactivity.)

Note: NOOP is an abbreviation for "no operation".

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
NOOP command in the IMAP4 specification

int NumResponses (   )  const
 

Gets the number of responses received from the server.

The Imap4Client object has a collection of Response objects, one for each response received from the server after the last client command. Use this function to get the number of responses in the collection. Use ResponseAt to get the individual responses.

Returns:
number of responses in the collection of responses
See also:
Imap4Client::ResponseAt()

int OsErrorCode (   )  const
 

Gets the platform-specific error code for the last error.

This function gets the error code reported by the operating system. The operating system's error code is necessarily platform-specific. This error code is probably not as useful as the platform-independent error code, but it might provide information helpful for debugging. The operating system's error code provides more specific information when the platform-independent error code is SYSTEM_ERROR.

Not all errors have an operating system error code. Some errors, such as library usage errors, are detected in the Hunny Mail++ library itself.

Returns:
platform-specific error code
See also:
Imap4Client::ErrorCode()

int ProxyAuth (  const char *  userName  ) 
 

Sends the PROXYAUTH command.

PROXYAUTH is a proprietary IMAP4 extension supported by Netscape/iPlanet/SunONE mail servers. It permits a user with administrator privileges to act on the account of an ordinary user.

Parameters:
userName the user name for the command

int Rename (  const char *  oldName,
const char *  newName
) 
 

Sends the RENAME command.

The RENAME command requests the server to change the name of an existing mailbox.

Parameters:
oldName name of mailbox to be renamed
newName new name for the mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
RENAME command in the IMAP4 specification

const Response & ResponseAt (  int  index  )  const
 

Gets the response at the specified position.

The Imap4Client object has a collection of Response objects, one for each response received from the server after the last client command. You may use this function to get a reference to the Response object at position index. The argument index must satisfy the condition 0 <= index < NumResponses().

Because Response is an abstract base class, the returned object reference actually references a subclass of Response.

Parameters:
index position of the response to get
Returns:
reference to the Response object

int Search (  const char *  charset,
const char *  criteria
) 
 

Sends the SEARCH command.

The SEARCH command requests the server to return a list of messages that match the specified search criteria. The search criteria can be quite complex. See the documentation in RFC 3501. In response to the SEARCH command, the server sends a SEARCH response, which contains a list of sequence numbers for the messages that satisfy the search criteria.

Example:
 void foo(Imap4Client& client) {
     const char* charset = "US-ASCII";
     const char* criteria = "SUBJECT \"Re: Humpty Dumpty\"";
     client.Search(charset, criteria);
 }
Parameters:
charset if not NULL, specifies the character set that applies to the search criteria
criteria a string containing the search criteria
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
SearchResponse

SEARCH command in the IMAP4 specification

int Select (  const char *  mailboxName  ) 
 

Sends the SELECT command.

The SELECT command takes one parameter: the name of a mailbox (often called a mail "folder"). In response to the SELECT command, the server sends a FLAGS response, an EXISTS response, and a RECENT response. The server may also send untagged OK responses with UNSEEN or PERMANENTFLAGS response codes.

Parameters:
mailboxName name of the mailbox to select
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FlagsResponse, ExistsResponse, RecentResponse, OkResponse

SELECT command in the IMAP4 specification

int SetQuota (  const char *  quotaRoot,
const char *  resourceList
) 
 

Sends the SETQUOTA command.

The SETQUOTA command allows an administrator to set or change the quota limits at the IMAP4 server. The SETQUOTA command takes a quota root name and a list of resource limits as parameters. In response to the SETQUOTA command, the server sends a QUOTA response that reports the new values of the resource limits.

The SETQUOTA command is an optional IMAP4 command. An IMAP4 server that supports the SETQUOTA command returns the QUOTA keyword in its CAPABILITY response.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
SETQUOTA command in RFC 2087

void SetReceiveTimeout (  int  secs  ) 
 

Sets the timeout for network receive operations.

The library supports separate timeout values for sending and receiving. This property affects the timeout for receive operations. The send timeout property affects the timeout for connect and send operations.

If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.

Parameters:
secs number of seconds before a timeout occurs

void SetSendTimeout (  int  secs  ) 
 

Sets the timeout for network send operations.

The library supports separate timeout values for sending and receiving. This propery affects the timeout for connect and send operations. The receive timeout property affects the timeout for receive operations.

If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.

Parameters:
secs number of seconds before a timeout occurs

void SetTimeout (  int  secs  ) 
 

Sets the timeout value for network send and receive operations.

The timeout applies to these network operations: connect, receive, and send. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.

This member function is deprecated. Use SetReceiveTimeout() and SetSendTimeout() to set network timeouts.

Parameters:
secs number of seconds before a timeout occurs
See also:
Imap4Client::SetReceiveTimeout(), Imap4Client::SetSendTimeout()

void SetTraceOutput (  TraceOutput *  out,
bool  takeOwnership
) 
 

Sets a TraceOutput instance.

When you set a TraceOutput instance, you enable trace output, which may be helpful for debugging. You may set a null value to disable trace output.

The Hunny Mail++ library provides a StdTraceOutput class that prints all output to standard output.

If you pass a true value for the takeOwnership parameter, then the Imap4Client object has the responsibility to delete the trace output object. On the other hand, if you pass false, then your code must delete the trace output object when it is no longer needed.

Parameters:
out pointer to the TraceOutput object, or NULL
takeOwnership if true, then the Imap4Client deletes the TraceOuput object

int Starttls (   ) 
 

Sends the STARTTLS command.

The STARTTLS command requests the server to begin a TLS handshake. If the STARTTLS command succeeds, as indicated by a tagged OK response from the server, then you should immediately call ConnectTls() to start the TLS handshake and to establish the secure connection.

The STARTTLS IMAP4 command is documented in RFC 2595.

Note: You must have Secure Mail++ to use this member function. In standard Mail++, the function returns -1.

Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
The STARTTLS command in RFC 2595

int Status (  const char *  mailboxName,
const char *  items
) 
 

Sends the STATUS command.

The STATUS command requests the server to send status information for the specified mailbox. You must specify the requested status data items in the command. In response to the STATUS command, the server sends a STATUS response.

Warning:
Do not use the STATUS command to get the number of messages or other status information about the currently selected mailbox. While such an action is seemingly allowed in RFC 2060, it is expressly forbidden in RFC 3501.
Example:
 void foo(Imap4Client& client) {
     const char* mailboxName = "drafts";
     const char* items = "(MESSAGES RECENT)";
     client.Status(mailbox, items);
 }
Parameters:
mailboxName name of the mailbox to query
items parenthesized list of query items
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
StatusResponse

STATUS command in the IMAP4 specification

int Store (  const char *  set,
const char *  item,
const char *  value
) 
 

Sends the STORE command.

The STORE command requests the server to change the values of the flags for specified messages. In response to the STORE command, the server sends one or more FETCH responses that indicate the new values of the flags.

This version of the overloaded member function allows flags for multiple messages to be changed, as specified by a set of message sequence numbers. The set parameter should specify a set of message sequence numbers in the syntax specified in RFC 3501. In this syntax, individual sequence numbers or sequence number ranges are separated by commas, and ranges are specified using a colon.

Example:
 void foo(Imap4Client& client)
 {
     const char* set = "99,101:103";
     const char* item = "+FLAGS";
     const char* value = "(\Deleted)";
     client.Store(set, item, value);
 }
Parameters:
set string that specifies a set of message sequence numbers
item data item to store
value value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

STORE command in the IMAP4 specification

int Store (  int  firstMsgNum,
int  lastMsgNum,
const char *  item,
const char *  value
) 
 

Sends the STORE command.

The STORE command requests the server to change the values of the flags for specified messages. In response to the STORE command, the server sends one or more FETCH responses that indicate the new values of the flags.

This version of the overloaded member function allows the flags for multiple messages to be changed, as specified by a range of message sequence numbers. The parameter firstMsgNum should be the sequence number of the first message in the range, and lastMsgNum should be the sequence number of the last message in the range.

Parameters:
firstMsgNum starting message sequence number for a range of messages
lastMsgNum ending message sequence number for a range of messages
item data item to store
value value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

STORE command in the IMAP4 specification

int Store (  int  msgNum,
const char *  item,
const char *  value
) 
 

Sends the STORE command.

The STORE command requests the server to change the values of the flags for specified messages. In response to the STORE command, the server sends one or more FETCH responses that indicate the new values of the flags.

This version of the overloaded member function allows the flags for a single message to be changed. The parameter msgNum should be the sequence number of the message.

Parameters:
msgNum message sequence number
item data item to store
value value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
FetchResponse

STORE command in the IMAP4 specification

int Subscribe (  const char *  mailboxName  ) 
 

Sends the SUBSCRIBE command.

The SUBSCRIBE command requests the server to add a mailbox to the list of subscribed mailboxes for the current user. You may use the LSUB command to get a list of the subscribed mailboxes. You may use the UNSUBSCRIBE command to remove a mailbox from the list of subscribed mailboxes.

Parameters:
mailboxName name of the mailbox to subscribe to
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Unsubscribe(), Imap4Client::Lsub()

SUBSCRIBE command in the IMAP4 specification

int UidCopy (  const char *  set,
const char *  mailboxName
) 
 

Sends the UID COPY command.

The UID COPY command is similar to the COPY command, with one difference: the UID COPY command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows multiple messages to be copied, as specified by a set of message UIDs. The set parameter should specify a set of UIDs in the syntax given in RFC 3501. In this syntax, individual UIDs or UID ranges are separated by commas, and ranges are indicated by a colon.

Parameters:
set string that specifies a set of message UIDs
mailboxName name of destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Copy()

UID command in the IMAP4 specification

int UidCopy (  int  firstUid,
int  lastUid,
const char *  mailboxName
) 
 

Sends the UID COPY command.

The UID COPY command is similar to the COPY command, with one difference: the UID COPY command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows multiple messages to be copied, as specified by a range of message UIDs. The parameter firstUid should be the UID of the first message in the range, and lastUid should be the UID of the last message in the range.

Parameters:
firstUid unique identifier (UID) of the first message
lastUid unique identifier (UID) of the last message
mailboxName name of destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Copy()

UID command in the IMAP4 specification

int UidCopy (  int  uid,
const char *  mailboxName
) 
 

Sends the UID COPY command.

The UID COPY command is similar to the COPY command, with one difference: the UID COPY command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows one message to be copied. The parameter uid should be the UID of the message.

Parameters:
uid unique identifier (UID) of the message
mailboxName name of destination mailbox
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Copy()

UID command in the IMAP4 specification

int UidFetch (  const char *  set,
const char *  items
) 
 

Sends the UID FETCH command.

The UID FETCH command is similar to the FETCH command, with one difference: the UID FETCH command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows information for multiple messages to be fetched, as specified by a set of message UIDs. The set parameter should specify a set of UIDs in the syntax given in RFC 3501. In this syntax, individual UIDs or UID ranges are separated by commas, and ranges are indicated by a colon.

Parameters:
set string that specifies a set of message UIDs
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Fetch()

UID command in the IMAP4 specification

int UidFetch (  int  firstUid,
int  lastUid,
const char *  items
) 
 

Sends the UID FETCH command.

The UID FETCH command is similar to the FETCH command, with one difference: the UID FETCH command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows information for multiple messages to be fetched, as specified by a range of message UIDs. The parameter firstUid should be the UID of the first message in the range, and lastUid should be the UID of the last message in the range.

Parameters:
firstUid unique identifier (UID) of the first message
lastUid unique identifier (UID) of the last message
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Fetch()

UID command in the IMAP4 specification

int UidFetch (  int  uid,
const char *  items
) 
 

Sends the UID FETCH command.

The UID FETCH command is similar to the FETCH command, with one difference: the UID FETCH command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows information for a single message to be fetched. The parameter uid should be the UID of the message.

Parameters:
uid unique identifier (UID) of the message
items list of items to be fetched
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Fetch()

UID command in the IMAP4 specification

int UidSearch (  const char *  charset,
const char *  criteria
) 
 

Sends the UID SEARCH command.

The UID SEARCH command is similar to the SEARCH command, with one difference: when the UID SEARCH command is sent, the server's SEARCH response contains the unique identifiers (UIDs) of the matching messages instead of their sequence numbers.

Parameters:
charset if not NULL, specifies the character set that applies to the search criteria
criteria a string containing the search criteria
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Search(), SearchResponse

UID command in the IMAP4 specification

int UidStore (  const char *  set,
const char *  item,
const char *  value
) 
 

Sends the UID STORE command.

The UID STORE command is similar to the STORE command, with one difference: the UID STORE command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows flags for multiple messages to be changed, as specified by a set of message UIDs. The set parameter should specify a set of UIDs in the syntax given in RFC 3501. In this syntax, individual UIDs or UID ranges are separated by commas, and ranges are indicated by a colon.

Parameters:
set string that specifies a set of message UIDs
item the data item to store
value the value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Store()

UID command in the IMAP4 specification

int UidStore (  int  firstUid,
int  lastUid,
const char *  item,
const char *  value
) 
 

Sends the UID STORE command.

The UID STORE command is similar to the STORE command, with one difference: the UID STORE command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows the flags for multiple messages to be changed, as specified by a range of message UIDs. The parameter firstUid should be the UID of the first message in the range, and lastUid should be the UID of the last message in the range.

Parameters:
firstUid unique identifier (UID) of the first message
lastUid unique identifier (UID) of the last message
item the data item to store
value the value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Store()

UID command in the IMAP4 specification

int UidStore (  int  uid,
const char *  item,
const char *  value
) 
 

Sends the UID STORE command.

The UID STORE command is similar to the STORE command, with one difference: the UID STORE command specifies messages by their unique identifiers (UIDs) instead of their sequence numbers.

This version of the overloaded member function allows flags for a single message to be changed. The parameter uid should be the UID of the message.

Parameters:
uid unique identifier (UID) of the message
item the data item to store
value the value of data item
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Store()

UID command in the IMAP4 specification

int Unsubscribe (  const char *  mailboxName  ) 
 

Sends the UNSUBSCRIBE command.

The UNSUBSCRIBE command requests the server to remove a mailbox from the list of subscribed mailboxes for the current user. You may use the LSUB command to get a list of the subscribed mailboxes. You may use the SUBSCRIBE command to add a mailbox to the list of subscribed mailboxes.

Parameters:
mailboxName name of the mailbox to unsubscribe from
Returns:
0 if communication between client and server succeeded; otherwise -1
See also:
Imap4Client::Subscribe(), Imap4Client::Lsub()

UNSUBSCRIBE command in the IMAP4 specification

Copyright © 2001-2005 Hunny Software, Inc. All rights reserved.