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

Annotation of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 11 - (hide annotations)
Sun Apr 18 13:05:20 2010 UTC (11 years, 5 months ago) by ben
File MIME type: text/plain
File size: 10156 byte(s)
updated doc for win32
1 ben 3 libspopc manual
2 ben 1
3     Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008
4    
5    
6 ben 3 = Introduction =
7    
8 ben 1 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 ben 2 It is available on http://herewe.servebeer.com/libspopc/index.html
14 ben 1 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 ben 3 = Building libspopc =
21 ben 1
22 ben 3
23     == on linux, *BSD (and other unices) ==
24    
25    
26     === using the Makefile ===
27    
28 ben 1 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 ben 3 === use dietlibc instead of the system's libc ===
46 ben 1
47     - install dietlibc and set the DIET macro to "diet" in the Makefile
48     - remove -pedantic-errors in CFLAGS
49    
50    
51 ben 3 === disable SSL support ===
52    
53 ben 1 - remove -DUSE_SSL from CFLAGS in the Makefile
54     - remove -lcrypto -lssl from LDFLAGS in the Makefile
55    
56    
57 ben 3 === disable use of semaphores if you do not use threads ===
58    
59 ben 1 - remove -D_REENTRANT from CFLAGS in the Makefile
60     - remove -lrt from LDFLAGS in the Makefile
61    
62    
63 ben 3 == on MacOSX ==
64    
65 ben 1 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 ben 3 == on MS-Windows NT/XP/2000/2003/Vista ==
70    
71 ben 1 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 ben 11 "project" for it. The archive contains a working project an Makefile.win for
74     the dev-cpp IDE.
75 ben 1
76    
77 ben 3 == on MS-Windows 95/98/ME ==
78    
79 ben 1 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 ben 11 version of libspopc should do the same. The archive contains a working project
82     and Makefile.win for the dev-cpp IDE.
83 ben 1
84    
85 ben 3 == on OpenVMS ==
86    
87 ben 1 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 ben 3 building libspopc, you can install an older binary package provided by Quadratrix. See: http://www.quadratrix.be/opensource.html
92 ben 1
93    
94 ben 3 = Programming with libspopc =
95    
96 ben 1 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 ben 3 == The high-level API (the easy way) ==
104    
105    
106     === declarations ===
107 ben 1 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 ben 3 === starting the pop session ===
118    
119 ben 1 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 ben 3 === dealing with the pop server ===
135    
136 ben 1 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 ben 3 === ending with libspopc routines ===
185    
186 ben 1 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 ben 3 == The low-level API (the hacky way) ==
198 ben 1
199 ben 3 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 ben 1
202 ben 3
203     === declarations ===
204    
205 ben 1 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 ben 3 === connection ===
233    
234 ben 1 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 ben 3 === dealing with the pop server ===
261    
262 ben 1 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 ben 3 ==== statistics ====
268    
269 ben 1 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 ben 3 ==== listing ====
281    
282 ben 1 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 ben 3 ==== retrieving ====
297    
298 ben 1 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 ben 3 ==== disconnecting ====
311    
312 ben 1 data = pop3_quit(mysock);
313     printf("server says:%s",data);
314     pop3_disconnect(mysock);
315    
316    
317 ben 3 === ending with libspopc routines ===
318    
319 ben 1 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 ben 3 == Download, Contribute... ==
331    
332    
333     === Download ===
334 ben 1 libspopc is always available at
335 ben 2 http://herewe.servebeer.com/libspopc/index.html
336 ben 1
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 ben 3 == 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