Libpop3 - A simple POP3 library (C)opyright 2001-2002 Kristian Van Der Vliet

API

The API for Libpop3 is very simple, with only four functions available.  They
allow you to connect to a server, perform common POP3 functions such as
retrieving and deleting mail, and disconnect from the server.

The functions as defined in inc/libpop3.h are as follows:

int pop3_connect(const char* zServer, int nPort);
int pop3_login(const char* zUsername, const char* zPassword);
int pop3_getmailcount(void);
int pop3_getmailsize(int nMessageNo);
int* pop3_getmailsizelist(void);
int pop3_getmail(int nMessageNo, int nMessageSize,
		struct pop3_mail * sNewMail);
int pop3_deletemail(int nMessageNo);
int pop3_disconnect(void);
int pop3_set_timeout(unsigned long nTimeout);

A simple example is provided at the end of this document.

pop3_connect()

This function simply attempts to connect to the required server on the
requested port number.  For example, if you wanted to connect to the server
"pop3.isp.com" on the default POP3 port (110), you would do:

	pop3_connect("pop3.isp.com",110);

pop3_connect() will return 0 on success, or one of the following if an error
occurs:

	-POP3_UNKNOWN_SERVER	- The server could not be found I.e a DNS error 
				occured or the server does not exist

	-POP3_CONNECT_FAILED	- libpop3 could not connect to the requested server 
				for some reason.  It may be that the port number you 
				have requested is incorrect.

	-POP3_TIMED_OUT		- The server did not respond within the set time 
				limits.  See pop3_set_timeout() for more information.

pop3_login()

After you have succesfully connected to the server with pop3_connect() you must
log in to the server with a valid user name and password.  If your username was
"frodo" and your password was "gandalf", you would do:

	pop3_login("frodo","gandalf");

pop3_login() returns 0 on success, or one of the following if an error occurs:

	-POP3_INVALID_USER_PASS	- Either the username or the password is invalid.  
				POP3 servers do not tell you if just the username is 
				incorrect for security reasons.

	-POP3_TIMED_OUT		- The server did not respond within the set time 
				limits.  See pop3_set_timeout() for more information.

pop3_getmailcount()

This function simply asks the POP3 server for the number of emails waiting for
the user which is connected.  To use it, you simply do:

	int nMailCount=pop3_getmailcount();

pop3_getmailcount() will return the mail count on success (Which can be 0) or
<0 if an error occured.

pop3_getmailsize()

pop3_getmailsize() will return the size of the requested mail in bytes, as
reported by the POP3 server.  If you want to know the size of the first mail on
the server, you would use:

	int nMailSize=pop3_getmailsize(1);

The function will return the mail size on success or <0 if an error occured.

Note that the size returned by some POP3 servers cannot be relied upon as an
accurate number of bytes that will be returned by RETR.

pop3_getmailsizelist()

If there are more than one mails on the POP3 server, you can use
pop3_getmailsizelist() instead of calling pop3_getmailsize() for each message.
pop3_getmailsizelist() will return an array of integers, with one entry for
each mail.  To use the function you can simply do the following:

	int *nSizes=pop3_getmailsizelist();

pop3_getmailsizelist() will return a pointer the array on success, or NULL if
an error occured.

pop3_getmail()

This function will download the requested mail from the server.  It will return
a pop3_mail structure containing the common mail headers, as well as the entire
message.  You must tell pop3_getmail() the expected size, in bytes, of the
mail.  You can get the size of the mail with either pop3_getmailsize() or
pop3_getmailsizelist().

As an example, assume that you want to download the first mail on the remote
server:

	struct pop3_mail sMailMessage;
	int nMailSize;

	nMailSize=pop3_getmailsize(1);
	pop3_getmail(1,nMailSize, sMailMessage);

If an error occures, pop3_getmail() will return POP3_INVALID_MESSAGE_NUM or
POP3_TIMED_OUT.

You must free the various headers from the mail structure when you are done
with them.  If a header did not exist in the message, the header will be a null
pointer.

pop3_deletemail()

This function will delete the requested mail from the POP3 server.  If you
wanted to delete the first mail on the server you simply need to do the
following:

	pop3_deletemail(1);

pop3_deletemail() will return 0 on success or one of the following if an error
occured:

	-EDELEFAILED	- The attempt to delete the mail failed for some reason.
			It may be that the mail you have tried to delete does not exist.

	-POP3_TIMED_OUT	- The server did not respond within the set time 	
			limits.  See pop3_set_timeout() for more information.

