|
The Internet Message Access Protocol (IMAP) is an application
protocol which is used to access a user's email 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
control implements the current standard for this protocol, and provides
methods to retrieve messages, create and manage mailboxes, and search
for specific messages based on some user-defined search criteria.
The following properties, methods and events are available for use
by your application:
Initialize
Initialize the control and validate the runtime license key for the
current process. This method is normally not used if the control is
placed on a form in languages such as Visual Basic. However, if the
control is being created dynamically using a function similar to
CreateObject, then the application must call this method to
initialize the component before setting any properties or calling any
other methods in the control.
Connect
Establish a connection to the IMAP server. Once the connection has
been established, the other methods in the control may be used to
access the messages on the server.
Disconnect
Disconnect from the server and release any resources that have been
allocated for the client session. After this method is called, the
client session is no longer valid.
Uninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last method
call that the application should make prior to terminating. This is
only necessary if the application has previously called the
Initialize method.
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 methods for managing
mailboxes:
CheckMailbox
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.
CreateMailbox
Create a new mailbox on the server with the specified name.
DeleteMailbox
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.
ExamineMailbox
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 method 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 SelectMailbox method.
RenameMailbox
Renames an existing mailbox. One of the interesting uses of this
method 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.
SelectMailbox
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 method selects the specified
mailbox in read-write mode so that changes can be made to the
mailbox.
UnselectMailbox
This method 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 methods in the IMAP control for managing messages which
enables the application to create, delete and move messages. To use
these methods, a mailbox must be selected, either by setting the
MailboxName property or calling the SelectMailbox method. Methods 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.
CopyMessage
Copy a message to a specific mailbox.
DeleteMessage
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.
UndeleteMessage
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.
GetHeader
This method returns the value for a specified header field in the
message. Using this method, it is not necessary to download and parse
the message header.
GetHeaders
This method retrieves the complete headers for the specified message
and stores it in a string or byte array provided by the caller.
GetMessage
This method retrieves the specified message and stores it
in a string or byte array 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.
OpenMessage
This method is a lower level method which opens a message
for reading from the server. The application would then call Read to
read the contents of the message, followed by CloseMessage when all
the message data has been read. Also see the GetMessage method, which
will return the contents of a message into a string or byte
array.
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 method call.
StoreMessage
This method downloads a complete message and stores it as a text file
on the local system.
|