/[libspopc]/libspopc.h
ViewVC logotype

Contents of /libspopc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (show annotations)
Thu Oct 8 11:53:59 2009 UTC (11 years, 3 months ago) by ben
File MIME type: text/plain
File size: 12429 byte(s)
import from old repo, version 0.10.2
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

  ViewVC Help
Powered by ViewVC 1.1.26