imap_fetch_ex

Retrieves data associated with mailbox messages, for a specific session.

int imap_fetch_ex( IMAP *ppimap, char *transaction, char *mode, char *message, char *saveto, ENDITEM, LAST );

ppimap	A session identifier.
transaction	A transaction name for this step in quotes. To avoid creating a transaction for this step, use a null string, "".
mode	The fetch mode in the following format: `"Mode=`mode`"`
message	The messages whose data you want to fetch and the data. The data can be any information associated with the message, such as UID, FLAGS, RFC822.SIZE, RFC822.HEADER, etc. `"Fetch=`begin_msg:end_msg (data)`"`
saveto	The name of the parameter to save message to.`"saveto=`ParameterName"
ENDITEM	A marker indicating the end of the data item list. Repeat the option and ENDITEM arguments for each set of data that you fetch.
LAST	A marker indicating the end of the argument list.

The imap_fetch_ex function retrieves data associated with mailbox messages, for a specific session. You can request the value of any message data including flags, headers, and message IDs.

This function is for use with multiple sessions. For global sessions, use the imap_fetch function, which leaves out the session identifier.

To save the content of the message to a parameter, use the saveto parameter. You must specify the size of the buffer that holds the message with a call to imap_set_max_param_len_ex.

Return Values

If this function succeeds, it returns LR_PASS. Otherwise, it returns LR_FAIL.

Parameterization

All arguments of this function of the type char, can be parameterized with standard parameterization.

Examples

Example 1

In the following example, the imap_fetch_ex function fetches information from messages 1 through 10—Message ID, flags, and the RFC822 size and header of the message.

imap_fetch_ex(&imap2, "FetchMessages", 
        "Mode=", 
        "Fetch=1:10 (UID FLAGS RFC822.SIZE RFC822.HEADER)", ENDITEM, 
        LAST );

Example 2

The next example saves the message to a parameter "Message" using the saveto parameter. imap_set_max_param_len indicates the size of the buffer to hold the message.

imap_set_max_param_len_ex(&imap2,"16384");
imap_fetch_ex(&imap2, "FetchMessages", "Mode=UID", 
               "Fetch=3 (UID RFC822.SIZE BODY[]<0.6144>)", 
               "saveto=Message", ENDITEM, LAST );
lr_log_message("Message = %s", lr_eval_string("<Message>"));

Example 3

In the following example, the imap_search_ex function gets UIDs, which can then be used by imap_fetch_ex

imap_search_ex(&imap1, "SearchMessages",
		"Mode=UID",
		"Search=ALL", // or any other search criteria
		"SaveTo=search_res1", ENDITEM,
		LAST);

Parse "search_res1" to get the UIDs. Example of the contents search_res1: “1 3 5”. “1 3 5” are the message IDs separated by spaces.

Replace the spaces with commas (“1,3,5”) and use the new string as below. One way to parse "search_re1" is with strtok.

imap_fetch_ex(&imap1, "FetchMessages", 
		"Mode=", 
		"Fetch=1,3,5 (UID)", ENDITEM, //1,3,5 should be replaced by result from imap_search_ex
		LAST);