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://brouits.free.fr/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>
#else
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#endif

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

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

/* call this function when you do not use anymore libspopc routines */
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"
 ******************************************************************************/
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.
 ******************************************************************************/
void pop3_ssl_never(void);
void pop3_ssl_auto(void);
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 *
 **************/

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 */

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

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


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

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

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

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

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


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

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

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

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

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

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

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

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' */

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

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

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

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

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 */

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

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) ! */

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

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 */

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 */

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

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 */

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

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

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 */

char* popgethead(popsession* session, int id);
/* returns the header of a message (id between 1 and poplast()) or NULL on bad id */

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

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

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 */

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

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 */

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