POP3 C API Reference
Table of Contents | Previous
| Next
| Index
Messaging Access SDK Guide
Part 2. Messaging Access SDK C Reference
This chapter describes the functions and structures of the C language API for the POP3 (Post Office Protocol) protocol of the Messaging Access SDK.
You'll find links to each function and structure in this introduction. Each reference entry gives the name of the function or structure, its header file, its syntax, and its parameters.
All C interface definitions are found in the pop3.h file.
[Top]
This table lists POP3 functions alphabetically by name, with descriptions. Click the function name to get information about it.
[Top] [POP3 Functions] [POP3 Functions by Task]
Connects to the server.
#include <pop3.h>
int pop3_connect( pop3Client_t * in_pPOP3,
const char * in_server,
unsigned short in_port );
The function has the following parameters:
This function connects the POP3 client to the specified server at the port you indicate. For more information, see Connecting to a Server.
This function is mapped to one or more callbacks in the pop3Sink_t.connect, pop3Sink_t.error,
pop3_disconnect, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Marks a message for deletion on the server.
#include <pop3.h>
int pop3_delete( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
This function marks the message for deletion; it is actually deleted when the pop3_quit function is called. For more information, see Ending the Session.
This function sends the DELE [arg] POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.dele, pop3Sink_t.error,
pop3_quit, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Closes the socket connection with the server.
#include <pop3.h>
int pop3_disconnect (
The function has the following parameter:
This function closes the socket connection. It could be used to implement a Cancel button.
NOTE:
Do not call the processResponses method after this function. Operations for
which you do not call processResponses: disconnecting, the set functions,
initializing and freeing the client and sink. §
pop3_connect
[Top] [POP3 Functions] [POP3 Functions by Task]
Frees the POP3 client structure.
#include <pop3.h>
void pop3_free( pop3Client_t ** in_ppPOP3 );
The function has the following parameter:
This function frees the pop3Client_t structure. When the function returns, the client structure is set to null.
pop3_initialize, pop3Sink_free
[Top] [POP3 Functions] [POP3 Functions by Task]
Gets IO models.
#include <pop3.h>
int pop3_get_option( pop3Client_t * in_pPOP3,
int in_option,
void * in_pOptionData );
The function has the following parameters:
This function gets the option set with pop3_set_option. Do not call pop3_processResponses after this function.
pop3_set_option
[Top] [POP3 Functions] [POP3 Functions by Task]
Initializes and allocates the pop3Client_t structure and sets the response sink.
#include <pop3.h>
int pop3_initialize( pop3Client_t ** out_ppPOP3,
pop3SinkPtr_t in_pPOP3Sink );
The function has the following parameters:
For more information, see Creating a Client.
pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Lists all messages.
#include <pop3.h>
int pop3_list( pop3Client_t * in_pPOP3 );
The function has the following parameters:
POP3 includes two forms of the list function. This form goes through all the messages in the mailbox and generates a list of messages. The other form takes the message number of the message to list as an argument. For more information, see Listing Messages.
This function sends the LIST POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.listStart, pop3Sink_t.list,
pop3Sink_t.listComplete, pop3Sink_t.error,
pop3_listA, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Lists the specified message.
#include <pop3.h>
int pop3_listA( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
POP3 includes two forms of the list function. This form takes the message number of the message to list as an argument. The other form goes through all the messages in the mailbox and generates a list of messages. For more information, see Listing Messages.
This function sends the LIST [arg] POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.listStart, pop3Sink_t.list,
pop3Sink_t.listComplete, pop3Sink_t.error,
pop3_list
[Top] [POP3 Functions] [POP3 Functions by Task]
Contacts the server, which sends a response indicating it is still present.
#include <pop3.h>
int pop3_noop( pop3Client_t * in_pPOP3 );
The function has the following parameters:
This function sends the NOOP POP3 protocol command.
If you send any command, the server responds with an "still here" response. Sending the pop3_noop function does nothing except force this server response. You can use this function to maintain server connection, perhaps issuing it at timed intervals to make sure that the server is still active.
The pop3_noop function resets the autologout timer inside the server and may change the number of messages in a mailbox (due to new mail). Also, using this function may change or update the status of messages in mailboxes.
Your application may not need this function. For example, if the application does something and then disconnects at once, there is no need to make sure that the server is still connected.
This function is mapped to one or more callbacks in the pop3Sink_t.noop, pop3Sink_t.error,
pop3_connect, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Identifies user password; on success, enters Transaction state.
#include <pop3.h>
int pop3_pass(
const char * in_password );
The function has the following parameters:
This function sends the PASS POP3 protocol command. For more information, see Logging In.
This function is mapped to one or more callbacks in the pop3Sink_t.pass, pop3Sink_t.error, pop3_user
[Top] [POP3 Functions] [POP3 Functions by Task]
Processes the server responses for API commands.
#include <pop3.h>
int pop3_processResponses(
The function has the following parameters:
This function processes the server responses for API commands. It invokes the callback functions provided by the user for all responses that are available at the time of execution.
If a time-out occurs, the user can continue by calling pop3_processResponses again.
Do not call pop3_processResponses after these operations: disconnecting, the set functions, initializing and freeing the client and sink.
pop3Sink_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Closes the connection with the server.
#include <pop3.h>
int pop3_quit( pop3Client_t * in_pPOP3 );
The function has the following parameters:
This function ends the session. It expunges deleted messages and logs the user out from the POP3 server. For more information, see Ending the Session.
If issued in the Authentication state, server closes connections. If issued in the Transaction state, the server enters the Update state and deletes marked messages, then quits.
This function sends the QUIT POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.quit, pop3Sink_t.error,
pop3_delete, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Undeletes any messages marked as deleted.
#include <pop3.h>
int pop3_reset( pop3Client_t * in_pPOP3 );
The function has the following parameters:
This function removes any delete flags.
This function sends the RSET POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.reset, pop3Sink_t.error, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Retrieves message with specified number.
#include <pop3.h>
int pop3_retrieve( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
This function retrieves messages in the form of data chunks, which have a default size of 1 K. The function issues a RETR IMAP4 protocol command. For more information, see Retrieving a Message.
This function is mapped to one or more callbacks in the pop3Sink_t.retrieveStart, pop3Sink_t.retrieve,
pop3Sink_t.retrieveComplete, pop3Sink_t.error,
pop3_setChunkSize
[Top] [POP3 Functions] [POP3 Functions by Task]
Sends a POP3 command that is not otherwise supported by the SDK.
#include <pop3.h>
int pop3_sendCommand( pop3Client_t * in_pPOP3,
const char * in_command,
boolean in_multiLine );
The function has the following parameters:
You can use this function to extend the protocol to meet your application needs. Using this function, you can extend the functionality of the SDK to meet your needs by adding functions or passing different parameters to a function.
This function is mapped to one or more callbacks in the pop3Sink_t.sendCommandStart, pop3Sink_t.sendCommand,
pop3Sink_t.sendCommandComplete
[Top] [POP3 Functions] [POP3 Functions by Task]
Sets the size of the message data chunk passed to the user.
#include <pop3.h>
int pop3_setChunkSize(
int in_chunkSize );
The function has the following parameters:
NOTE:
Do not call the processResponses method after this method. §
pop3_retrieve
[Top] [POP3 Functions] [POP3 Functions by Task]
Sets IO models.
#include <pop3.h>
int pop3_set_option( pop3Client_t * in_pPOP3,
int in_option,
void * in_pOptionData );
The function has the following parameters:
To inquire on options set with this function, use pop3_get_option. Do not call pop3_processResponses after this function.
pop3_get_option
[Top] [POP3 Functions] [POP3 Functions by Task]
Sets a new response sink.
#include <pop3.h>
int pop3_setResponseSink ( pop3Client_t * in_pPOP3,
pop3SinkPtr_t in_pPOP3Sink );
The function has the following parameters:
This function overrides the response sink passed into the initialized function.
NOTE:
Do not call pop3_processResponses after this function. §
pop3Sink_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Sets the amount of time allowed to wait before returning control to the user.
#include <pop3.h>
int pop3_setTimeout( pop3Client_t * in_pPOP3,
double in_timeout );
The function has the following parameters:
This function sets the amount of time, in seconds, allowed to wait before returning control to the user.
NOTE:
Do not call pop3_processResponses after this function. §
pop3_processResponses, pop3_setChunkSize, pop3Client_t
[Top] [POP3 Functions] [POP3 Functions by Task]
Frees the POP3 response sink and its data members.
#include <pop3.h>
void pop3Sink_free( pop3Sink_t ** in_ppPOP3Sink );
The function has the following parameters:
This function frees the pop3Sink_t structure. When the function returns, the sink structure is set to null. The user must free any pointers to opaque data.
NOTE:
Do not call pop3_processResponses after this function. §
pop3_quit, pop3_free, pop3Sink_initialize
[Top] [POP3 Functions] [POP3 Functions by Task]
Initializes and allocates the pop3Sink_t structure.
#include <smtp.h>
int pop3Sink_initialize( pop3Sink_t ** out_ppPOP3Sink );
The function has the following parameters:
For more information, see Creating a Response Sink and SDK Response Sinks for C.
NOTE:
Do not call the processResponses method after this method. §
pop3_connect, pop3_noop, pop3Sink_free, pop3_initialize
[Top] [POP3 Functions] [POP3 Functions by Task]
Gets the status of the mail drop.
#include <pop3.h>
int pop3_stat(
The function has the following parameters:
The client calls this function to get the number of messages in and octet size of the mail drop. The function issues a STAT IMAP4 protocol command. For more information, see Getting Message Count.
This function is mapped to one or more callbacks in the pop3Sink_t.stat, pop3Sink_t.error
[Top] [POP3 Functions] [POP3 Functions by Task]
Retrieves the headers plus the specified number of lines from the body.
#include <pop3.h>
int pop3_top ( pop3Client_t * in_pPOP3,
int in_messageNumber,
int in_lines );
The function has the following parameters:
This function returns the header and specified number of lines from the message. It issues a TOP [arg1] [arg2]' command. For more information, see Retrieving Message Headers.
This function is mapped to one or more callbacks in the pop3Sink_t.topStart, pop3Sink_t.top,
pop3Sink_t.topComplete, pop3Sink_t.error,
pop3_retrieve
[Top] [POP3 Functions] [POP3 Functions by Task]
Returns the message numbers and the corresponding unique ids of the message in the maildrop.
#include <pop3.h>
int pop3_uidList( pop3Client_t * in_pPOP3 );
The function has the following parameters:
This function uses the UIDL POP3 protocol command to specify that the LIST command uses unique message identifiers. For more information, see Listing Messages.
This function is mapped to one or more callbacks in the pop3Sink_t.uidListStart, pop3Sink_t.uidList,
pop3Sink_t.uidListComplete, pop3Sink_t.error,
pop3_uidListA
[Top] [POP3 Functions] [POP3 Functions by Task]
Returns a specified message and its corresponding unique id.
#include <pop3.h>
int pop3_uidListA( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
This function lists all the messages in a mailbox along with their unique identifiers and message numbers. It uses the UIDL POP3 protocol command to specify that the LIST command uses unique message identifiers. For more information, see Listing Messages.
This function is mapped to one or more callbacks in the pop3Sink_t.uidListStart, pop3Sink_t.uidList,
pop3Sink_t.uidListComplete, pop3Sink_t.error,
pop3_uidList
[Top] [POP3 Functions] [POP3 Functions by Task]
Enters a user name.
#include <pop3.h>
int pop3_user(
const char * in_user );
The function has the following parameters:
This function identifies the user or mail drop by name to the server. It sends the USER POP3 protocol command. For more information, see Logging In.
This function is mapped to one or more callbacks in the pop3Sink_t.user, pop3Sink_t.error, pop3_pass
[Top] [POP3 Functions] [POP3 Functions by Task]
Returns a list of authenticated users.
#include <pop3.h>
int pop3_xAuthList( pop3Client_t * in_pPOP3 );
The function has the following parameters:
This function sends the XAUTHLIST POP3 protocol command. For more information, see Listing Messages.
This function is mapped to one or more callbacks in the pop3Sink_t.xAuthListStart, pop3Sink_t.xAuthList,
pop3Sink_t.xAuthListComplete, pop3Sink_t.error,
pop3_xAuthListA
[Top] [POP3 Functions] [POP3 Functions by Task]
Returns an authenticated user for a given message.
#include <pop3.h>
int pop3_xAuthListA( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
This function sends the XAUTHLIST [arg] POP3 protocol command. For more information, see Listing Messages.
This function is mapped to one or more callbacks in the pop3Sink_t.xAuthListStart, pop3Sink_t.xAuthList,
pop3Sink_t.xAuthListComplete, pop3Sink_t.error,
pop3_xSender
[Top] [POP3 Functions] [POP3 Functions by Task]
Gets the email address of the sender of the specified message.
#include <pop3.h>
int pop3_xSender( pop3Client_t * in_pPOP3,
int in_messageNumber );
The function has the following parameters:
This function allows a client to query whether an particular message has been authenticated. The server returns the email address of the authenticated sender in a callback or, if no authenticated sender is found, an empty OK string.
This function sends the XSENDER [arg] POP3 protocol command. It is mapped to one or more callbacks in the pop3Sink_t.xSender, pop3Sink_t.error,
pop3_xAuthList, pop3_xAuthListA
[Top] [POP3 Functions] [POP3 Functions by Task]
This section defines POP3 data structures, listed in alphabetical order.
[Top] [POP3 Functions]
Structure used by a client to communicate with a POP3 server.
typedef struct pop3Client pop3Client_t;
The client uses this structure to communicate with an SMTP server. The developer uses this structure to perform SMTP API operations. All data contained within the client structure is used internally by the API.
For more information, see Creating a Client.
pop3_free, pop3_initialize
[Top] [POP3 Structures] [POP3 Functions]
Definition of the POP3 response sink.
typedef struct pop3Sink
{
void * pOpaqueData;
void (*connect)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*dele)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*error)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*listStart) ( pop3SinkPtr_t * in_pPOP3Sink );
void (*list)( pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber, int in_octetCount );
void (*listComplete)(
pop3SinkPtr_t * in_pPOP3Sink );
void (*noop)( pop3SinkPtr_t * in_pPOP3Sink );
void (*pass)(pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*quit)(pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*reset)(pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*retrieveStart)(
pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber, int in_octetCount );
void (*retrieve)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_messageChunk );
void (*retrieveComplete) ( pop3SinkPtr_t *
in_pPOP3Sink );
void (*sendCommandStart) ( pop3SinkPtr_t *
in_pPOP3Sink );
void (*sendCommand) ( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*sendCommandComplete)(
pop3SinkPtr_t * in_pPOP3Sink );
void (*stat)( pop3SinkPtr_t * in_pPOP3Sink,
int in_messageCount, int in_octetCount );
void (*topStart)( pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber );
void (*top)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseLine );
void (*topComplete)( pop3SinkPtr_t * in_pPOP3Sink );
void (*uidListStart)( pop3SinkPtr_t * in_pPOP3Sink );
void (*uidList)( pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber, const char * in_uid );
void (*uidListComplete)( pop3SinkPtr_t * in_pPOP3Sink );
void (*user)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_responseMessage );
void (*xAuthListStart)(
pop3SinkPtr_t * in_pPOP3Sink );
void (*xAuthList)( pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber,
const char * in_emailAddress );
void (*xAuthListComplete)(
pop3SinkPtr_t * in_pPOP3Sink );
void (*xSender)( pop3SinkPtr_t * in_pPOP3Sink,
const char * in_emailAddress );
} pop3SinkPtr_t;
The structure has the following fields:
void * pOpaqueData; |
User data.
|
void (*connect)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the connection to the server. Parameters: the response sink to use, the server's response message.
|
void (*dele)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the DELE command. Parameters: the response sink to use, the server's response message.
|
void (*error)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for an error. Parameters: the response sink to use, the server's error response message.
|
void (*listStart)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the start of the LIST command. Parameters: the response sink to use.
|
void (*list)(
pop3SinkPtr_t in_pPOP3Sink,
int in_messageNumber,
int in_octetCount ); |
Notification for the response to the LIST command. Parameters: the response sink to use, number of the message, octet count of the message.
|
void (*listComplete)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of the LIST command. Parameters: the response sink to use.
|
void (*noop)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the response to the NOOP command. Parameters: the response sink to use.
|
void (*pass)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the PASS command. Parameters: the response sink to use, server response.
|
void (*quit)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the QUIT command. Parameters: the response sink to use, server response.
|
void (*reset)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the RSET command. Parameters: the response sink to use, server response.
|
void (*retrieveStart)(
pop3SinkPtr_t in_pPOP3Sink,
int in_messageNumber,
int in_octetCount ); |
Notification for the start of the RETR command. Parameters: the response sink to use, message numbers, octet count of message.
|
void (*retrieve)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_messageChunk ); |
Notification for the response to the RETR command. Parameters: the response sink to use, chunk of message to retrieve
|
void (*retrieveComplete)
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of the RETR command. Parameters: the response sink to use.
|
void (*sendCommandStart)
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the start of an extended command. Parameters: the response sink to use.
|
void (*sendCommand)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response of an extended command. Parameters: the response sink to use, server response.
|
void (*sendCommandComplete)
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of and extended command. Parameters: the response sink to use.
|
void (*stat)(
pop3SinkPtr_t in_pPOP3Sink,
int in_messageCount,
int in_octetCount ); |
Notification for the response to the STAT command. Parameters: the response sink to use, message numbers, octet count of message.
|
void (*topStart)(
pop3SinkPtr_t * in_pPOP3Sink,
int in_messageNumber ); |
Notification for the start of the TOP command. Parameters: the response sink to use, number of the message.
|
void (*top)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseLine ); |
Notification for the response to the TOP command. Parameters: the response sink to use, line of message.
|
void (*topComplete)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of the TOP command. Parameters: the response sink to use.
|
void (*uidListStart)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the start of the UIDL command. Parameters: the response sink to use.
|
void (*uidList)(
pop3SinkPtr_t in_pPOP3Sink,
int in_messageNumber,
const char * in_uid ); |
Notification for the response to the UIDL command. Parameters: the response sink to use, number of the message, unique identifier.
|
void (*uidListComplete)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of the UIDL command. Parameters: the response sink to use.
|
void (*user)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_responseMessage ); |
Notification for the response to the USER command. Parameters: the response sink to use, server response.
|
void (*xAuthListStart)(
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the start of the XAUTHLIST command. Parameters: the response sink to use.
|
void (*xAuthList)(
pop3SinkPtr_t in_pPOP3Sink,
int in_messageNumber,
const char * in_emailAddress ); |
Notification for the response to the XAUTHLIST command. Parameters: the response sink to use, number of the message, email address.
|
void (*xAuthListComplete)
pop3SinkPtr_t in_pPOP3Sink ); |
Notification for the completion of the XAUTHLIST command. Parameters: the response sink to use.
|
void (*xSender)(
pop3SinkPtr_t in_pPOP3Sink,
const char * in_emailAddress ); |
Notification for the response to the XSENDER command. Parameters: the response sink to use, the email address.
|
The POP3 response sink structure is made up of function pointers and opaque data. You must define the functions yourself, and you must point these pointers to your functions if you want to receive the related server responses. For more information, see SDK Response Sinks for C and Creating a Response Sink.
The function pointers serve as callbacks for many POP3 functions. See POP3 Function Callback Mapping.
pop3_initialize, pop3Sink_free
[Top] [POP3 Structures]
Table of Contents | Previous
| Next
| Index
Last Updated: June 3, 1998
Copyright © 1998
Netscape Communications Corporation