/[libspopc]/libspopc.h
ViewVC logotype

Annotation of /libspopc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2 - (hide annotations)
Thu Oct 8 15:37:49 2009 UTC (11 years, 3 months ago) by ben
File MIME type: text/plain
File size: 12434 byte(s)
changed project url
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 ben 2 * more information on http://herewe.servebeer.com/libspopc/
8 ben 1 *
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

  ViewVC Help
Powered by ViewVC 1.1.26