IMAP C API Reference
Table of Contents | Previous | Next | Index

Messaging Access SDK Guide
Part 2. Messaging Access SDK C Reference

Chapter 11
IMAP C API Reference

This chapter describes the functions and structures of the C language API for the IMAP4 (Internet Message Access Protocol, Version 4) protocol of the Messaging Access SDK.

You'll find links to each function and structure in this introduction. Each reference entry gives the name of the function or structure, its header file, its syntax, and its parameters.

All C interface definitions are found in the imap4.h file.

[Top]

IMAP4 Functions by Functional Group

IMAP4 functions are organized into functional groups. Click the group name to find the reference entries for the functions in the group. To find functions listed in alphabetical order by name, see IMAP4 Functions by Name.

[Top] [IMAP4 Functions by Task]

IMAP4 Functions by Name

This table lists IMAP4 functions in alphabetical order by name. To find functions listed by functional group, see IMAP4 Functions by Functional Group.

imap4_append
imap4_namespace 
imap4_capability 
imap4_noop 
imap4_check 
imap4_processResponses 
imap4_close 
imap4_rename 
imap4_copy
imap4_select
imap4_connect
imap4_sendCommand
imap4_create
imap4_setChunkSize 
imap4_delete
imap4_set_option
imap4_deleteACL
imap4_setResponseSink
imap4_disconnect
imap4_setTimeout
imap4_examine 
imap4_search
imap4_expunge
imap4_setACL 
imap4_fetch
imap4Sink_initialize
imap4_free
imap4Sink_free
imap4_getACL
imap4_status
imap4_get_option
imap4_store
imap4_initialize
imap4_subscribe
imap4_list 
imap4Tag_free
imap4_listRights
imap4_unsubscribe 
imap4_lsub 
imap4_uidCopy
imap4_login
imap4_uidFetch
imap4_logout 
imap4_uidSearch
imap4_myRights
imap4_uidStore

[Top] [IMAP4 Functions by Name] [IMAP4 Functions by Task]

General Functions

This table lists IMAP4 General functions, which map to IMAP4 protocol commands defined in RFC 2060. For links to IMAP4 RFCs, see IMAP4 RFCs. Click the function name to get information about it.

Function Description 
imap4_connect

Connects to the IMAP server in_host through the specified port.

imap4_disconnect

Disconnects from the IMAP4 server.

imap4_free

Frees the IMAP4 client structure and its data members. 

imap4_get_option

Gets the IO model.

imap4_initialize

Allocates space for the IMAP4 client structure.

imap4_processResponses

Processes the server responses for all API commands executed prior to this command.

imap4_sendCommand

Sends the specified command to the IMAP4 server. 

imap4_setChunkSize

Sets the size of the message data chunk returned in fetchData.

imap4_set_option

Sets the IO model.

imap4_setResponseSink

Sets the response sink to the specified sink. 

imap4_setTimeout

Sets the amount of time allowed to wait for data within processsResponses before returning control to the user.

imap4Sink_free

Frees the response sink.

imap4Sink_initialize

Initializes all pointers to default pointers (empty function definitions).

imap4Tag_free

Frees the tag associated with a command.

[Top] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_connect

Connects to the IMAP server in_host through the port in_portNumber.

Syntax 

