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

Contents of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 11 - (show annotations)
Sun Apr 18 13:05:20 2010 UTC (10 years, 7 months ago) by ben
File MIME type: text/plain
File size: 10156 byte(s)
updated doc for win32
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

  ViewVC Help
Powered by ViewVC 1.1.26