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

Diff of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2 by ben, Thu Oct 8 15:37:49 2009 UTC revision 3 by ben, Wed Oct 14 03:13:57 2009 UTC
# Line 1  Line 1 
1  = libspopc manual  libspopc manual
2    
3  Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008  Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008
4    
5  == Introduction  
6    = Introduction =
7    
8  libspopc is a pop3 client library written in C and uses BSD-style sockets.  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.  It uses sort of blocking sockets, but with a 15s timeout on read and write.
# Line 15  use low-level API, it is recommended to Line 16  use low-level API, it is recommended to
16  special knowledge is required to use the high-level API.  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.  This manual tells how to use libspopc in both low-level and high-level methods.
18    
 == Building libspopc  
19    
20  === on linux, *BSD (and other unices):  = 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:  The given Makefile allows to build libspopc in a simple way, on your terminal:
29    
# Line 35  For the full version of libspopc, you ne Line 41  For the full version of libspopc, you ne
41  - a librt provided with libc   (for libspopc version >= 0.9)  - a librt provided with libc   (for libspopc version >= 0.9)
42  - openssl and libcrypto        (for SSL support)  - openssl and libcrypto        (for SSL support)
43    
 However, you can force libspopc to:  
44    
45  ==== use dietlibc instead of the system's libc:  === use dietlibc instead of the system's libc ===
46    
47  - install dietlibc and set the DIET macro to "diet" in the Makefile  - install dietlibc and set the DIET macro to "diet" in the Makefile
48  - remove -pedantic-errors in CFLAGS  - remove -pedantic-errors in CFLAGS
49    
50  ==== disable SSL support:  
51    === disable SSL support ===
52    
53  - remove -DUSE_SSL from CFLAGS in the Makefile  - remove -DUSE_SSL from CFLAGS in the Makefile
54  - remove -lcrypto -lssl from LDFLAGS in the Makefile  - remove -lcrypto -lssl from LDFLAGS in the Makefile
55    
56  ==== disable use of semaphores if you do not use threads  
57    === disable use of semaphores if you do not use threads ===
58    
59  - remove -D_REENTRANT from CFLAGS in the Makefile  - remove -D_REENTRANT from CFLAGS in the Makefile
60  - remove -lrt from LDFLAGS in the Makefile  - remove -lrt from LDFLAGS in the Makefile
61    
62  === on MacOSX  
63    == on MacOSX ==
64    
65  libspopc should build easily on MacOSX, using the developer tools (gnu make,  libspopc should build easily on MacOSX, using the developer tools (gnu make,
66  gcc). Please tell me if you succeed to or not.  gcc). Please tell me if you succeed to or not.
67    
68  === on MS-Windows NT/XP/2000/2003/Vista  
69    == on MS-Windows NT/XP/2000/2003/Vista ==
70    
71  It has been reported that libspopc builds successfuly on these flavours. The  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  main trick is to import libspopc sources in you IDE and create an appropriate
# Line 66  since i do not run this operating system Line 75  since i do not run this operating system
75  "project" file for your IDE, please send it to me in order to share it with  "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.  other people having the same IDE as you.
77    
78  === on MS-Windows 95/98/ME  
79    == on MS-Windows 95/98/ME ==
80    
81  Early versions of libspopc have been successfully built upon these flavours.  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  As far as i know, you must have MSVCRT.DLL and WSOCK32.DLL... The latest
# Line 75  run MS-Windows. To compile libspopc on t Line 85  run MS-Windows. To compile libspopc on t
85  defined. If you have a recent working "project" file for your IDE, please send  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.  it to me in order to share it with other people having the same IDE as you.
87    
88  === on OpenVMS  
89    == on OpenVMS ==
90    
91  libspopc builds successfully on OpenVMS. Use the build_libspopc.com in the  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  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,  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  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.  building libspopc, you can install an older binary package provided by Quadratrix. See: http://www.quadratrix.be/opensource.html
96  see: http://www.quadratrix.be/opensource_material.html  
97    
98  == Programming with libspopc  = Programming with libspopc =
99    
100  libspopc provides 2 levels of programmation. One of them allow you to know  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.  nothing about socket programming nor to have read entirely the POP3 RFC.
# Line 92  The second one allow you to deal with so Line 103  The second one allow you to deal with so
103  the latter case, you must have read rhe POP3 RFC and know a bit on network  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.  programming. Use the one you prefer, but DO NOT MIX USE OF THE 2 APIs.
105    
 === The high-level API (the easy way)  
