|
The Internet Message Access Protocol (IMAP) is an application
protocol which is used to access a user's e-mail messages which are
stored on a mail server. However, unlike the Post Office Protocol
(POP) where messages are downloaded and processed on the local
system, the messages on an IMAP server are retained on the server
and processed remotely. This is ideal for users who need access to
a centralized store of messages or have limited bandwidth. The
SocketTools IMAP library implements the current standard for this
protocol, and provides functions to retrieve messages, create and
manage mailboxes, and search for specific messages based on some
user-defined search criteria.
The first step your application must take is to initialize the
library, then establish a connection to the server and authenticate
the client. The following functions are available for use by your
application:
ImapInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other IMAP API functions.
ImapConnect
Establish a connection to the IMAP server. This function will
return a handle to a client session which is used in subsequent
calls to the IMAP API.
ImapDisconnect
Disconnect from the IMAP server and release any resources that have
been allocated for the client session. After this function is
called, the client handle is no longer valid.
ImapLogin
Authenticate yourself to the server using a username and password.
This function should be called immediately after the connection has
been established to the server.
ImapUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call the application should make prior to terminating.
Managing Mailboxes
One of the primary differences between the IMAP and POP3
protocol is that IMAP is designed to manage messages on the mail
server, rather than downloading all of the messages and storing
them on the local system. To support this, IMAP allows the client
to maintain multiple mailboxes on the server, which are similar in
concept to message folders used by mail client software. A mailbox
can contain messages, and in some cases a mailbox can contain other
mailboxes, forming a hierarchy of mailboxes and messages, similar
to directories and files in a filesystem. A special mailbox named
INBOX contains new messages for the user, and additional mailboxes
can be created, renamed and deleted as needed. Here are the most
important functions for managing mailboxes:
ImapCheckMailbox
Check the mailbox for any new messages which may have arrived.
Because messages are managed on the server, it is possible for new
mail to arrive during the client session.
ImapCreateMailbox
Create a new mailbox on the server with the specified name.
ImapDeleteMailbox
Delete a mailbox from the server. Most servers will only permit a
mailbox to be deleted if it does not contain any mailboxes itself.
Unlike deleting a message, which can be undeleted, deleting a
mailbox is permanent.
ImapExamineMailbox
Once the session has been established and authenticated, a mailbox
should be selected. This enables the client to manage the messages
in that mailbox. This function selects the specified mailbox in
read-only mode so that messages can be read, but not modified. To
select the mailbox in read-write mode, use the ImapSelectMailbox
function.
ImapExpungeMailbox
Remove all of the messages marked for deletion and return updated
status information about the current mailbox.
ImapGetFirstMailbox
This function begins the process of enumerating the available
mailboxes on the server, according to certain criteria provided to
the function.
ImapGetNextMailbox
This function returns the next mailbox from the server, based on
the criteria specified to the ImapGetFirstMailbox function.
When all the mailboxes have been returned, this function will
return an error indicating that there are no more mailboxes.
ImapRenameMailbox
Renames an existing mailbox. One of the interesting uses of this
function is the ability to rename the special INBOX mailbox.
Instead of actually renaming it, it moves all of the messages to
the new mailbox and empties the INBOX.
ImapSelectMailbox
Once the session has been established and authenticated, a mailbox
should be selected. Selecting a mailbox enables the client to
manage the messages in that mailbox. This function selects the
specified mailbox in read-write mode so that changes can be made to
the mailbox.
ImapUnselectMailbox
This function unselects the currently selected mailbox, and allows
the caller to specify if messages marked for deletion should be
expunged (removed) from the mailbox or reset back to an undeleted
state.
Managing Messages
There are functions in the IMAP library for managing messages
which enables the application to create, delete and move messages.
To use these functions, a mailbox must be selected, either by
calling the ImapSelectMailbox or ImapExamineMailbox
function. Functions which modify the mailbox require that it be
opened in read-write mode. Messages are identified by a number,
starting with one for the first message in the mailbox.
ImapCopyMessage
Copy a message to a specific mailbox.
ImapDeleteMessage
Mark the specified message for deletion. Unlike the POP3 protocol,
when a message is deleted on an IMAP server it can still be
accessed. The message will not actually be removed from the mailbox
unless the mailbox is expunged, unselected or the client
disconnects from the server.
ImapEnumMessages
Return information about all, or a specific range of, messages on
the server.
ImapGetMessageCount
Return the number of messages in the currently selected
mailbox.
ImapGetMessageFlags
Return the status flags for a specific message. Messages have a
number of flags which can be set that determines their status in
the mailbox. For example, messages can be flagged as answered, seen
(read), recent (new) or deleted.
ImapGetMessageSize
Return the size of the message in bytes.
ImapSetMessageFlags
Set one or more flags for the specified message. Flags can be
cleared, added or replaced using this function.
ImapUndeleteMessage
Remove the deletion flag from the specified message.
Viewing Messages
One of the more powerful features of the IMAP protocol is the
ability to precisely select what kinds of message data you wish to
retrieve from the server. It is possible to retrieve only specific
headers, or specific sections of a multipart message. Because IMAP
understands MIME formatted messages, it is possible to only
retrieve the textual portion of a message without having to
download any attachments that may have come with it.
ImapGetHeaderValue
This function returns the value for a specified header field in the
message. Using this function, it is not necessary to download and
parse the message header. To obtain the value of a header field in
a specific part of a multipart message, use the
ImapGetHeaderValueEx function.
ImapOpenMessage
This is a lower level function which opens a message for reading
from the server. A more complex version of this function called
ImapOpenMessageEx function allows you to specify the type of
message data that you want, a specific part of a multipart message,
and a byte offset into the message. The application would then call
ImapRead to read the contents of the message, followed by
ImapCloseMessage when all the message data has been read.
Also see the ImapGetMessage function, which will return the
contents of a message into a memory buffer.
ImapGetMessageParts
This function returns the number of parts in a multipart message
and is useful for determining if a message is a simple message or a
MIME formatted message with multiple parts, such as one that
includes file attachments.
Downloading Messages
In some cases, it may be preferable to download a complete
message from the server to the local system. This can be easily
done with a single function call.
ImapGetMessage
This function retrieves the specified message and stores it in a
buffer provided by the caller; you can specify the type of message
data that you want, a specific part of a multipart message and the
amount of data that you want. For example, it is possible to
request that only the first 1500 bytes of the body of the 3rd part
of a multipart message should be returned.
ImapStoreMessage
This function downloads a complete message and stores it as a text
file on the local system.
|