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

Annotation of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 25 - (hide annotations)
Wed Apr 11 14:06:48 2012 UTC (9 years, 5 months ago) by ben
File MIME type: text/plain
File size: 9912 byte(s)
Removed old homepage reference in docs and headers

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     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    
19 ben 3 = Building libspopc =
20 ben 1
21 ben 3
22     == on linux, *BSD (and other unices) ==
23    
24    
25     === using the Makefile ===
26    
27 ben 1 The given Makefile allows to build libspopc in a simple way, on your terminal:
28    
29     $ make
30     [...]
31     $ su -c "make install"
32     or
33     $ sudo make install
34    
35     For the full version of libspopc, you need:
36    
37     - GNU make (or old standard make, though not tested)
38     - a c compiler (gcc only has been tested)
39     - a libc (glibc and dietlibc have been tested)
40     - a librt provided with libc (for libspopc version >= 0.9)
41     - openssl and libcrypto (for SSL support)
42    
43    
44 ben 3 === use dietlibc instead of the system's libc ===
45 ben 1
46     - install dietlibc and set the DIET macro to "diet" in the Makefile
47     - remove -pedantic-errors in CFLAGS
48    
49    
50 ben 3 === disable SSL support ===
51    
52 ben 1 - remove -DUSE_SSL from CFLAGS in the Makefile
53     - remove -lcrypto -lssl from LDFLAGS in the Makefile
54    
55    
56 ben 3 === disable use of semaphores if you do not use threads ===
57    
58 ben 1 - remove -D_REENTRANT from CFLAGS in the Makefile
59     - remove -lrt from LDFLAGS in the Makefile
60    
61    
62 ben 3 == on MacOSX ==
63    
64 ben 1 libspopc should build easily on MacOSX, using the developer tools (gnu make,
65     gcc). Please tell me if you succeed to or not.
66    
67    
68 ben 12 == on MS-Windows 95/98/ME and NT/XP/2000/2003/Vista ==
69 ben 3
70 ben 12 Libspopc builds successfuly on these flavours. The main trick is to import
71     libspopc sources in you IDE and create an appropriate "project" for it.
72     The archive contains a working project for the dev-cpp IDE (and Makefile.win
73     that should work for MinGW. This porject/Makefile enables openssl, so you have
74     to download openssl for win32 if you use them as is.
75     You also need at last MSVCRT.DLL and WSOCK32.DLL.
76 ben 1
77    
78 ben 3 == on OpenVMS ==
79    
80 ben 1 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 ben 3 building libspopc, you can install an older binary package provided by Quadratrix. See: http://www.quadratrix.be/opensource.html
85 ben 1
86    
87 ben 3 = Programming with libspopc =
88    
89 ben 1 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    
96 ben 3 == The high-level API (the easy way) ==
97    
98    
99     === declarations ===
100 ben 1 To use libspopc, you have to include in your main program the libspopc header:
101    
102     #include <libspopc.h>
103    
104     Then, in you main function, declare a popsession* object. You don't need to
105     know what a popsession consists of, but if you are curious, see libspopc.h.
106    
107     popsession* mysession;
108    
109    
110 ben 3 === starting the pop session ===
111    
112 ben 1 Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
113    
114     libspopc_init(); /* version >= 0.9 */
115    
116     Now, to start a pop3 dialog with a pop3 server, use:
117    
118     error = popbegin(char* servername, char* user, char* pass, popsession** &mysession);
119    
120     If no error occurs, popbegin returns a NULL pointer. Else, it returns an error
121     message and the session is not initialized. When the session is initialized,
122     popbegin will asks the pop3 server to give him knowledge of how many messages
123     are stored, and how many bytes, etc... You can know them by reading the popsession
124     members with provided macros (see <libspopc.h>).
125    
126    
127 ben 3 === dealing with the pop server ===
128    
129 ben 1 Once the session has begun, you can directly ask what is the last mail id:
130    
131     int last,total;
132     last = mysession->last;
133     total = mysession->num;
134    
135     In the begining of a pop3 session, last and total emails are the same.
136     An email is accessable through its 'id' (from 1 to last).
137     Hence, you can ask everything you want on messages:
138    
139     for(i=1;i<=last;i++){
140     size=popmsgsize(mysession,i);
141     /* the size in bytes of message i */
142    
143     sig=popmsguid(mysession,i);
144     /* the unique signature of message i */
145    
146     head=popgethead(mysession,i);
147     /* the message header */
148    
149     msg=popgetmsg(mysession,i);
150     /* the message itself */
151    
152     popdelmsg(mysession,i);
153     /* deletes the message on server */
154     }
155    
156     You can perform automatic deletion after retrieving a message by asking it to
157     the session:
158    
159     popsetdel(mysession);
160    
161     or stop it by calling:
162    
163     popsetundel(mysession);
164    
165     Be careful if you use threads, then: avoid using 2 threads on the same session.
166     If you want to force cancelation of all previous deletions, ask before quit:
167    
168     popcancel(mysession);
169    
170     Deconnection is then made by a call to:
171    
172     popend(mysession);
173    
174     To start a new pop3 session, you will have to use popbegin(...) again.
175    
176    
177 ben 3 === ending with libspopc routines ===
178    
179 ben 1 Since version 0.9, you must call libspopc_clean() when you do not want to use
180     anymore libspopc routines. For example, before your program exits, you will
181     have to call the following routine:
182    
183     libspopc_clean(); /* version >= 0.9 */
184    
185     There are several other methods to deal with the pop server, see the complete
186     list in file libspopc.h in section "high-level methods".
187     See also example poptest2.c in libspopc example sources.
188    
189    
190 ben 3 == The low-level API (the hacky way) ==
191 ben 1
192 ben 3 The low-level API is *another way* to dilog with a pop3 server.
193     If you choose to use this API, forget about the previous sections.
194 ben 1
195 ben 3
196     === declarations ===
197    
198 ben 1 To use libspopc, you have to include in your main program the libspopc header:
199    
200     #include <libspopc.h>
201    
202     Then, in your main function, you have to declare some network-oriented
203     structures in order to use BSD sockets:
204    
205     int mysocket;
206     struct hostent myserver;
207     struct sockaddr_in myconnection;
208    
209     and some specific libspopc types:
210    
211     int* mylist;
212     char** myuidl;
213    
214     mylist will hold an array of sizes of any messages stored in the pop server.
215     (int)mylist[0] is a special cell which holds the number of elements in the list.
216     This list is indexed by the current session's message number.
217    
218     myuidl will hold an array of unique signatures of messages stored in the pop server.
219     This list is indexed by the all-time messages ids. This allows you to
220     keep track of which message you have already read in a previous pop3 session.
221     (char*)myuidl[0] is a special cell which holds the number of signatures.
222     You can get it with well known function atoi() declared in <stdlib.h>.
223    
224    
225 ben 3 === connection ===
226    
227 ben 1 Since version 0.9, you must call libspopc_init() before starting to use libspopc routines.
228    
229     libspopc_init(); /* version >= 0.9 */
230    
231     Now, you can prepare a pop3 connection:
232    
233     mysocket = pop3_prepare(myservername,0,&myconnection,&myserver);
234    
235     where myservername is a (char*) string holding the internet name of the pop3 server.
236     pop3_prepare will return -1 if a problem occured.
237     If no problem occured, you can connect to the pop3 server:
238    
239     (char*)message = pop3_connect(mysock,&myconnection);
240    
241     if message is NULL, the connection failed. Else, check the server's response:
242    
243     if(pop3_error(message)){
244     printf("%s",message);
245     pop3_disconnect(mysock);
246     }
247    
248     As you can see in this sample, a call to pop3_disconnect will disconnect from
249     the server if connection failed, and free all data structures allocated by
250     pop3_prepare and pop3connect.
251    
252    
253 ben 3 === dealing with the pop server ===
254    
255 ben 1 For a complete description of pop3 methods, see <libspopc.h> in section 'pop3 queries'.
256     It is recommended to read RFC 1725 also, because of some
257     particularities of the pop3 protocol. Else, here are some tricks about them:
258    
259    
260 ben 3 ==== statistics ====
261    
262 ben 1 char* data;
263     data = pop3_stat(mysock);
264     if(pop3_error(data)){
265     printf("%s",data);
266     }else{
267     printf("stat: %d mail(s)\n",stat2num(data));
268     printf("stat: %d bytes\n",stat2bytes(data));
269     }
270     free(data);
271    
272    
273 ben 3 ==== listing ====
274    
275 ben 1 int* mylist
276     data = pop3_list(mysock,0); /* 0 means all messages */
277     if(pop3_error(data)){
278     printf("%s",data);
279     }else{
280     mylist=list2array(data);
281     }
282     free(data);
283     for(i=1;i<=mylist[0];i++){
284     printf("msg %d is of %d bytes\n",i,mylist[i]);
285     }
286     free(mylist);
287    
288    
289 ben 3 ==== retrieving ====
290    
291 ben 1 char* mymessage;
292     data = pop3_retr(mysock,i);
293     if(pop3_error(data)){
294     printf("%s",data);
295     }else{
296     mymessage=retr2msg(data);
297     printf("message %d:\n%s",i,mymessage);
298     free(mymessage);
299     }
300     free(data);
301    
302    
303 ben 3 ==== disconnecting ====
304    
305 ben 1 data = pop3_quit(mysock);
306     printf("server says:%s",data);
307     pop3_disconnect(mysock);
308    
309    
310 ben 3 === ending with libspopc routines ===
311    
312 ben 1 Since version 0.9, you must call libspopc_clean() when you do not want to use
313     anymore libspopc routines. For example, before your program exits, you will
314     have to call the following routine:
315    
316     libspopc_clean(); /* version >= 0.9 */
317    
318     There are several other pop3 queries that you can see in <libspopc.h> and
319     explained in RFC1725. For an example, see examples/poptest1.c in libspopc
320     example sources.
321    
322    
323 ben 3 == Download, Contribute... ==
324    
325    
326     === Download ===
327 ben 1
328 ben 25 The SVN development tree is freely accessible in read-only anonymous mode:
329     https://dbx.gtmp.org/svn/libspopc
330 ben 1
331     feedback, patches, questions and bug report can be sent to <brouits@free.fr>
332    
333    
334 ben 3 == Authors ==
335     - Original and main author: BenoĆ®t Rouits <brouits@free.fr>
336     - Main contributors: see AUTHORS file in the libspopc sources.
337     - Contributions: see ChangeLog file in the libspopc sources.
338    

  ViewVC Help
Powered by ViewVC 1.1.26