Figure 4.1 IMAP4 Session States
| Step |
Section with details
|
|
|
|
|
|
|
|
|
| |
|---|
out_ppTagID) that you can use to help match the command and the response associated with it within the imap4Sink_t.taggedLine response. Remember to use
null. For general information about the response sink, see SDK Response Sinks for C.
To initialize and allocate the response sink, call the imap4Sink_initialize function. If successful, this function returns int imap4Sink_initialize(imap4Sink_t** out_ppimap4Sink);The following section of code initializes the response sink and sets the sink function pointers.
int l_retCode;
imap4Sink_t* l_pimap4Sink = NULL;
l_retCode = imap4Sink_initialize( &l_pimap4Sink);
if(l_retCode != NSMAIL_OK) { /*Deal with error */ } setSinkFunctions(l_pimap4Sink); /* Set sink function pointers */After you create the response sink, the next step is Creating a Client. When a session is finished, you must free any memory associated with the response sink. To free the response sink and its data members, use
imap4Sink_free:
int imap4Sink_free(imap4Sink_t** out_ppimap4Sink);When this function returns, the response sink is set to
null. The user must free any opaque data.
[Top] [Creating a Response Sink]imap4Client_t structure to communicate with an IMAP4 server. To initialize and allocate the imap4Client_t structure and set the response sink for the client's use, call the imap4_initialize function.
When you create the client structure, you pass in the identifier. Use this syntax:
int imap4_initialize(imap4Client_t ** in_ppimap4,The following section of code creates a client.
imap4Sink_t* in_pimap4Sink);
/* Initialize sink first as described in Creating a Response Sink */
imap4Client_t * l_pimap4Client = NULL;
l_retCode = imap4_initialize(&l_pimap4Client, l_pimap4Sink);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ }
After you initialize the client, the next step is Connecting to a Server.
When a session is finished, you must free any memory associated with the client. To free the client structure and its data members, use this function:
int imap4_free(imap4Client_t ** in_ppimap4);The
in_ppimap4 parameter represents the IMAP4 client. When this function returns, the client structure is set to null.
[Top]imap4_connect function:
int imap4_connect(imap4Client_t * in_pimap4,Supply the identifier of the IMAP4 client that wants to connect with the server, the identifier of the host server, and the connection port to use. This function generates a tag that you can use to help match the command and the response associated with it. Remember to use
const char * in_host,
unsigned short in_port,
char** out_ppTagID);
/* After Creating a Response Sink and Creating a Client */
char * l_szServer = "Server Name";
char * l_szTagID = "NULL";
l_retCode = imap4_connect(l_pimap4Client, l_szServer, 143, &l_szTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&l_szTagID);During the connect process, you can find out what extensions the server supports. For more information, see Determining Server Capabilities. You also might want to log in. For more information, see Logging In and Out. When a session is finished, free any memory associated with the client. To disconnect the client from the server and close the socket connection, use this function:
int imap4_disconnect( imap4Client_t * in_pimap4 );The
in_pimap4 parameter represents the IMAP4 client. You could use this function as part of a Cancel operation while retrieving a message. Remember that you do not call imap4_processResponses after imap4_disconnect.
NOTE: For the callback mapping for these functions, see IMAP4 Function Callback Mapping. §[Top]
imap4_capability function:
int imap4_capability(imap4Client_t* in_pimap4,This function calls the CAPABILITY IMAP4 protocol command, which can be issued in any session state, but is usually issued after connecting to the server. This function generates a tag that you can use to help match the command and the response associated with it. Remember to use
char** out_ppTagID);
NOTE: For this function's callback mapping, see IMAP4 Function Callback Mapping. §The following section of code retrieves a list of server capabilities.
/* After Connecting to a Server */
l_retCode = imap4_capability(l_pimap4Client, &out_pTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&out_pTagID);[Top]
int imap4_login(imap4Client_t* in_pimap4,The function sends the LOGIN IMAP4 protocol command, which can be issued during the Non-Authenticated state. Successful login moves the IMAP4 session to the Authenticated state, where the user can search for messages and manage messages on the server. This function generates a tag that you can use to help match the command and the response associated with it. Remember to use
const char* in_user,
const char* in_password,
char** out_ppTagID);
l_retCode = imap4_login(l_pimap4Client, l_szUser, l_szPassword, NULL);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&l_szTagID);After you log in, the next step is Checking for New Messages. To log out at the end of a session, use this function:
int imap4_logout(imap4Client_t* in_pimap4, char** out_ppTagID);Remember to use
l_retCode = imap4_logout(l_pimap4Client, &l_szTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&l_szTagID);
NOTE: For the callback mapping for these functions, see IMAP4 Function Callback Mapping. §[Top]
imap4_noop function is ideal for polling for new mail and ensuring that the server connection is still active. imap4_noop does nothing in itself, so it only produces the side effect of resetting the autologout timer inside the server and retrieving unsolicited server responses, which all commands do. The server responses may indicate the arrival of new messages or a change in the attributes of an existing message. Use this function:
int imap4_noop(imap4Client_t* in_pimap4, char** out_ppTagID);The
in_pimap4 parameter represents the IMAP4 client. The function generates a tag to associate with the command. Remember to use NOTE: For this function's callback mapping, see IMAP4 Function Callback Mapping. §The following section of code uses
imap4_noop to check for messages.
l_retCode = imap4_noop(l_pimap4Client, &out_pTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&out_pTagID);After checking for new messages, the next step is Searching for Messages. [Top]
imap4_search and imap4_uidsearch, search the currently selected mailbox and return the message numbers of messages that match a search key. These numbers can be used in turn to fetch the messages themselves.
You can supply one or more of the search keys defined in RFC 2060. Place more than one search key in a parenthesized list. For a table that summarizes the data items you can use to search, see Search Function Search Keys.
The imap4_search function searches the mailbox for messages that match the search criteria and returns their message numbers:
int imap4_search( imap4Client_t* in_pimap4,This function sends the SEARCH IMAP4 protocol command, which can be issued in the Selected session state. The
const char* in_criteria,
char** out_ppTagID);
imap4_uidsearch function searches the mailbox for messages specified with a unique identifier:
int imap4_uidSearch( imap4Client_t* in_pimap4,This function uses the UID IMAP4 protocol command to specify that the SEARCH command uses unique message identifiers rather than sequence numbers. This function generates a tag that you can use to help match the command and the response associated with it. Remember to use
const char* in_criteria,
char** out_ppTagID);
NOTE: For the callback mapping for these functions, see IMAP4 Function Callback Mapping. §The following section of code searches for messages that have the SUBJECT "afternoon meeting."
int l_retCode = 0;
l_retCode = imap4_search(l_pimap4Client, "SUBJECT \"afternoon meeting\"",
&out_pTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&out_pTagID);After locating messages, the next step is Fetching Message Data. [Top]
imap4_fetch and imap4_uidfetch both search the currently selected mailbox and retrieve the data specified by the fetch criteria.
When you fetch messages, you supply the message set (mailbox) and one or more fetch criteria, placing more than one data item in a parenthesized list. The fetch criteria determine the information that is returned. You can fetch one or more of the data items defined in in RFC 2060. For a table that summarizes these data items, see RFC 2060 Fetch Data Items.
The imap4_fetch and imap4_uidfetch functions retrieve the data specified by the fetch criteria for the given message set.
This function performs a fetch:
int imap4_fetch(imap4Client_t* in_pimap4,The
const char* in_msgSet,
const char* in_fetchCriteria,
char** out_ppTagID);
imap4_uidfetch function performs a fetch using unique identifiers for messages:
int imap4_uidFetch(imap4Client_t* in_pimap4,This function uses the UID IMAP4 protocol command to specify that the FETCH command uses unique message identifiers rather than sequence numbers. Both functions generate a tag that you can use to help match the commands and the responses associated with them. Remember to use
const char* in_msgSet,
const char* in_fetchCriteria,
char** out_ppTagID);
NOTE: For the callback mapping for these functions, see IMAP4 Function Callback Mapping. §The following section of code fetches the body of the message specified by the message number.
l_retCode = imap4_fetch(l_pimap4Client, "1:2", "BODY[]", &out_pTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&out_pTagID);[Top]
imap4_close function. This function sends the CLOSE IMAP4 protocol command, which closes the mailbox and removes any messages marked with the \Deleted flag. You can close the mailbox without logging out. In this case, the session moves to the parent mailbox. Use this syntax:
int imap4_close(imap4Client_t* in_pimap4, char** out_ppTagID);If you need to permanently delete messages without closing, call the
NOTE: For this function's callback mapping, see IMAP4 Function Callback Mapping. §The following section of code closes a mailbox.
l_retCode = imap4_close(l_pimap4Client, &out_pTagID);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } l_retCode = imap4_processResponses(l_pimap4Client);
if(l_retCode != NSMAIL_OK) { /*Deal with error*/ } imap4Tag_free(&out_pTagID);[Top]
NOTE: All functions that allocate tags must useimap4Tag_freeto free the associated memory. §
Last Updated: June 3, 1998