libspopc/libspopc.h

/* this is libspopc.h file, part of the libspopc library sources
 * copyright © 2002- Benoit Rouits <brouits@free.fr>
 * released under the terms of the GNU Lesser General Public Licence.
 *
 * libspopc offers simple API for a pop3 client.
 * See RFC 1725 for pop3 specifications.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#ifndef LIBSPOPC_H
#define LIBSPOPC_H

#ifdef __cplusplus
extern "C" {
#endif

#include <sys/types.h>

#ifdef WIN32
#include <winsock.h>
#if BUILDING_DLL
# define DLLIMPORT __declspec (dllexport)
#else /* Not BUILDING_DLL */
# define DLLIMPORT __declspec (dllimport)
#endif /* Not BUILDING_DLL */
#else
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#define DLLIMPORT
#endif

/* thread-safe version of libspopc (>0.8) */

/* call this function before to use any routine from libspopc */
DLLIMPORT int libspopc_init(void);

/* call this function when you do not use anymore libspopc routines */
DLLIMPORT int libspopc_clean(void);

#ifdef USE_SSL

#include <openssl/ssl.h>

/******************************************************************************
 * If compiled with SSL support, the low-level functions will act on a 
 * "pop3sock" structure, which contains the socket, SSL instance and context 
 * for the connection. This structure is dynamically allocated and initialized 
 * when you do pop3_prepare() or popbegin(), and is cleaned-up and destroyed in 
 * pop3_disconnect() or popend().
 ******************************************************************************/

typedef struct {
        int sock;
        SSL *ssl;
        SSL_CTX *ctx;
} pop3sock;

typedef pop3sock* pop3sock_t;

#define BAD_SOCK NULL

/******************************************************************************
 * Use pop3_cert_setup() to specify the location of your SSL certificate
 * bundle. If it is not set (or set to NULL), SSL connections can be still be 
 * made, but certificates will not be verified!
 * This function sets a global variable, and should be called before 
 * pop3_prepare() or popbegin() if you want to verify certs.
 * 
 * Hint: If you have a recent version of curl/libcurl installed, you can try 
 * setting this to the output of:  "curl-config --ca"
 ******************************************************************************/
DLLIMPORT void pop3_cert_setup(const char *certfile);

/******************************************************************************
 * pop3_ssl_never() disable the use of SSL on any port, even 995.
 * pop3_ssl_auto() enable the use of SSL only on port 995. (default)
 * pop3_ssl_always() enable the use of SSL on any port, even 110.
 *
 * These functions set a library-wide variable, and should be called before
 * pop3_prepare() or popbegin() if you want to modify libspopc behaviour.
 * By default, not calling any of these, the behaviour of libspopc follows
 * the same as pop3_ssl_auto() for backward compatibility reason.
 ******************************************************************************/
DLLIMPORT void pop3_ssl_never(void);
DLLIMPORT void pop3_ssl_auto(void);
DLLIMPORT void pop3_ssl_always(void);

#else /* Non-SSL */

/******************************************************************************
 *  If the library is compiled without SSL, the "pop3sock_t" type is a simple
 *  integer (i.e. socket) and all the functions should work just as they did
 *  in previous libspopc versions (< 0.8).
 ******************************************************************************/

typedef int pop3sock_t;


#define BAD_SOCK -1

#endif /* SSL/Non-SSL */


/***************************************
 * low-level methods for a pop3 client *
 ***************************************/
#define SOCKET_TIMEOUT 15 /* seconds a socket can block read/write */
#define TCPBUFLEN 512 /* length of generic socket buffer */
#define DOTLINELEN 5 /* length of the strict dotline string */
#define POPBUF 513 /* length of the pop resp: 512 bytes (RFC1939) + '\0' */
/******************************************************************************
 * Be careful, using the low-level API is uncompliant with using the high     
 * level API. Here, you make your choice. If you don't know the pop3 protocol 
 * or what a socket is, it is then warmly recommended to use the *high-level* 
 * API if which is shown far below on this file.                              
 ******************************************************************************/

