/[libspopc]/libspopc.h
ViewVC logotype

Annotation of /libspopc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6 - (hide annotations)
Sun Apr 18 11:05:58 2010 UTC (10 years, 9 months ago) by ben
File MIME type: text/plain
File size: 13042 byte(s)
windows version revival (dev-cpp)
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 ben 6 #if BUILDING_DLL
36     # define DLLIMPORT __declspec (dllexport)
37     #else /* Not BUILDING_DLL */
38     # define DLLIMPORT __declspec (dllimport)
39     #endif /* Not BUILDING_DLL */
40 ben 1 #else
41     #include <sys/socket.h>
42     #include <netinet/in.h>
43     #include <netdb.h>
44 ben 6 #define DLLIMPORT
45 ben 1 #endif
46    
47     /* thread-safe version of libspopc (>0.8) */
48    
49     /* call this function before to use any routine from libspopc */
50 ben 6 DLLIMPORT int libspopc_init(void);
51 ben 1
52     /* call this function when you do not use anymore libspopc routines */
53 ben 6 DLLIMPORT int libspopc_clean(void);
54 ben 1
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 ben 6 DLLIMPORT void pop3_cert_setup(const char *certfile);
88 ben 1
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 ben 6 DLLIMPORT void pop3_ssl_never(void);
100     DLLIMPORT void pop3_ssl_auto(void);
101     DLLIMPORT void pop3_ssl_always(void);
102 ben 1
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 ben 6 DLLIMPORT pop3sock_t pop3_prepare(const char* servername, const int port, struct sockaddr_in* connection, struct hostent* server);
137 ben 1 /* prepares the pop session and returns a socket descriptor, or BAD_SOCK on error */
138    
139 ben 6 DLLIMPORT char* pop3_connect(pop3sock_t sock, struct sockaddr_in* connection);
140 ben 1 /* connects to the server through the sock and returns server's welcome */
141    
142 ben 6 DLLIMPORT void pop3_disconnect(pop3sock_t sock, struct hostent* server);
143 ben 1 /* close socket and free server info */
144    
145    
146     /****************
147     * pop3 queries *
148     ****************/
149    
150 ben 6 DLLIMPORT char* pop3_user(pop3sock_t sock, const char* name);
151 ben 1 /* performs "USER" pop query and returns server's <=512 bytes resp */
152    
153 ben 6 DLLIMPORT char* pop3_pass(pop3sock_t sock, const char* pw);
154 ben 1 /* performs "PASS" pop query and return server's <=512 bytes resp */
155    
156 ben 6 DLLIMPORT char* pop3_quit(pop3sock_t sock);
157 ben 1 /* performs "QUIT" pop query and returns server's <=512 bytes resp */
158    
159 ben 6 DLLIMPORT char* pop3_stat(pop3sock_t sock);
160 ben 1 /* performs "STAT" pop query and returns server's <=512 bytes resp */
161    
162    
163 ben 6 DLLIMPORT char* pop3_list(pop3sock_t sock, int id);
164 ben 1 /* performs a "LIST" pop query and returns server's (long) resp */
165    
166 ben 6 DLLIMPORT char* pop3_retr(pop3sock_t sock, int id);
167 ben 1 /* performs a "RETR" pop query and returns server's (long) resp */
168    
169 ben 6 DLLIMPORT char* pop3_dele(pop3sock_t sock, int id);
170 ben 1 /* performs a "DELE" pop query and returns server's <=512 bytes resp */
171    
172 ben 6 DLLIMPORT char* pop3_noop(pop3sock_t sock);
173 ben 1 /* performs a "NOOP" pop query and returns server's <=512 bytes resp */
174    
175 ben 6 DLLIMPORT char* pop3_rset(pop3sock_t sock);
176 ben 1 /* performs a "RSET" pop query and returns server's <=512 bytes resp */
177    
178 ben 6 DLLIMPORT char* pop3_top(pop3sock_t sock, int id, int lines);
179 ben 1 /* performs a "TOP" pop query and returns server's (long) resp */
180    
181 ben 6 DLLIMPORT char* pop3_uidl(pop3sock_t sock, int id);
182 ben 1 /* performs a "UIDL" pop query and returns server's (long) resp */
183    
184 ben 6 DLLIMPORT char* pop3_apop(pop3sock_t sock, const char* name, const char* digest);
185 ben 1 /* performs a "APOP" secure pop query and returns server's <=512 bytes resp */
186    
187    
188     /*********************
189     * parsing utilities *
190     *********************/
191     #define DOTBEGIN(s) ((s)[0]=='\n'&&(s)[1]=='.')
192    
193     int dotline(char* buf);
194     /* returns 1 if 'buf' contains a "\n.\n" or "\n.\0" or \r.(etc) substring
195     * buf must be terminated by '\0' */
196    
197 ben 6 DLLIMPORT int pop3_error(char* string);
198 ben 1 /* returns 1 on pop server error (i.e : -ERR ...) or NULL reply */
199    
200     /************************************
201     * reply re-formatting, after query *
202     ************************************/
203 ben 6 DLLIMPORT char* nextline(char* string);
204 ben 1 /* returns a pointer to the next line of given string */
205    
206 ben 6 DLLIMPORT char* retr2msg(char* data);
207 ben 1 /* returns formatted mail from a pop RETR X query
208     * must only be called on data returned by pop3_retr() */
209    
210 ben 6 DLLIMPORT void freemsg(char* msg);
211 ben 1 /* free the message received by reetr2msg */
212    
213 ben 6 DLLIMPORT int* list2array(char* poplist);
214 ben 1 /* WARNING: must not be called after a mail deletion
215     * returns an int array of sizes of messages from a LIST pop query
216     * array[0] holds id of the array's last element
217     * must only be called on data received by a pop3_list(sock,0) request */
218    
219 ben 6 DLLIMPORT void freelistarray(int* array);
220 ben 1 /* free the message sizes array created by list2array */
221    
222 ben 6 DLLIMPORT int listi2size(char* resp);
223 ben 1 /* grep the given size (in bytes) in resp after a pop3_list(sock,ID) request
224     * do not use after a pop3_list(sock,0) ! */
225    
226 ben 6 DLLIMPORT int stat2num(char* resp);
227 ben 1 /* returns the number of downloadable messages on pop server */
228    
229 ben 6 DLLIMPORT int stat2bytes(char* resp);
230 ben 1 /* returns the sumsize in bytes of all stored messages on server
231     * must only be called just after a pop3_stat() request */
232    
233 ben 6 DLLIMPORT char** uidl2array(char* resp);
234 ben 1 /* WARNING: mus not be called after a mail deletion
235     * returns an array of unique strings for each message id
236     * array[0] gives array's last id
237     * must only be called just after a pop3_uidl(sock,0) request */
238    
239 ben 6 DLLIMPORT void freeuidlarray(char** arrray);
240 ben 1 /* free the uidl array created by uidl2array */
241    
242 ben 6 DLLIMPORT char* uidli2sig(char* resp);
243 ben 1 /* grep the pop signature of *one* message signature reply
244     * should only be called on data received by a pop3_uidl(sock,ID) request
245     * do not use it after a pop3_uidl(sock,0) ! */
246    
247    
248     /***************************************************
249     * high-level API for a SIMPLE MDA/MUA *
250     ***************************************************/
251    
252     /******************************************************************************
253     * This is the high-level API of libspopc and it is recommended to use it
254     * instead of the low-level one. This high-level API, in spite of its very
255     * 'teasing' name, just provides a *very simple* way to access and query a
256     * pop3 server with your e-mail client. This API handles pop3 in a very
257     * convenient manner for the non 'socket-aware' C developper.
258     ******************************************************************************/
259    
260     typedef struct{
261     pop3sock_t sock; /* socket descriptor */
262     struct sockaddr_in* connection;
263     struct hostent* server;
264     int* list; /* pop messages size list */
265     char** uidl; /* pop messages signature list */
266     int bytes; /* total stored (in bytes) on pop server */
267     int last; /* last available message id */
268     int num; /* number of available messages */
269     int del; /* 0|1 flag to ask deletion of retrieved messages */
270     int sync; /* session state: 1 = sync-ed; 0 = need sync */
271     } popsession;
272    
273     #define popbytes(s) ((s)->bytes)
274     /* gives the total stored data size (in bytes) on the pop server
275     * arg 's' is type 'popsession*'; 'result' is type 'int' */
276    
277     #define popsetdel(s) ((s)->del=1)
278     /* asks the session to delete any retrieved messages on the server
279     * arg 's' is type 'popsession*' */
280    
281     #define popsetundel(s) ((s)->del=0)
282     /* asks the session to not delete any retrieved message on the server
283     * arg 's' is type 'popsession*' */
284    
285     #define popmsgsize(s,i) ((s)->list[(i)])
286     /* gives the size of message 'i' for session 's'
287     * args are type 'session*'(s) and 'int'(i)
288     * 'i' must *not* be 0 */
289    
290     #define popmsguid(s,i) ((s)->uidl[(i)])
291     /* points to the 'char*' uid (unique signature) of 'int'(i) message id */
292    
293 ben 6 DLLIMPORT int poplast(popsession* session);
294 ben 1 /* gives the id of the last message of the current session */
295    
296 ben 6 DLLIMPORT int popnum(popsession* session);
297 ben 1 /* gives the current number of stored message. it is != to poplast() */
298    
299 ben 6 DLLIMPORT char* popbegin(const char* servername,const char* user, const char* pass, popsession** sp);
300 ben 1 /* prepares, connect and get lists of messages stored on pop server
301     * you must give a valid servername, user and pass
302     * returns an error message if a problem occurs, else NULL */
303    
304 ben 6 DLLIMPORT char* popgethead(popsession* session, int id);
305 ben 1 /* returns the header of a message (id between 1 and poplast()) or NULL on bad id */
306    
307 ben 6 DLLIMPORT char* popgetmsg(popsession* session, int id);
308 ben 1 /* returns a message (id between 1 and poplast()) or NULL on bad id */
309    
310 ben 6 DLLIMPORT int popdelmsg(popsession* session, int id);
311 ben 1 /* deletes message 'id' on pop server
312     * returns -1 on server error, 0 else */
313    
314 ben 6 DLLIMPORT int popchkmsg(popsession* session, int id);
315 ben 1 /* tells if a message is still accessible on the server (not deleted)
316     * returns 1 of so, or 0 if message has been marked for deletion */
317    
318 ben 6 DLLIMPORT int popcancel(popsession* session);
319 ben 1 /* cancels all previous deletion on pop server
320     * returns -1 on server error, 0 else */
321    
322 ben 6 DLLIMPORT int popsync(popsession* session);
323 ben 1 /* re-synchronize the session object from the server
324     * need to be called if session->sync is 0
325     * returns -1 on error, 0 else */
326    
327 ben 6 DLLIMPORT void popend(popsession* session);
328 ben 1 /* quit and destroys pop session */
329    
330     #ifdef __cplusplus
331     }
332     #endif
333     #endif

  ViewVC Help
Powered by ViewVC 1.1.26