1 |
libspopc manual |
2 |
|
3 |
Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008 |
4 |
|
5 |
|
6 |
= Introduction = |
7 |
|
8 |
libspopc is a pop3 client library written in C and uses BSD-style sockets. |
9 |
It uses sort of blocking sockets, but with a 15s timeout on read and write. |
10 |
It is available on all Unices and MS-Windows NT/2000/XP with minor tweaks. |
11 |
It may also work on MS-Windows 95/98/ME with some tweaks (old versions worked) |
12 |
libspopc is free software, released under the GNU LGPLv2 License. |
13 |
It is available on http://herewe.servebeer.com/libspopc/index.html |
14 |
libspopc offers low-level and high-level methods to acces a pop3 server. To |
15 |
use low-level API, it is recommended to read RFC 1725 (see doc/rfc/). No |
16 |
special knowledge is required to use the high-level API. |
17 |
This manual tells how to use libspopc in both low-level and high-level methods. |
18 |
|
19 |
|
20 |
= Building libspopc = |
21 |
|
22 |
|
23 |
== on linux, *BSD (and other unices) == |
24 |
|
25 |
|
26 |
=== using the Makefile === |
27 |
|
28 |
The given Makefile allows to build libspopc in a simple way, on your terminal: |
29 |
|
30 |
$ make |
31 |
[...] |
32 |
$ su -c "make install" |
33 |
or |
34 |
$ sudo make install |
35 |
|
36 |
For the full version of libspopc, you need: |
37 |
|
38 |
- GNU make (or old standard make, though not tested) |
39 |
- a c compiler (gcc only has been tested) |
40 |
- a libc (glibc and dietlibc have been tested) |
41 |
- a librt provided with libc (for libspopc version >= 0.9) |
42 |
- openssl and libcrypto (for SSL support) |
43 |
|
44 |
|
45 |
=== use dietlibc instead of the system's libc === |
46 |
|
47 |
- install dietlibc and set the DIET macro to "diet" in the Makefile |
48 |
- remove -pedantic-errors in CFLAGS |
49 |
|
50 |
|
51 |
=== disable SSL support === |
52 |
|
53 |
- remove -DUSE_SSL from CFLAGS in the Makefile |
54 |
- remove -lcrypto -lssl from LDFLAGS in the Makefile |
55 |
|
56 |
|
57 |
=== disable use of semaphores if you do not use threads === |
58 |
|
59 |
- remove -D_REENTRANT from CFLAGS in the Makefile |
60 |
- remove -lrt from LDFLAGS in the Makefile |
61 |
|
62 |
|
63 |
== on MacOSX == |
64 |
|
65 |
libspopc should build easily on MacOSX, using the developer tools (gnu make, |
66 |
gcc). Please tell me if you succeed to or not. |
67 |
|
68 |
|
69 |
== on MS-Windows NT/XP/2000/2003/Vista == |
70 |
|
71 |
It has been reported that libspopc builds successfuly on these flavours. The |
72 |
main trick is to import libspopc sources in you IDE and create an appropriate |
73 |
"project" for it. The archive contains a working project an Makefile.win for |
74 |
the dev-cpp IDE. |
75 |
|
76 |
|
77 |
== on MS-Windows 95/98/ME == |
78 |
|
79 |
Early versions of libspopc have been successfully built upon these flavours. |
80 |
As far as i know, you must have MSVCRT.DLL and WSOCK32.DLL... The latest |
81 |
version of libspopc should do the same. The archive contains a working project |
82 |
and Makefile.win for the dev-cpp IDE. |
83 |
|
84 |
|
85 |
== on OpenVMS == |
86 |
|
87 |
libspopc builds successfully on OpenVMS. Use the build_libspopc.com in the |
88 |
vms/ directory to build libspopc with or without SSL suuport. See how to use |
89 |
this script in the vms_readme.txt documentation file. Note that currently, |
90 |
the re-entrant code of libspopc is disabled for OpenVMS. If you have troubles |
91 |
building libspopc, you can install an older binary package provided by Quadratrix. See: http://www.quadratrix.be/opensource.html |
92 |
|
93 |
|
94 |
= Programming with libspopc = |
95 |
|
96 |
libspopc provides 2 levels of programmation. One of them allow you to know |
97 |
nothing about socket programming nor to have read entirely the POP3 RFC. |
98 |
The second one allow you to deal with sockets and low-level POP3 queries. In |
99 |
the latter case, you must have read rhe POP3 RFC and know a bit on network |
100 |
programming. Use the one you prefer, but DO NOT MIX USE OF THE 2 APIs. |
101 |
|
102 |
|
103 |
== The high-level API (the easy way) == |
104 |
|
105 |
|
106 |
=== declarations === |
107 |
To use libspopc, you have to include in your main program the libspopc header: |
108 |
|
109 |
#include <libspopc.h> |
110 |
|
111 |
Then, in you main function, declare a popsession* object. You don't need to |
112 |
know what a popsession consists of, but if you are curious, see libspopc.h. |
113 |
|
114 |
popsession* mysession; |
115 |
|
116 |
|
117 |
=== starting the pop session === |
118 |
|
119 |
Since version 0.9, you must call libspopc_init() before starting to use libspopc routines. |
120 |
|
121 |
libspopc_init(); /* version >= 0.9 */ |
122 |
|
123 |
Now, to start a pop3 dialog with a pop3 server, use: |
124 |
|
125 |
error = popbegin(char* servername, char* user, char* pass, popsession** &mysession); |
126 |
|
127 |
If no error occurs, popbegin returns a NULL pointer. Else, it returns an error |
128 |
message and the session is not initialized. When the session is initialized, |
129 |
popbegin will asks the pop3 server to give him knowledge of how many messages |
130 |
are stored, and how many bytes, etc... You can know them by reading the popsession |
131 |
members with provided macros (see <libspopc.h>). |
132 |
|
133 |
|
134 |
=== dealing with the pop server === |
135 |
|
136 |
Once the session has begun, you can directly ask what is the last mail id: |
137 |
|
138 |
int last,total; |
139 |
last = mysession->last; |
140 |
total = mysession->num; |
141 |
|
142 |
In the begining of a pop3 session, last and total emails are the same. |
143 |
An email is accessable through its 'id' (from 1 to last). |
144 |
Hence, you can ask everything you want on messages: |
145 |
|
146 |
for(i=1;i<=last;i++){ |
147 |
size=popmsgsize(mysession,i); |
148 |
/* the size in bytes of message i */ |
149 |
|
150 |
sig=popmsguid(mysession,i); |
151 |
/* the unique signature of message i */ |
152 |
|
153 |
head=popgethead(mysession,i); |
154 |
/* the message header */ |
155 |
|
156 |
msg=popgetmsg(mysession,i); |
157 |
/* the message itself */ |
158 |
|
159 |
popdelmsg(mysession,i); |
160 |
/* deletes the message on server */ |
161 |
} |
162 |
|
163 |
You can perform automatic deletion after retrieving a message by asking it to |
164 |
the session: |
165 |
|
166 |
popsetdel(mysession); |
167 |
|
168 |
or stop it by calling: |
169 |
|
170 |
popsetundel(mysession); |
171 |
|
172 |
Be careful if you use threads, then: avoid using 2 threads on the same session. |
173 |
If you want to force cancelation of all previous deletions, ask before quit: |
174 |
|
175 |
popcancel(mysession); |
176 |
|
177 |
Deconnection is then made by a call to: |
178 |
|
179 |
popend(mysession); |
180 |
|
181 |
To start a new pop3 session, you will have to use popbegin(...) again. |
182 |
|
183 |
|
184 |
=== ending with libspopc routines === |
185 |
|
186 |
Since version 0.9, you must call libspopc_clean() when you do not want to use |
187 |
anymore libspopc routines. For example, before your program exits, you will |
188 |
have to call the following routine: |
189 |
|
190 |
libspopc_clean(); /* version >= 0.9 */ |
191 |
|
192 |
There are several other methods to deal with the pop server, see the complete |
193 |
list in file libspopc.h in section "high-level methods". |
194 |
See also example poptest2.c in libspopc example sources. |
195 |
|
196 |
|
197 |
== The low-level API (the hacky way) == |
198 |
|
199 |
The low-level API is *another way* to dilog with a pop3 server. |
200 |
If you choose to use this API, forget about the previous sections. |
201 |
|
202 |
|
203 |
=== declarations === |
204 |
|
205 |
To use libspopc, you have to include in your main program the libspopc header: |
206 |
|
207 |
#include <libspopc.h> |
208 |
|
209 |
Then, in your main function, you have to declare some network-oriented |
210 |
structures in order to use BSD sockets: |
211 |
|
212 |
int mysocket; |
213 |
struct hostent myserver; |
214 |
struct sockaddr_in myconnection; |
215 |
|
216 |
and some specific libspopc types: |
217 |
|
218 |
int* mylist; |
219 |
char** myuidl; |
220 |
|
221 |
mylist will hold an array of sizes of any messages stored in the pop server. |
222 |
(int)mylist[0] is a special cell which holds the number of elements in the list. |
223 |
This list is indexed by the current session's message number. |
224 |
|
225 |
myuidl will hold an array of unique signatures of messages stored in the pop server. |
226 |
This list is indexed by the all-time messages ids. This allows you to |
227 |
keep track of which message you have already read in a previous pop3 session. |
228 |
(char*)myuidl[0] is a special cell which holds the number of signatures. |
229 |
You can get it with well known function atoi() declared in <stdlib.h>. |
230 |
|
231 |
|
232 |
=== connection === |
233 |
|
234 |
Since version 0.9, you must call libspopc_init() before starting to use libspopc routines. |
235 |
|
236 |
libspopc_init(); /* version >= 0.9 */ |
237 |
|
238 |
Now, you can prepare a pop3 connection: |
239 |
|
240 |
mysocket = pop3_prepare(myservername,0,&myconnection,&myserver); |
241 |
|
242 |
where myservername is a (char*) string holding the internet name of the pop3 server. |
243 |
pop3_prepare will return -1 if a problem occured. |
244 |
If no problem occured, you can connect to the pop3 server: |
245 |
|
246 |
(char*)message = pop3_connect(mysock,&myconnection); |
247 |
|
248 |
if message is NULL, the connection failed. Else, check the server's response: |
249 |
|
250 |
if(pop3_error(message)){ |
251 |
printf("%s",message); |
252 |
pop3_disconnect(mysock); |
253 |
} |
254 |
|
255 |
As you can see in this sample, a call to pop3_disconnect will disconnect from |
256 |
the server if connection failed, and free all data structures allocated by |
257 |
pop3_prepare and pop3connect. |
258 |
|
259 |
|
260 |
=== dealing with the pop server === |
261 |
|
262 |
For a complete description of pop3 methods, see <libspopc.h> in section 'pop3 queries'. |
263 |
It is recommended to read RFC 1725 also, because of some |
264 |
particularities of the pop3 protocol. Else, here are some tricks about them: |
265 |
|
266 |
|
267 |
==== statistics ==== |
268 |
|
269 |
char* data; |
270 |
data = pop3_stat(mysock); |
271 |
if(pop3_error(data)){ |
272 |
printf("%s",data); |
273 |
}else{ |
274 |
printf("stat: %d mail(s)\n",stat2num(data)); |
275 |
printf("stat: %d bytes\n",stat2bytes(data)); |
276 |
} |
277 |
free(data); |
278 |
|
279 |
|
280 |
==== listing ==== |
281 |
|
282 |
int* mylist |
283 |
data = pop3_list(mysock,0); /* 0 means all messages */ |
284 |
if(pop3_error(data)){ |
285 |
printf("%s",data); |
286 |
}else{ |
287 |
mylist=list2array(data); |
288 |
} |
289 |
free(data); |
290 |
for(i=1;i<=mylist[0];i++){ |
291 |
printf("msg %d is of %d bytes\n",i,mylist[i]); |
292 |
} |
293 |
free(mylist); |
294 |
|
295 |
|
296 |
==== retrieving ==== |
297 |
|
298 |
char* mymessage; |
299 |
data = pop3_retr(mysock,i); |
300 |
if(pop3_error(data)){ |
301 |
printf("%s",data); |
302 |
}else{ |
303 |
mymessage=retr2msg(data); |
304 |
printf("message %d:\n%s",i,mymessage); |
305 |
free(mymessage); |
306 |
} |
307 |
free(data); |
308 |
|
309 |
|
310 |
==== disconnecting ==== |
311 |
|
312 |
data = pop3_quit(mysock); |
313 |
printf("server says:%s",data); |
314 |
pop3_disconnect(mysock); |
315 |
|
316 |
|
317 |
=== ending with libspopc routines === |
318 |
|
319 |
Since version 0.9, you must call libspopc_clean() when you do not want to use |
320 |
anymore libspopc routines. For example, before your program exits, you will |
321 |
have to call the following routine: |
322 |
|
323 |
libspopc_clean(); /* version >= 0.9 */ |
324 |
|
325 |
There are several other pop3 queries that you can see in <libspopc.h> and |
326 |
explained in RFC1725. For an example, see examples/poptest1.c in libspopc |
327 |
example sources. |
328 |
|
329 |
|
330 |
== Download, Contribute... == |
331 |
|
332 |
|
333 |
=== Download === |
334 |
libspopc is always available at |
335 |
http://herewe.servebeer.com/libspopc/index.html |
336 |
|
337 |
The SVN development tree is freely accessible in read-only anonymous mode. |
338 |
|
339 |
feedback, patches, questions and bug report can be sent to <brouits@free.fr> |
340 |
|
341 |
|
342 |
== Authors == |
343 |
- Original and main author: BenoƮt Rouits <brouits@free.fr> |
344 |
- Main contributors: see AUTHORS file in the libspopc sources. |
345 |
- Contributions: see ChangeLog file in the libspopc sources. |
346 |
|