106    
107  ==== declarations:  == 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:  To use libspopc, you have to include in your main program the libspopc header:
112    
113          #include <libspopc.h>          #include <libspopc.h>
# Line 104  know what a popsession consists of, but Line 117  know what a popsession consists of, but
117    
118          popsession* mysession;          popsession* mysession;
119    
120  ==== starting the pop session:  
121    === starting the pop session ===
122    
123  Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.  Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
124    
# Line 120  popbegin will asks the pop3 server to gi Line 134  popbegin will asks the pop3 server to gi
134  are stored, and how many bytes, etc... You can know them by reading the popsession  are stored, and how many bytes, etc... You can know them by reading the popsession
135  members with provided macros (see <libspopc.h>).  members with provided macros (see <libspopc.h>).
136    
137  ==== dealing with the pop server:  
138    === dealing with the pop server ===
139    
140  Once the session has begun, you can directly ask what is the last mail id:  Once the session has begun, you can directly ask what is the last mail id:
141    
# Line 169  Deconnection is then made by a call to: Line 184  Deconnection is then made by a call to:
184    
185  To start a new pop3 session, you will have to use popbegin(...) again.  To start a new pop3 session, you will have to use popbegin(...) again.
186    
187  ==== ending with libspopc routines:  
188    === ending with libspopc routines ===
189    
190  Since version 0.9, you must call libspopc_clean() when you do not want to use  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  anymore libspopc routines. For example, before your program exits, you will
# Line 181  There are several other methods to deal Line 197  There are several other methods to deal
197  list in file libspopc.h in section "high-level methods".  list in file libspopc.h in section "high-level methods".
198  See also example poptest2.c in libspopc example sources.  See also example poptest2.c in libspopc example sources.
199    
   
200    
201  === The low-level API (the hacky way)  == 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:  === declarations ===
208    
209  To use libspopc, you have to include in your main program the libspopc header:  To use libspopc, you have to include in your main program the libspopc header:
210    
# Line 213  keep track of which message you have alr Line 232  keep track of which message you have alr
232  (char*)myuidl[0] is a special cell which holds the number of signatures.  (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>.  You can get it with well known function atoi() declared in <stdlib.h>.
234    
235  ==== connection:  
236    === connection ===
237    
238  Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.  Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
239    
# Line 240  As you can see in this sample, a call to Line 260  As you can see in this sample, a call to
260  the server if connection failed, and free all data structures allocated by  the server if connection failed, and free all data structures allocated by
261  pop3_prepare and pop3connect.  pop3_prepare and pop3connect.
262    
263  ==== dealing with the pop server:  
264    === dealing with the pop server ===
265    
266  For a complete description of pop3 methods, see <libspopc.h> in section 'pop3 queries'.  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  It is recommended to read RFC 1725 also, because of some
268  particularities of the pop3 protocol. Else, here are some tricks about them:  particularities of the pop3 protocol. Else, here are some tricks about them:
269    
270  ===== statistics:  
271    ==== statistics ====
272    
273          char* data;          char* data;
274          data = pop3_stat(mysock);          data = pop3_stat(mysock);
# Line 258  particularities of the pop3 protocol. El Line 280  particularities of the pop3 protocol. El
280          }          }
281          free(data);          free(data);
282    
283  ===== listing:  
284    ==== listing ====
285    
286          int* mylist          int* mylist
287          data = pop3_list(mysock,0); /* 0 means all messages */          data = pop3_list(mysock,0); /* 0 means all messages */
# Line 273  particularities of the pop3 protocol. El Line 296  particularities of the pop3 protocol. El
296          }          }
297          free(mylist);          free(mylist);
298    
299  ===== retrieving:  
300    ==== retrieving ====
301    
302          char* mymessage;          char* mymessage;
303          data = pop3_retr(mysock,i);          data = pop3_retr(mysock,i);
# Line 286  particularities of the pop3 protocol. El Line 310  particularities of the pop3 protocol. El
310          }          }
311          free(data);          free(data);
312    
313  ===== disconnectiong:  
314    ==== disconnecting ====
315    
316          data = pop3_quit(mysock);          data = pop3_quit(mysock);
317          printf("server says:%s",data);          printf("server says:%s",data);
318          pop3_disconnect(mysock);          pop3_disconnect(mysock);
319    
320  ==== ending with libspopc routines:  
321    === ending with libspopc routines ===
322    
323  Since version 0.9, you must call libspopc_clean() when you do not want to use  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  anymore libspopc routines. For example, before your program exits, you will
# Line 304  There are several other pop3 queries tha Line 330  There are several other pop3 queries tha
330  explained in RFC1725. For an example, see examples/poptest1.c in libspopc  explained in RFC1725. For an example, see examples/poptest1.c in libspopc
331  example sources.  example sources.
332    
 === Download, Contribute...  
333    
334  === Download  == Download, Contribute... ==
335    
336    
337    === Download ===
338  libspopc is always available at  libspopc is always available at
339          http://herewe.servebeer.com/libspopc/index.html          http://herewe.servebeer.com/libspopc/index.html
340    
# Line 314  The SVN development tree is freely acces Line 342  The SVN development tree is freely acces
342    
343  feedback, patches, questions and bug report can be sent to <brouits@free.fr>  feedback, patches, questions and bug report can be sent to <brouits@free.fr>
344    
345  === Authors  
346  Original and main author: Benoît Rouits <brouits@free.fr>  == Authors ==
347  Main contributors: see AUTHORS file in the libspopc sources.  - Original and main author: Benoît Rouits <brouits@free.fr>
348  Contributions: see ChangeLog file in the libspopc sources.  - Main contributors: see AUTHORS file in the libspopc sources.
349    - Contributions: see ChangeLog file in the libspopc sources.
350    

Legend:
Removed from v.2  
changed lines
  Added in v.3

  ViewVC Help
Powered by ViewVC 1.1.26