The Post Office Protocol (POP3) class 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 class also has methods for changing the user's password and sending messages if they are supported by the server.
Initialize
Initialize an instance of the class, loading the networking library
and validating the development license. This method must be called
before any properties are changed or any other methods in this
class are called by the application.
Connect
Establish a connection to the server. Once the connection has been
established, the other methods in the class may be used to access
the messages on the server.
Disconnect
Disconnect from the server and release the memory allocated for
that client session. After this method is called, the client
session is no longer valid.
Reset
Reset the internal state of the component. This can be useful if
your application wishes to discard any settings made by a user and
return that instance of the class to its default state.
Uninitialize
Unload the networking 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.
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.
The class also includes methods which enable the application to access 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.
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.
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.
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.