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

Annotation of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2 - (hide annotations)
Thu Oct 8 15:37:49 2009 UTC (11 years, 11 months ago) by ben
File MIME type: text/plain
File size: 10319 byte(s)
changed project url
1 ben 1 = libspopc manual
2    
3     Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008
4    
5     == Introduction
6    
7     libspopc is a pop3 client library written in C and uses BSD-style sockets.
8     It uses sort of blocking sockets, but with a 15s timeout on read and write.
9     It is available on all Unices and MS-Windows NT/2000/XP with minor tweaks.
10     It may also work on MS-Windows 95/98/ME with some tweaks (old versions worked)
11     libspopc is free software, released under the GNU LGPLv2 License.
12 ben 2 It is available on http://herewe.servebeer.com/libspopc/index.html
13 ben 1 libspopc offers low-level and high-level methods to acces a pop3 server. To
14     use low-level API, it is recommended to read RFC 1725 (see doc/rfc/). No
15     special knowledge is required to use the high-level API.
16     This manual tells how to use libspopc in both low-level and high-level methods.
17    
18     == Building libspopc
19    
20     === on linux, *BSD (and other unices):
21    
22     The given Makefile allows to build libspopc in a simple way, on your terminal:
23    
24     $ make
25     [...]
26     $ su -c "make install"
27     or
28     $ sudo make install
29    
30     For the full version of libspopc, you need:
31    
32     - GNU make (or old standard make, though not tested)
33     - a c compiler (gcc only has been tested)
34     - a libc (glibc and dietlibc have been tested)
35     - a librt provided with libc (for libspopc version >= 0.9)
36     - openssl and libcrypto (for SSL support)
37    
38     However, you can force libspopc to:
39    
40     ==== use dietlibc instead of the system's libc:
41    
42     - install dietlibc and set the DIET macro to "diet" in the Makefile
43     - remove -pedantic-errors in CFLAGS
44    
45     ==== disable SSL support:
46    
47     - remove -DUSE_SSL from CFLAGS in the Makefile
48     - remove -lcrypto -lssl from LDFLAGS in the Makefile
49    
50     ==== disable use of semaphores if you do not use threads
51    
52     - remove -D_REENTRANT from CFLAGS in the Makefile
53     - remove -lrt from LDFLAGS in the Makefile
54    
55     === on MacOSX
56    
57     libspopc should build easily on MacOSX, using the developer tools (gnu make,
58     gcc). Please tell me if you succeed to or not.
59    
60     === on MS-Windows NT/XP/2000/2003/Vista
61    
62     It has been reported that libspopc builds successfuly on these flavours. The
63     main trick is to import libspopc sources in you IDE and create an appropriate
64     "project" for it. Read the Makefile to know dependencies. I could not test it
65     since i do not run this operating system. If you have a recent working
66     "project" file for your IDE, please send it to me in order to share it with
67     other people having the same IDE as you.
68    
69     === on MS-Windows 95/98/ME
70    
71     Early versions of libspopc have been successfully built upon these flavours.
72     As far as i know, you must have MSVCRT.DLL and WSOCK32.DLL... The latest
73     version of libspopc should do the same, but i could not test it since i do not
74     run MS-Windows. To compile libspopc on these flavours, WIN32 macro must be
75     defined. If you have a recent working "project" file for your IDE, please send
76     it to me in order to share it with other people having the same IDE as you.
77    
78     === on OpenVMS
79    
80     libspopc builds successfully on OpenVMS. Use the build_libspopc.com in the
81     vms/ directory to build libspopc with or without SSL suuport. See how to use
82     this script in the vms_readme.txt documentation file. Note that currently,
83     the re-entrant code of libspopc is disabled for OpenVMS. If you have troubles
84     building libspopc, you can install an older binary package provided by Quadratrix.
85     see: http://www.quadratrix.be/opensource_material.html
86    
87     == Programming with libspopc
88    
89     libspopc provides 2 levels of programmation. One of them allow you to know
90     nothing about socket programming nor to have read entirely the POP3 RFC.
91     The second one allow you to deal with sockets and low-level POP3 queries. In
92     the latter case, you must have read rhe POP3 RFC and know a bit on network
93     programming. Use the one you prefer, but DO NOT MIX USE OF THE 2 APIs.
94    
95     === The high-level API (the easy way)
96    
97     ==== declarations:
98     To use libspopc, you have to include in your main program the libspopc header:
99    
100     #include <libspopc.h>
101    
102     Then, in you main function, declare a popsession* object. You don't need to
103     know what a popsession consists of, but if you are curious, see libspopc.h.
104    
105     popsession* mysession;
106    
107     ==== starting the pop session:
108    
109     Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
110    
111     libspopc_init(); /* version >= 0.9 */
112    
113     Now, to start a pop3 dialog with a pop3 server, use:
114    
115     error = popbegin(char* servername, char* user, char* pass, popsession** &mysession);
116    
117     If no error occurs, popbegin returns a NULL pointer. Else, it returns an error
118     message and the session is not initialized. When the session is initialized,
119     popbegin will asks the pop3 server to give him knowledge of how many messages
120     are stored, and how many bytes, etc... You can know them by reading the popsession
121     members with provided macros (see <libspopc.h>).
122    
123     ==== dealing with the pop server:
124    
125     Once the session has begun, you can directly ask what is the last mail id:
126    
127     int last,total;
128     last = mysession->last;
129     total = mysession->num;
130    
131     In the begining of a pop3 session, last and total emails are the same.
132     An email is accessable through its 'id' (from 1 to last).
133     Hence, you can ask everything you want on messages:
134    
135     for(i=1;i<=last;i++){
136     size=popmsgsize(mysession,i);
137     /* the size in bytes of message i */
138    
139     sig=popmsguid(mysession,i);
140     /* the unique signature of message i */
141    
142     head=popgethead(mysession,i);
143     /* the message header */
144    
145     msg=popgetmsg(mysession,i);
146     /* the message itself */
147    
148     popdelmsg(mysession,i);
149     /* deletes the message on server */
150     }
151    
152     You can perform automatic deletion after retrieving a message by asking it to
153     the session:
154    
155     popsetdel(mysession);
156    
157     or stop it by calling:
158    
159     popsetundel(mysession);
160    
161     Be careful if you use threads, then: avoid using 2 threads on the same session.
162     If you want to force cancelation of all previous deletions, ask before quit:
163    
164     popcancel(mysession);
165    
166     Deconnection is then made by a call to:
167    
168     popend(mysession);
169    
170     To start a new pop3 session, you will have to use popbegin(...) again.
171    
172     ==== ending with libspopc routines:
173    
174     Since version 0.9, you must call libspopc_clean() when you do not want to use
175     anymore libspopc routines. For example, before your program exits, you will
176     have to call the following routine:
177    
178     libspopc_clean(); /* version >= 0.9 */
179    
180     There are several other methods to deal with the pop server, see the complete
181     list in file libspopc.h in section "high-level methods".
182     See also example poptest2.c in libspopc example sources.
183    
184    
185    
186     === The low-level API (the hacky way)
187    
188     ==== declarations:
189    
190     To use libspopc, you have to include in your main program the libspopc header:
191    
192     #include <libspopc.h>
193    
194     Then, in your main function, you have to declare some network-oriented
195     structures in order to use BSD sockets:
196    
197     int mysocket;
198     struct hostent myserver;
199     struct sockaddr_in myconnection;
200    
201     and some specific libspopc types:
202    
203     int* mylist;
204     char** myuidl;
205    
206     mylist will hold an array of sizes of any messages stored in the pop server.
207     (int)mylist[0] is a special cell which holds the number of elements in the list.
208     This list is indexed by the current session's message number.
209    
210     myuidl will hold an array of unique signatures of messages stored in the pop server.
211     This list is indexed by the all-time messages ids. This allows you to
212     keep track of which message you have already read in a previous pop3 session.
213     (char*)myuidl[0] is a special cell which holds the number of signatures.
214     You can get it with well known function atoi() declared in <stdlib.h>.
215    
216     ==== connection:
217    
218     Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
219    
220     libspopc_init(); /* version >= 0.9 */
221    
222     Now, you can prepare a pop3 connection:
223    
224     mysocket = pop3_prepare(myservername,0,&myconnection,&myserver);
225    
226     where myservername is a (char*) string holding the internet name of the pop3 server.
227     pop3_prepare will return -1 if a problem occured.
228     If no problem occured, you can connect to the pop3 server:
229    
230     (char*)message = pop3_connect(mysock,&myconnection);
231    
232     if message is NULL, the connection failed. Else, check the server's response:
233    
234     if(pop3_error(message)){
235     printf("%s",message);
236     pop3_disconnect(mysock);
237     }
238    
239     As you can see in this sample, a call to pop3_disconnect will disconnect from
240     the server if connection failed, and free all data structures allocated by
241     pop3_prepare and pop3connect.
242    
243     ==== dealing with the pop server:
244    
245     For a complete description of pop3 methods, see <libspopc.h> in section 'pop3 queries'.
246     It is recommended to read RFC 1725 also, because of some
247     particularities of the pop3 protocol. Else, here are some tricks about them:
248    
249     ===== statistics:
250    
251     char* data;
252     data = pop3_stat(mysock);
253     if(pop3_error(data)){
254     printf("%s",data);
255     }else{
256     printf("stat: %d mail(s)\n",stat2num(data));
257     printf("stat: %d bytes\n",stat2bytes(data));
258     }
259     free(data);
260    
261     ===== listing:
262    
263     int* mylist
264     data = pop3_list(mysock,0); /* 0 means all messages */
265     if(pop3_error(data)){
266     printf("%s",data);
267     }else{
268     mylist=list2array(data);
269     }
270     free(data);
271     for(i=1;i<=mylist[0];i++){
272     printf("msg %d is of %d bytes\n",i,mylist[i]);
273     }
274     free(mylist);
275    
276     ===== retrieving:
277    
278     char* mymessage;
279     data = pop3_retr(mysock,i);
280     if(pop3_error(data)){
281     printf("%s",data);
282     }else{
283     mymessage=retr2msg(data);
284     printf("message %d:\n%s",i,mymessage);
285     free(mymessage);
286     }
287     free(data);
288    
289     ===== disconnectiong:
290    
291     data = pop3_quit(mysock);
292     printf("server says:%s",data);
293     pop3_disconnect(mysock);
294    
295     ==== ending with libspopc routines:
296    
297     Since version 0.9, you must call libspopc_clean() when you do not want to use
298     anymore libspopc routines. For example, before your program exits, you will
299     have to call the following routine:
300    
301     libspopc_clean(); /* version >= 0.9 */
302    
303     There are several other pop3 queries that you can see in <libspopc.h> and
304     explained in RFC1725. For an example, see examples/poptest1.c in libspopc
305     example sources.
306    
307     === Download, Contribute...
308    
309     === Download
310     libspopc is always available at
311 ben 2 http://herewe.servebeer.com/libspopc/index.html
312 ben 1
313     The SVN development tree is freely accessible in read-only anonymous mode.
314    
315     feedback, patches, questions and bug report can be sent to <brouits@free.fr>
316    
317     === Authors
318     Original and main author: BenoĆ®t Rouits <brouits@free.fr>
319     Main contributors: see AUTHORS file in the libspopc sources.
320     Contributions: see ChangeLog file in the libspopc sources.
321    

  ViewVC Help
Powered by ViewVC 1.1.26