|
The Post Office Protocol (POP3) library enables an application
to retrieve a user's mail messages and store them on the local
system. The POP3 API 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 library also has
functions for changing the user's password and sending messages if
they are supported by the server.
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:
PopInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call the
application makes before calling the other POP3 API functions.
PopConnect
Establish a connection to the POP3 server. This function will
return a handle to a client session which is used in subsequent
calls to the POP3 API.
PopLogin
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. You can specify either the standard
authentication method, or the APOP authentication method if
required by the server.
PopDisconnect
Disconnect from the POP3 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.
PopUninitialize
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 Messages
There are functions in the POP3 library 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.
PopGetMessageCount
Return 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.
PopGetMessageCountEx
An extended version of the PopGetMessageCount function, this
function will return the number of available messages, along with
the last available message number and the total size of all
messages in the mailbox.
PopGetMessage
Retrieve a message from the server, storing the contents in memory.
This can be used to process the contents of a message without the
overhead of storing it in a file on the local system.
PopStoreMessage
This function downloads a complete message and stores it as a text
file on the local system.
PopDeleteMessage
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 PopReset function
instead of calling PopDisconnect.
PopGetMessageSize
This function returns the size of the message in bytes. One thing
to be aware of when using this function 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.
Message Headers
The POP3 API also includes functions 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 functions
can be used to examine the headers in a message:
PopGetMessageHeaders
This function 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.
PopGetHeaderValue
This function returns the value for a specific header field in a
message. This function 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 function fails with the
error that the feature is not supported, you should use the
PopGetMessageHeaders function instead.
PopGetMessageId
This function returns the value of the Message-ID header in the
specified message. This is a unique string that is used to identify
the message. Note that it is not the same as the UID value returned
by the POP3 server.
PopGetMessageUID
This function 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.
PopGetMessageSender
This function returns the email address of the person who sent the
message. This function requires that the server support extended
POP3 commands. If the server does not support the command used to
retrieve the sender, it will return a value of zero. Applications
should not depend on this function returning a valid address.
Typically it is used for informational purposes, such as displaying
the sender to the user as a message is being retrieved.
|