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