#include <imap4.h>
int imap4_connect( imap4Client_t * in_pimap4, 
                   const char * in_host,
                   unsigned short in_port, 
                   char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_host

Pointer to the name of the host to which to connect.

in_port

Number of port to which you want to connect.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

For more information, see Connecting to a Server.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.error, imap4Sink_t.ok, imap4_login,
imap4Tag_free, imap4_disconnect
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_disconnect

Disconnects from the IMAP4 server.

Syntax 

#include <imap4.h>
int imap4_disconnect( imap4Client_t * in_pimap4 );

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client to disconnect.

Returns

Description

This function closes the socket connection with the server. For more information, see Connecting to a Server.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.bye, imap4_connect, imap4_logout, imap4_close
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_free

Frees the IMAP4 client structure and its underlying data members.

Syntax 

#include <imap4.h>
int imap4_free(imap4Client_t ** in_ppimap4);

Parameters

The function has the following parameters: 
in_ppimap4

Pointer to a pointer to a client structure associated with the data members to free. Sets the pointer to the client structure to null on return.

Returns

Description

This function frees the imap4Client_t structure. When the function returns, the client structure is set to null. The user must free any pointers to opaque data.

See Also 

imap4_logout, imap4_initialize, imap4Sink_free
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_get_option

Gets the IO model.

Syntax 

#include <imap4.h>
int imap4_get_option(imap4Client_t * in_pimap4, 
                     int in_option, 
                     void* in_pOptionData);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_option

Pointer to option you want to set. See nsmail_io_fns_t. For the option that is currently supported, see "Option Definition."

in_pOptionData

Pointer to option data set with imap4_set_option.

Returns

See Also 

imap4_set_option
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_initialize

Initializes and allocates the IMAP4 client structure and sets the response sink.

Syntax 

#include <imap4.h> 
int imap4_initialize(imap4Client_t ** in_ppimap4,
                     imap4Sink_t * in_pimap4Sink);

Parameters

The function has the following parameters: 
in_ppimap4

Pointer to pointer to the IMAP4 client.

in_pimap4Sink

Pointer to an existing IMAP4 response sink.

Returns

Description

For more information, see Creating a Client.

See Also 

imap4Sink_free
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_processResponses

Processes the server responses for all API commands executed prior to this command.

Syntax 

#include <imap4.h> 
int imap4_processResponses(imap4Client_t* in_pimap4);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

Returns

Description

This function processes the server responses for API commands. It invokes the callback functions provided by the user for all responses that are available at the time of execution.

If a time-out occurs, the user can continue by calling imap4_processResponses again.

Do not call imap4_processResponses after these operations: disconnecting, the set functions, initializing and freeing the client and sink.

See Also 

imap4Sink_t
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_sendCommand

Sends the specified command to the IMAP4 server.

Syntax 

#include <imap4.h>
int imap4_sendCommand(imap4Client_t* in_pimap4,
                      const char* in_command, 
                      char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_command

Pointer to the unsupported command to send.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

You can use this function to extend the protocol to meet your application needs. Using this function, you can extend the functionality of the SDK to meet your needs by adding functions or passing different parameters to a function.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.rawResponse, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_setChunkSize

Sets the size of the message data chunk returned in fetchData.

Syntax 

#include <imap4.h> 
int imap4_setChunkSize(imap4Client_t* in_pIMAP4, 
                        int in_size);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_size

Size of chunk to set.

Returns

See Also 

imap4_setTimeout, imap4_connect
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_set_option

Sets the IO model.

Syntax 

#include <imap4.h>
int imap4_set_option(imap4Client_t* in_pimap4, 
                     int in_option, 
                     void* in_pOptionData);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_option

Pointer to option you want to set. See nsmail_io_fns_t. For the option that is currently supported, see "Option Definition."

in_pOptionData

Pointer to option data.

Returns

See Also 

imap4_get_option
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_setResponseSink

Sets the sink to the specified sink.

Syntax 

#include <imap4.h>
void imap4_setResponseSink(imap4Client_t* in_pimap4, 
                           imap4Sink_t *in_pimap4Sink);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_pimap4Sink

Pointer to the response sink to set.

Description

This function sets the sink to in_pimap4Sink. This response sink replaces the one that was passed into imap4_initialize.

See Also 

imap4_initialize
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_setTimeout

Sets the amount of time allowed to wait for data within processsResponses before returning control to the user.

Syntax 

include <imap4.h>
void imap4_setTimeout(imap4Client_t* in_pimap4, 
                      int in_timeout);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_timeout

Time-out period to set. Values, in seconds:

Description

This function sets the amount of time, in seconds, allowed to wait before returning control to the user.

See Also 

imap4_processResponses
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4Sink_free

Frees the IMAP4 response sink and its data members.

Syntax 

#include <imap4.h>
int imap4Sink_free(imap4Sink_t** out_ppimap4Sink);

Parameters

The function has the following parameters: 
out_ppimap4Sink

Pointer to a pointer to a client structure associated with the response sink to free.

Returns

Description

This function frees the IMAP4 response sink. It sets the pointer to the sink structure to null on return. The user must free any opaque data.

See Also 

imap4Sink_initialize, imap4Tag_free, imap4_free
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4Sink_initialize

Allocates space for the IMAP4 sink structure.

Syntax 

#include <imap4.h> 
int imap4Sink_initialize(imap4Sink_t** out_ppimap4Sink);

Parameters

The function has the following parameters: 
out_ppimap4Sink

Pointer to the IMAP4 client.

Returns

Description

This function initializes all pointers to default pointers (empty function definitions) and allocates the space for the imap4Sink structure.

For more information, see Creating a Response Sink and SDK Response Sinks for C.

See Also 

imap4Sink_t, imap4_connect, imap4_noop, 
imap4Sink_free, imap4_initialize
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4Tag_free

Frees the tag associated with an IMAP4 command.

Syntax 

#include <imap4.h>
int imap4Tag_free(char** out_ppimap4Tag);

Parameters

The function has the following parameters: 
out_ppimap4Tag

Pointer to pointer to the tag to free.

Returns

Description

Many functions allocate tags that can be associated with an IMAP4 command. Any function that allocates a tag must use imap4Tag_free to free the memory associated with the tag. This function frees the tag and sets the tag pointer to null on return.

The tag (out_ppTagID) generated by the IMAP4 functions can be used to help match the command and the response associated with it within the imap4Sink_t.taggedLine response.

See Also 

imap4_logout, imap4Sink_free, imap4_free, imap4Sink_t.taggedLine
[Top] [General Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

Non-Authenticated State Functions

Non-Authenticated State functions can occur before login. For links to IMAP4 RFCs, see IMAP4 RFCs. Click the function name to get information about it.

Function Description 
imap4_capability

Requests a listing of capabilities that the server supports. 

imap4_login

Identifies the client to the server with the user password.

imap4_logout

Informs the server that the client is done with the connection. 

imap4_noop

Issues a command that always succeeds and does nothing.

[Top] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_capability

Requests a listing of capabilities that the server supports.

Syntax 

#include <imap4.h> 
int imap4_capability(imap4Client_t* in_pimap4, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function returns a listing of the IMAP4 extensions and authentication mechanisms that are supported by the server. It sends the CAPABILITY IMAP4 protocol command. For more information, see Determining Server Capabilities.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.capability, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_connect, imap4Tag_free
[Top] [Non-Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_login

Identifies the client to the server and carries the plain text password that authenticates this user.

Syntax 

#include <imap4.h> 
int imap4_login(imap4Client_t* in_pimap4, 
                const char* in_user, 
                const char* in_password, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_user

Pointer to the user name.

in_password

Pointer to the user password.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function identifies the client to the server and carries the plain text password that authenticates this user. It sends the LOGIN IMAP4 protocol command. For more information, see Logging In and Out.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error,
imap4_logout, imap4Tag_free
[Top] [Non-Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_logout

Informs the server that the client is done with the connection.

Syntax 

#include <imap4.h> 
int imap4_logout(imap4Client_t* in_pimap4, 
                  char** out_ppTagID );

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function closes the connection and logs the user out. It sends the LOGOUT IMAP4 protocol command. For more information, see Logging In and Out.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.bye, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_close, imap4Tag_free
[Top] [Non-Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_noop

Issues a command that always succeeds and does nothing.

Syntax 

#include <imap4.h> 
int imap4_noop(imap4Client_t* in_pimap4, 
               char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function issues a command that should always succeed. it sends the NOOP IMAP4 protocol command. In itself, imap4_noop does nothing, but it induces useful side effects.

Most IMAP4 servers check for messages whenever a command is issued. In the absence of commands, the server does not check for messages and may disconnect. To keep the server open indefinitely and check for messages periodically, the developer could call imap4_noop at set intervals.

The imap4_noop function does nothing in itself, so it is ideal for polling for new mail and ensuring that the server connection is still active. imap4_noop resets the autologout timer inside the server and results in the retrieval of unsolicited server responses. This may indicate the arrival of new messages or a change in the attributes of an existing message. For an example, see Checking for New Messages.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Remember to use imap4Tag_free to free the memory associated with the tag allocated by this function. §

See Also 

imap4Sink_t.exists, imap4Sink_t.expunge, 
imap4Sink_t.recent, imap4Sink_t.fetchStart, 
imap4Sink_t.fetchFlags, imap4Sink_t.fetchEnd, 
imap4Sink_t.taggedLine, imap4Sink_t.error,
imap4_connect, imap4Tag_free
[Top] [Non-Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

Authenticated State Functions

Authenticated State functions provide operations involving mailboxes. Before these functions are available, login must take place.

Function Description 
imap4_append

Appends a message to the specified mailbox.

imap4_create

Creates a mailbox with the given name. 

imap4_delete

PERMANENTLY removes the mailbox with the given name. 

imap4_examine

Selects a server mailbox for read-only access. 

imap4_list

Lists the mailboxes.

imap4_lsub

Returns a subset of user-defined "active" or "subscribed" names.

imap4_rename

Renames a mailbox. 

imap4_select

Selects a mailbox on the server.

imap4_status

Request the status of a particular mailbox.

imap4_subscribe

Adds the specified mailbox name to the server's set of "active" or "subscribed" mailboxes.

imap4_unsubscribe

Removes a mailbox from server's subscribed mailbox list.

[Top] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_append

Appends a message to the specified mailbox.

Syntax 

#include <imap4.h> 
int imap4_append( imap4Client_t* in_pimap4, 
                  const char* in_mailbox,
                  const char* in_optFlags, 
                  const char* in_optDateTime, 
                  nsmail_inputstream_t* in_literal,
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to which to append message.

in_optFlags

Pointer to a list of optional flags in parentheses.

in_optDateTime

Pointer to optional date/time string.

in_pInputLiteralStream

Pointer to the message literal.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function appends a literal argument as a new message to the end of the specified mailbox.

This function sends the APPEND IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error,
imap4_noop, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_create

Creates a mailbox with the given name.

Syntax 

#include <imap4.h>
int imap4_create( imap4Client_t* in_pimap4, 
                  const char* in_mailbox, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to create.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function creates a mailbox with the given name. If you want to create a directory on the server side, be careful to use the correct separator character.

This function sends the CREATE IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_delete, imap4_rename, 
imap4_subscribe, imap4_unsubscribe, 
imap4_list, imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_delete

PERMANENTLY removes the mailbox with the given name.

Syntax 

#include <imap4.h> 
int imap4_delete( imap4Client_t* in_pimap4, 
                  const char* in_mailbox, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to delete.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function PERMANENTLY removes the mailbox with the given name. You cannot and should not DELETE the INBOX. The system needs it.

This function sends the DELETE IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_store, imap4_create,
imap4_rename, imap4_examine, imap4_subscribe,
imap4_unsubscribe, imap4_list,
imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_examine

Selects a server mailbox for read-only access.

Syntax 

#include <imap4.h>
int imap4_examine(imap4Client_t* in_pimap4, 
                  const char* in_mailbox, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to examine.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

When issued in the Authorization state, this function sends the EXAMINE IMAP4 protocol command, which moves the IMAP4 session into the Selected state. This function selects a mailbox on the server and makes it available for operations that involve read-only access to messages, such as checking, closing, searching, fetching, and copying.

The imap4_select function works like imap4_examine, except that it selects the mailbox and its messages with update access. The user can perform operations that permanently alter the mailbox, such as storing or expunging.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.flags, imap4Sink_t.exists, imap4Sink_t.recent, 
imap4Sink_t.ok, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_select, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_list

Lists the names of mailboxes matching the specified pattern.

Syntax 

#include <imap4.h> 
int imap4_list(imap4Client_t* in_pimap4, 
               const char* in_refName, 
               const char* in_mailbox, 
               char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_refName

Pointer to the mailbox name within which you want to search.

in_mailbox

Pointer to a mailbox name with possible wild cards.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function lists a subset of all names available to the client and returns the tag associated with this function. The names listed must match the pattern given in the in_mailbox and in_refName parameters.

This function sends the LIST IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.list, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_lsub, imap4_create, 
imap4_delete, imap4_rename, imap4_subscribe, 
imap4_unsubscribe, imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_lsub

Returns a subset of user-defined "active" or "subscribed." names.

Syntax 

#include <imap4.h>
int imap4_lsub( imap4Client_t* in_pimap4, 
               const char* in_refName, 
               const char* in_mailbox, 
               char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_refName

Pointer to the reference name.

in_mailbox

Pointer to a mailbox name with possible wild cards. 

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function returns a subset of names from the set of names that the user has declared as "active" or "subscribed."

This function sends the LSUB IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.lsub, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_list, imap4_create, 
imap4_delete, imap4_rename, imap4_subscribe, 
imap4_unsubscribe, imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_rename

Renames a mailbox.

Syntax 

#include <imap4.h>
int imap4_rename( imap4Client_t* in_pimap4, 
                  const char* in_currentMB, 
                  const char* in_newMB, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_currentMB

Pointer to the mailbox's current name.

in_newMB

Pointer to the mailbox's new name.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function sends the RENAME IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_select, 
imap4_create, imap4_delete, 
imap4_subscribe, imap4_unsubscribe, 
imap4_list, imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_select

Selects a mailbox on the server.

Syntax 

#include <imap4.h> 
int imap4_select( imap4Client_t* in_pimap4, 
                const char* in_mailbox, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to select.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

When issued in the Authorization state, this function sends the SELECT IMAP4 protocol command, which moves the IMAP4 session into the Selected state. This function selects a mailbox on the server and makes it available for operations that involve messages, such as checking, closing, searching, fetching, copying, storing, and expunging.

The imap4_examine function works like imap4_select, except that it selects the mailbox and its messages with read-only access. Operations that permanently alter the mailbox, such as storing, are not available.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.flags, imap4Sink_t.exists, 
imap4Sink_t.recent, imap4Sink_t.ok, 
imap4Sink_t.taggedLine, imap4Sink_t.error,
imap4_examine, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_status

Requests the status of the indicated mailbox.

Syntax 

#include <imap4.h> 
int imap4_status(imap4Client_t* in_pimap4, 
               const char* in_mailbox, 
               const char* in_statusData, 
               char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox_name

Pointer to the name of mailbox for which to get status.

in_statusData

Pointer to status data: All or a subset of MESSAGES, RECENT, UID_NEXT, UID_VALIDITY, UNSEEN.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function requests one or more types of status from the specified mailbox. It sends the STATUS IMAP4 protocol command.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.statusMessages, imap4Sink_t.statusRecent,
imap4Sink_t.statusUidnext, imap4Sink_t.statusUidvalidity,
imap4Sink_t.statusUnseen, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_subscribe

Adds the specified mailbox name to the server's set of "active" or "subscribed" mailboxes.

Syntax 

#include <imap4.h> 
int imap4_subscribe( imap4Client_t* in_pimap4, 
                     const char* in_mailbox, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to which to add subscriber.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function sends the SUBSCRIBE IMAP4 protocol command.

To access the list of the server's set of "active" or "subscribed" mailboxes, use the LSUB protocol command through the imap4_lsub function.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_lsub, imap4_create, 
imap4_delete, imap4_rename,
imap4_unsubscribe, imap4_list, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_unsubscribe

Removes mailbox from server's subscribed mailbox list.

Syntax 

#include <imap4.h> 
int imap4_unsubscribe(imap4Client_t* in_pimap4, 
                     const char* in_mailbox, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the name of mailbox to remove from subscribed list.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function removes the specified mailbox name from the server's set of "active" or "subscribed" mailboxes. To do this, it sends the UNSUBSCRIBE IMAP4 protocol command.

NOTE: Use imap4Tag_free to free the associated tag. §
This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_subscribe, imap4_create, imap4_delete, 
imap4_rename, imap4_list, imap4_lsub, imap4Tag_free
[Top] [Authenticated State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

Selected State Functions

Selected State functions provide operations involving messages. Before these functions are available, login must take place and the mailbox must be selected. For links to IMAP4 RFCs, see IMAP4 RFCs. Click the function name to get information about it.

Function Description 
imap4_check

Requests a checkpoint of the currently selected mailbox.

imap4_close

Closes the mailbox.

imap4_copy

Copies the specified message(s) from the currently selected mailbox to the end of the specified destination mailbox.

imap4_expunge

Removes all messages flagged for deletion.

imap4_fetch

Retrieves data specified by the fetch criteria for the given message set and returns the corresponding message sequence numbers.

imap4_search

Search the mailbox for messages that match the given search criteria and retrieve the corresponding message sequence numbers.

imap4_store

Alters data associated with a message in the mailbox.

imap4_uidCopy

Copies messages specified with a unique identifier.

imap4_uidFetch

Fetches messages specified with a unique identifier and retrieves the corresponding unique identifiers.

imap4_uidSearch

Searches the mailbox for messages that match your search criteria and retrieve the corresponding unique identifiers.

imap4_uidStore

Updates message data associated with a unique identifier.

[Top] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_check

Requests a checkpoint of the currently selected mailbox.

Syntax 

#include <imap4.h> 
int imap4_check(imap4Client_t* in_pimap4, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function requests a checkpoint of the currently selected mailbox and flushes existing mailbox states to disk. Function behavior may be different, depending on the server implementation. It returns a tag.

This function sends the CHECK IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_close

Closes the mailbox.

Syntax 

#include <imap4.h>
int imap4_close(imap4Client_t* in_pimap4, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function closes a mailbox and removes any messages marked with the \Deleted flag. The session moves to the mailbox that contains the closed mailbox. This function sends the CLOSE IMAP4 protocol command. If you need to remove messages without closing, use imap4_expunge. Also see Closing a Mailbox.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_logout, imap4_expunge, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_copy

Copies the specified message(s) from the currently selected mailbox to the end of the specified destination mailbox.

Syntax 

#include <imap4.h> 
int imap4_copy( imap4Client_t* in_pimap4, 
                const char* in_msgSet, 
                const char* in_mailbox, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the message numbers to copy, for example, "1:2".

in_mailbox

Pointer to the name of target mailbox.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function sends the COPY IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_store,
imap4_expunge, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_expunge

Removes all messages flagged for deletion.

Syntax 

#include <imap4.h> 
int imap4_expunge(imap4Client_t* in_pimap4, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function removes all messages in the mailbox that have the \Deleted flag. As described in RFC 2060, when a message is expunged, all messages with higher numbers are automatically decremented by one. This happens BEFORE this call returns, so, immediately following this call, you should decide whether you need to make adjustments to this change in the state of the message cache. Also see Closing a Mailbox.

This function sends the EXPUNGE IMAP4 protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Sink_t.expunge, 
imap4_delete, imap4_close, imap4_store,
imap4_copy, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_fetch

Retrieves data specified by the fetch criteria for the given message set and returns the corresponding message sequence numbers.

Syntax 

#include <imap4.h> 
int imap4_fetch(imap4Client_t* in_pimap4, 
                const char* in_msgSet, 
                const char* in_fetchCriteria, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the message set.

in_fetchCriteria

Pointer to the criteria that fetched messages must meet. See the RFC 2060 Fetch Data Items table below for RFC 2060 values for this parameter. 

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function retrieves the data specified by the fetch criteria for the given message set. You can specify a variety of fetch criteria, as shown in Table 11.1 in this section. These fetch criteria are defined in RFC 2060. If you specify more than one item, place the items in a parenthesized list. This function sends the FETCH IMAP4 protocol command.

For more information, see Fetching Message Data.

Table 11.1 RFC 2060 Fetch Data Items

Data Item Description 
ALL

Combines FLAGS, INTERNALDATE, ENVELOPE, RFC822.SIZE

BODY

[MIME-IMB] body structure of the message, not non-extensible

BODY[<section>]<<partial>>

text of a particular body section; sets \Seen flag.
section: zero or more part specifiers separated by periods, for example HEADER, HEADER.FIELDS.
partial: whether fetch is partial

BODY.PEEK[<section>]<<partial>>

alternate to BODY[<section>]; does not set \Seen flag

BODYSTRUCTURE

[MIME-IMB] body structure of the message,

ENVELOPE

message's envelope structure

FAST

combines FLAGS, INTERNALDATE, RFC822.SIZE

FLAGS

flags set for this message

FULL

combines FLAGS, INTERNALDATE, RFC822.SIZE, ENVELOPE, BODY

INTERNALDATE

message's internal data

RFC822

equivalent to BODY[], but with different syntax in the resulting untagged FETCH data

RFC822.HEADER

equivalent to BODY.PEEK[HEADER], but with different syntax in the resulting untagged FETCH data

RFC822.SIZE

message size

RFC822.TEXT

equivalent to BODY[TEXT], but with different syntax in the resulting untagged FETCH 

UID

unique identifier of the message

 This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.fetchStart, imap4Sink_t.fetchEnd,
imap4Sink_t.fetchSize, imap4Sink_t.fetchData,
imap4Sink_t.fetchFlags, imap4Sink_t.fetchBodyStructure,
imap4Sink_t.fetchEnvelope, imap4Sink_t.fetchInternalDate,
imap4Sink_t.fetchHeader, imap4Sink_t.taggedLine, 
imap4Sink_t.error, imap4_search, 
imap4_uidFetch, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_search

Search the selected mailbox for messages that match your search criteria and retrieve the corresponding message sequence numbers.

Syntax 

#include <imap4.h> 
int imap4_search( imap4Client_t* in_pimap4, 
                  const char* in_criteria, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_criteria

Pointer to search criteria consisting of one or more search keys. See the Search Function Search Keys table below for RFC 2060 values for this parameter.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function retrieves the message numbers that correspond to the search criteria. You can specify a variety of search criteria, as shown in Table 11.2 in this section. These fetch criteria are defined in RFC 2060. If you specify more than one item, place the items in a parenthesized list. This function sends the SEARCH IMAP4 protocol command.

For more information, see Searching for Messages.

Table 11.2 Search Function Search Keys

Search Key Search for messages with: 
<message set>

Message sequence numbers corresponding to specified Message sequence number set

ALL

All messages in mailbox; default initial key for ANDing

ANSWERED

\Answered flag set

BCC <string>

Specified string in envelope's BCC field.

BEFORE <date>

Internal date earlier than specified date.

BODY <string>

Specified string in message body

CC <string>

Specified string in the envelope structure's CC field.

DELETED

\Deleted flag set.

DRAFT

\Draft flag set.

FLAGGED

\Flagged flag set.

FROM <string>

Specified string in the envelope structure's FROM field.

HEADER <field-name> <string>

Header with specified field-name (as defined in [RFC-822]) and that specified string in [RFC-822] field-body.

KEYWORD <flag>

Specified keyword set.

LARGER <n>

[RFC-822] size larger than the specified number of octets.

NEW

\Recent flag set but not the \Seen flag. This is functionally equivalent to "(RECENT UNSEEN)".

NOT <search-key>

Do not match the specified search key.

OLD

No \Recent flag set; equivalent to "NOT RECENT" (as opposed to "NOT NEW").

ON <date>

Internal date within the specified date.

OR <search-key1> <search-key2>

Match either search key.

RECENT

\Recent flag set.

SEEN

\Seen flag set.

SENTBEFORE <date>

[RFC-822] Date: header earlier than specified date.

SENTON <date>

[RFC-822] Date: header within specified date.

SENTSINCE <date>

[RFC-822] Date: header within or later than specified date.

SINCE <date>

Internal date is within or later than specified date.

SMALLER <n>

[RFC-822] size smaller than specified number of octets.

SUBJECT <string>

Specified string in envelope structure's SUBJECT field.

TEXT <string>

Specified string in header or body of message.

TO <string>

Specified string in envelope structure's TO field.

UID <message set>

Unique identifiers corresponding to specified unique identifier set.

UNANSWERED

No \Answered flag set.

UNDELETED

No \Deleted flag set.

UNDRAFT

No \Draft flag set.

UNFLAGGED

No \Flagged flag set.

UNKEYWORD <flag>

No specified keyword set.

UNSEEN

No \Seen flag set.

 This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.searchStart, imap4Sink_t.search,
imap4Sink_t.searchEnd, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_fetch, 
imap4_uidSearch, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_store

Alters data associated with one or more messages in the mailbox.

Syntax 

#include <imap4.h> 
int imap4_store(imap4Client_t* in_pimap4, 
                const char* in_msgSet, 
                const char* in_dataItem, 
                const char* in_value, 
                char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the message set.

in_dataItem

Pointer to the data items you can search for. See the Data Item in the Store Function Data Items table below for RFC 2060 values for this parameter.

in_value

Pointer to the value for the message data item. See the Value item in the Store Function Data Items table below for RFC 2060 values for this parameter.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function sends the STORE IMAP4 protocol command.

Table 11.3 Store Function Data Items

Data Item Value Description 
FLAGS
<flag list>

Replace message flags with items in flag list. Returns the new value of the flags.

FLAGS.SILENT
<flag list>

Like FLAGS, but does not return a new value.

+FLAGS
<flag list>

Add the items in flag list to the message flags. Returns the new value of the flags.

+FLAGS.SILENT
<flag list>

Like +FLAGS, but does not return a new value.

-FLAGS
<flag list>

Remove the items in flag list from the message flags. Returns the new value of the flags.

-FLAGS.SILENT
<flag list>

Like -FLAGS, but does not return a new value.

 You can find a link to RFC 2060 in IMAP4 RFCs.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_delete, 
imap4_copy, imap4_expunge, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_uidCopy

Copies messages specified with a unique identifier.

Syntax 

#include <imap4.h> 
int imap4_uidCopy(imap4Client_t* in_pimap4, 
                  const char* in_msgSet, 
                  const char* in_mailbox, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the unique message identifiers (UIDs) to copy, for example, "1:2"

in_mailbox

Pointer to the name of target mailbox.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Functions whose names start with UID use a unique identifier to specify messages rather than sequence numbers. This function uses the UID IMAP4 protocol command to specify that the COPY command uses unique message identifiers.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_copy, 
imap4_expunge, imap4_store, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_uidFetch

Fetches messages specified with a unique identifier and retrieves the corresponding unique identifiers.

Syntax 

#include <imap4.h> 
int imap4_uidFetch ( imap4Client_t* in_pimap4, 
                     const char* in_msgSet, 
                     const char* in_fetchCriteria, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the unique message identifiers (UIDs) to fetch, for example, "1:2".

in_fetchCriteria

Pointer to the message data item names; criteria that fetched messages must meet. See the RFC 2060 Fetch Data Items table below for RFC 2060 values for this parameter. 

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function retrieves the data specified by the fetch criteria for the given message set. You can specify a variety of fetch criteria, as shown in Table 11.1 in this section. If you pass more than one item, they should be in a parenthesized list. For more information, see Fetching Message Data.

Functions whose names start with UID use a unique identifier to specify messages rather than sequence numbers. This function uses the UID IMAP4 protocol command to specify that the FETCH command uses unique message identifiers.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.fetchStart, imap4Sink_t.fetchEnd,
imap4Sink_t.fetchSize, imap4Sink_t.fetchData,
imap4Sink_t.fetchFlags, imap4Sink_t.fetchBodyStructure,
imap4Sink_t.fetchEnvelope, imap4Sink_t.fetchInternalDate,
imap4Sink_t.fetchHeader, imap4Sink_t.fetchUid,
imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_search, imap4_uidFetch, imap4Tag_free,
imap4_fetch
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_uidSearch

Searches the mailbox for messages that match your search criteria and retrieve the corresponding unique identifiers.

Syntax 

#include <imap4.h> 
int imap4_uidSearch( imap4Client_t* in_pimap4, 
                     const char* in_criteria, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_criteria

Pointer to the search criteria consisting of one or more search keys. See the Search Function Search Keys table in the imap4_search function entry for RFC 2060 values for this parameter.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

You can specify a variety of search criteria, as shown in Table 11.2 in this section. If you specify more than one item, place them in a parenthesized list. For more information, see Searching for Messages.

Functions whose names start with UID use a unique identifier to specify messages rather than sequence numbers that match the search criteria. This function uses the UID imap4 protocol command to specify that the SEARCH command returns unique message identifiers.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.searchStart, imap4Sink_t.search,
imap4Sink_t.searchEnd, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_search,
imap4_uidStore, imap4_uidFetch, 
imap4_uidCopy, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_uidStore

Updates message data associated with a unique identifier.

Syntax 

#include <imap4.h> 
int imap4_uidStore(imap4Client_t* in_pimap4, 
                   const char* in_msgSet, 
                   const char* in_dataItem, 
                   const char* in_value, 
                   char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_msgSet

Pointer to the message set, specified as unique identifiers.

in_dataItem

Pointer to the message data item name.

in_value

Pointer to the value for the message data item.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Functions whose names start with UID use a unique identifier to specify messages rather than sequence numbers. This function uses the UID IMAP4 protocol command to specify that the STORE command uses unique message identifiers.

This function is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine, imap4Sink_t.error,
imap4_uidSearch, imap4_uidStore, imap4_uidFetch, 
imap4_uidCopy, imap4_store, imap4Tag_free
[Top] [Selected State Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

Extended IMAP4 Functions

Extended IMAP4 Functions provide operations involving IMAP4 extensions, such as ACL (access control list) and rights. Before these functions are available, login must take place. To find out if the server supports any extensions, use the imap4_capability function.

For details about extensions to IMAP4, see RFC 2086. For links to IMAP4 RFCs, see IMAP4 RFCs. Click the function name to get information about it.

NOTE: Only Message Server 4.0 supports the ACL and Namespace extensions. §

Function Description 
imap4_deleteACL

Removes an identifier from the access control list for a mailbox.

imap4_getACL

Gets the access control list for a mailbox.

imap4_listRights

Finds which rights you can grant a specified user to a particular mailbox. 

imap4_myRights

Retrieves the rights that the user has to a mailbox.

imap4_namespace

Finds the prefixes of namespaces used by a server for personal mailboxes, other user's mailboxes, and shared objects.

imap4_setACL

Changes the access control list to grant specified permissions to an identifier for a mailbox.

[Top] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_deleteACL

Remove an identifier from the access control list for a mailbox.

Syntax 

#include <imap4.h> 
int imap4_deleteACL( imap4Client_t* in_pimap4, 
                     const char* in_mailbox, 
                     const char* in_authID, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the mailbox.

in_authID

Pointer to the authentication identifier.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

This function revokes a user's rights to a mailbox. Given the mailbox name and an identifier, it removes the identifier/rights pair from the access control list.

This function sends the DELETEACL protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_getACL, 
imap4_setACL, imap4Tag_free
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_getACL

Gets the access control list for a mailbox in an untagged ACL reply.

Syntax 

#include <imap4.h> 
int imap4_getACL( imap4Client_t* in_pimap4, 
                  const char* in_mailbox, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the mailbox.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

An access control list is made up of a set of <identifier, rights> pairs. The identifier represents the authorized user. Rights include any operations that the user can perform a mailbox. These can include lookup, read, write, post, create, delete, or keep information seen or unseen. For details, see RFC 2086.

This function sends the GETACL protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.aclStart, imap4Sink_t.aclIdentifierRight, 
imap4Sink_t.aclEnd, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free, 
imap4_deleteACL, imap4_setACL
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_listRights

Find which rights you can grant a specified user to a particular mailbox.

Syntax 

#include <imap4.h> 
int imap4_listRights(imap4Client_t* in_pimap4, 
                     const char* in_mailbox, 
                     const char* in_authID, 
                     char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the mailbox.

in_authID

Pointer to the authentication identifier.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Given the mailbox name and an identifier, this function tells which rights you can grant a specified user to a particular mailbox using the imap4_setACL function. The access control list is returned in an untagged ACL reply.

This function sends the LISTRIGHTS protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.listRightsStart,
imap4Sink_t.listRightsRequiredRights,
imap4Sink_t.listRightsOptionalRights,
imap4Sink_t.listRightsEnd, imap4_setACL, 
imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_myRights, imap4Tag_free
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_myRights

Retrieves the set of rights that the user has to a mailbox.

Syntax 

#include <imap4.h> 
int imap4_myRights(imap4Client_t* in_pimap4, 
                   const char* in_mailbox,
                   char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the mailbox.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Rights include any operations that the user can perform a mailbox. These can include lookup, read, write, post, create, delete, or keep information seen or unseen. For details, see RFC 2086.

This function sends the MYRIGHTS protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.myRights, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4_listRights, 
imap4Tag_free
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_namespace

Finds the prefixes of namespaces used by a server for personal mailboxes, other user's mailboxes, and shared mailboxes.

Syntax 

#include <imap4.h> 
int imap4_nameSpace( imap4Client_t* in_pimap4,
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Different types of mailbox stores, such as newsgroups or corporate mailboxes, have their own namespace identifiers. The namespace is identified by prefixing # and the store name at the beginning of the mailbox address. For example, #news can identify an address as a newsgroup mailbox name.

This function issues the NAMESPACE command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.nameSpaceStart, 
imap4Sink_t.nameSpacePersonal,
imap4Sink_t.nameSpaceOtherUsers, 
imap4Sink_t.nameSpaceShared,
imap4Sink_t.nameSpaceEnd, imap4Sink_t.taggedLine,
imap4Sink_t.error, imap4Tag_free
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

imap4_setACL

Changes the access control list to grant specified permissions to an identifier for a mailbox.

Syntax 

#include <imap4.h> 
int imap4_setACL( imap4Client_t* in_pimap4, 
                  const char* in_mailbox, 
                  const char* in_authID, 
                  const char* in_accessRight, 
                  char** out_ppTagID);

Parameters

The function has the following parameters: 
in_pimap4

Pointer to the IMAP4 client.

in_mailbox

Pointer to the mailbox.

in_authID

Pointer to the authentication identifier.

in_accessRight

Pointer to access rights to grant.

out_ppTagID

Pointer to pointer to the tag associated with the function. Use imap4Tag_free to free the associated memory.

Returns

Description

Functions that have ACL in their names are able to manipulate the access control list (ACL), as described in RFC 2086. You can find out if the server supports ACL by issuing the imap4_capability command.

The identifier specified in the in_authID parameter is granted rights as specified in the in_accessRight parameter. Rights include any operations that the user can perform a mailbox. These can include lookup, read, write, post, create, delete, or keep information seen or unseen. For details, see RFC 2086.

This function sends the SETACL protocol command. It is mapped to one or more callbacks in the imap4Sink_t structure. For more information, see IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free the associated tag. §

See Also 

imap4Sink_t.aclStart, 
imap4Sink_t.taggedLine, imap4Sink_t.error, 
imap4_deleteACL, imap4_getACL, 
imap4_myRights, imap4Tag_free
[Top] [Extended IMAP4 Functions] [IMAP4 Functions by Functional Group] [IMAP4 Functions by Task]

IMAP4 Structures

This section defines IMAP4 data structures, listed in alphabetical order.

imap4Client_t

 imap4Sink_t

[Top]

imap4Client_t

Contains a reference to all major objects within the IMAP SDK, including data members.

Syntax 

#include <imap4.h> 
typedef struct IMAP4 imap4Client_t;

Description

The client uses this structure to communicate with an IMAP4 server. The developer uses this structure to perform IMAP4 API operations. All data contained within the client structure is used internally by the API. For more information, see Creating a Client.

See Also 

imap4Sink_t
[Top] [IMAP4 Structures]

imap4Sink_t

Represents the response sink for all IMAP4 commands.

Syntax 

#include <imap4.h> 
typedef struct IMAP4Sink 
{ 
void *pOpaqueData;
void (*taggedLine)(
            imap4SinkPtr_t in_pimap4Sink, 
            char* in_tag, 
            const char* in_status, 
            const char* in_reason);
void (*error)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_tag, 
            const char* in_status, 
            const char* in_reason); 
void (*ok)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_responseCode, 
            const char* in_information); 
void (*rawResponse)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_data); 
/*Fetch Response*/ 
void* (*fetchStart)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_msg); 
void (*fetchEnd)(
            imap4SinkPtr_t in_pimap4Sink); 
void (*fetchSize)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_size); 
void (*fetchData)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_data,
            int in_bytesRead, 
            int in_totalBytes); 
void (*fetchFlags)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_flags); 
void (*fetchBodyStructure)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_bodyStructure);
void (*fetchEnvelope)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char** in_value,
            int in_valueLength); 
void (*fetchInternalDate)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_internalDate); 
void (*fetchHeader)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_field, 
            const char* in_value); 
void (*fetchUid)(imap4SinkPtr_t in_pimap4Sink, 
            int in_uid); 
/*Lsub Response*/ 
void (*lsub)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_attribute, 
            const char* in_delimeter, 
            const char* in_name); 
/*List Response*/ 
void (*list)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_attribute, 
            const char* in_delimeter, 
            const char* in_name); 
/*Search Response*/ 
void* (*searchStart)(
            imap4SinkPtr_t in_pimap4Sink); 
void (*search)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_message); 
void (*searchEnd)(
            imap4SinkPtr_t in_pimap4Sink); 
/*Status Response*/ 
void (*statusMessages)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_messages); 
void (*statusRecent)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_recent); 
void (*statusUidnext)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_uidNext); 
void (*statusUidvalidity)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_uidValidity); 
void (*statusUnseen)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_unSeen); 
/*Capability Response*/ 
void (*capability)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_listing); 
/*Exists Response*/ 
void (*exists)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_messages); 
/*Expunge Response*/ 
void (*expunge)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_message); 
/*Recent Response*/ 
void (*recent)(
            imap4SinkPtr_t in_pimap4Sink, 
            int in_messages); 
/*Flags Response*/ 
void (*flags)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_flags); 
/*Bye Response*/ 
void (*bye)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_reason); 
/*Namespace Response*/ 
void* (*nameSpaceStart)(
            imap4SinkPtr_t in_pimap4Sink); 
void (*nameSpacePersonal)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_personal); 
void (*nameSpaceOtherUsers)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_otherUsers);
void (*nameSpaceShared)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_shared); 
void (*nameSpaceEnd)(
            imap4SinkPtr_t in_pimap4Sink); 
/*ACL Responses*/ 
void* (*aclStart)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_mailbox);
void (*aclIdentifierRight)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_identifier, 
            const char* in_rights);
void (*aclEnd)(imap4SinkPtr_t in_pimap4Sink); 
/*LISTRIGHTS Responses*/ 
void* (*listRightsStart)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_mailbox, 
            const char* in_identifier); 
void (*listRightsRequiredRights)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_requiredRights); 
void (*listRightsOptionalRights)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_optionalRights); 
void (*listRightsEnd)(
            imap4SinkPtr_t in_pimap4Sink); 
/*MYRIGHTS Responses*/ 
void (*myRights)(
            imap4SinkPtr_t in_pimap4Sink, 
            const char* in_mailbox, 
            const char* in_rights); 
}imap4Sink_t;

Fields

The structure has the following fields:
void *pOpaqueData;

Opaque user data.

void (*taggedLine)(
   imap4SinkPtr_t in_pimap4Sink, 
   char* in_tag, 
   const char* in_status, 
   const char* in_reason);

Tagged line. Indicates the end of response(s) for successful commands. Parameters: the response sink to use, the tag associated with the command, response code, descriptive text.

void (*error)(
   imap4SinkPtr_t in_pimap4Sink,
   const char* in_tag,
   const char* in_status,
   const char* in_reason);

Notification of an error. Indicates the response for unsuccessful commands. Parameters: the response sink to use, the tag associated with the command, response code, descriptive text.

void (*ok)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_responseCode, 
   const char* in_information);

Unsolicited OK response. Parameters: the response sink to use, response code, additional text.

void (*no)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_responseCode, 
   const char* in_information);

NO response. Indicates an operational error message from the server. Parameters: the response sink to use, response code, additional text.

void (*bad)(
   imap4SinkPtr_t in_pimap4Sink,
   const char* in_responseCode,
   const char* in_information);

BAD response: Indicates an error message for the server. Parameters: the response sink to use, response code, additional text.

xvoid (*rawResponse)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_data);

Raw (unparsed) data is pushed into here. Parameters: the response sink to use, raw data.

void* (*fetchStart)(
   imap4SinkPtr_t in_pimap4Sink,
   int in_msg);

Indicates the beginning of a fetch response. Parameters: the response sink to use, the message number.

void (*fetchEnd)(
   imap4SinkPtr_t in_pimap4Sink);

Indicates that the data for this message is completely fetched. Parameter: the response sink to use.

void (*fetchSize)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_size);

Size of the message. Parameters: the response sink to use, size of message.

void (*fetchData)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_data, 
   int in_bytesRead, 
   int in_totalBytes);

Fetches data associated with specific data items. Parameters: the response sink to use, message data, number of bytes read, total number of bytes to be returned.

void (*fetchFlags)(
   imap4SinkPtr_t in_pimap4Sink,
   const char* in_flags);

Fetches the value of the flags. Parameters: the response sink to use, flags on the message.

void (*fetchBodyStructure)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_bodyStructure);

Fetches the value of the body structure. Parameters: the response sink to use, message body structure.

void (*fetchEnvelope)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char** in_value, 
   int in_valueLength);

