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

Annotation of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 12 - (hide annotations)
Thu Apr 22 01:46:56 2010 UTC (10 years, 9 months ago) by ben
File MIME type: text/plain
File size: 10027 byte(s)
updated docs
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 12 == on MS-Windows 95/98/ME and NT/XP/2000/2003/Vista ==
70 ben 3
71 ben 12 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 ben 1
78    
79 ben 3 == on OpenVMS ==
80    
81 ben 1 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 ben 3 building libspopc, you can install an older binary package provided by Quadratrix. See: http://www.quadratrix.be/opensource.html
86 ben 1
87    
88 ben 3 = Programming with libspopc =
89    
90 ben 1 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 ben 3 == The high-level API (the easy way) ==
98    
99    
100     === declarations ===
101 ben 1 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 ben 3 === starting the pop session ===
112    
113 ben 1 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 ben 3 === dealing with the pop server ===
129    
130 ben 1 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 ben 3 === ending with libspopc routines ===
179    
180 ben 1 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 ben 3 == The low-level API (the hacky way) ==
192 ben 1
193 ben 3 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 ben 1
196 ben 3
197     === declarations ===
198    
199 ben 1 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 ben 3 === connection ===
227    
228 ben 1 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 ben 3 === dealing with the pop server ===
255    
256 ben 1 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 ben 3 ==== statistics ====
262    
263 ben 1 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 ben 3 ==== listing ====
275    
276 ben 1 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 ben 3 ==== retrieving ====
291    
292 ben 1 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 ben 3 ==== disconnecting ====
305    
306 ben 1 data = pop3_quit(mysock);
307     printf("server says:%s",data);
308     pop3_disconnect(mysock);
309    
310    
311 ben 3 === ending with libspopc routines ===
312    
313 ben 1 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 ben 3 == Download, Contribute... ==
325    
326    
327     === Download ===
328 ben 1 libspopc is always available at
329 ben 2 http://herewe.servebeer.com/libspopc/index.html
330 ben 1
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 ben 3 == 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