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.
 * more information on http://herewe.servebeer.com/libspopc/
 *
 *  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 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);
/* 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	/* 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	* more information on http://herewe.servebeer.com/libspopc/
8	*
9	* This library is free software; you can redistribute it and/or
10	* modify it under the terms of the GNU Lesser General Public
11	* License as published by the Free Software Foundation; either
12	* version 2.1 of the License, or (at your option) any later version.
13	*
14	* This library is distributed in the hope that it will be useful,
15	* but WITHOUT ANY WARRANTY; without even the implied warranty of
16	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17	* Lesser General Public License for more details.
18	*
19	* You should have received a copy of the GNU Lesser General Public
20	* License along with this library; if not, write to the Free Software
21	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22	*/
23
24	#ifndef LIBSPOPC_H
25	#define LIBSPOPC_H
26
27	#ifdef __cplusplus
28	extern "C" {
29	#endif
30
31	#include <sys/types.h>
32
33	#ifdef WIN32
34	#include <winsock.h>
35	#if BUILDING_DLL
36	# define DLLIMPORT __declspec (dllexport)
37	#else /* Not BUILDING_DLL */
38	# define DLLIMPORT __declspec (dllimport)
39	#endif /* Not BUILDING_DLL */
40	#else
41	#include <sys/socket.h>
42	#include <netinet/in.h>
43	#include <netdb.h>
44	#define DLLIMPORT
45	#endif
46
47	/* thread-safe version of libspopc (>0.8) */
48
49	/* call this function before to use any routine from libspopc */
50	DLLIMPORT int libspopc_init(void);
51
52	/* call this function when you do not use anymore libspopc routines */
53	DLLIMPORT int libspopc_clean(void);
54
55	#ifdef USE_SSL
56
57	#include <openssl/ssl.h>
58
59	/******************************************************************************
60	* If compiled with SSL support, the low-level functions will act on a
61	* "pop3sock" structure, which contains the socket, SSL instance and context
62	* for the connection. This structure is dynamically allocated and initialized
63	* when you do pop3_prepare() or popbegin(), and is cleaned-up and destroyed in
64	* pop3_disconnect() or popend().
65	******************************************************************************/
66
67	typedef struct {
68	int sock;
69	SSL *ssl;
70	SSL_CTX *ctx;
71	} pop3sock;
72
73	typedef pop3sock* pop3sock_t;
74
75	#define BAD_SOCK NULL
76
77	/******************************************************************************
78	* Use pop3_cert_setup() to specify the location of your SSL certificate
79	* bundle. If it is not set (or set to NULL), SSL connections can be still be
80	* made, but certificates will not be verified!
81	* This function sets a global variable, and should be called before
82	* pop3_prepare() or popbegin() if you want to verify certs.
83	*
84	* Hint: If you have a recent version of curl/libcurl installed, you can try
85	* setting this to the output of: "curl-config --ca"
86	******************************************************************************/
87	DLLIMPORT void pop3_cert_setup(const char *certfile);
88
89	/******************************************************************************
90	* pop3_ssl_never() disable the use of SSL on any port, even 995.
91	* pop3_ssl_auto() enable the use of SSL only on port 995. (default)
92	* pop3_ssl_always() enable the use of SSL on any port, even 110.
93	*
94	* These functions set a library-wide variable, and should be called before
95	* pop3_prepare() or popbegin() if you want to modify libspopc behaviour.
96	* By default, not calling any of these, the behaviour of libspopc follows
97	* the same as pop3_ssl_auto() for backward compatibility reason.
98	******************************************************************************/
99	DLLIMPORT void pop3_ssl_never(void);
100	DLLIMPORT void pop3_ssl_auto(void);
101	DLLIMPORT void pop3_ssl_always(void);
102
103	#else /* Non-SSL */
104
105	/******************************************************************************
106	* If the library is compiled without SSL, the "pop3sock_t" type is a simple
107	* integer (i.e. socket) and all the functions should work just as they did
108	* in previous libspopc versions (< 0.8).
109	******************************************************************************/
110
111	typedef int pop3sock_t;
112
113
114	#define BAD_SOCK -1
115
116	#endif /* SSL/Non-SSL */
117
118
119	/***************************************
120	* low-level methods for a pop3 client *
121	***************************************/
122	#define SOCKET_TIMEOUT 15 /* seconds a socket can block read/write */
123	#define TCPBUFLEN 512 /* length of generic socket buffer */
124	#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	DLLIMPORT pop3sock_t pop3_prepare(const char* servername, const int port, struct sockaddr_in* connection, struct hostent* server);
137	/* prepares the pop session and returns a socket descriptor, or BAD_SOCK on error */
138
139	DLLIMPORT char* pop3_connect(pop3sock_t sock, struct sockaddr_in* connection);
140	/* connects to the server through the sock and returns server's welcome */
141
142	DLLIMPORT void pop3_disconnect(pop3sock_t sock, struct hostent* server);
143	/* close socket and free server info */
144
145	DLLIMPORT int pop3_timeout(pop3sock_t sock, int timeout);
146	/* sets the timeout in seconds for a socket descriptor */
147
148	/****************
149	* pop3 queries *
150	****************/
151
152	DLLIMPORT char* pop3_user(pop3sock_t sock, const char* name);
153	/* performs "USER" pop query and returns server's <=512 bytes resp */
154
155	DLLIMPORT char* pop3_pass(pop3sock_t sock, const char* pw);
156	/* performs "PASS" pop query and return server's <=512 bytes resp */
157
158	DLLIMPORT char* pop3_quit(pop3sock_t sock);
159	/* performs "QUIT" pop query and returns server's <=512 bytes resp */
160
161	DLLIMPORT char* pop3_stat(pop3sock_t sock);
162	/* performs "STAT" pop query and returns server's <=512 bytes resp */
163
164
165	DLLIMPORT char* pop3_list(pop3sock_t sock, int id);
166	/* performs a "LIST" pop query and returns server's (long) resp */
167
168	DLLIMPORT char* pop3_retr(pop3sock_t sock, int id);
169	/* performs a "RETR" pop query and returns server's (long) resp */
170
171	DLLIMPORT char* pop3_dele(pop3sock_t sock, int id);
172	/* performs a "DELE" pop query and returns server's <=512 bytes resp */
173
174	DLLIMPORT char* pop3_noop(pop3sock_t sock);
175	/* performs a "NOOP" pop query and returns server's <=512 bytes resp */
176
177	DLLIMPORT char* pop3_rset(pop3sock_t sock);
178	/* performs a "RSET" pop query and returns server's <=512 bytes resp */
179
180	DLLIMPORT char* pop3_top(pop3sock_t sock, int id, int lines);
181	/* performs a "TOP" pop query and returns server's (long) resp */
182
183	DLLIMPORT char* pop3_uidl(pop3sock_t sock, int id);
184	/* performs a "UIDL" pop query and returns server's (long) resp */
185
186	DLLIMPORT char* pop3_apop(pop3sock_t sock, const char* name, const char* digest);
187	/* 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	int dotline(char* buf);
196	/* returns 1 if 'buf' contains a "\n.\n" or "\n.\0" or \r.(etc) substring
197	* buf must be terminated by '\0' */
198
199	DLLIMPORT int pop3_error(char* string);
200	/* returns 1 on pop server error (i.e : -ERR ...) or NULL reply */
201
202	/************************************
203	* reply re-formatting, after query *
204	************************************/
205	DLLIMPORT char* nextline(char* string);
206	/* returns a pointer to the next line of given string */
207
208	DLLIMPORT char* retr2msg(char* data);
209	/* returns formatted mail from a pop RETR X query
210	* must only be called on data returned by pop3_retr() */
211
212	DLLIMPORT void freemsg(char* msg);
213	/* free the message received by reetr2msg */
214
215	DLLIMPORT int* list2array(char* poplist);
216	/* 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	DLLIMPORT void freelistarray(int* array);
222	/* free the message sizes array created by list2array */
223
224	DLLIMPORT int listi2size(char* resp);
225	/* 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	DLLIMPORT int stat2num(char* resp);
229	/* returns the number of downloadable messages on pop server */
230
231	DLLIMPORT int stat2bytes(char* resp);
232	/* returns the sumsize in bytes of all stored messages on server
233	* must only be called just after a pop3_stat() request */
234
235	DLLIMPORT char** uidl2array(char* resp);
236	/* 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	DLLIMPORT void freeuidlarray(char** arrray);
242	/* free the uidl array created by uidl2array */
243
244	DLLIMPORT char* uidli2sig(char* resp);
245	/* 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	DLLIMPORT int poplast(popsession* session);
296	/* gives the id of the last message of the current session */
297
298	DLLIMPORT int popnum(popsession* session);
299	/* gives the current number of stored message. it is != to poplast() */
300
301	DLLIMPORT char* popbegin(const char* servername,const char* user, const char* pass, popsession** sp);
302	/* 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	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	DLLIMPORT char* popgethead(popsession* session, int id);
310	/* returns the header of a message (id between 1 and poplast()) or NULL on bad id */
311
312	DLLIMPORT char* popgetmsg(popsession* session, int id);
313	/* returns a message (id between 1 and poplast()) or NULL on bad id */
314
315	DLLIMPORT int popdelmsg(popsession* session, int id);
316	/* deletes message 'id' on pop server
317	* returns -1 on server error, 0 else */
318
319	DLLIMPORT int popchkmsg(popsession* session, int id);
320	/* 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	DLLIMPORT int popcancel(popsession* session);
324	/* cancels all previous deletion on pop server
325	* returns -1 on server error, 0 else */
326
327	DLLIMPORT int popsync(popsession* session);
328	/* 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	DLLIMPORT void popend(popsession* session);
333	/* quit and destroys pop session */
334
335	#ifdef __cplusplus
336	}
337	#endif
338	#endif