Fetches the value of the envelope. Parameters: the response sink to use, an array of the envelope fields, length of the in_value array.

void (*fetchInternalDate)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_internalDate);

Fetches the value of the internal date. Parameters: the response sink to use, internal date.

void (*fetchHeader)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_field, 
   const char* in_value);

Fetches the value of the header. Parameters: the response sink to use, followed by name and value parts of header name:value pair.

void (*fetchUid)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_uid);

Fetches the value of the unique ID of the message. Parameters: the response sink to use, unique id of message.

void (*lsub)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_attribute, 
   const char* in_delimeter, 
   const char* in_name);

Lists subscribed or active mailboxes that match the search criteria. Parameters: the response sink to use, attribute message, delimiter of message, mailbox name.

void (*list)(
   imap4SinkPtr_t in_pimap4Sink,
   const char* in_attribute,
   const char* in_delimeter, 
   const char* in_name);

Lists mailboxes that match the search criteria. Parameters: the response sink to use, attribute message, delimiter of message, mailbox name.

void* (*searchStart)(
   imap4SinkPtr_t in_pimap4Sink);

Indicates the start of the retrieval of messages numbers that match the search criteria. Parameter: response sink to use.

void (*search)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_message);

Gets the messages that match the search criteria. Parameters: the response sink to use, message to search for.

