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