|
The Post Office Protocol (POP3) control enables an application to
retrieve a user's mail messages and store them on the local system. The
control provides support for all of the standard functionality such as
listing and downloading messages, as well as extended features such as
the ability to retrieve only the headers for a message or just specific
header values. The control also has methods for changing the user's
password and sending messages if they are supported by the server.
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 method 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 POP3 server. Once the connection has
been established, the other methods in the control may be used to
access the resources 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 Messages
There are methods in the POP3 control for managing messages which
enables the application to list, delete and retrieve messages stored on
the server. Messages are identified by a number, starting with one for
the first message in the mailbox. The most typical operation for a POP3
client is to retrieve each message, store it on the local system and
then delete the message from the server. Any processing that is done on
the message would then be done on the local copy.
Message
This property sets or returns the message number for the currently
selected mailbox. Message numbers range from 1 through the number of
messages available on the server, as returned by the MessageCount
property.
MessageCount,
LastMessage
A property which returns the number of messages available for
retrieval. There are two values the application should use. One is
the number of currently available messages and the other is the last
valid message number. As messages are deleted from the server, the
total number of available messages will decrease; however, the last
available message number will remain constant.
MessageSize
This property returns the size of the message in bytes. One thing to
be aware of when using this method is that some servers will only
return approximate message sizes. In addition, because of the
difference between the end-of-line characters on UNIX and Windows
systems, the size reported by the server may not be the actual size
of the message when stored on the local system. Therefore, the
application should not depend on this value as an absolute. For
example, it should not use this value to determine the maximum number
of bytes to read from the server; instead, it should read until the
server indicates that the end of the message has been reached.
GetMessage
This method is used to retrieve a message from the server and copy it
into a local string or byte array buffer. This method will cause the
current thread to block until the message transfer completes, a
timeout occurs or the transfer is canceled.
StoreMessage
This method downloads a complete message and stores it as a text file
on the local system.
DeleteMessage
Mark the message for deletion. When the connection with the server is
closed, the message will be removed from the user's inbox. An
important difference between the POP3 and IMAP protocols is that when
a message is marked as deleted on a POP3 server, that message can no
longer be accessed. An attempt to retrieve a message after it has
been marked for deletion will result in an error. The only way to
undelete a message once it has been deleted is to terminate the
connection with the server by calling the Reset method instead of
calling the Disconnect method.
Message Headers
The POP3 control also includes methods which enable the application
to access just the headers for a message. This can be useful if the
program doesn't want to incur the overhead of downloading the entire
message contents. The following methods can be used to examine the
headers in a message:
GetHeaders
This method returns the complete set of headers for the specified
message. If your program has to process multiple header fields, this
is the most efficient method to use. It is possible to retrieve
specific header values, however not all servers support that option
and it is somewhat slower because it involves sending individual
commands to request each value.
GetHeader
This method returns the value for a specific header field in a
message. This method does not require that you parse the message
headers; however it does incur additional overhead. It is also
important to note that not all servers support the command that is
used to request the header value. If this method fails with the error
that the feature is not supported, you should use the GetHeaders
method instead.
MessageUID
This property returns the unique ID (UID) that the server has
associated with the message. The UID can be used by an
application to track whether or not it has previously viewed the
message. Unlike the message number, which can change between client
sessions, the message UID is guaranteed to be the same value across
sessions until the message is deleted.
|