/[libspopc]/doc/manual.txt
ViewVC logotype

Contents of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 12 - (show annotations)
Thu Apr 22 01:46:56 2010 UTC (10 years, 7 months ago) by ben
File MIME type: text/plain
File size: 10027 byte(s)
updated docs
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

  ViewVC Help
Powered by ViewVC 1.1.26