/**************
 * connecting *
 **************/

DLLIMPORT pop3sock_t pop3_prepare(const char* servername, const int port, struct sockaddr_in* connection, struct hostent* server);
/* prepares the pop session and returns a socket descriptor, or BAD_SOCK on error */

DLLIMPORT char* pop3_connect(pop3sock_t sock, struct sockaddr_in* connection);
/* connects to the server through the sock and returns server's welcome */

DLLIMPORT void pop3_disconnect(pop3sock_t sock, struct hostent* server);
/* close socket and free server info */

DLLIMPORT int pop3_timeout(pop3sock_t sock, int timeout);
/* sets the timeout in seconds for a socket descriptor */

/****************
 * pop3 queries *
 ****************/

DLLIMPORT char* pop3_user(pop3sock_t sock, const char* name);
/* performs "USER" pop query and returns server's <=512 bytes resp */

DLLIMPORT char* pop3_pass(pop3sock_t sock, const char* pw);
/* performs "PASS" pop query and return server's <=512 bytes resp */

DLLIMPORT char* pop3_quit(pop3sock_t sock);
/* performs "QUIT" pop query and returns server's <=512 bytes resp */

DLLIMPORT char* pop3_stat(pop3sock_t sock);
/* performs "STAT" pop query and returns server's <=512 bytes resp */


DLLIMPORT char* pop3_list(pop3sock_t sock, int id);
/* performs a "LIST" pop query and returns server's (long) resp */

DLLIMPORT char* pop3_retr(pop3sock_t sock, int id);
/* performs a "RETR" pop query and returns server's (long) resp */

DLLIMPORT char* pop3_dele(pop3sock_t sock, int id);
/* performs a "DELE" pop query and returns server's <=512 bytes resp */

DLLIMPORT char* pop3_noop(pop3sock_t sock);
/* performs a "NOOP" pop query and returns server's <=512 bytes resp */

DLLIMPORT char* pop3_rset(pop3sock_t sock);
/* performs a "RSET" pop query and returns server's <=512 bytes resp */

DLLIMPORT char* pop3_top(pop3sock_t sock, int id, int lines);
/* performs a "TOP" pop query and returns server's (long) resp */

DLLIMPORT char* pop3_uidl(pop3sock_t sock, int id);
/* performs a "UIDL" pop query and returns server's (long) resp */

DLLIMPORT char* pop3_apop(pop3sock_t sock, const char* name, const char* digest);
/* performs a "APOP" secure pop query and returns server's <=512 bytes resp */


/*********************
 * parsing utilities *
 *********************/
#define DOTBEGIN(s) ((s)[0]=='\n'&&(s)[1]=='.')

int dotline(char* buf, int total_size);
/* returns 1 if 'buf' contains a "\n.\n" or "\n.\0" or \r.(etc) substring
 * buf must be terminated by '\0' */

DLLIMPORT int pop3_error(char* string);
/* returns 1 on pop server error (i.e : -ERR ...) or NULL reply */

/************************************
 * reply re-formatting, after query *
 ************************************/
DLLIMPORT char* nextline(char* string);
/* returns a pointer to the next line of given string */

DLLIMPORT char* retr2msg(char* data);
/* returns formatted mail from a pop RETR X query
 * must only be called on data returned by pop3_retr() */

DLLIMPORT void freemsg(char* msg);
/* free the message received by reetr2msg */

DLLIMPORT int* list2array(char* poplist);
/* WARNING: must not be called after a mail deletion
 * returns an int array of sizes of messages from a LIST pop query
 * array[0] holds id of the array's last element
 * must only be called on data received by a pop3_list(sock,0) request */

DLLIMPORT void freelistarray(int* array);
/* free the message sizes array created by list2array */

DLLIMPORT int listi2size(char* resp);
/* grep the given size (in bytes) in resp after a pop3_list(sock,ID) request
 * do not use after a pop3_list(sock,0) ! */

