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

Contents of /doc/manual.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 25 - (show 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 libspopc manual
2
3 Benoit Rouits <brouits@free.fr> 12/28/2001, 12/12/2008
4
5
6 = Introduction =
7
8 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 = Building libspopc =
20
21
22 == on linux, *BSD (and other unices) ==
23
24
25 === using the Makefile ===
26
27 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 === use dietlibc instead of the system's libc ===
45
46 - install dietlibc and set the DIET macro to "diet" in the Makefile
47 - remove -pedantic-errors in CFLAGS
48
49
50 === disable SSL support ===
51
52 - remove -DUSE_SSL from CFLAGS in the Makefile
53 - remove -lcrypto -lssl from LDFLAGS in the Makefile
54
55
56 === disable use of semaphores if you do not use threads ===
57
58 - remove -D_REENTRANT from CFLAGS in the Makefile
59 - remove -lrt from LDFLAGS in the Makefile
60
61
62 == on MacOSX ==
63
64 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 == on MS-Windows 95/98/ME and NT/XP/2000/2003/Vista ==
69
70 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
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. See: http://www.quadratrix.be/opensource.html
85
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
96 == The high-level API (the easy way) ==
97
98
99 === declarations ===
100 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 === starting the pop session ===
111
112 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 === dealing with the pop server ===
128
129 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 === ending with libspopc routines ===
178
179 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 == The low-level API (the hacky way) ==
191
192 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
195
196 === declarations ===
197
198 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 === connection ===
226
227 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 === dealing with the pop server ===
254
255 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 ==== statistics ====
261
262 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 ==== listing ====
274
275 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 ==== retrieving ====
290
291 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 ==== disconnecting ====
304
305 data = pop3_quit(mysock);
306 printf("server says:%s",data);
307 pop3_disconnect(mysock);
308
309
310 === ending with libspopc routines ===
311
312 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 == Download, Contribute... ==
324
325
326 === Download ===
327
328 The SVN development tree is freely accessible in read-only anonymous mode:
329 https://dbx.gtmp.org/svn/libspopc
330
331 feedback, patches, questions and bug report can be sent to <brouits@free.fr>
332
333
334 == 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