void (*searchEnd)(
   imap4SinkPtr_t in_pimap4Sink);

Indicates the end of the retrieval of message numbers that match the search criteria. Parameter: the response sink to use.

void (*statusMessages)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_messages);

Total number of messages. Parameters: the response sink to use, messages to count.

void (*statusRecent)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_recent);

Number of messages with the recent flag set. Parameter: the response sink to use.

void (*statusUidnext)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_uidNext);

UID value to assign to a new message in the mailbox. Parameters: the response sink to use, unique id of the next message.

void (*statusUidvalidity)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_uidValidity);

UID validity value of the mailbox. Parameters: the response sink to use, unique id to validate.

void (*statusUnseen)(
   imap4SinkPtr_t in_pimap4Sink,
   int in_unSeen);

Number of messages without the \Seen flag set. Parameters: the response sink to use, unique id of message flagged \Unseen.

void (*capability)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_listing);

Listing of capabilities supported by the server. Parameters: the response sink to use, list of server extensions.

void (*exists)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_messages);

Total number of messages in selected mailbox. Parameters: the response sink to use, number of messages in the mailbox.

void (*expunge)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_message);

Expunges the specified message. Parameters: the response sink to use, number of messages.

void (*recent)(
   imap4SinkPtr_t in_pimap4Sink, 
   int in_messages);