DLLIMPORT int stat2num(char* resp);
/* returns the number of downloadable messages on pop server */

DLLIMPORT int stat2bytes(char* resp);
/* returns the sumsize in bytes of all stored messages on server
 * must only be called just after a pop3_stat() request */

DLLIMPORT char** uidl2array(char* resp);
/* WARNING: mus not be called after a mail deletion
 * returns an array of unique strings for each message id
 * array[0] gives array's last id
 * must only be called just after a pop3_uidl(sock,0) request */

DLLIMPORT void freeuidlarray(char** arrray);
/* free the uidl array created by uidl2array */

DLLIMPORT char* uidli2sig(char* resp);
/* grep the pop signature of *one* message signature reply
 * should only be called on data received by a pop3_uidl(sock,ID) request
 * do not use it after a pop3_uidl(sock,0) ! */


/***************************************************
 * high-level API for a SIMPLE MDA/MUA             *
 ***************************************************/

/******************************************************************************
 * This is the high-level API of libspopc and it is recommended to use it     
 * instead of the low-level one. This high-level API, in spite of its very    
 * 'teasing' name, just provides a *very simple* way to access and query a    
 * pop3 server with your e-mail client. This API handles pop3 in a very       
 * convenient manner for the non 'socket-aware' C developper.                 
 ******************************************************************************/

typedef struct{
        pop3sock_t sock;                 /* socket descriptor */
        struct sockaddr_in* connection;
        struct hostent* server;
        int* list;                       /* pop messages size list */
        char** uidl;                     /* pop messages signature list */
        int bytes;                       /* total stored (in bytes) on pop server */
        int last;                        /* last available message id */
        int num;                         /* number of available messages */
        int del;                         /* 0|1 flag to ask deletion of retrieved messages */
        int sync;                        /* session state: 1 = sync-ed; 0 = need sync */
} popsession;

#define popbytes(s) ((s)->bytes)
/* gives the total stored data size (in bytes) on the pop server
 * arg 's' is type 'popsession*'; 'result' is type 'int' */

#define popsetdel(s) ((s)->del=1)
/* asks the session to delete any retrieved messages on the server
 * arg 's' is type 'popsession*' */

#define popsetundel(s) ((s)->del=0)
/* asks the session to not delete any retrieved message on the server
 * arg 's' is type 'popsession*' */

#define popmsgsize(s,i) ((s)->list[(i)])
/* gives the size of message 'i' for session 's'
 * args are type 'session*'(s) and 'int'(i)
 * 'i' must *not* be 0 */

#define popmsguid(s,i) ((s)->uidl[(i)])
/* points to the 'char*' uid (unique signature) of 'int'(i) message id */

DLLIMPORT int poplast(popsession* session);
/* gives the id of the last message of the current session */

DLLIMPORT int popnum(popsession* session);
/* gives the current number of stored message. it is != to poplast() */

DLLIMPORT char* popbegin(const char* servername,const char* user, const char* pass, popsession** sp);
/* prepares, connect and get lists of messages stored on pop server
 * you must give a valid servername, user and pass
 * returns an error message if a problem occurs, else NULL */

DLLIMPORT int popsettimeout(popsession* session, int timeout);
/* sets the timeout in seconds for a session, returns 0 on success, < 0 on error */
 
DLLIMPORT char* popgethead(popsession* session, int id);
/* returns the header of a message (id between 1 and poplast()) or NULL on bad id */

DLLIMPORT char* popgetmsg(popsession* session, int id);
/* returns a message (id between 1 and poplast()) or NULL on bad id */

DLLIMPORT int popdelmsg(popsession* session, int id);
/* deletes message 'id' on pop server
 * returns -1 on server error, 0 else */

DLLIMPORT int popchkmsg(popsession* session, int id);
/* tells if a message is still accessible on the server (not deleted)
 * returns 1 of so, or 0 if message has been marked for deletion */