pop3_disconnect()

Attempts to disconnect cleanly from the remote server.  It is the last function
you should call.  The function takes no arguments and returns either 0 on
success, or one of the following if an error occured:

	-POP3_TIMED_OUT		- The server did not respond within the set time 
				limits.  See pop3_set_timeout() for more information.

No matter if an error occured, libpop3 will still close the connection to the
remote server.

pop3_set_timeout()

By default, libpop3 will timeout and return an error if it does receive a
response from the server after 30 seconds.  You can change this timeout value
with the pop3_set_timeout() function.  There are no upper or lower limits on
the timeout value you can set, but a timeout value of 0 is "No timeout", which
means that libpop3 will sit and wait indefinatly for the server to respond.
Conversely, a very large timeout value will cause libpop3 to seem to be waiting
forever for the server to respond!  You should be careful about the values you
use.  Something between 20 and 120 seconds is probably a good value to use.

Example Usage

Below is a very simple example for using libpop3.  The code attempts to connect
to the (Fictional) server "mail.isp.com" on the default POP3 port, finds the
number of emails on the server, then downloads the first mail and displays the
headers.

--Begin Example--

#include "inc/libpop3.h"
#include <stdio.h>

int main(void);

int main(void)
{
	int nMailCount=0;		/* Number of mails on server */
	int nMailSize=0;		/* Size of first email in bytes */
	struct pop3_mail sMailMessage;	/* The mail we download */

	printf("Connecting to server\n");

	if(pop3_connect("mail.isp.com",110)!=0)
	{
		printf("Error: Could not connect to server\n");
		return(1);
	}

	printf("Logging in\n");

	if(pop3_login("frodo","gandalf")!=0)
	{
		printf("Error: Could not login to server\n");
		/* Attempt to disconnect */
		pop3_disconnect();
		return(1);
	}
	
	printf("Logged in\nGetting number of mails\n");

	nMailCount=pop3_getmailcount();

	if(nMailCount<0)
	{
		printf("Error: Could not get mail count\n");
		/* Attempt to disconnect */
		pop3_disconnect();
		return(1);
	}	

	printf("There are %i messages on the server\n",nMailCount);

	if(nMailCount==0)
	{
		printf("No mail to download\nDone\n");
		/* Attempt to disconnect */
		pop3_disconnect();
		return(1);
	}

	/* Get mail 1 */
	nMailSize=pop3_getmailsize(1);

	sMailMessage=pop3_getmail(1,nMailSize);

	if(sMailMessage==NULL)
	{
		printf("Error: Could not get mail no. 1\n");
		/* Attempt to disconnect */
		pop3_disconnect();
		return(1);
	}

	/* Print some headers */

	printf("To: %s\n",sMailMessage.zTo);
	printf("From: %s\n",sMailMessage.zFrom);
	printf("Subject: %s\n",sMailMessage.zSubject);

	/* Free the data from the mail structure */
	if(sMailMessage.zTo!=0)
		free(sMailMessage.zTo);

	if(sMailMessage.zCc!=0)
		free(sMailMessage.zCc);

	if(sMailMessage.zBcc!=0)
		free(sMailMessage.zBcc);

	if(sMailMessage.zReplyTo!=0)
		free(sMailMessage.zReplyTo);

	if(sMailMessage.zSubject!=0)
		free(sMailMessage.zSubject);

	if(sMailMessage.zBody!=0)
		free(sMailMessage.zBody);

	if(sMailMessage.zMessageId!=0)
		free(sMailMessage.zMessageId);

	if(sMailMessage.zFrom!=0)
		free(sMailMessage.zFrom);

	if(sMailMessage.zSender!=0)
		free(sMailMessage.zSender);

	if(sMailMessage.zDate!=0)
		free(sMailMessage.zDate);

	if(sMailMessage.zContent!=0)
		free(sMailMessage.zContent);

	if(sMailMessage.zEncoding!=0)
		free(sMailMessage.zEncoding);

	if(sMailMessage.zInReplyTo!=0)
		free(sMailMessage.zInReplyTo);

	if(sMailMessage.zHeaders!=0)
		free(sMailMessage.zHeaders);

	/* Disconnect from the server */
	printf("Disconnecting from server\n");
	pop3_disconnect();

	return(0);
}

--End Example--