libspopc manual

Introduction

libspopc is a pop3 client library written in C and uses BSD-style sockets. It is available on all Unices and Ms-Windows NT/2000/XP. libspopc is available on http://brouits.free.fr/libspopc/ and released under the GNU LGPLicence. libspopc offers low-level and high-level methods to acces a pop3 server. To use low-level API, it is recommended to read RFC 1725. No special knowledge is required to use high-level API. This manual tells how to use libspopc in both low-level and high-level methods.

The high-level API

declarations:

To use libspopc, you have to include in your main program the libspopc header:

#include < libspopc.h>

Then, in you main function, declare a popsession* object. You don't need to know what a popsession consists of, but if you are curious, see libspopc.h.

popsession* mysession;

starting the pop session:

To start a pop dialog with a pop3 server, use:

error=popbegin(char* servername, char* user, char* pass, popsession** & mysession);

If no error occurs, popbegin returns a NULL pointer. Else, it returns an error message and the session is not initialized. When the session is initialized, popbegin will asks the pop3 server to give him knowledge of how many messages are stored, and how many bytes, etc...

dealing with the pop server:

Once the session has begun, you can directly ask what is the last mail id:

int last;
last=popnum(mysession);
Hence, you can ask everything you want on messages:
for(i=1;i<=last;i++){
	size=popmsgsize(mysession,i);
/* the size in bytes of message i */
	sig=popmsguid(mysession,i);
/* the unique signature of message i */
	head=popgethead(mysession,i);
/* the message header */
	msg=popgetmsg(mysession,i);
/* the message itself */
	popdelmsg(mysession,i);
/* deletes the message on server */
}

You can perform automatic deletion after retrieving a message by asking it to the session:

popsetdel(mysession);

or stop it by:

popsetundel(mysession);

If you want to cancel all deletion, ask before quit;

popcancel(mysession);

Deconnection is made by a call to:

popend(mysession);

There are other methods to chat with the pop server, see them in file libspopc.h in section "high-level methods". See also example poptest2.c in libspopc sources.

The low-level API

declarations:

To use libspopc, you have to include in your main program the libspopc header:

#include < libspopc.h>

Then, in your main function, you have to declare some network-oriented structures in order to use BSD sockets:

int mysocket;
struct hostent myserver;
struct sockaddr_in myconnection;

and some specific libspopc types:

int* mylist;
char** myuidl;

mylist will hold an array of sizes of any messages stored in the pop server. (int)mylist[0] will hold the number of elements in the list. myuidl will hold an array of uniques signatures of messages stored in the pop server. (char*)myuidl[0] will hold the number of signatures. You can get it with well known function atoi() declared in stdlib.h.

connection:

Now, you can prepare a pop3 connection:

mysocket=pop3_prepare(myservername,0,& myconnection,& myserver);

where myservername is a (char*) string holding the internet name of the pop3 server. pop3_prepare will return -1 if a problem occured. If no problem occured, you can connect to the pop3 server:

(char*)message=pop3_connect(mysock,& myconnection);

if message is NULL, the connection failed. Else, check the server's response with:

if(pop3_error(message)){
printf("%s",message);
	pop3_disconnect(mysock);
}

As you can see in this sample, you must pop3_disconnect from the server if connection failed, in order to free all data structures allocated by pop3_prepare/pop3connect.

dealing with the pop server:

For a complete description of pop3 methods, see libspopc.h in section "pop3 queries". It is recommended to read RFC1725 also, because of some particularities of the pop3 protocol. Else, here are some tricks about them: statistics:

char* data;
data=pop3_stat(mysock);
if(pop3_error(data)){
	printf("%s",data);
}else{
	printf("stat: %d mail(s)\n",stat2last(data));
	printf("stat: %d bytes\n",stat2bytes(data));
}
free(data);

listing:

int* mylist
data=pop3_list(mysock,0); /* 0 means all messages */
if(pop3_error(data)){
	printf("%s",data);
}else{
	mylist=list2array(data);
}
free(data);
for(i=1;i<=mylist[0];i++){
	printf("msg %d is of %d bytes\n",i,mylist[i]);
}
free(mylist);

retrieving:

char* mymessage;
data=pop3_retr(mysock,i);
if(pop3_error(data)){
	printf("%s",data);
}else{
	mymessage=retr2msg(data);
	printf("message %d:\n%s",i,mymessage);
	free(mymessage);
}
free(data);

disconnectiong:

data=pop3_quit(mysock);
printf("server says:%s",data);
pop3_disconnect(mysock);

There are many other pop3 queries that you can see in libspopc.h and explained in RFC1725. For an example, see examples/poptest1.c in libspopc sources. -- libspopc is always available at http://brouits./free.fr/libspopc/index.html
feedback, questions and bug report can be sent at brouits@free.fr
-- See http://brouits.free.fr/libspopc/index.html libspopc manual, Ó2001 Benoit Rouits, 12/28/01