DLLIMPORT int popcancel(popsession* session);
/* cancels all previous deletion on pop server
 * returns -1 on server error, 0 else */

DLLIMPORT int popsync(popsession* session);
/* re-synchronize the session object from the server
 * need to be called if session->sync is 0
 * returns -1 on error, 0 else */

DLLIMPORT void popend(popsession* session);
/* quit and destroys pop session */

#ifdef __cplusplus
}
#endif
#endif
1	ben	1	/* this is libspopc.h file, part of the libspopc library sources
2			* copyright © 2002- Benoit Rouits <brouits@free.fr>
3			* released under the terms of the GNU Lesser General Public Licence.
4			*
5			* libspopc offers simple API for a pop3 client.
6			* See RFC 1725 for pop3 specifications.
7			*
8			* This library is free software; you can redistribute it and/or
9			* modify it under the terms of the GNU Lesser General Public
10			* License as published by the Free Software Foundation; either
11			* version 2.1 of the License, or (at your option) any later version.
12			*
13			* This library is distributed in the hope that it will be useful,
14			* but WITHOUT ANY WARRANTY; without even the implied warranty of
15			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16			* Lesser General Public License for more details.
17			*
18			* You should have received a copy of the GNU Lesser General Public
19			* License along with this library; if not, write to the Free Software
20			* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21			*/
22
23			#ifndef LIBSPOPC_H
24			#define LIBSPOPC_H
25
26			#ifdef __cplusplus
27			extern "C" {
28			#endif
29
30			#include <sys/types.h>
31
32			#ifdef WIN32
33			#include <winsock.h>
34	ben	6	#if BUILDING_DLL
35			# define DLLIMPORT __declspec (dllexport)
36			#else /* Not BUILDING_DLL */
37			# define DLLIMPORT __declspec (dllimport)
38			#endif /* Not BUILDING_DLL */
39	ben	1	#else
40			#include <sys/socket.h>
41			#include <netinet/in.h>
42			#include <netdb.h>
43	ben	6	#define DLLIMPORT
44	ben	1	#endif
45
46			/* thread-safe version of libspopc (>0.8) */
47
48			/* call this function before to use any routine from libspopc */
49	ben	6	DLLIMPORT int libspopc_init(void);
50	ben	1
51			/* call this function when you do not use anymore libspopc routines */
52	ben	6	DLLIMPORT int libspopc_clean(void);
53	ben	1
54			#ifdef USE_SSL
55
56			#include <openssl/ssl.h>
57
58			/******************************************************************************
59			* If compiled with SSL support, the low-level functions will act on a
60			* "pop3sock" structure, which contains the socket, SSL instance and context
61			* for the connection. This structure is dynamically allocated and initialized
62			* when you do pop3_prepare() or popbegin(), and is cleaned-up and destroyed in
63			* pop3_disconnect() or popend().
64			******************************************************************************/
65
66			typedef struct {
67			int sock;
68			SSL *ssl;
69			SSL_CTX *ctx;
70			} pop3sock;
71
72			typedef pop3sock* pop3sock_t;
73
74			#define BAD_SOCK NULL
75
76			/******************************************************************************
77			* Use pop3_cert_setup() to specify the location of your SSL certificate
78			* bundle. If it is not set (or set to NULL), SSL connections can be still be
79			* made, but certificates will not be verified!
80			* This function sets a global variable, and should be called before
81			* pop3_prepare() or popbegin() if you want to verify certs.
82			*
83			* Hint: If you have a recent version of curl/libcurl installed, you can try
84			* setting this to the output of: "curl-config --ca"
85			******************************************************************************/
86	ben	6	DLLIMPORT void pop3_cert_setup(const char *certfile);
87	ben	1
88			/******************************************************************************
89			* pop3_ssl_never() disable the use of SSL on any port, even 995.
90			* pop3_ssl_auto() enable the use of SSL only on port 995. (default)
91			* pop3_ssl_always() enable the use of SSL on any port, even 110.
92			*
93			* These functions set a library-wide variable, and should be called before
94			* pop3_prepare() or popbegin() if you want to modify libspopc behaviour.
95			* By default, not calling any of these, the behaviour of libspopc follows
96			* the same as pop3_ssl_auto() for backward compatibility reason.
97			******************************************************************************/
98	ben	6	DLLIMPORT void pop3_ssl_never(void);
99			DLLIMPORT void pop3_ssl_auto(void);
100			DLLIMPORT void pop3_ssl_always(void);
101	ben	1
102			#else /* Non-SSL */
103
104			/******************************************************************************
105			* If the library is compiled without SSL, the "pop3sock_t" type is a simple
106			* integer (i.e. socket) and all the functions should work just as they did
107			* in previous libspopc versions (< 0.8).
108			******************************************************************************/
109
110			typedef int pop3sock_t;
111
112
113			#define BAD_SOCK -1
114
115			#endif /* SSL/Non-SSL */
116
117
118			/***************************************
119			* low-level methods for a pop3 client *
120			***************************************/
121	ben	21	#define SOCKET_TIMEOUT 15 /* seconds a socket can block read/write */
122	ben	1	#define TCPBUFLEN 512 /* length of generic socket buffer */
123	ben	26	#define DOTLINELEN 5 /* length of the strict dotline string */
124	ben	1	#define POPBUF 513 /* length of the pop resp: 512 bytes (RFC1939) + '\0' */
125			/******************************************************************************
126			* Be careful, using the low-level API is uncompliant with using the high
127			* level API. Here, you make your choice. If you don't know the pop3 protocol
128			* or what a socket is, it is then warmly recommended to use the high-level
129			* API if which is shown far below on this file.
130			******************************************************************************/
131
132			/**************
133			* connecting *
134			**************/
135
136	ben	6	DLLIMPORT pop3sock_t pop3_prepare(const char* servername, const int port, struct sockaddr_in* connection, struct hostent* server);
137	ben	1	/* prepares the pop session and returns a socket descriptor, or BAD_SOCK on error */
138
139	ben	6	DLLIMPORT char* pop3_connect(pop3sock_t sock, struct sockaddr_in* connection);
140	ben	1	/* connects to the server through the sock and returns server's welcome */
141
142	ben	6	DLLIMPORT void pop3_disconnect(pop3sock_t sock, struct hostent* server);
143	ben	1	/* close socket and free server info */
144
145	ben	22	DLLIMPORT int pop3_timeout(pop3sock_t sock, int timeout);
146			/* sets the timeout in seconds for a socket descriptor */
147	ben	1
148			/****************
149			* pop3 queries *
150			****************/
151
152	ben	6	DLLIMPORT char* pop3_user(pop3sock_t sock, const char* name);
153	ben	1	/* performs "USER" pop query and returns server's <=512 bytes resp */
154
155	ben	6	DLLIMPORT char* pop3_pass(pop3sock_t sock, const char* pw);
156	ben	1	/* performs "PASS" pop query and return server's <=512 bytes resp */
157
158	ben	6	DLLIMPORT char* pop3_quit(pop3sock_t sock);
159	ben	1	/* performs "QUIT" pop query and returns server's <=512 bytes resp */
160
161	ben	6	DLLIMPORT char* pop3_stat(pop3sock_t sock);
162	ben	1	/* performs "STAT" pop query and returns server's <=512 bytes resp */
163
164
165	ben	6	DLLIMPORT char* pop3_list(pop3sock_t sock, int id);
166	ben	1	/* performs a "LIST" pop query and returns server's (long) resp */
167
168	ben	6	DLLIMPORT char* pop3_retr(pop3sock_t sock, int id);
169	ben	1	/* performs a "RETR" pop query and returns server's (long) resp */
170
171	ben	6	DLLIMPORT char* pop3_dele(pop3sock_t sock, int id);
172	ben	1	/* performs a "DELE" pop query and returns server's <=512 bytes resp */
173
174	ben	6	DLLIMPORT char* pop3_noop(pop3sock_t sock);
175	ben	1	/* performs a "NOOP" pop query and returns server's <=512 bytes resp */
176
177	ben	6	DLLIMPORT char* pop3_rset(pop3sock_t sock);
178	ben	1	/* performs a "RSET" pop query and returns server's <=512 bytes resp */
179
180	ben	6	DLLIMPORT char* pop3_top(pop3sock_t sock, int id, int lines);
181	ben	1	/* performs a "TOP" pop query and returns server's (long) resp */
182
183	ben	6	DLLIMPORT char* pop3_uidl(pop3sock_t sock, int id);
184	ben	1	/* performs a "UIDL" pop query and returns server's (long) resp */
185
186	ben	6	DLLIMPORT char* pop3_apop(pop3sock_t sock, const char* name, const char* digest);
187	ben	1	/* performs a "APOP" secure pop query and returns server's <=512 bytes resp */
188
189
190			/*********************
191			* parsing utilities *
192			*********************/
193			#define DOTBEGIN(s) ((s)[0]=='\n'&&(s)[1]=='.')
194
195	ben	24	int dotline(char* buf, int total_size);
196	ben	1	/* returns 1 if 'buf' contains a "\n.\n" or "\n.\0" or \r.(etc) substring
197			* buf must be terminated by '\0' */
198
199	ben	6	DLLIMPORT int pop3_error(char* string);
200	ben	1	/* returns 1 on pop server error (i.e : -ERR ...) or NULL reply */
201
202			/************************************
203			* reply re-formatting, after query *
204			************************************/
205	ben	6	DLLIMPORT char* nextline(char* string);
206	ben	1	/* returns a pointer to the next line of given string */
207
208	ben	6	DLLIMPORT char* retr2msg(char* data);
209	ben	1	/* returns formatted mail from a pop RETR X query
210			* must only be called on data returned by pop3_retr() */
211
212	ben	6	DLLIMPORT void freemsg(char* msg);
213	ben	1	/* free the message received by reetr2msg */
214
215	ben	6	DLLIMPORT int* list2array(char* poplist);
216	ben	1	/* WARNING: must not be called after a mail deletion
217			* returns an int array of sizes of messages from a LIST pop query
218			* array[0] holds id of the array's last element
219			* must only be called on data received by a pop3_list(sock,0) request */
220
221	ben	6	DLLIMPORT void freelistarray(int* array);
222	ben	1	/* free the message sizes array created by list2array */
223
224	ben	6	DLLIMPORT int listi2size(char* resp);
225	ben	1	/* grep the given size (in bytes) in resp after a pop3_list(sock,ID) request
226			* do not use after a pop3_list(sock,0) ! */
227
228	ben	6	DLLIMPORT int stat2num(char* resp);
229	ben	1	/* returns the number of downloadable messages on pop server */
230
231	ben	6	DLLIMPORT int stat2bytes(char* resp);
232	ben	1	/* returns the sumsize in bytes of all stored messages on server
233			* must only be called just after a pop3_stat() request */
234
235	ben	6	DLLIMPORT char** uidl2array(char* resp);
236	ben	1	/* WARNING: mus not be called after a mail deletion
237			* returns an array of unique strings for each message id
238			* array[0] gives array's last id
239			* must only be called just after a pop3_uidl(sock,0) request */
240
241	ben	6	DLLIMPORT void freeuidlarray(char** arrray);
242	ben	1	/* free the uidl array created by uidl2array */
243
244	ben	6	DLLIMPORT char* uidli2sig(char* resp);
245	ben	1	/* grep the pop signature of one message signature reply
246			* should only be called on data received by a pop3_uidl(sock,ID) request
247			* do not use it after a pop3_uidl(sock,0) ! */
248
249
250			/***************************************************
251			* high-level API for a SIMPLE MDA/MUA *
252			***************************************************/
253
254			/******************************************************************************
255			* This is the high-level API of libspopc and it is recommended to use it
256			* instead of the low-level one. This high-level API, in spite of its very
257			* 'teasing' name, just provides a very simple way to access and query a
258			* pop3 server with your e-mail client. This API handles pop3 in a very
259			* convenient manner for the non 'socket-aware' C developper.
260			******************************************************************************/
261
262			typedef struct{
263			pop3sock_t sock; /* socket descriptor */
264			struct sockaddr_in* connection;
265			struct hostent* server;
266			int* list; /* pop messages size list */
267			char** uidl; /* pop messages signature list */
268			int bytes; /* total stored (in bytes) on pop server */
269			int last; /* last available message id */
270			int num; /* number of available messages */
271			int del; /* 0\|1 flag to ask deletion of retrieved messages */
272			int sync; /* session state: 1 = sync-ed; 0 = need sync */
273			} popsession;
274
275			#define popbytes(s) ((s)->bytes)
276			/* gives the total stored data size (in bytes) on the pop server
277			* arg 's' is type 'popsession'; 'result' is type 'int' /
278
279			#define popsetdel(s) ((s)->del=1)
280			/* asks the session to delete any retrieved messages on the server
281			* arg 's' is type 'popsession' /
282
283			#define popsetundel(s) ((s)->del=0)
284			/* asks the session to not delete any retrieved message on the server
285			* arg 's' is type 'popsession' /
286
287			#define popmsgsize(s,i) ((s)->list[(i)])
288			/* gives the size of message 'i' for session 's'
289			* args are type 'session*'(s) and 'int'(i)
290			* 'i' must not be 0 */
291
292			#define popmsguid(s,i) ((s)->uidl[(i)])
293			/* points to the 'char' uid (unique signature) of 'int'(i) message id /
294
295	ben	6	DLLIMPORT int poplast(popsession* session);
296	ben	1	/* gives the id of the last message of the current session */
297
298	ben	6	DLLIMPORT int popnum(popsession* session);
299	ben	1	/* gives the current number of stored message. it is != to poplast() */
300
301	ben	6	DLLIMPORT char* popbegin(const char* servername,const char* user, const char* pass, popsession** sp);
302	ben	1	/* prepares, connect and get lists of messages stored on pop server
303			* you must give a valid servername, user and pass
304			* returns an error message if a problem occurs, else NULL */
305
306	ben	22	DLLIMPORT int popsettimeout(popsession* session, int timeout);
307			/* sets the timeout in seconds for a session, returns 0 on success, < 0 on error */
308
309	ben	6	DLLIMPORT char* popgethead(popsession* session, int id);
310	ben	1	/* returns the header of a message (id between 1 and poplast()) or NULL on bad id */
311
312	ben	6	DLLIMPORT char* popgetmsg(popsession* session, int id);
313	ben	1	/* returns a message (id between 1 and poplast()) or NULL on bad id */
314
315	ben	6	DLLIMPORT int popdelmsg(popsession* session, int id);
316	ben	1	/* deletes message 'id' on pop server
317			* returns -1 on server error, 0 else */
318
319	ben	6	DLLIMPORT int popchkmsg(popsession* session, int id);
320	ben	1	/* tells if a message is still accessible on the server (not deleted)
321			* returns 1 of so, or 0 if message has been marked for deletion */
322
323	ben	6	DLLIMPORT int popcancel(popsession* session);
324	ben	1	/* cancels all previous deletion on pop server
325			* returns -1 on server error, 0 else */
326
327	ben	6	DLLIMPORT int popsync(popsession* session);
328	ben	1	/* re-synchronize the session object from the server
329			* need to be called if session->sync is 0
330			* returns -1 on error, 0 else */
331
332	ben	6	DLLIMPORT void popend(popsession* session);
333	ben	1	/* quit and destroys pop session */
334
335			#ifdef __cplusplus
336			}
337			#endif
338			#endif