Total number of messages with the \Recent flag set. Parameters: the response sink to use, number of messages.

void (*flags)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_flags);

Applicable flags for the selected mailbox. Parameters: the response sink to use, list of flags.

void (*bye)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_reason);

Reason the connection was closed. Parameters: the response sink to use.

void* (*nameSpaceStart)(
   imap4SinkPtr_t in_pimap4Sink);

Indicates the beginning of a namespace response. Parameter: the response sink to use.

void (*nameSpacePersonal)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_personal);

Personal namespace. Parameters: the response sink to use, the user.

void (*nameSpaceOtherUsers)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_otherUsers);

Other user's namespace. Parameters: the response sink to use, list of other users.

void (*nameSpaceShared)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_shared);

Shared namespace. Parameters: the response sink to use, list of users with rights to shared mailbox.

void (*nameSpaceEnd)(
   imap4SinkPtr_t in_pimap4Sink);

Signals completion of fetch of data for the particular namespace. Parameters: the response sink to use.

void* (*aclStart)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_mailbox);

Mailbox name for which the ACL applies. Parameters: the response sink to use, identifier of the mailbox.

void (*aclIdentifierRight)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_identifier, 
   const char* in_rights);

Identifier rights pairs that apply to mailbox specified in aclStart. Parameters: response sink to use, identifier of the user, list of rights to the mailbox.

