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

Contents of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.26