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

Contents of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (show annotations)
Thu Oct 8 11:53:59 2009 UTC (11 years, 11 months ago) by ben
File MIME type: text/plain
File size: 10309 byte(s)
import from old repo, version 0.10.2
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 It is available on http://brouits.free.fr/libspopc/index.html
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 == 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 http://brouits.free.fr/libspopc/index.html
312
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