void (*aclEnd)(
   imap4SinkPtr_t in_pimap4Sink);

End of an ACL response. Parameters: the response sink to use.

void* (*listRightsStart)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_mailbox, 
   const char* in_identifier);

Start of response to the LISTRIGHTS command. Parameters: response sink to use, identifier for the mailbox, identifier of the user.

void (*listRightsRequiredRights)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_requiredRights);

Required rights for the identifier defined in listRightsStart. Parameters: response sink to use, list of required rights to the mailbox.

void (*listRightsOptionalRights)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_optionalRights);

Optional rights for the identifier defined in listRightsStart. Parameters: response sink to use, list of optional rights to the mailbox.

void (*listRightsEnd)(
   imap4SinkPtr_t in_pimap4Sink);

End of a LISTRIGHTS response. Parameters: response sink to use.

void (*myRights)(
   imap4SinkPtr_t in_pimap4Sink, 
   const char* in_mailbox, 
   const char* in_rights);

Set of rights that the user has to the mailbox. Parameters: response sink to use, identifier for the mailbox, list of rights to the mailbox.

Description

The IMAP4 response sink structure is made up of function pointers and opaque data. You must define the functions yourself, and you must point these pointers to your functions if you want to receive the related server responses. For more information, see SDK Response Sinks for C and Creating a Response Sink.

The function pointers serve as callbacks for many IMAP4 functions. See IMAP4 Function Callback Mapping.

NOTE: Use imap4Tag_free to free tags generated by IMAP4 functions. §

See Also 

imap4_initialize, imap4Sink_free, imap4Tag_free
[Top] [IMAP4 Structures]

Table of Contents | Previous | Next | Index

Last Updated: June 3, 1998

Copyright © 1998 Netscape Communications Corporation