author | zautrix <zautrix> | 2004-07-03 16:33:12 (UTC) |
---|---|---|
committer | zautrix <zautrix> | 2004-07-03 16:33:12 (UTC) |
commit | e3b89230f065c48c84b48c88edb6eb088374c487 (patch) (unidiff) | |
tree | 162ea2ef909a6f82ccfcedf45d80d6c821174912 /kmicromail/libetpan/doc/API.sgml | |
parent | 2dd6ac0b2d24c91d35ce674a6c26351352df2b15 (diff) | |
download | kdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.zip kdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.tar.gz kdepimpi-e3b89230f065c48c84b48c88edb6eb088374c487.tar.bz2 |
Initial revision
Diffstat (limited to 'kmicromail/libetpan/doc/API.sgml') (more/less context) (show whitespace changes)
-rw-r--r-- | kmicromail/libetpan/doc/API.sgml | 15097 |
1 files changed, 15097 insertions, 0 deletions
diff --git a/kmicromail/libetpan/doc/API.sgml b/kmicromail/libetpan/doc/API.sgml new file mode 100644 index 0000000..4516979 --- a/dev/null +++ b/kmicromail/libetpan/doc/API.sgml | |||
@@ -0,0 +1,15097 @@ | |||
1 | <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN"> | ||
2 | |||
3 | <book id="libetpan-api"> | ||
4 | <bookinfo> | ||
5 | <date>2003-12-03</date> | ||
6 | <title>libEtPan! API</title> | ||
7 | <authorgroup> | ||
8 | <author> | ||
9 | <firstname>Viet Hoa</firstname> | ||
10 | <surname>DINH</surname> | ||
11 | </author> | ||
12 | </authorgroup> | ||
13 | <copyright> | ||
14 | <year>2003</year> | ||
15 | <holder>DINH Viet Hoa</holder> | ||
16 | </copyright> | ||
17 | </bookinfo> | ||
18 | <toc></toc> | ||
19 | |||
20 | <!-- Introduction --> | ||
21 | <chapter> | ||
22 | <title>Introduction</title> | ||
23 | <para> | ||
24 | This document will describe the API of libEtPan! | ||
25 | </para> | ||
26 | </chapter> | ||
27 | |||
28 | <!-- Tools --> | ||
29 | <chapter> | ||
30 | <title>Tools and datatypes</title> | ||
31 | |||
32 | <para> | ||
33 | libEtPan! include a collection of datatypes such as lists, | ||
34 | arrays, hash tables and tools such as buffered I/O. | ||
35 | </para> | ||
36 | |||
37 | <!-- Array --> | ||
38 | <sect1> | ||
39 | <title>Array</title> | ||
40 | |||
41 | <programlisting role="C"> | ||
42 | #include <libetpan/libetpan.h> | ||
43 | |||
44 | typedef struct carray_s carray; | ||
45 | </programlisting> | ||
46 | |||
47 | <para> | ||
48 | <command>carray</command> is an array of pointers that will | ||
49 | resize automatically in case a new element is added. | ||
50 | </para> | ||
51 | |||
52 | <para> | ||
53 | The <command>carray</command> is implemented with an array | ||
54 | <command>(void **)</command> that can be resized. An array has a | ||
55 | size: this is the number of elements that can be added before | ||
56 | the table is resized. It also has a count of elements: this is | ||
57 | the elements that exist in the array. | ||
58 | </para> | ||
59 | |||
60 | <sect2 id="carray-new"> | ||
61 | <title>carray_new and carray_free</title> | ||
62 | |||
63 | <programlisting role="C"> | ||
64 | carray * carray_new(unsigned int initsize); | ||
65 | |||
66 | void carray_free(carray * array); | ||
67 | </programlisting> | ||
68 | |||
69 | <para> | ||
70 | <command>carray_new()</command> creates a new array with an | ||
71 | initial size. The array is not resized until the number of | ||
72 | element reach the initial size. It returns | ||
73 | <command>NULL</command> in case of failure. | ||
74 | </para> | ||
75 | |||
76 | <para> | ||
77 | <command>carray_free()</command> releases memory used by the | ||
78 | given array. | ||
79 | </para> | ||
80 | |||
81 | <example> | ||
82 | <title>carray creation</title> | ||
83 | <programlisting role="C"> | ||
84 | #include <libetpan/libetpan.h> | ||
85 | #include <stdlib.h> | ||
86 | |||
87 | #define SIZE 50 | ||
88 | |||
89 | int main(void) | ||
90 | { | ||
91 | carray * a; | ||
92 | |||
93 | a = carray_new(SIZE); | ||
94 | if (a == NULL) | ||
95 | exit(EXIT_FAILURE); | ||
96 | |||
97 | /* do things here */ | ||
98 | |||
99 | carray_free(a); | ||
100 | |||
101 | exit(EXIT_SUCESS); | ||
102 | } | ||
103 | </programlisting> | ||
104 | </example> | ||
105 | </sect2> | ||
106 | |||
107 | <sect2 id="carray-set-size"> | ||
108 | <title>carray_set_size</title> | ||
109 | |||
110 | <programlisting role="C"> | ||
111 | int carray_set_size(carray * array, uint32_t new_size); | ||
112 | </programlisting> | ||
113 | |||
114 | <para> | ||
115 | <command>carray_set_size()</command> sets the size of the | ||
116 | array. It returns <command>0</command> in case of success, | ||
117 | <command>-1</command> in case of failure. | ||
118 | </para> | ||
119 | |||
120 | <example> | ||
121 | <title>preallocating carray</title> | ||
122 | <programlisting role="C"> | ||
123 | #include <libetpan/libetpan.h> | ||
124 | #include <stdlib.h> | ||
125 | |||
126 | #define SIZE 50 | ||
127 | #define NEWSIZE 200 | ||
128 | |||
129 | int main(void) | ||
130 | { | ||
131 | carray * a; | ||
132 | unsigned int i; | ||
133 | char p[500]; | ||
134 | |||
135 | a = carray_new(SIZE); | ||
136 | if (a == NULL) | ||
137 | goto err; | ||
138 | |||
139 | r = carray_set_size(NEWSIZE); | ||
140 | if (r < 0) | ||
141 | goto free; | ||
142 | |||
143 | for(i = 0 ; i < NEWSIZE ; i ++) | ||
144 | carray_set(a, i, &p[i]); | ||
145 | |||
146 | /* do things here */ | ||
147 | |||
148 | carray_free(a); | ||
149 | |||
150 | exit(EXIT_SUCESS); | ||
151 | |||
152 | free: | ||
153 | carray_free(a); | ||
154 | err: | ||
155 | exit(EXIT_FAILURE); | ||
156 | } | ||
157 | </programlisting> | ||
158 | </example> | ||
159 | </sect2> | ||
160 | |||
161 | <!-- carray_count, carray_add, carray_get and carray_set --> | ||
162 | <sect2 id="carray-count"> | ||
163 | <title>carray_count, carray_add, carray_get and carray_set</title> | ||
164 | |||
165 | <programlisting role="C"> | ||
166 | int carray_count(carray); | ||
167 | |||
168 | int carray_add(carray * array, void * data, unsigned int * index); | ||
169 | |||
170 | void * carray_get(carray * array, unsigned int indx); | ||
171 | |||
172 | void carray_set(carray * array, unsigned int indx, void * value); | ||
173 | </programlisting> | ||
174 | |||
175 | <para> | ||
176 | <command>carray_count()</command> returns the number of | ||
177 | elements in the <command>carray</command>. | ||
178 | Complexity is O(1). | ||
179 | </para> | ||
180 | |||
181 | <para> | ||
182 | <command>carray_add()</command>adds an element at the end of | ||
183 | the array. The <command>index</command> of the element is | ||
184 | returns in <command>(* index)</command> if | ||
185 | <command>index</command> is not <command>NULL</command>. It | ||
186 | returns <command>0</command> in case of success, | ||
187 | <command>-1</command> in case of failure. | ||
188 | Complexity is O(1). | ||
189 | </para> | ||
190 | |||
191 | <para> | ||
192 | <command>carray_get()</command> returns the elements contained | ||
193 | at the given cell of the table. | ||
194 | Complexity is O(1). | ||
195 | </para> | ||
196 | |||
197 | <para> | ||
198 | <command>carray_set()</command> replace the element at the | ||
199 | given index of table table with the given value. | ||
200 | Complexity is O(1). | ||
201 | </para> | ||
202 | |||
203 | <example> | ||
204 | <title>carray access</title> | ||
205 | <programlisting role="C"> | ||
206 | #include <libetpan/libetpan.h> | ||
207 | #include <string.h> | ||
208 | |||
209 | #define SIZE 50 | ||
210 | |||
211 | int main(void) | ||
212 | { | ||
213 | carray * a; | ||
214 | int r; | ||
215 | |||
216 | a = carray_new(SIZE); | ||
217 | if (a == NULL) | ||
218 | goto err; | ||
219 | |||
220 | r = carray_add(a, "foo-bar-1", NULL); | ||
221 | if (r < 0) | ||
222 | goto free; | ||
223 | |||
224 | carray_add(a, "foo-bar-2", NULL); | ||
225 | if (r < 0) | ||
226 | goto free; | ||
227 | |||
228 | carray_add(a, "foo-bar-3", NULL); | ||
229 | if (r < 0) | ||
230 | goto free; | ||
231 | |||
232 | for(i = 0 ; i < carray_count(a) ; i ++) { | ||
233 | char * str; | ||
234 | |||
235 | str = carray_get(a, i); | ||
236 | if (strcmp("foo-bar-2", str) == 0) | ||
237 | carray_set(a, i, "foo-bar-2-replacement"); | ||
238 | |||
239 | printf("%s\n", str); | ||
240 | } | ||
241 | |||
242 | carray_free(a); | ||
243 | |||
244 | exit(EXIT_SUCESS); | ||
245 | |||
246 | free: | ||
247 | carray_free(a); | ||
248 | err: | ||
249 | exit(EXIT_FAILURE); | ||
250 | } | ||
251 | </programlisting> | ||
252 | </example> | ||
253 | |||
254 | </sect2> | ||
255 | |||
256 | <!-- carray_delete --> | ||
257 | <sect2 id="carray-delete"> | ||
258 | <title>carray_delete</title> | ||
259 | |||
260 | <programlisting role="C"> | ||
261 | int carray_delete(carray * array, uint32_t indx); | ||
262 | |||
263 | int carray_delete_slow(carray * array, uint32_t indx); | ||
264 | |||
265 | int carray_delete_fast(carray * array, uint32_t indx); | ||
266 | </programlisting> | ||
267 | |||
268 | <para> | ||
269 | <command>carray_delete()</command> removes an element of the | ||
270 | table. Order will not be garanteed. The returned result can | ||
271 | be ignored. | ||
272 | Complexity is O(1). | ||
273 | </para> | ||
274 | |||
275 | <para> | ||
276 | <command>carray_delete_slow()</command> removes an element of | ||
277 | the table. Order will be garanteed. The returned result can | ||
278 | be ignored. | ||
279 | Complexity is O(n). | ||
280 | </para> | ||
281 | |||
282 | <para> | ||
283 | <command>carray_delete_fast()</command> the element will just | ||
284 | be replaced with <command>NULL</command>. Order will be kept | ||
285 | but the number of elements will remains the same. The | ||
286 | returned result can be ignored. | ||
287 | Complexity is O(1). | ||
288 | </para> | ||
289 | |||
290 | <example> | ||
291 | <title>deletion in carray</title> | ||
292 | <programlisting role="C"> | ||
293 | #include <libetpan/libetpan.h> | ||
294 | |||
295 | #define SIZE 50 | ||
296 | |||
297 | carray * build_array(void) | ||
298 | { | ||
299 | carray * a; | ||
300 | |||
301 | a = carray_new(SIZE); | ||
302 | if (a == NULL) | ||
303 | goto err; | ||
304 | |||
305 | r = carray_add(a, "foo-bar-1", NULL); | ||
306 | if (r < 0) | ||
307 | goto free; | ||
308 | |||
309 | carray_add(a, "foo-bar-2", NULL); | ||
310 | if (r < 0) | ||
311 | goto free; | ||
312 | |||
313 | carray_add(a, "foo-bar-3", NULL); | ||
314 | if (r < 0) | ||
315 | goto free; | ||
316 | |||
317 | return a; | ||
318 | |||
319 | free: | ||
320 | carray_free(a); | ||
321 | err: | ||
322 | exit(EXIT_FAILURE); | ||
323 | } | ||
324 | |||
325 | void delete(carray * a) | ||
326 | { | ||
327 | /* deleting foo-bar-1 */ | ||
328 | carray_delete(a, 0); | ||
329 | /* resulting size is 2, order of elements is undefined */ | ||
330 | } | ||
331 | |||
332 | void delete_slow(carray * a) | ||
333 | { | ||
334 | /* deleting foo-bar-1 */ | ||
335 | carray_delete_slow(a, 0); | ||
336 | /* resulting size is 2, order of elements is the same */ | ||
337 | } | ||
338 | |||
339 | void delete_fast(carray * a) | ||
340 | { | ||
341 | /* deleting foo-bar-1 */ | ||
342 | carray_delete_slow(a, 0); | ||
343 | /* | ||
344 | resulting size is 3, | ||
345 | order of elements is { NULL, foo-bar-2, foo-bar-3 } | ||
346 | */ | ||
347 | } | ||
348 | </programlisting> | ||
349 | </example> | ||
350 | </sect2> | ||
351 | |||
352 | <!-- carray_data --> | ||
353 | <sect2 id="carray-data"> | ||
354 | <title>carray_data</title> | ||
355 | |||
356 | <programlisting role="C"> | ||
357 | void ** carray_data(carray); | ||
358 | </programlisting> | ||
359 | |||
360 | <para> | ||
361 | <command>carray_data</command>returns the table used for | ||
362 | implementation : | ||
363 | <command>(void **)</command>. | ||
364 | </para> | ||
365 | |||
366 | </sect2> | ||
367 | |||
368 | |||
369 | </sect1> | ||
370 | |||
371 | <!-- List --> | ||
372 | <sect1 id="clist"> | ||
373 | <title>List</title> | ||
374 | |||
375 | <programlisting role="C"> | ||
376 | #include <libetpan/libetpan.h> | ||
377 | |||
378 | typedef struct clist_s clist; | ||
379 | |||
380 | typedef clistcell clistiter; | ||
381 | </programlisting> | ||
382 | |||
383 | <para> | ||
384 | <command>clist()</command> is a list of cells. | ||
385 | Each cell of the list contains one element. This element is a | ||
386 | pointer. An iterator (<command>clistiter</command>) is a | ||
387 | pointer to an element of the list. With an iterator, we can | ||
388 | get the previous element of the list, the next element of the | ||
389 | list and the content of the element. | ||
390 | </para> | ||
391 | |||
392 | <sect2 id="clist-new"> | ||
393 | <title>clist_new and clist_free</title> | ||
394 | |||
395 | <programlisting role="C"> | ||
396 | clist * clist_new(void); | ||
397 | |||
398 | void clist_free(clist *); | ||
399 | </programlisting> | ||
400 | |||
401 | <para> | ||
402 | <command>clist_new()</command> allocates a new empty list and | ||
403 | returns it. | ||
404 | </para> | ||
405 | |||
406 | <para> | ||
407 | <command>clist_free()</command> frees the entire list with | ||
408 | its cells. | ||
409 | </para> | ||
410 | |||
411 | <example> | ||
412 | <title>clist creation</title> | ||
413 | <programlisting role="C"> | ||
414 | #include <libetpan/libetpan.h> | ||
415 | |||
416 | int main(void) | ||
417 | { | ||
418 | clist * list; | ||
419 | |||
420 | list = clist_new(); | ||
421 | if (list == NULL) | ||
422 | goto err; | ||
423 | |||
424 | r = clist_append(list, "foo-bar"); | ||
425 | if (r < 0) | ||
426 | |||
427 | clist_free(list); | ||
428 | |||
429 | exit(EXIT_SUCCESS); | ||
430 | |||
431 | free: | ||
432 | clist_free(list); | ||
433 | err: | ||
434 | exit(EXIT_FAILURE); | ||
435 | } | ||
436 | </programlisting> | ||
437 | </example> | ||
438 | </sect2> | ||
439 | |||
440 | <sect2 id="clist-count"> | ||
441 | <title>clist_isempty and clist_count</title> | ||
442 | |||
443 | <programlisting role="C"> | ||
444 | int clist_isempty(clist *); | ||
445 | |||
446 | int clist_count(clist *); | ||
447 | </programlisting> | ||
448 | |||
449 | <para> | ||
450 | <command>clist_isempty()</command> returns 1 if the list is | ||
451 | empty, else it is 0. | ||
452 | Complexity is O(1). | ||
453 | </para> | ||
454 | |||
455 | <para> | ||
456 | <command>clist_count()</command> returns the number of | ||
457 | elements in the list. | ||
458 | Complexity is O(1). | ||
459 | </para> | ||
460 | </sect2> | ||
461 | |||
462 | <sect2 id="clist-begin"> | ||
463 | <title>running through clist</title> | ||
464 | |||
465 | <programlisting role="C"> | ||
466 | clistiter * clist_begin(clist *); | ||
467 | |||
468 | clistiter * clist_end(clist *); | ||
469 | |||
470 | clistiter * clist_next(clistiter *); | ||
471 | |||
472 | clistiter * clist_previous(clistiter *); | ||
473 | |||
474 | void * clist_content(clistiter *); | ||
475 | |||
476 | void * clist_nth_data(clist * lst, int index); | ||
477 | |||
478 | clistiter * clist_nth(clist * lst, int index); | ||
479 | </programlisting> | ||
480 | |||
481 | <para> | ||
482 | <command>clist_begin()</command> returns an iterator to the | ||
483 | first element of the list. | ||
484 | Complexity is O(1). | ||
485 | </para> | ||
486 | |||
487 | <para> | ||
488 | <command>clist_end()</command> returns an iterator to the last | ||
489 | element of the list. | ||
490 | Complexity is O(1). | ||
491 | </para> | ||
492 | |||
493 | <para> | ||
494 | <command>clist_next()</command> returns an iterator to the | ||
495 | next element of the list. | ||
496 | Complexity is O(1). | ||
497 | </para> | ||
498 | |||
499 | <para> | ||
500 | <command>clist_previous()</command> returns an iterator to the | ||
501 | previous element of the list. | ||
502 | Complexity is O(1). | ||
503 | </para> | ||
504 | |||
505 | <para> | ||
506 | <command>clist_content()</command> returns the element | ||
507 | contained in the cell pointed by the iterator in the list. | ||
508 | Complexity is O(1). | ||
509 | </para> | ||
510 | |||
511 | <para> | ||
512 | <command>clist_nth()</command> returns an iterator on the | ||
513 | <command>index</command>-th element of the list. | ||
514 | Complexity is O(n). | ||
515 | </para> | ||
516 | |||
517 | <para> | ||
518 | <command>clist_nth_data()</command> returns the index-th | ||
519 | element of the list. | ||
520 | Complexity is O(n). | ||
521 | </para> | ||
522 | |||
523 | <example> | ||
524 | <title>displaying content of clist</title> | ||
525 | <programlisting role="C"> | ||
526 | #include <libetpan/libetpan.h> | ||
527 | |||
528 | int main(void) | ||
529 | { | ||
530 | clist * list; | ||
531 | clistiter * iter; | ||
532 | |||
533 | list = build_string_list(); | ||
534 | if (list == NULL) | ||
535 | goto err; | ||
536 | |||
537 | for(iter = clist_begin(list) ; iter != NULL ; iter = | ||
538 | clist_next(iter)) { | ||
539 | char * str; | ||
540 | |||
541 | str = clist_content(iter); | ||
542 | printf("%s\n", str); | ||
543 | } | ||
544 | |||
545 | clist_free(list); | ||
546 | |||
547 | exit(EXIT_SUCCESS); | ||
548 | |||
549 | free: | ||
550 | clist_free(list); | ||
551 | err: | ||
552 | exit(EXIT_FAILURE); | ||
553 | } | ||
554 | </programlisting> | ||
555 | </example> | ||
556 | </sect2> | ||
557 | |||
558 | |||
559 | <sect2 id="clist-append"> | ||
560 | <title>clist modification</title> | ||
561 | |||
562 | <programlisting role="C"> | ||
563 | int clist_prepend(clist *, void *); | ||
564 | |||
565 | int clist_append(clist *, void *); | ||
566 | |||
567 | int clist_insert_before(clist *, clistiter *, void *); | ||
568 | |||
569 | int clist_insert_after(clist *, clistiter *, void *); | ||
570 | |||
571 | clistiter * clist_delete(clist *, clistiter *); | ||
572 | </programlisting> | ||
573 | |||
574 | <para> | ||
575 | <command>clist_prepend()</command> adds an element at the | ||
576 | beginning of the list. Returns 0 on sucess, -1 on error. | ||
577 | Complexity is O(1). | ||
578 | </para> | ||
579 | |||
580 | <para> | ||
581 | <command>clist_append()</command> adds an element at the end | ||
582 | of the list. Returns 0 on sucess, -1 on error. | ||
583 | Complexity is O(1). | ||
584 | </para> | ||
585 | |||
586 | <para> | ||
587 | <command>clist_insert_before()</command> adds an element | ||
588 | before the element pointed by the given iterator in the | ||
589 | list. Returns 0 on sucess, -1 on error. | ||
590 | Complexity is O(1). | ||
591 | </para> | ||
592 | |||
593 | <para> | ||
594 | <command>clist_insert_after()</command> adds an element after | ||
595 | the element pointed by the given iterator in the list. | ||
596 | Returns 0 on sucess, -1 on error. | ||
597 | Complexity is O(1). | ||
598 | </para> | ||
599 | |||
600 | <para> | ||
601 | <command>clist_delete()</command> the elements pointed by | ||
602 | the given iterator in the list and returns an iterator to | ||
603 | the next element of the list. | ||
604 | Complexity is O(1). | ||
605 | </para> | ||
606 | |||
607 | <example> | ||
608 | <title>deleting elements in a clist</title> | ||
609 | <programlisting role="C"> | ||
610 | #include <libetpan/libetpan.h> | ||
611 | |||
612 | voir print_content(void * content, void * user_data) | ||
613 | { | ||
614 | char * str; | ||
615 | |||
616 | str = content; | ||
617 | |||
618 | printf("%s\n", str); | ||
619 | } | ||
620 | |||
621 | int main(void) | ||
622 | { | ||
623 | clist * list; | ||
624 | clistiter * iter; | ||
625 | |||
626 | list = build_string_list(); | ||
627 | if (list == NULL) | ||
628 | goto err; | ||
629 | |||
630 | iter = = clist_begin(list); | ||
631 | while (iter != NULL) | ||
632 | char * str; | ||
633 | |||
634 | str = clist_content(iter); | ||
635 | if (strcmp(str, "foo-bar") == 0) | ||
636 | iter = clist_delete(list, cur); | ||
637 | else | ||
638 | iter = clist_next(iter); | ||
639 | } | ||
640 | |||
641 | clist_foreach(list, print_content, NULL); | ||
642 | printf("\n"); | ||
643 | |||
644 | clist_free(list); | ||
645 | |||
646 | exit(EXIT_SUCCESS); | ||
647 | |||
648 | free: | ||
649 | clist_free(list); | ||
650 | err: | ||
651 | exit(EXIT_FAILURE); | ||
652 | } | ||
653 | </programlisting> | ||
654 | </example> | ||
655 | </sect2> | ||
656 | |||
657 | <sect2 id="clist-foreach"> | ||
658 | <title>clist_foreach</title> | ||
659 | |||
660 | <programlisting role="C"> | ||
661 | typedef void (* clist_func)(void *, void *); | ||
662 | |||
663 | void clist_foreach(clist * lst, clist_func func, void * data); | ||
664 | </programlisting> | ||
665 | |||
666 | <para> | ||
667 | <command>clist_foreach()</command> apply a fonction to each | ||
668 | element of the list. | ||
669 | Complexity is O(n). | ||
670 | </para> | ||
671 | </sect2> | ||
672 | |||
673 | <sect2 id="clist-concat"> | ||
674 | <title>clist_concat</title> | ||
675 | |||
676 | <programlisting role="C"> | ||
677 | void clist_concat(clist * dest, clist * src); | ||
678 | </programlisting> | ||
679 | |||
680 | <para> | ||
681 | <command>clist_concat()</command> adds all the elements of src | ||
682 | at the end of dest. Elements are added in the same | ||
683 | order. src is an empty list when the operation is finished. | ||
684 | Complexity is O(1). | ||
685 | </para> | ||
686 | |||
687 | <example> | ||
688 | <title>merging two clists</title> | ||
689 | <programlisting role="C"> | ||
690 | #include <libetpan/libetpan.h> | ||
691 | |||
692 | int main(void) | ||
693 | { | ||
694 | clist * list; | ||
695 | clist * list_2; | ||
696 | clistiter * iter; | ||
697 | |||
698 | list = build_string_list(); | ||
699 | if (list == NULL) | ||
700 | goto err; | ||
701 | |||
702 | list_2 = build_string_list_2(); | ||
703 | if (list == NULL) | ||
704 | goto free_list; | ||
705 | |||
706 | clist_concat(list, list_2); | ||
707 | clist_free(list_2); | ||
708 | |||
709 | for(iter = clist_begin(list) ; iter != NULL ; iter = | ||
710 | clist_next(iter)) { | ||
711 | char * str; | ||
712 | |||
713 | str = clist_content(iter); | ||
714 | printf("%s\n", str); | ||
715 | } | ||
716 | |||
717 | clist_free(list); | ||
718 | |||
719 | exit(EXIT_SUCCESS); | ||
720 | |||
721 | free_list: | ||
722 | clist_free(list); | ||
723 | err: | ||
724 | exit(EXIT_FAILURE); | ||
725 | } | ||
726 | </programlisting> | ||
727 | </example> | ||
728 | |||
729 | </sect2> | ||
730 | </sect1> | ||
731 | |||
732 | <!-- Hash --> | ||
733 | <sect1> | ||
734 | <title>Hash table</title> | ||
735 | |||
736 | <programlisting role="C"> | ||
737 | #include <libetpan/libetpan.h> | ||
738 | |||
739 | typedef struct chash chash; | ||
740 | |||
741 | typedef struct chashcell chashiter; | ||
742 | |||
743 | typedef struct { | ||
744 | char * data; | ||
745 | int len; | ||
746 | } chashdatum; | ||
747 | </programlisting> | ||
748 | |||
749 | <para> | ||
750 | <command>chash</command> is a hash table. | ||
751 | <command>chashiter</command> is a pointer to an element of the | ||
752 | hash table. | ||
753 | <command>chashdatum</command> is an element to be placed in | ||
754 | the hash table as a key or a value. It consists in | ||
755 | data and a corresponding length. | ||
756 | </para> | ||
757 | |||
758 | <sect2 id="chash-new"> | ||
759 | <title>chash_new and chash_free</title> | ||
760 | <programlisting role="C"> | ||
761 | #define CHASH_COPYNONE 0 | ||
762 | #define CHASH_COPYKEY 1 | ||
763 | #define CHASH_COPYVALUE 2 | ||
764 | #define CHASH_COPYALL (CHASH_COPYKEY | CHASH_COPYVALUE) | ||
765 | |||
766 | chash * chash_new(int size, int flags); | ||
767 | |||
768 | void chash_free(chash * hash); | ||
769 | </programlisting> | ||
770 | |||
771 | <para> | ||
772 | <command>chash_new()</command> returns a new empty hash table | ||
773 | or <command>NULL</command> if this | ||
774 | failed. <command>size</command> is the initial size of the | ||
775 | table used for implementation. <command>flags</command> can | ||
776 | be a combinaison of <command>CHASH_COPYKEY</command> and | ||
777 | <command>CHASH_COPYVALUE</command>. | ||
778 | <command>CHASH_COPYKEY</command> enables copy of key, so | ||
779 | that the initial value used for <command>chash_set()</command> | ||
780 | </para> | ||
781 | |||
782 | <para> | ||
783 | <command>chash_free()</command> releases memory used by the | ||
784 | hash table. | ||
785 | </para> | ||
786 | </sect2> | ||
787 | |||
788 | <sect2 id="chash-get"> | ||
789 | <title>chash_set and chash_get</title> | ||
790 | <programlisting role="C"> | ||
791 | int chash_set(chash * hash, | ||
792 | chashdatum * key, chashdatum * value, chashdatum * oldvalue); | ||
793 | |||
794 | int chash_get(chash * hash, | ||
795 | chashdatum * key, chashdatum * result); | ||
796 | </programlisting> | ||
797 | |||
798 | <para> | ||
799 | <command>chash_set()</command> adds a new element into the | ||
800 | hash table. If a previous element had the same key, it is | ||
801 | returns into oldvalue if <command>oldvalue</command> is | ||
802 | different of NULL. | ||
803 | Medium complexity is O(1). | ||
804 | </para> | ||
805 | |||
806 | <para> | ||
807 | returns -1 if it fails, 0 on success. | ||
808 | </para> | ||
809 | |||
810 | <para> | ||
811 | <command>chash_get()</command>returns the corresponding value | ||
812 | of the given key. If there is no corresponding value, -1 is | ||
813 | returned. 0 on success. | ||
814 | Medium complexity is O(1). | ||
815 | </para> | ||
816 | |||
817 | <example> | ||
818 | <title>chash insert and lookup</title> | ||
819 | <programlisting role="C"> | ||
820 | int main(void) | ||
821 | { | ||
822 | chash * hash; | ||
823 | int r; | ||
824 | chashdatum key; | ||
825 | chashdatum value; | ||
826 | char * str1 = "my-data"; | ||
827 | char * str2 = "my-data"; | ||
828 | |||
829 | hash = chash_new(CHASH_DEFAULTSIZE, CHASH_COPYNONE); | ||
830 | |||
831 | key.data = "foo"; | ||
832 | key.len = strlen("foo"); | ||
833 | value.data = str1; | ||
834 | value.data = strlen(str1) + 1; | ||
835 | /* + 1 is needed to get the terminal zero in the returned string */ | ||
836 | r = chash_set(hash, &key, &value, NULL); | ||
837 | if (r < 0) | ||
838 | goto free_hash; | ||
839 | |||
840 | key.data = "bar"; | ||
841 | key.len = strlen("bar"); | ||
842 | value.data = str2; | ||
843 | value.data = strlen(str2) + 1; | ||
844 | if (r < 0) | ||
845 | goto free_hash; | ||
846 | |||
847 | key.data = "foo"; | ||
848 | key.len = strlen("foo"); | ||
849 | r = chash_get(hash, &key, &value); | ||
850 | if (r < 0) { | ||
851 | printf("element not found\n"); | ||
852 | } | ||
853 | else { | ||
854 | char * str; | ||
855 | |||
856 | str = value.data; | ||
857 | printf("found : %s", str); | ||
858 | } | ||
859 | |||
860 | chash_free(hash); | ||
861 | |||
862 | exit(EXIT_SUCCESS); | ||
863 | |||
864 | free_hash: | ||
865 | chash_free(hash); | ||
866 | err: | ||
867 | exit(EXIT_FAILURE); | ||
868 | } | ||
869 | </programlisting> | ||
870 | </example> | ||
871 | </sect2> | ||
872 | |||
873 | <sect2 id="chash-delete"> | ||
874 | <title>chash_delete</title> | ||
875 | <programlisting role="C"> | ||
876 | int chash_delete(chash * hash, | ||
877 | chashdatum * key, chashdatum * oldvalue); | ||
878 | </programlisting> | ||
879 | |||
880 | <para> | ||
881 | deletes the key/value pair given the corresponding key. | ||
882 | The value is returned in old_value. | ||
883 | If there is no corresponding value, -1 is returned. 0 on success. | ||
884 | Medium complexity is O(1). | ||
885 | </para> | ||
886 | |||
887 | <example> | ||
888 | <title>key deletion in a chash</title> | ||
889 | <programlisting role="C"> | ||
890 | int main(void) | ||
891 | { | ||
892 | chash * hash; | ||
893 | int r; | ||
894 | chashdatum key; | ||
895 | chashdatum value; | ||
896 | char * str1 = "my-data"; | ||
897 | char * str2 = "my-data"; | ||
898 | |||
899 | hash = build_hash(); | ||
900 | |||
901 | key.data = "foo"; | ||
902 | key.len = strlen("foo"); | ||
903 | chash_delete(hash, &key, &value); | ||
904 | |||
905 | /* it will never be possible to lookup "foo" */ | ||
906 | key.data = "foo"; | ||
907 | key.len = strlen("foo"); | ||
908 | r = chash_get(hash, &key, &value); | ||
909 | if (r < 0) { | ||
910 | printf("element not found\n"); | ||
911 | } | ||
912 | else { | ||
913 | char * str; | ||
914 | |||
915 | str = value.data; | ||
916 | printf("found : %s", str); | ||
917 | } | ||
918 | |||
919 | chash_free(hash); | ||
920 | |||
921 | exit(EXIT_SUCCESS); | ||
922 | |||
923 | free_hash: | ||
924 | chash_free(hash); | ||
925 | err: | ||
926 | exit(EXIT_FAILURE); | ||
927 | } | ||
928 | </programlisting> | ||
929 | </example> | ||
930 | </sect2> | ||
931 | |||
932 | <sect2 id="chash-resize"> | ||
933 | <title>chash_resize</title> | ||
934 | <programlisting role="C"> | ||
935 | int chash_resize(chash * hash, int size); | ||
936 | </programlisting> | ||
937 | |||
938 | <para> | ||
939 | <command>chash_resize()</command> changes the size of the | ||
940 | table used for implementation of the hash table. | ||
941 | returns 0 on success, -1 on failure. | ||
942 | </para> | ||
943 | </sect2> | ||
944 | |||
945 | <sect2 id="chash-begin"> | ||
946 | <title>running through the chash</title> | ||
947 | <programlisting role="C"> | ||
948 | chashiter * chash_begin(chash * hash); | ||
949 | |||
950 | chashiter * chash_next(chash * hash, chashiter * iter); | ||
951 | |||
952 | void chash_key(chashiter * iter, chashdatum * result); | ||
953 | |||
954 | void chash_value(chashiter iter, chashdatum * result); | ||
955 | </programlisting> | ||
956 | |||
957 | <para> | ||
958 | <command>chash_begin()</command> returns a pointer to the | ||
959 | first element of the hash table. Returns | ||
960 | <command>NULL</command> if there is no elements in the hash | ||
961 | table. | ||
962 | Complexity is O(n). | ||
963 | </para> | ||
964 | |||
965 | <para> | ||
966 | <command>chash_next()</command> returns a pointer to the next | ||
967 | element of the hash table. Returns <command>NULL</command> | ||
968 | if there is no next element. | ||
969 | Complexity is O(n) but n calls to chash_next() also has | ||
970 | a complexity of O(n). | ||
971 | </para> | ||
972 | |||
973 | <para> | ||
974 | <command>chash_key()</command> returns the key of the given | ||
975 | element of the hash table. | ||
976 | </para> | ||
977 | |||
978 | <para> | ||
979 | <command>chash_value</command> returns the value of the | ||
980 | given element of the hash table. | ||
981 | </para> | ||
982 | |||
983 | <example> | ||
984 | <title>running through a chash</title> | ||
985 | <programlisting role="C"> | ||
986 | int main(void) | ||
987 | { | ||
988 | chash * hash; | ||
989 | int r; | ||
990 | chashiter * iter; | ||
991 | |||
992 | hash = build_hash(); | ||
993 | |||
994 | /* this will display all the values stored in the hash */ | ||
995 | for(iter = chash_begin(hash) ; iter != NULL ; iter = | ||
996 | chash_next(hash, iter)) { | ||
997 | chashdatum key; | ||
998 | chashdatum value; | ||
999 | char * str; | ||
1000 | |||
1001 | chash_value(iter, &value); | ||
1002 | str = value.data; | ||
1003 | printf("%s\n", str); | ||
1004 | } | ||
1005 | |||
1006 | chash_free(hash); | ||
1007 | } | ||
1008 | </programlisting> | ||
1009 | </example> | ||
1010 | </sect2> | ||
1011 | |||
1012 | <sect2 id="chash-count"> | ||
1013 | <title>chash_size and chash_count</title> | ||
1014 | <programlisting role="C"> | ||
1015 | int chash_size(chash * hash); | ||
1016 | |||
1017 | int chash_count(chash * hash); | ||
1018 | </programlisting> | ||
1019 | |||
1020 | <para> | ||
1021 | <command>chash_size()</command> returns the size of the table | ||
1022 | used for implementation of the hash table. | ||
1023 | Complexity is O(1). | ||
1024 | </para> | ||
1025 | |||
1026 | <para> | ||
1027 | <command>chash_count()</command> returns the number of | ||
1028 | elements in the hash table. | ||
1029 | Complexity is O(1). | ||
1030 | </para> | ||
1031 | </sect2> | ||
1032 | </sect1> | ||
1033 | |||
1034 | <!-- mailstream --> | ||
1035 | <sect1> | ||
1036 | <title>Buffered I/O</title> | ||
1037 | |||
1038 | <programlisting role="C"> | ||
1039 | #include <libetpan/libetpan.h> | ||
1040 | |||
1041 | typedef struct _mailstream mailstream; | ||
1042 | </programlisting> | ||
1043 | |||
1044 | <para> | ||
1045 | streams are objects where we can read data from and write data | ||
1046 | to. They are not seekable. That can be for example a pipe or a | ||
1047 | network stream. | ||
1048 | </para> | ||
1049 | |||
1050 | <programlisting role="C"> | ||
1051 | mailstream * mailstream_new(mailstream_low * low, size_t buffer_size); | ||
1052 | |||
1053 | int mailstream_close(mailstream * s); | ||
1054 | </programlisting> | ||
1055 | |||
1056 | <para> | ||
1057 | <command>mailstream_new()</command> creates a new stream | ||
1058 | stream with the low-level (see <xref linkend="mailstream-low">) | ||
1059 | stream and a given buffer size. | ||
1060 | </para> | ||
1061 | |||
1062 | <para> | ||
1063 | <command>mailstream_close()</command> closes the stream. | ||
1064 | This function will be in charge to free the | ||
1065 | <command>mailstream_low</command> structure. | ||
1066 | </para> | ||
1067 | |||
1068 | |||
1069 | <programlisting role="C"> | ||
1070 | ssize_t mailstream_write(mailstream * s, void * buf, size_t count); | ||
1071 | |||
1072 | int mailstream_flush(mailstream * s); | ||
1073 | |||
1074 | ssize_t mailstream_read(mailstream * s, void * buf, size_t count); | ||
1075 | |||
1076 | ssize_t mailstream_feed_read_buffer(mailstream * s); | ||
1077 | </programlisting> | ||
1078 | |||
1079 | <para> | ||
1080 | <command>mailstream_write()</command> writes a buffer to the | ||
1081 | given stream. This write operation will be buffered. | ||
1082 | </para> | ||
1083 | |||
1084 | <para> | ||
1085 | <command>mailstream_flush()</command> will force a write of | ||
1086 | all buffered data for a given stream. | ||
1087 | </para> | ||
1088 | |||
1089 | <para> | ||
1090 | <command>mailstream_read()</command> reads data from the | ||
1091 | stream to the given buffer. | ||
1092 | </para> | ||
1093 | |||
1094 | <para> | ||
1095 | <command>mailstream_feed_read_buffer()</command> this function | ||
1096 | will just fill the buffer for reading. | ||
1097 | </para> | ||
1098 | |||
1099 | <programlisting role="C"> | ||
1100 | mailstream_low * mailstream_get_low(mailstream * s); | ||
1101 | |||
1102 | void mailstream_set_low(mailstream * s, mailstream_low * low); | ||
1103 | </programlisting> | ||
1104 | |||
1105 | <para> | ||
1106 | <command>mailstream_get_low()</command> returns the low-level | ||
1107 | stream of the given stream. | ||
1108 | </para> | ||
1109 | |||
1110 | <para> | ||
1111 | <command>mailstream_set_low()</command> changes the low-level | ||
1112 | of the given stream. Useful, for | ||
1113 | example, when a stream change from clear stream to SSL | ||
1114 | stream. | ||
1115 | </para> | ||
1116 | |||
1117 | <programlisting role="C"> | ||
1118 | char * mailstream_read_line(mailstream * stream, MMAPString * line); | ||
1119 | |||
1120 | char * mailstream_read_line_append(mailstream * stream, MMAPString * line); | ||
1121 | |||
1122 | char * mailstream_read_line_remove_eol(mailstream * stream, MMAPString * line); | ||
1123 | |||
1124 | char * mailstream_read_multiline(mailstream * s, size_t size, | ||
1125 | MMAPString * stream_buffer, | ||
1126 | MMAPString * multiline_buffer, | ||
1127 | size_t progr_rate, | ||
1128 | progress_function * progr_fun); | ||
1129 | </programlisting> | ||
1130 | |||
1131 | <para> | ||
1132 | <command>mailstream_read_line()</command> reads an entire line | ||
1133 | from the buffer and store it into the | ||
1134 | given string. returns <command>NULL</command> on error, the | ||
1135 | corresponding array | ||
1136 | of <command>char</command> is returned otherwise. | ||
1137 | </para> | ||
1138 | |||
1139 | <para> | ||
1140 | <command>mailstream_read_line_append()</command> reads an entire | ||
1141 | line from the buffer and appends it to the | ||
1142 | given string. returns <command>NULL</command> on error, the | ||
1143 | array of char corresponding to the entire buffer is returned | ||
1144 | otherwise. | ||
1145 | </para> | ||
1146 | |||
1147 | <para> | ||
1148 | <command>mailstream_read_line_remove_eol()</command> reads an | ||
1149 | entire line from the buffer and store it into the | ||
1150 | given string. All CR LF are removed. | ||
1151 | returns <command>NULL</command> on error, the corresponding | ||
1152 | array of <command>char</command> is returned otherwise. | ||
1153 | </para> | ||
1154 | |||
1155 | <para> | ||
1156 | <command>mailstream_read_multiline()</command> reads a | ||
1157 | multiline data (several lines, the data are ended with | ||
1158 | a single period '.') | ||
1159 | from the given stream and store it into the given | ||
1160 | multiline buffer (multiline_buffer). progr_rate should be 0 | ||
1161 | and progr_fun <command>NULL</command> (deprecated things). | ||
1162 | <command>stream_buffer</command> is a buffer used for internal | ||
1163 | work of the function. | ||
1164 | size should be 0 (deprecated things). | ||
1165 | </para> | ||
1166 | |||
1167 | <programlisting role="C"> | ||
1168 | int mailstream_is_end_multiline(char * line); | ||
1169 | </programlisting> | ||
1170 | |||
1171 | <para> | ||
1172 | returns 1 if the line is an end of multiline data (a single | ||
1173 | period '.', eventually with CR and/or LF). 0 is returned | ||
1174 | otherwise. | ||
1175 | </para> | ||
1176 | |||
1177 | <programlisting role="C"> | ||
1178 | int mailstream_send_data(mailstream * s, char * message, | ||
1179 | size_t size, | ||
1180 | size_t progr_rate, | ||
1181 | progress_function * progr_fun); | ||
1182 | </programlisting> | ||
1183 | |||
1184 | <para> | ||
1185 | sends multiline data to the given stream. | ||
1186 | <command>size</command> is the size of the data. | ||
1187 | <command>progr_rate</command> and <command>progr_fun</command> | ||
1188 | are deprecated. <command>progr_rate</command> must be 0, | ||
1189 | <command>progr_fun</command> must be NULL. | ||
1190 | </para> | ||
1191 | |||
1192 | <sect2 id="mailstream-socket"> | ||
1193 | <title>socket stream</title> | ||
1194 | |||
1195 | <programlisting role="C"> | ||
1196 | mailstream * mailstream_socket_open(int fd); | ||
1197 | </programlisting> | ||
1198 | |||
1199 | <para> | ||
1200 | <command>mailstream_socket_open()</command> will open a | ||
1201 | clear-text socket. | ||
1202 | </para> | ||
1203 | </sect2> | ||
1204 | |||
1205 | <sect2 id="mailstream-ssl"> | ||
1206 | <title>TLS stream</title> | ||
1207 | |||
1208 | <programlisting role="C"> | ||
1209 | mailstream * mailstream_ssl_open(int fd); | ||
1210 | </programlisting> | ||
1211 | |||
1212 | <para> | ||
1213 | <command>mailstream_ssl_open()</command> will open a | ||
1214 | TLS/SSL socket. | ||
1215 | </para> | ||
1216 | </sect2> | ||
1217 | </sect1> | ||
1218 | |||
1219 | <!-- mailstream_low --> | ||
1220 | <sect1 id="mailstream-low"> | ||
1221 | <title>non-buffered I/O</title> | ||
1222 | |||
1223 | <programlisting role="C"> | ||
1224 | #include <libetpan/libetpan.h> | ||
1225 | |||
1226 | struct mailstream_low_driver { | ||
1227 | ssize_t (* mailstream_read)(mailstream_low *, void *, size_t); | ||
1228 | ssize_t (* mailstream_write)(mailstream_low *, void *, size_t); | ||
1229 | int (* mailstream_close)(mailstream_low *); | ||
1230 | int (* mailstream_get_fd)(mailstream_low *); | ||
1231 | void (* mailstream_free)(mailstream_low *); | ||
1232 | }; | ||
1233 | |||
1234 | typedef struct mailstream_low_driver mailstream_low_driver; | ||
1235 | |||
1236 | struct _mailstream_low { | ||
1237 | void * data; | ||
1238 | mailstream_low_driver * driver; | ||
1239 | }; | ||
1240 | </programlisting> | ||
1241 | |||
1242 | <para> | ||
1243 | <command>mailstream_low</command> is a non-buffered stream. | ||
1244 | </para> | ||
1245 | |||
1246 | <para> | ||
1247 | The <command>mailstream_low_driver</command> is a set of | ||
1248 | functions used to access the stream. | ||
1249 | </para> | ||
1250 | |||
1251 | <itemizedlist> | ||
1252 | <listitem> | ||
1253 | <para> | ||
1254 | <command>mailstream_read/write/close()</command> is the same | ||
1255 | interface as <command>read/write/close()</command> | ||
1256 | system calls, except that the file descriptor is replaced with the | ||
1257 | <command>mailstream_low</command> structure. | ||
1258 | </para> | ||
1259 | </listitem> | ||
1260 | <listitem> | ||
1261 | <para> | ||
1262 | <command>mailstream_get_fd()</command> returns the file | ||
1263 | descriptor used for this non-buffered stream. | ||
1264 | </para> | ||
1265 | </listitem> | ||
1266 | <listitem> | ||
1267 | <para> | ||
1268 | <command>mailstream_free()</command> is in charge to free | ||
1269 | the internal structure of the mailstream_low and the | ||
1270 | mailstream_low itself. | ||
1271 | </para> | ||
1272 | </listitem> | ||
1273 | </itemizedlist> | ||
1274 | |||
1275 | <programlisting role="C"> | ||
1276 | mailstream_low * mailstream_low_new(void * data, | ||
1277 | mailstream_low_driver * driver); | ||
1278 | </programlisting> | ||
1279 | |||
1280 | <para> | ||
1281 | mailstream_low_new() creates a low-level mailstream with the | ||
1282 | given internal structure (data) and using the given set of | ||
1283 | functions (driver). | ||
1284 | </para> | ||
1285 | |||
1286 | <programlisting role="C"> | ||
1287 | ssize_t mailstream_low_write(mailstream_low * s, void * buf, size_t count); | ||
1288 | |||
1289 | ssize_t mailstream_low_read(mailstream_low * s, void * buf, size_t count); | ||
1290 | |||
1291 | int mailstream_low_close(mailstream_low * s); | ||
1292 | |||
1293 | int mailstream_low_get_fd(mailstream_low * s); | ||
1294 | |||
1295 | void mailstream_low_free(mailstream_low * s); | ||
1296 | </programlisting> | ||
1297 | |||
1298 | <para> | ||
1299 | Each of these calls will call the corresponding function defined | ||
1300 | in the driver. | ||
1301 | </para> | ||
1302 | |||
1303 | </sect1> | ||
1304 | |||
1305 | |||
1306 | <!-- MMAPString --> | ||
1307 | <sect1> | ||
1308 | <title>strings</title> | ||
1309 | |||
1310 | <programlisting role="C"> | ||
1311 | #include <libetpan/libetpan.h> | ||
1312 | |||
1313 | struct _MMAPString | ||
1314 | { | ||
1315 | char * str; | ||
1316 | size_t len; | ||
1317 | size_t allocated_len; | ||
1318 | int fd; | ||
1319 | size_t mmapped_size; | ||
1320 | }; | ||
1321 | |||
1322 | typedef struct _MMAPString MMAPString; | ||
1323 | </programlisting> | ||
1324 | |||
1325 | <para> | ||
1326 | MMAPString is a string which size that can increase automatically. | ||
1327 | </para> | ||
1328 | |||
1329 | <sect2 id="mmap-string-new"> | ||
1330 | <title>constructor and destructor</title> | ||
1331 | <programlisting role="C"> | ||
1332 | MMAPString * mmap_string_new(const char * init); | ||
1333 | |||
1334 | MMAPString * mmap_string_new_len(const char * init, size_t len); | ||
1335 | |||
1336 | MMAPString * mmap_string_sized_new(size_t dfl_size); | ||
1337 | |||
1338 | void mmap_string_free(MMAPString * string); | ||
1339 | </programlisting> | ||
1340 | |||
1341 | <para> | ||
1342 | <command>mmap_string_new()</command> allocates a new | ||
1343 | string. init is the intial value of the string. | ||
1344 | <command>NULL</command> will be returned on error. | ||
1345 | </para> | ||
1346 | |||
1347 | <para> | ||
1348 | <command>mmap_string_new_len()</command> allocates a new | ||
1349 | string. init is the intial value of the | ||
1350 | string, len is the length of the initial string. | ||
1351 | <command>NULL</command> will be returned on error. | ||
1352 | </para> | ||
1353 | |||
1354 | <para> | ||
1355 | <command>mmap_string_sized_new()</command> allocates a new | ||
1356 | string. dfl_size is the initial allocation of | ||
1357 | the string. <command>NULL</command> will be returned on error. | ||
1358 | </para> | ||
1359 | |||
1360 | <para> | ||
1361 | <command>mmap_string_free()</command> release the memory used | ||
1362 | by the string. | ||
1363 | </para> | ||
1364 | </sect2> | ||
1365 | |||
1366 | <sect2 id="mmap-string-assign"> | ||
1367 | <title>string value modification</title> | ||
1368 | <programlisting role="C"> | ||
1369 | MMAPString * mmap_string_assign(MMAPString * string, const char * rval); | ||
1370 | |||
1371 | MMAPString * mmap_string_truncate(MMAPString *string, size_t len); | ||
1372 | </programlisting> | ||
1373 | |||
1374 | <para> | ||
1375 | <command>mmap_string_assign()</command> sets a new value for | ||
1376 | the given string. | ||
1377 | <command>NULL</command> will be returned on error. | ||
1378 | </para> | ||
1379 | |||
1380 | <para> | ||
1381 | <command>mmap_string_truncate()</command> sets a length for | ||
1382 | the string. | ||
1383 | <command>NULL</command> will be returned on error. | ||
1384 | </para> | ||
1385 | |||
1386 | <programlisting role="C"> | ||
1387 | MMAPString * mmap_string_set_size (MMAPString * string, size_t len); | ||
1388 | </programlisting> | ||
1389 | |||
1390 | <para> | ||
1391 | sets the allocation of the string. | ||
1392 | <command>NULL</command> will be returned on error. | ||
1393 | </para> | ||
1394 | </sect2> | ||
1395 | |||
1396 | <sect2 id="mmap-string-append"> | ||
1397 | <title>insertion in string, deletion in string</title> | ||
1398 | <programlisting role="C"> | ||
1399 | MMAPString * mmap_string_insert_len(MMAPString * string, size_t pos, | ||
1400 | const char * val, size_t len); | ||
1401 | |||
1402 | MMAPString * mmap_string_append(MMAPString * string, const char * val); | ||
1403 | |||
1404 | MMAPString * mmap_string_append_len(MMAPString * string, | ||
1405 | const char * val, size_t len); | ||
1406 | |||
1407 | MMAPString * mmap_string_append_c(MMAPString * string, char c); | ||
1408 | |||
1409 | MMAPString * mmap_string_prepend(MMAPString * string, const char * val); | ||
1410 | |||
1411 | MMAPString * mmap_string_prepend_c(MMAPString * string, char c); | ||
1412 | |||
1413 | MMAPString * mmap_string_prepend_len(MMAPString * string, const char * val, | ||
1414 | size_t len); | ||
1415 | |||
1416 | MMAPString * mmap_string_insert(MMAPString * string, size_t pos, | ||
1417 | const char * val); | ||
1418 | |||
1419 | MMAPString * mmap_string_insert_c(MMAPString *string, size_t pos, | ||
1420 | char c); | ||
1421 | |||
1422 | MMAPString * mmap_string_erase(MMAPString * string, size_t pos, | ||
1423 | size_t len); | ||
1424 | </programlisting> | ||
1425 | |||
1426 | <para> | ||
1427 | For complexity here, n is the size of the given MMAPString, | ||
1428 | and len is the size of the string to insert. | ||
1429 | </para> | ||
1430 | |||
1431 | <para> | ||
1432 | <command>mmap_string_insert_len()</command> inserts the given | ||
1433 | string value of given length in the string at the given | ||
1434 | position. <command>NULL</command> will be returned on error. | ||
1435 | Complexity is O(n + len). | ||
1436 | </para> | ||
1437 | |||
1438 | <para> | ||
1439 | <command>mmap_string_append()</command> appends the given | ||
1440 | string value at the end of the string. | ||
1441 | <command>NULL</command> will be returned on error. | ||
1442 | Complexity is O(len). | ||
1443 | </para> | ||
1444 | |||
1445 | <para> | ||
1446 | <command>mmap_string_append_len()</command> appends the | ||
1447 | given string value of given length at the end of the | ||
1448 | string. <command>NULL</command> will be returned on error. | ||
1449 | Complexity is O(len). | ||
1450 | </para> | ||
1451 | |||
1452 | <para> | ||
1453 | <command>mmap_string_append_c()</command> appends the given | ||
1454 | character at the end of the string. | ||
1455 | <command>NULL</command> will be returned on error. | ||
1456 | Complexity is O(1). | ||
1457 | </para> | ||
1458 | |||
1459 | <para> | ||
1460 | <command>mmap_string_prepend()</command> insert the given | ||
1461 | string value at the beginning of the string. | ||
1462 | <command>NULL</command> will be returned on error. | ||
1463 | Complexity is O(n + len). | ||
1464 | </para> | ||
1465 | |||
1466 | <para> | ||
1467 | <command>mmap_string_prepend_c()</command> insert the given | ||
1468 | character at the beginning of the string. | ||
1469 | <command>NULL</command> will be returned on error. | ||
1470 | Complexity is O(n). | ||
1471 | </para> | ||
1472 | |||
1473 | <para> | ||
1474 | <command>mmap_string_prepend_len()</command> insert the given | ||
1475 | string value of given length at the beginning of the string. | ||
1476 | <command>NULL</command> will be returned on error. | ||
1477 | Complexity is O(n + len). | ||
1478 | </para> | ||
1479 | |||
1480 | <para> | ||
1481 | <command>mmap_string_insert()</command> inserts the given | ||
1482 | string value in the string at the given position. | ||
1483 | NULL will be returned on error. | ||
1484 | Complexity is O(n + len). | ||
1485 | </para> | ||
1486 | |||
1487 | <para> | ||
1488 | <command>mmap_string_insert_c()</command> inserts the given | ||
1489 | character in the string at the given position. | ||
1490 | NULL will be returned on error. | ||
1491 | Complexity is O(n). | ||
1492 | </para> | ||
1493 | |||
1494 | <para> | ||
1495 | <command>mmap_string_erase()</command> removes the given | ||
1496 | count of characters (len) at the given position of the | ||
1497 | string. <command>NULL</command> will be returned on error. | ||
1498 | Complexity is O(n). | ||
1499 | </para> | ||
1500 | |||
1501 | </sect2> | ||
1502 | |||
1503 | <sect2 id="mmap-string-ref"> | ||
1504 | <title>referencing string</title> | ||
1505 | <programlisting role="C"> | ||
1506 | int mmap_string_ref(MMAPString * string); | ||
1507 | |||
1508 | int mmap_string_unref(char * str); | ||
1509 | </programlisting> | ||
1510 | |||
1511 | <para> | ||
1512 | MMAPString provides a mechanism that let you use MMAPString | ||
1513 | like normal strings. You have first to use | ||
1514 | <command>mmap_string_ref()</command>, so that you notify | ||
1515 | that the string will be used as a normal string, then, you | ||
1516 | use <command>mmapstr->str</command> to refer to the | ||
1517 | string. When you have finished and you want to free a string | ||
1518 | corresponding to a <command>MMAPString</command>, you will | ||
1519 | use <command>mmap_string_unref</command>. | ||
1520 | </para> | ||
1521 | |||
1522 | <para> | ||
1523 | <command>mmap_string_ref()</command> references the string | ||
1524 | so that the array of characters can be used as a normal | ||
1525 | string then released with | ||
1526 | <command>mmap_string_unref()</command>. | ||
1527 | The array of characters will be obtained with string->str. | ||
1528 | returns -1 on error, 0 on success. | ||
1529 | </para> | ||
1530 | </sect2> | ||
1531 | </sect1> | ||
1532 | </chapter> | ||
1533 | |||
1534 | <!-- IMF --> | ||
1535 | <chapter id="imf"> | ||
1536 | <title>Internet Message Format</title> | ||
1537 | |||
1538 | <para> | ||
1539 | libEtPan! implements Internet Message parser. Currently, format | ||
1540 | is RFC 2822. | ||
1541 | This module also allows to generate messages. | ||
1542 | </para> | ||
1543 | |||
1544 | <warning> | ||
1545 | <para> | ||
1546 | All allocation functions will take as argument allocated data | ||
1547 | and will store these data in the structure they will allocate. | ||
1548 | Data should be persistant during all the use of the structure | ||
1549 | and will be freed by the free function of the structure | ||
1550 | </para> | ||
1551 | |||
1552 | <para> | ||
1553 | allocation functions will return <command>NULL</command> on failure | ||
1554 | |||
1555 | functions returning integer will be returning one of the | ||
1556 | following error code: | ||
1557 | <command>MAILIMF_NO_ERROR</command>, | ||
1558 | <command>MAILIMF_ERROR_PARSE</command>, | ||
1559 | <command>MAILIMF_ERROR_MEMORY</command>, | ||
1560 | <command>MAILIMF_ERROR_INVAL</command>, | ||
1561 | or <command>MAILIMF_ERROR_FILE</command>. | ||
1562 | </para> | ||
1563 | </warning> | ||
1564 | |||
1565 | <sect1> | ||
1566 | <title>Quick start</title> | ||
1567 | |||
1568 | <para> | ||
1569 | You will need this module when you want to parse headers | ||
1570 | of messages or when you want to build message headers | ||
1571 | conformant to standards. | ||
1572 | </para> | ||
1573 | |||
1574 | <sect2> | ||
1575 | <title>Parse message headers</title> | ||
1576 | <para> | ||
1577 | You will use one of the four following functions, depending | ||
1578 | on your needs : | ||
1579 | </para> | ||
1580 | <itemizedlist> | ||
1581 | <listitem> | ||
1582 | <para> | ||
1583 | <command>mailimf_envelope_and_optional_fields_parse</command> | ||
1584 | (<xref linkend="mailimf-envelope-and-optional-fields-parse">), | ||
1585 | </para> | ||
1586 | </listitem> | ||
1587 | <listitem> | ||
1588 | <para> | ||
1589 | <command>mailimf_envelope_fields_parse</command> | ||
1590 | (<xref linkend="mailimf-envelope-fields-parse">), | ||
1591 | </para> | ||
1592 | </listitem> | ||
1593 | <listitem> | ||
1594 | <para> | ||
1595 | <command>mailimf_optional_fields_parse</command> | ||
1596 | (<xref linkend="mailimf-optional-fields-parse">), | ||
1597 | </para> | ||
1598 | </listitem> | ||
1599 | <listitem> | ||
1600 | <para> | ||
1601 | <command>mailimf_fields_parse</command> | ||
1602 | (<xref linkend="mailimf-fields-parse">). | ||
1603 | </para> | ||
1604 | </listitem> | ||
1605 | </itemizedlist> | ||
1606 | </sect2> | ||
1607 | |||
1608 | <sect2> | ||
1609 | <title>Render the message headers</title> | ||
1610 | <para> | ||
1611 | Build your message headers, then use | ||
1612 | <command>mailimf_fields_write</command> | ||
1613 | (<xref linkend="mailimf-fields-write">) | ||
1614 | to render the headers. | ||
1615 | </para> | ||
1616 | </sect2> | ||
1617 | </sect1> | ||
1618 | |||
1619 | <sect1> | ||
1620 | <title>Data types</title> | ||
1621 | <!-- mailimf_mailbox --> | ||
1622 | <sect2 id="mailimf-mailbox"> | ||
1623 | <title>mailimf_mailbox - mailbox</title> | ||
1624 | <para> | ||
1625 | #include <libetpan/libetpan.h> | ||
1626 | |||
1627 | struct mailimf_mailbox { | ||
1628 | char * mb_display_name; /* can be NULL */ | ||
1629 | char * mb_addr_spec; /* != NULL */ | ||
1630 | }; | ||
1631 | |||
1632 | struct mailimf_mailbox * | ||
1633 | mailimf_mailbox_new(char * mb_display_name, char * mb_addr_spec); | ||
1634 | |||
1635 | void mailimf_mailbox_free(struct mailimf_mailbox * mailbox); | ||
1636 | </para> | ||
1637 | |||
1638 | <para> | ||
1639 | This is an email mailbox with a display name. | ||
1640 | </para> | ||
1641 | |||
1642 | <example> | ||
1643 | <title>example of mailbox</title> | ||
1644 | <programlisting> | ||
1645 | DINH Viet Hoa <hoa@users.sourceforge.net> | ||
1646 | </programlisting> | ||
1647 | </example> | ||
1648 | |||
1649 | <para> | ||
1650 | <command>mailimf_mailbox_new</command> creates and | ||
1651 | initializes a data structure with a value. | ||
1652 | Strings given as argument are referenced by the created | ||
1653 | object and will be freed if the object is released. | ||
1654 | </para> | ||
1655 | |||
1656 | <para> | ||
1657 | <command>mailimf_mailbox_free</command> frees memory used by | ||
1658 | the structure and substructures will also be released. | ||
1659 | </para> | ||
1660 | |||
1661 | <example> | ||
1662 | <title>mailbox creation and display</title> | ||
1663 | <programlisting role="C"> | ||
1664 | #include <libetpan/libetpan.h> | ||
1665 | |||
1666 | int main(int argc, char ** argv) | ||
1667 | { | ||
1668 | struct mailimf_mailbox * mb; | ||
1669 | char * display_name; | ||
1670 | char * address; | ||
1671 | |||
1672 | display_name = strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="); | ||
1673 | address = strdup("dinh.viet.hoa@free.fr"); | ||
1674 | mb = mailimf_mailbox_new(str, address); | ||
1675 | /* do the things */ | ||
1676 | mailimf_mailbox_free(mb); | ||
1677 | |||
1678 | return 0; | ||
1679 | } | ||
1680 | |||
1681 | /* display mailbox information */ | ||
1682 | |||
1683 | #include <libetpan/libetpan.h> | ||
1684 | #include <stdio.h> | ||
1685 | |||
1686 | void display_mailbox(struct mailimf_mailbox * mb) | ||
1687 | { | ||
1688 | if (mb->mb_display_name != NULL) | ||
1689 | printf("display name: %s\n", mb->mb_display_name); | ||
1690 | printf("address specifier : %s\n", mb->mb_addr_spec); | ||
1691 | } | ||
1692 | </programlisting> | ||
1693 | </example> | ||
1694 | </sect2> | ||
1695 | |||
1696 | <!-- mailimf_address --> | ||
1697 | <sect2 id="mailimf-address"> | ||
1698 | <title>mailimf_address - address</title> | ||
1699 | |||
1700 | <programlisting role="C"> | ||
1701 | #include <libetpan/libetpan.h> | ||
1702 | |||
1703 | struct mailimf_address { | ||
1704 | int ad_type; | ||
1705 | union { | ||
1706 | struct mailimf_mailbox * ad_mailbox; /* can be NULL */ | ||
1707 | struct mailimf_group * ad_group; /* can be NULL */ | ||
1708 | } ad_data; | ||
1709 | }; | ||
1710 | |||
1711 | struct mailimf_address * | ||
1712 | mailimf_address_new(int ad_type, struct mailimf_mailbox * ad_mailbox, | ||
1713 | struct mailimf_group * ad_group); | ||
1714 | |||
1715 | void mailimf_address_free(struct mailimf_address * address); | ||
1716 | </programlisting> | ||
1717 | |||
1718 | <para> | ||
1719 | This is a mailbox or a group of mailbox. | ||
1720 | </para> | ||
1721 | |||
1722 | <itemizedlist> | ||
1723 | <listitem> | ||
1724 | <para> | ||
1725 | <command>ad_type</command> can be MAILIMF_ADDRESS_MAILBOX or | ||
1726 | <command>MAILIMF_ADDRESS_GROUP</command>. | ||
1727 | </para> | ||
1728 | </listitem> | ||
1729 | <listitem> | ||
1730 | <para> | ||
1731 | <command>ad_data.ad_mailbox</command> is a mailbox if | ||
1732 | <command>ad_type</command> is | ||
1733 | <command>MAILIMF_ADDRESS_MAILBOX</command> | ||
1734 | see <xref linkend="mailimf-mailbox">) | ||
1735 | </para> | ||
1736 | </listitem> | ||
1737 | <listitem> | ||
1738 | <para> | ||
1739 | <command>ad_data.group</command> is a group if type is | ||
1740 | <command>MAILIMF_ADDRESS_GROUP</command>. | ||
1741 | see <xref linkend="mailimf-group">) | ||
1742 | </para> | ||
1743 | </listitem> | ||
1744 | </itemizedlist> | ||
1745 | |||
1746 | <para> | ||
1747 | <command>mailimf_address_new()</command> creates and initializes | ||
1748 | a data structure with a value. | ||
1749 | Structures given as argument are referenced by the created | ||
1750 | object and will be freed if the object is released. | ||
1751 | </para> | ||
1752 | |||
1753 | <para> | ||
1754 | <command>mailimf_address_free</command> frees memory used by | ||
1755 | the structure and substructures will also be released. | ||
1756 | </para> | ||
1757 | |||
1758 | <example> | ||
1759 | <title>address creation and display</title> | ||
1760 | <programlisting role="C"> | ||
1761 | /* creates an address of type mailbox */ | ||
1762 | |||
1763 | #include <libetpan/libetpan.h> | ||
1764 | |||
1765 | int main(int argc, char ** argv) | ||
1766 | { | ||
1767 | struct mailimf_address * a_mb; | ||
1768 | struct mailimf_mailbox * mb; | ||
1769 | char * display_name; | ||
1770 | char * address; | ||
1771 | |||
1772 | display_name = strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="); | ||
1773 | address = strdup("dinh.viet.hoa@free.fr"); | ||
1774 | mb = mailimf_mailbox_new(str, address); | ||
1775 | |||
1776 | a_mb = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
1777 | /* do the things */ | ||
1778 | mailimf_address_free(a_mb); | ||
1779 | } | ||
1780 | |||
1781 | /* creates an address of type group */ | ||
1782 | |||
1783 | #include <libetpan/libetpan.h> | ||
1784 | |||
1785 | int main(int argc, char ** argv) | ||
1786 | { | ||
1787 | struct mailimf_address * a_g; | ||
1788 | struct mailimf_group * g; | ||
1789 | char * display_name; | ||
1790 | |||
1791 | display_name = strdup("undisclosed-recipient"); | ||
1792 | g = mailimf_group_new(display_name, NULL); | ||
1793 | |||
1794 | a_g = mailimf_address_new(MAILIMF_ADDRESS_GROUP, NULL, g); | ||
1795 | /* do the things */ | ||
1796 | mailimf_address_free(a_g); | ||
1797 | |||
1798 | return 0; | ||
1799 | } | ||
1800 | |||
1801 | /* display the content of an address */ | ||
1802 | |||
1803 | #include <libetpan/libetpan.h> | ||
1804 | |||
1805 | void display_address(struct mailimf_address * a) | ||
1806 | { | ||
1807 | clistiter * cur; | ||
1808 | |||
1809 | switch (a->ad_type) { | ||
1810 | case MAILIMF_ADDRESS_GROUP: | ||
1811 | display_mailimf_group(a->ad_data.ad_group); | ||
1812 | break; | ||
1813 | |||
1814 | case MAILIMF_ADDRESS_MAILBOX: | ||
1815 | display_mailimf_mailbox(a->ad_data.ad_mailbox); | ||
1816 | break; | ||
1817 | } | ||
1818 | } | ||
1819 | </programlisting> | ||
1820 | </example> | ||
1821 | </sect2> | ||
1822 | |||
1823 | <!-- mailimf_mailbox_list --> | ||
1824 | <sect2 id="mailimf-mailbox-list"> | ||
1825 | <title>mailimf_mailbox_list - list of mailboxes</title> | ||
1826 | |||
1827 | <programlisting role="C"> | ||
1828 | #include <libetpan/libetpan.h> | ||
1829 | |||
1830 | struct mailimf_mailbox_list { | ||
1831 | clist * mb_list; /* list of (struct mailimf_mailbox *), != NULL */ | ||
1832 | }; | ||
1833 | |||
1834 | struct mailimf_mailbox_list * | ||
1835 | mailimf_mailbox_list_new(clist * mb_list); | ||
1836 | |||
1837 | void mailimf_mailbox_list_free(struct mailimf_mailbox_list * mb_list); | ||
1838 | </programlisting> | ||
1839 | |||
1840 | <para> | ||
1841 | This is a list of mailboxes. | ||
1842 | </para> | ||
1843 | |||
1844 | <para> | ||
1845 | <command>mb_list</command> is a list of mailboxes. This is a | ||
1846 | <command>clist</command> which elements are of type | ||
1847 | mailimf_mailbox (see <xref linkend="mailimf-mailbox">). | ||
1848 | </para> | ||
1849 | |||
1850 | <para> | ||
1851 | <command>mailimf_mailbox_list_new()</command> creates and | ||
1852 | initializes a data structure with a value. | ||
1853 | Structures given as argument are referenced by the created | ||
1854 | object and will be freed if the object is released. | ||
1855 | </para> | ||
1856 | |||
1857 | <para> | ||
1858 | <command>mailimf_mailbox_list_free()</command> frees memory used by the | ||
1859 | structure and substructures will also be released. | ||
1860 | </para> | ||
1861 | |||
1862 | <example> | ||
1863 | <title>Creation and display of mailimf_mailbox_list</title> | ||
1864 | <programlisting role="C"> | ||
1865 | /* creates a list of mailboxes with two mailboxes */ | ||
1866 | |||
1867 | #include <libetpan/libetpan.h> | ||
1868 | |||
1869 | int main(int argc, char ** argv) | ||
1870 | { | ||
1871 | struct mailimf_group * g; | ||
1872 | char * display_name; | ||
1873 | struct mailimf_mailbox_list * mb_list; | ||
1874 | clist * list; | ||
1875 | |||
1876 | list = clist_new(); | ||
1877 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
1878 | strdup("dinh.viet.hoa@free.fr")); | ||
1879 | list = clist_append(mb); | ||
1880 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
1881 | strdup("christophe@giaume.com")); | ||
1882 | list = clist_append(mb); | ||
1883 | |||
1884 | mb_list = mailimf_mailbox_list_new(list); | ||
1885 | /* do the things */ | ||
1886 | mailimf_mailbox_list_free(mb_list); | ||
1887 | |||
1888 | return 0; | ||
1889 | } | ||
1890 | |||
1891 | /* display a list of mailboxes */ | ||
1892 | |||
1893 | #include <libetpan/libetpan.h> | ||
1894 | #include <stdio.h> | ||
1895 | |||
1896 | void display_mailbox_list(struct mailimf_mailbox_list * mb_list) | ||
1897 | { | ||
1898 | clistiter * cur; | ||
1899 | |||
1900 | for(cur = clist_begin(mb_list->mb_list) ; cur != NULL ; | ||
1901 | cur = clist_next(cur)) { | ||
1902 | struct mailimf_mailbox * mb; | ||
1903 | |||
1904 | mb = clist_content(cur); | ||
1905 | |||
1906 | display_mailbox(mb); | ||
1907 | printf("\n"); | ||
1908 | } | ||
1909 | } | ||
1910 | </programlisting> | ||
1911 | </example> | ||
1912 | </sect2> | ||
1913 | |||
1914 | <!-- mailimf_address_list --> | ||
1915 | <sect2 id="mailimf-address-list"> | ||
1916 | <title>mailimf_address_list - list of addresses</title> | ||
1917 | |||
1918 | <programlisting role="C"> | ||
1919 | #include <libetpan/libetpan.h> | ||
1920 | |||
1921 | struct mailimf_address_list { | ||
1922 | clist * ad_list; /* list of (struct mailimf_address *), != NULL */ | ||
1923 | }; | ||
1924 | |||
1925 | struct mailimf_address_list * | ||
1926 | mailimf_address_list_new(clist * ad_list); | ||
1927 | |||
1928 | void mailimf_address_list_free(struct mailimf_address_list * addr_list); | ||
1929 | </programlisting> | ||
1930 | |||
1931 | <para> | ||
1932 | This is a list of addresses. | ||
1933 | </para> | ||
1934 | |||
1935 | <para> | ||
1936 | <command>ad_list</command> is a list of addresses. This is a | ||
1937 | <command>clist</command> which elements are | ||
1938 | of type mailimf_address (see <xref linkend="mailimf-address">). | ||
1939 | </para> | ||
1940 | |||
1941 | <para> | ||
1942 | <command>mailimf_address_list_new()</command> creates and | ||
1943 | initializes a data structure with | ||
1944 | a value. Structures given as argument are referenced by the | ||
1945 | created object and will be freed if the object is released. | ||
1946 | </para> | ||
1947 | |||
1948 | <para> | ||
1949 | <command>mailimf_address_list_free()</command> frees memory | ||
1950 | used by the structure and substructures will also be released. | ||
1951 | </para> | ||
1952 | |||
1953 | <example> | ||
1954 | <title>creation and display of list of addresses</title> | ||
1955 | <programlisting role="C"> | ||
1956 | /* creates a list of addresses with two addresses */ | ||
1957 | |||
1958 | #include <libetpan/libetpan.h> | ||
1959 | |||
1960 | int main(int argc, char ** argv) | ||
1961 | { | ||
1962 | struct mailimf_address_list * addr_list; | ||
1963 | clist * list; | ||
1964 | struct mailimf_mailbox * mb; | ||
1965 | struct mailimf_address * addr; | ||
1966 | |||
1967 | list = clist_new(); | ||
1968 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
1969 | strdup("dinh.viet.hoa@free.fr")); | ||
1970 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
1971 | list = clist_append(addr); | ||
1972 | |||
1973 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
1974 | strdup("christophe@giaume.com")); | ||
1975 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
1976 | list = clist_append(addr); | ||
1977 | |||
1978 | addr_list = mailimf_address_list_new(list); | ||
1979 | /* do the things */ | ||
1980 | mailimf_address_list_free(mb_list); | ||
1981 | |||
1982 | return 0; | ||
1983 | } | ||
1984 | |||
1985 | /* display a list of addresses */ | ||
1986 | |||
1987 | #include <libetpan/libetpan.h> | ||
1988 | #include <stdio.h> | ||
1989 | |||
1990 | void display_address_list(struct mailimf_address_list * addr_list) | ||
1991 | { | ||
1992 | clistiter * cur; | ||
1993 | |||
1994 | for(cur = clist_begin(addr_list->ad_list) ; cur != NULL ; | ||
1995 | cur = clist_next(cur)) { | ||
1996 | struct mailimf_address * addr; | ||
1997 | |||
1998 | addr = clist_content(cur); | ||
1999 | |||
2000 | display_address(addr); | ||
2001 | printf("\n"); | ||
2002 | } | ||
2003 | } | ||
2004 | </programlisting> | ||
2005 | </example> | ||
2006 | </sect2> | ||
2007 | |||
2008 | <!-- mailimf_group --> | ||
2009 | <sect2 id="mailimf-group"> | ||
2010 | <title>mailimf_group - named group of mailboxes</title> | ||
2011 | <programlisting role="C"> | ||
2012 | #include <libetpan/libetpan.h> | ||
2013 | |||
2014 | struct mailimf_group { | ||
2015 | char * grp_display_name; /* != NULL */ | ||
2016 | struct mailimf_mailbox_list * grp_mb_list; /* can be NULL */ | ||
2017 | }; | ||
2018 | |||
2019 | struct mailimf_group * | ||
2020 | mailimf_group_new(char * grp_display_name, | ||
2021 | struct mailimf_mailbox_list * grp_mb_list); | ||
2022 | |||
2023 | void mailimf_group_free(struct mailimf_group * group); | ||
2024 | </programlisting> | ||
2025 | |||
2026 | <para> | ||
2027 | This is a list of mailboxes tagged with a name. | ||
2028 | </para> | ||
2029 | |||
2030 | <example> | ||
2031 | <title>example of group</title> | ||
2032 | <programlisting> | ||
2033 | they play music: <steve@morse.foo>, <neal@morse.foo>, | ||
2034 | <yngwie@malmsteen.bar>, <michael@romeo.bar>; | ||
2035 | </programlisting> | ||
2036 | </example> | ||
2037 | |||
2038 | <para> | ||
2039 | <command>grp_display_name</command> is the name that will be | ||
2040 | displayed for this group, | ||
2041 | for example '<command>group_name</command>' in | ||
2042 | '<command>group_name: address1@domain1, | ||
2043 | address2@domain2;</command>'. | ||
2044 | This must be allocated with malloc(). | ||
2045 | <command>grp_mb_list</command> is a list of mailboxes | ||
2046 | (see <xref linkend="mailimf-mailbox-list">). | ||
2047 | </para> | ||
2048 | |||
2049 | <para> | ||
2050 | <command>mailimf_group_new()</command> creates and initializes | ||
2051 | a data structure with a value. | ||
2052 | Structures given as argument are referenced by the created | ||
2053 | object and will be freed if the object is released. | ||
2054 | </para> | ||
2055 | |||
2056 | <para> | ||
2057 | <command>mailimf_group_free()</command> frees memory used by | ||
2058 | the structure and substructures will also be released. | ||
2059 | </para> | ||
2060 | |||
2061 | <example> | ||
2062 | <title>creation and display of a group</title> | ||
2063 | <programlisting role="C"> | ||
2064 | /* creates an empty group */ | ||
2065 | |||
2066 | #include <libetpan/libetpan.h> | ||
2067 | |||
2068 | int main(int argc, char ** argv) | ||
2069 | { | ||
2070 | struct mailimf_group * g; | ||
2071 | char * display_name; | ||
2072 | |||
2073 | display_name = strdup("undisclosed-recipient"); | ||
2074 | g = mailimf_group_new(display_name, NULL); | ||
2075 | /* do the things */ | ||
2076 | mailimf_group_free(g); | ||
2077 | } | ||
2078 | |||
2079 | /* creates a group with two mailboxes */ | ||
2080 | |||
2081 | #include <libetpan/libetpan.h> | ||
2082 | |||
2083 | int main(int argc, char ** argv) | ||
2084 | { | ||
2085 | struct mailimf_group * g; | ||
2086 | char * display_name; | ||
2087 | struct mailimf_mailbox_list * mb_list; | ||
2088 | struct mailimf_mailbox * mb; | ||
2089 | clist * list; | ||
2090 | |||
2091 | list = clist_new(); | ||
2092 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2093 | strdup("dinh.viet.hoa@free.fr")); | ||
2094 | list = clist_append(mb); | ||
2095 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
2096 | strdup("christophe@giaume.com")); | ||
2097 | list = clist_append(mb); | ||
2098 | |||
2099 | mb_list = mailimf_mailbox_list_new(list); | ||
2100 | |||
2101 | display_name = strdup("my_group"); | ||
2102 | g = mailimf_group_new(display_name, mb_list); | ||
2103 | /* do the things */ | ||
2104 | mailimf_group_free(g); | ||
2105 | |||
2106 | return 0; | ||
2107 | } | ||
2108 | |||
2109 | /* display content of group */ | ||
2110 | |||
2111 | #include <libetpan/libetpan.h> | ||
2112 | #include <stdio.h> | ||
2113 | |||
2114 | void display_group(struct mailimf_group * group) | ||
2115 | { | ||
2116 | printf("name of the group: %s\n", a->group->display_name); | ||
2117 | for(cur = clist_begin(a->group->mb_list->list) ; cur != NULL ; | ||
2118 | cur = clist_next(cur)) { | ||
2119 | struct mailimf_mailbox * mb; | ||
2120 | |||
2121 | mb = clist_content(cur); | ||
2122 | display_mailbox(mb); | ||
2123 | printf("\n"); | ||
2124 | } | ||
2125 | } | ||
2126 | </programlisting> | ||
2127 | </example> | ||
2128 | </sect2> | ||
2129 | |||
2130 | <!-- mailimf_date_time --> | ||
2131 | <sect2 id="mailimf-date-time"> | ||
2132 | <title>mailimf_date_time - date of a message</title> | ||
2133 | |||
2134 | <para> | ||
2135 | #include <libetpan/libetpan.h> | ||
2136 | |||
2137 | struct mailimf_date_time { | ||
2138 | int dt_day; | ||
2139 | int dt_month; | ||
2140 | int dt_year; | ||
2141 | int dt_hour; | ||
2142 | int dt_min; | ||
2143 | int dt_sec; | ||
2144 | int dt_zone; | ||
2145 | }; | ||
2146 | |||
2147 | struct mailimf_date_time * | ||
2148 | mailimf_date_time_new(int dt_day, int dt_month, int dt_year, | ||
2149 | int dt_hour, int dt_min, int dt_sec, int dt_zone); | ||
2150 | |||
2151 | void mailimf_date_time_free(struct mailimf_date_time * date_time); | ||
2152 | </para> | ||
2153 | |||
2154 | <para> | ||
2155 | This is the date and time of a message. | ||
2156 | For example : | ||
2157 | </para> | ||
2158 | <example> | ||
2159 | <title>example of date</title> | ||
2160 | <programlisting> | ||
2161 | Thu, 11 Dec 2003 00:15:02 +0100. | ||
2162 | </programlisting> | ||
2163 | </example> | ||
2164 | |||
2165 | <itemizedlist> | ||
2166 | <listitem> | ||
2167 | <para> | ||
2168 | <command>dt_day</command> is the day of month (1 to 31) | ||
2169 | </para> | ||
2170 | </listitem> | ||
2171 | <listitem> | ||
2172 | <para> | ||
2173 | <command>dt_month</command> (1 to 12) | ||
2174 | </para> | ||
2175 | </listitem> | ||
2176 | <listitem> | ||
2177 | <para> | ||
2178 | <command>dt_year</command> (4 digits) | ||
2179 | </para> | ||
2180 | </listitem> | ||
2181 | <listitem> | ||
2182 | <para> | ||
2183 | <command>dt_hour</command> (0 to 23) | ||
2184 | </para> | ||
2185 | </listitem> | ||
2186 | <listitem> | ||
2187 | <para> | ||
2188 | <command>dt_min</command> (0 to 59) | ||
2189 | </para> | ||
2190 | </listitem> | ||
2191 | <listitem> | ||
2192 | <para> | ||
2193 | <command>dt_sec</command> (0 to 59) | ||
2194 | </para> | ||
2195 | </listitem> | ||
2196 | <listitem> | ||
2197 | <para> | ||
2198 | <command>dt_zone</command> (this is the decimal value that | ||
2199 | we can read, for example: for | ||
2200 | '<command>-0200</command>', the value is | ||
2201 | <command>-200</command>). | ||
2202 | </para> | ||
2203 | </listitem> | ||
2204 | </itemizedlist> | ||
2205 | |||
2206 | <para> | ||
2207 | <command>mailimf_date_time_new()</command> creates and | ||
2208 | initializes a date structure with a value. | ||
2209 | </para> | ||
2210 | |||
2211 | <para> | ||
2212 | <command>mailimf_date_time_free()</command> frees memory used | ||
2213 | by the structure. | ||
2214 | </para> | ||
2215 | |||
2216 | <example> | ||
2217 | <title>creation and display of date</title> | ||
2218 | <programlisting role="C"> | ||
2219 | #include <libetpan/libetpan.h> | ||
2220 | |||
2221 | int main(int argc, char ** argv) | ||
2222 | { | ||
2223 | struct mailimf_date_time * d; | ||
2224 | |||
2225 | d = mailimf_date_time_new(9, 5, 2003, 3, 01, 40, -0200); | ||
2226 | /* do the things */ | ||
2227 | mailimf_date_time_free(d); | ||
2228 | |||
2229 | return 0; | ||
2230 | } | ||
2231 | |||
2232 | /* display the date */ | ||
2233 | |||
2234 | #include <libetpan/libetpan.h> | ||
2235 | #include <stdio.h> | ||
2236 | |||
2237 | void display_date(struct mailimf_date_time * d) | ||
2238 | { | ||
2239 | printf("%02i/%02i/%i %02i:%02i:%02i %+04i\n", | ||
2240 | d->dt_day, d->dt_month, d->dt_year, | ||
2241 | d->dt_hour, d->dt_min, d->dt_sec, d->dt_zone); | ||
2242 | } | ||
2243 | </programlisting> | ||
2244 | </example> | ||
2245 | </sect2> | ||
2246 | |||
2247 | <!-- mailimf_orig_date --> | ||
2248 | <sect2 id="mailimf-orig-date"> | ||
2249 | <title>mailimf_orig_date - parsed content of date header</title> | ||
2250 | |||
2251 | <programlisting role="C"> | ||
2252 | #include <libetpan/libetpan.h> | ||
2253 | |||
2254 | struct mailimf_orig_date { | ||
2255 | struct mailimf_date_time * dt_date_time; /* != NULL */ | ||
2256 | }; | ||
2257 | |||
2258 | struct mailimf_orig_date * mailimf_orig_date_new(struct mailimf_date_time * | ||
2259 | dt_date_time); | ||
2260 | |||
2261 | void mailimf_orig_date_free(struct mailimf_orig_date * orig_date); | ||
2262 | </programlisting> | ||
2263 | |||
2264 | <para> | ||
2265 | This is the content of a header <command>Date</command> or | ||
2266 | <command>Resent-Date</command>. | ||
2267 | It encapsulates a mailimf_date_time | ||
2268 | </para> | ||
2269 | |||
2270 | <para> | ||
2271 | <command>dt_date_time</command> is the parsed date | ||
2272 | (see <xref linkend="mailimf-date-time">). | ||
2273 | </para> | ||
2274 | |||
2275 | <para> | ||
2276 | <command>mailimf_orig_date_new()</command> creates and | ||
2277 | initializes a data structure with | ||
2278 | a value. Structures given as argument are referenced by the | ||
2279 | created object and will be freed if the object is released. | ||
2280 | </para> | ||
2281 | |||
2282 | <para> | ||
2283 | <command>mailimf_orig_date_free()</command> frees memory used | ||
2284 | by the structure and substructures will also be released. | ||
2285 | </para> | ||
2286 | |||
2287 | <example> | ||
2288 | <title>creation and display of Date field</title> | ||
2289 | <programlisting role="C"> | ||
2290 | #include <libetpan/libetpan.h> | ||
2291 | |||
2292 | int main(int argc, char ** argv) | ||
2293 | { | ||
2294 | struct mailimf_date_time * d; | ||
2295 | struct mailimf_orig_date * date; | ||
2296 | |||
2297 | d = mailimf_date_time_new(9, 5, 2003, 3, 01, 40, -0200); | ||
2298 | date = mailimf_orig_date_new(d); | ||
2299 | /* do the things */ | ||
2300 | mailimf_orig_date_free(date); | ||
2301 | |||
2302 | return 0; | ||
2303 | } | ||
2304 | |||
2305 | /* display date header */ | ||
2306 | |||
2307 | #include <libetpan/libetpan.h> | ||
2308 | |||
2309 | void display_orig_date(struct mailimf_orig_date * orig_date) | ||
2310 | { | ||
2311 | display_date_time(d->dt_date_time); | ||
2312 | } | ||
2313 | </programlisting> | ||
2314 | </example> | ||
2315 | </sect2> | ||
2316 | |||
2317 | <!-- mailimf_from --> | ||
2318 | <sect2 id="mailimf-from"> | ||
2319 | <title>mailimf_from - parsed content of From header</title> | ||
2320 | <programlisting role="C"> | ||
2321 | #include <libetpan/libetpan.h> | ||
2322 | |||
2323 | struct mailimf_from { | ||
2324 | struct mailimf_mailbox_list * frm_mb_list; /* != NULL */ | ||
2325 | }; | ||
2326 | |||
2327 | struct mailimf_from * | ||
2328 | mailimf_from_new(struct mailimf_mailbox_list * frm_mb_list); | ||
2329 | |||
2330 | void mailimf_from_free(struct mailimf_from * from); | ||
2331 | </programlisting> | ||
2332 | |||
2333 | <para> | ||
2334 | This is the content of a header <command>From</command> or | ||
2335 | <command>Resent-From</command>. | ||
2336 | </para> | ||
2337 | <para> | ||
2338 | <command>frm_mb_list</command> is the parsed mailbox list | ||
2339 | (see <xref linkend="mailimf-mailbox-list">). | ||
2340 | </para> | ||
2341 | |||
2342 | <para> | ||
2343 | <command>mailimf_from_new()</command> creates and initializes | ||
2344 | a data structure with a value. | ||
2345 | Structures given as argument are referenced by the created | ||
2346 | object and will be freed if the object is released. | ||
2347 | </para> | ||
2348 | |||
2349 | <para> | ||
2350 | <command>mailimf_from_free()</command> frees memory used by | ||
2351 | the structure and substructures will also be released. | ||
2352 | </para> | ||
2353 | |||
2354 | <example> | ||
2355 | <title>creation and display of a From header</title> | ||
2356 | <programlisting role="C"> | ||
2357 | #include <libetpan/libetpan.h> | ||
2358 | |||
2359 | int main(int argc, char ** argv) | ||
2360 | { | ||
2361 | clist * list; | ||
2362 | struct mailimf_mailbox * mb; | ||
2363 | struct mailimf_mailbox_list * mb_list; | ||
2364 | struct mailimf_from * from; | ||
2365 | |||
2366 | list = clist_new(); | ||
2367 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2368 | strdup("dinh.viet.hoa@free.fr")); | ||
2369 | clist_append(list, mb); | ||
2370 | mb_list = mailimf_mailbox_list_new(list); | ||
2371 | |||
2372 | from = mailimf_from_new(mb_list); | ||
2373 | /* do the things */ | ||
2374 | mailimf_from_free(from); | ||
2375 | |||
2376 | return 0; | ||
2377 | } | ||
2378 | |||
2379 | /* display content of from header */ | ||
2380 | |||
2381 | #include <libetpan/libetpan.h> | ||
2382 | |||
2383 | void display_from(struct mailimf_from * from) | ||
2384 | { | ||
2385 | display_mailbox_list(from->frm_mb_list); | ||
2386 | } | ||
2387 | </programlisting> | ||
2388 | </example> | ||
2389 | </sect2> | ||
2390 | |||
2391 | <!-- mailimf_sender --> | ||
2392 | <sect2 id="mailimf-sender"> | ||
2393 | <title>mailimf_sender - parsed content of Sender header</title> | ||
2394 | |||
2395 | <programlisting role="C"> | ||
2396 | #include <libetpan/libetpan.h> | ||
2397 | |||
2398 | struct mailimf_sender { | ||
2399 | struct mailimf_mailbox * snd_mb; /* != NULL */ | ||
2400 | }; | ||
2401 | |||
2402 | struct mailimf_sender * mailimf_sender_new(struct mailimf_mailbox * snd_mb); | ||
2403 | |||
2404 | void mailimf_sender_free(struct mailimf_sender * sender); | ||
2405 | </programlisting> | ||
2406 | |||
2407 | <para> | ||
2408 | This is the content of a header <command>Sender</command> or | ||
2409 | <command>Resent-Sender</command>. | ||
2410 | </para> | ||
2411 | |||
2412 | <para> | ||
2413 | <command>snd_mb</command> is the parsed mailbox | ||
2414 | (see <xref linkend="mailimf-mailbox">). | ||
2415 | </para> | ||
2416 | |||
2417 | <para> | ||
2418 | <command>mailimf_sender_new()</command> creates and | ||
2419 | initializes a data structure with a value. | ||
2420 | Structures given as argument are referenced by the created | ||
2421 | object and will be freed if the object is released. | ||
2422 | </para> | ||
2423 | |||
2424 | <para> | ||
2425 | <command>mailimf_sender_free()</command> This function frees | ||
2426 | memory used by the structure and substructures | ||
2427 | will also be released. | ||
2428 | </para> | ||
2429 | |||
2430 | <example> | ||
2431 | <title>creation and display of Sender field</title> | ||
2432 | <programlisting role="C"> | ||
2433 | #include <libetpan/libetpan.h> | ||
2434 | |||
2435 | int main(int argc, char ** argv) | ||
2436 | { | ||
2437 | struct mailimf_mailbox * mb; | ||
2438 | struct mailimf_sender * sender; | ||
2439 | |||
2440 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2441 | strdup("dinh.viet.hoa@free.fr")); | ||
2442 | |||
2443 | sender = mailimf_sender_new(mb); | ||
2444 | /* do the things */ | ||
2445 | mailimf_sender_free(sender); | ||
2446 | |||
2447 | return 0; | ||
2448 | } | ||
2449 | |||
2450 | #include <libetpan/libetpan.h> | ||
2451 | #include <stdio.h> | ||
2452 | |||
2453 | void display_sender(struct mailimf_sender * sender) | ||
2454 | { | ||
2455 | display_mailbox(sender->snd_mb); | ||
2456 | } | ||
2457 | </programlisting> | ||
2458 | </example> | ||
2459 | </sect2> | ||
2460 | |||
2461 | <!-- mailimf_reply_to --> | ||
2462 | <sect2 id="mailimf-reply-to"> | ||
2463 | <title>mailimf_reply_to - parsed content of Reply-To header</title> | ||
2464 | |||
2465 | <programlisting role="C"> | ||
2466 | #include <libetpan/libetpan.h> | ||
2467 | |||
2468 | struct mailimf_reply_to { | ||
2469 | struct mailimf_address_list * rt_addr_list; /* != NULL */ | ||
2470 | }; | ||
2471 | |||
2472 | struct mailimf_reply_to * | ||
2473 | mailimf_reply_to_new(struct mailimf_address_list * rt_addr_list); | ||
2474 | |||
2475 | void mailimf_reply_to_free(struct mailimf_reply_to * reply_to); | ||
2476 | </programlisting> | ||
2477 | |||
2478 | <para> | ||
2479 | This is the content of a header <command>Reply-To</command>. | ||
2480 | </para> | ||
2481 | |||
2482 | <para> | ||
2483 | <command>addr_list</command> is the parsed address list | ||
2484 | (see <xref linkend="mailimf-address-list">). | ||
2485 | </para> | ||
2486 | |||
2487 | <para> | ||
2488 | <command>mailimf_reply_to_new()</command> creates and | ||
2489 | initializes a data structure with a value. Structures given | ||
2490 | as argument are referenced by the created object and will be | ||
2491 | freed if the object is released. | ||
2492 | </para> | ||
2493 | |||
2494 | <para> | ||
2495 | <command>mailimf_reply_to_free()</command> frees memory used | ||
2496 | by the structure and substructures will also be released. | ||
2497 | </para> | ||
2498 | |||
2499 | <example> | ||
2500 | <title>creation and display of Reply-To field</title> | ||
2501 | <programlisting role="C"> | ||
2502 | #include <libetpan/libetpan.h> | ||
2503 | |||
2504 | int main(int argc, char ** argv) | ||
2505 | { | ||
2506 | clist * list; | ||
2507 | struct mailimf_mailbox * mb; | ||
2508 | struct mailimf_address * addr; | ||
2509 | struct mailimf_address_list * addr_list; | ||
2510 | struct mailimf_reply_to * reply_to; | ||
2511 | |||
2512 | list = clist_new(); | ||
2513 | |||
2514 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2515 | strdup("dinh.viet.hoa@free.fr")); | ||
2516 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2517 | clist_append(list, addr); | ||
2518 | |||
2519 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
2520 | strdup("christophe@giaume.com")); | ||
2521 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2522 | clist_append(list, addr); | ||
2523 | |||
2524 | addr_list = mailimf_address_list_new(list); | ||
2525 | |||
2526 | reply_to = mailimf_reply_to_new(addr_list); | ||
2527 | /* do the things */ | ||
2528 | mailimf_reply_to_free(reply_to); | ||
2529 | |||
2530 | return 0; | ||
2531 | } | ||
2532 | |||
2533 | /* display Reply-To header */ | ||
2534 | |||
2535 | #include <libetpan/libetpan.h> | ||
2536 | |||
2537 | void display_reply_to(struct mailimf_reply_to * reply_to) | ||
2538 | { | ||
2539 | display_address_list(reply_to->addr_list); | ||
2540 | } | ||
2541 | </programlisting> | ||
2542 | </example> | ||
2543 | </sect2> | ||
2544 | |||
2545 | <!-- mailimf_to --> | ||
2546 | <sect2 id="mailimf-to"> | ||
2547 | <title>mailimf_to - parsed content of To header</title> | ||
2548 | |||
2549 | <programlisting role="C"> | ||
2550 | struct mailimf_to { | ||
2551 | struct mailimf_address_list * to_addr_list; /* != NULL */ | ||
2552 | }; | ||
2553 | |||
2554 | struct mailimf_to * mailimf_to_new(struct mailimf_address_list * to_addr_list); | ||
2555 | |||
2556 | void mailimf_to_free(struct mailimf_to * to); | ||
2557 | </programlisting> | ||
2558 | |||
2559 | <para> | ||
2560 | This is the content of a header <command>To</command> or | ||
2561 | <command>Resent-To</command>. | ||
2562 | </para> | ||
2563 | |||
2564 | <para> | ||
2565 | <command>to_addr_list</command> is the parsed address list | ||
2566 | (see <xref linkend="mailimf-address-list">). | ||
2567 | </para> | ||
2568 | |||
2569 | <para> | ||
2570 | <command>mailimf_to_new()</command> creates and initializes a | ||
2571 | data structure with a value. Structures given as argument | ||
2572 | are referenced by the created | ||
2573 | object and will be freed if the object is released. | ||
2574 | </para> | ||
2575 | |||
2576 | <para> | ||
2577 | <command>mailimf_to_free()</command> frees memory used by the | ||
2578 | structure and substructures will also be released. | ||
2579 | </para> | ||
2580 | |||
2581 | <example> | ||
2582 | <title>creation and display of To field</title> | ||
2583 | <programlisting role="C"> | ||
2584 | #include <libetpan/libetpan.h> | ||
2585 | |||
2586 | int main(int argc, char ** argv) | ||
2587 | { | ||
2588 | clist * list; | ||
2589 | struct mailimf_mailbox * mb; | ||
2590 | struct mailimf_address * addr; | ||
2591 | struct mailimf_address_list * addr_list; | ||
2592 | struct mailimf_to * to; | ||
2593 | |||
2594 | list = clist_new(); | ||
2595 | |||
2596 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2597 | strdup("dinh.viet.hoa@free.fr")); | ||
2598 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2599 | clist_append(list, addr); | ||
2600 | |||
2601 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
2602 | strdup("christophe@giaume.com")); | ||
2603 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2604 | clist_append(list, addr); | ||
2605 | |||
2606 | addr_list = mailimf_address_list_new(list); | ||
2607 | |||
2608 | to = mailimf_to_new(addr_list); | ||
2609 | /* do the things */ | ||
2610 | mailimf_to_free(to); | ||
2611 | |||
2612 | return 0; | ||
2613 | } | ||
2614 | |||
2615 | /* display To header */ | ||
2616 | |||
2617 | #include <libetpan/libetpan.h> | ||
2618 | |||
2619 | void display_to(struct mailimf_to * to) | ||
2620 | { | ||
2621 | display_address_list(to->to_addr_list); | ||
2622 | } | ||
2623 | </programlisting> | ||
2624 | </example> | ||
2625 | </sect2> | ||
2626 | |||
2627 | <!-- mailimf_cc --> | ||
2628 | <sect2 id="mailimf-cc"> | ||
2629 | <title>mailimf_cc - parsed content of Cc</title> | ||
2630 | |||
2631 | <programlisting> | ||
2632 | #include <libetpan/libetpan.h> | ||
2633 | |||
2634 | struct mailimf_cc { | ||
2635 | struct mailimf_address_list * cc_addr_list; /* != NULL */ | ||
2636 | }; | ||
2637 | |||
2638 | struct mailimf_cc * | ||
2639 | mailimf_cc_new(struct mailimf_address_list * cc_addr_list); | ||
2640 | |||
2641 | void mailimf_cc_free(struct mailimf_cc * cc); | ||
2642 | </programlisting> | ||
2643 | |||
2644 | <para> | ||
2645 | This is the content of a header <command>Cc</command> or | ||
2646 | <command>Resent-Cc</command>. | ||
2647 | </para> | ||
2648 | |||
2649 | <para> | ||
2650 | <command>cc_addr_list</command> is the parsed address list | ||
2651 | (see <xref linkend="mailimf-address-list">). | ||
2652 | </para> | ||
2653 | |||
2654 | <para> | ||
2655 | <command>mailimf_cc_new()</command> creates and initializes a | ||
2656 | data structure with a value. Structures given as argument | ||
2657 | are referenced by the created object and will be freed if | ||
2658 | the object is released. | ||
2659 | </para> | ||
2660 | |||
2661 | <para> | ||
2662 | <command>mailimf_cc_free()</command> This function frees | ||
2663 | memory used by the structure and substructures will also be | ||
2664 | released. | ||
2665 | </para> | ||
2666 | |||
2667 | <example> | ||
2668 | <title>creation and display of Cc field</title> | ||
2669 | <programlisting role="C"> | ||
2670 | #include <libetpan/libetpan.h> | ||
2671 | |||
2672 | int main(int argc, char ** argv) | ||
2673 | { | ||
2674 | clist * list; | ||
2675 | struct mailimf_mailbox * mb; | ||
2676 | struct mailimf_address * addr; | ||
2677 | struct mailimf_address_list * addr_list; | ||
2678 | struct mailimf_cc * cc; | ||
2679 | |||
2680 | list = clist_new(); | ||
2681 | |||
2682 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2683 | strdup("dinh.viet.hoa@free.fr")); | ||
2684 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2685 | clist_append(list, addr); | ||
2686 | |||
2687 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
2688 | strdup("christophe@giaume.com")); | ||
2689 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2690 | clist_append(list, addr); | ||
2691 | |||
2692 | addr_list = mailimf_address_list_new(list); | ||
2693 | |||
2694 | cc = mailimf_cc_new(addr_list); | ||
2695 | /* do the things */ | ||
2696 | mailimf_cc_free(cc); | ||
2697 | |||
2698 | return 0; | ||
2699 | } | ||
2700 | |||
2701 | /* display content of Cc field */ | ||
2702 | |||
2703 | #include <libetpan/libetpan.h> | ||
2704 | |||
2705 | void display_cc(struct mailimf_cc * cc) | ||
2706 | { | ||
2707 | display_address_list(cc->cc_addr_list); | ||
2708 | } | ||
2709 | |||
2710 | </programlisting> | ||
2711 | </example> | ||
2712 | |||
2713 | </sect2> | ||
2714 | |||
2715 | <!-- mailimf_bcc --> | ||
2716 | <sect2 id="mailimf-bcc"> | ||
2717 | <title>mailimf_bcc - parsed content of Bcc field</title> | ||
2718 | |||
2719 | <programlisting role="C"> | ||
2720 | #include <libetpan/libetpan.h> | ||
2721 | |||
2722 | struct mailimf_bcc { | ||
2723 | struct mailimf_address_list * bcc_addr_list; /* can be NULL */ | ||
2724 | }; | ||
2725 | |||
2726 | struct mailimf_bcc * | ||
2727 | mailimf_bcc_new(struct mailimf_address_list * bcc_addr_list); | ||
2728 | |||
2729 | void mailimf_bcc_free(struct mailimf_bcc * bcc); | ||
2730 | </programlisting> | ||
2731 | |||
2732 | <para> | ||
2733 | This is the content of a header <command>Bcc</command> or | ||
2734 | <command>Resent-Bcc</command>. | ||
2735 | </para> | ||
2736 | |||
2737 | <para> | ||
2738 | <command>bcc_addr_list</command> is the parsed address list | ||
2739 | (see <xref linkend="mailimf-address-list">). | ||
2740 | </para> | ||
2741 | |||
2742 | <para> | ||
2743 | <command>mailimf_bcc_new()</command> creates and initializes a | ||
2744 | data structure with a value. Structures given as argument | ||
2745 | are referenced by the created object and will be freed if | ||
2746 | the object is released. | ||
2747 | </para> | ||
2748 | |||
2749 | <para> | ||
2750 | <command>mailimf_bcc_free()</command> frees memory used by the | ||
2751 | structure and substructures will also be released. | ||
2752 | </para> | ||
2753 | |||
2754 | <example> | ||
2755 | <title>creation and display of Bcc field</title> | ||
2756 | <programlisting role="C"> | ||
2757 | /* create visible Bcc */ | ||
2758 | |||
2759 | #include <libetpan/libetpan.h> | ||
2760 | |||
2761 | int main(int argc, char ** argv) | ||
2762 | { | ||
2763 | clist * list; | ||
2764 | struct mailimf_mailbox * mb; | ||
2765 | struct mailimf_address * addr; | ||
2766 | struct mailimf_address_list * addr_list; | ||
2767 | struct mailimf_bcc * bcc; | ||
2768 | |||
2769 | list = clist_new(); | ||
2770 | |||
2771 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
2772 | strdup("dinh.viet.hoa@free.fr")); | ||
2773 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2774 | clist_append(list, addr); | ||
2775 | |||
2776 | mb = mailimf_mailbox_new(strdup("Christophe GIAUME"), | ||
2777 | strdup("christophe@giaume.com")); | ||
2778 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
2779 | clist_append(list, addr); | ||
2780 | |||
2781 | addr_list = mailimf_address_list_new(list); | ||
2782 | |||
2783 | bcc = mailimf_bcc_new(addr_list); | ||
2784 | /* do the things */ | ||
2785 | mailimf_bcc_free(bcc); | ||
2786 | |||
2787 | return 0; | ||
2788 | } | ||
2789 | |||
2790 | /* create unvisible Bcc */ | ||
2791 | |||
2792 | #include <libetpan/libetpan.h> | ||
2793 | |||
2794 | int main(int argc, char ** argv) | ||
2795 | { | ||
2796 | struct mailimf_bcc * bcc; | ||
2797 | |||
2798 | bcc = mailimf_bcc_new(NULL); | ||
2799 | /* do the things */ | ||
2800 | mailimf_bcc_free(bcc); | ||
2801 | |||
2802 | return 0; | ||
2803 | } | ||
2804 | |||
2805 | /* display content of Bcc field */ | ||
2806 | |||
2807 | #include <libetpan/libetpan.h> | ||
2808 | #include <stdio.h> | ||
2809 | |||
2810 | void display_bcc(struct mailimf_bcc * bcc) | ||
2811 | { | ||
2812 | if (bcc->addr_list == NULL) { | ||
2813 | printf("hidden Bcc\n"); | ||
2814 | } | ||
2815 | else { | ||
2816 | display_address_list(bcc->bcc_addr_list); | ||
2817 | } | ||
2818 | } | ||
2819 | </programlisting> | ||
2820 | </example> | ||
2821 | </sect2> | ||
2822 | |||
2823 | <!-- mailimf_message_id --> | ||
2824 | <sect2 id="mailimf-message-id"> | ||
2825 | <title>mailimf_message_id - parsed content of Message-ID header</title> | ||
2826 | |||
2827 | <programlisting role="C"> | ||
2828 | #include <libetpan/libetpan.h> | ||
2829 | |||
2830 | struct mailimf_message_id { | ||
2831 | char * mid_value; /* != NULL */ | ||
2832 | }; | ||
2833 | |||
2834 | struct mailimf_message_id * mailimf_message_id_new(char * mid_value); | ||
2835 | |||
2836 | void mailimf_message_id_free(struct mailimf_message_id * message_id); | ||
2837 | </programlisting> | ||
2838 | |||
2839 | <para> | ||
2840 | This is the content of a header <command>Message-ID</command> | ||
2841 | or <command>Resent-Message-ID</command>. For example : | ||
2842 | </para> | ||
2843 | |||
2844 | <example> | ||
2845 | <title>example of Message-ID</title> | ||
2846 | <programlisting> | ||
2847 | Message-ID: <200312100009.43592@c01n-c01n.plop.P4N>> | ||
2848 | </programlisting> | ||
2849 | </example> | ||
2850 | |||
2851 | <para> | ||
2852 | <command>mid_value</command> is the message identifier. | ||
2853 | It is not enclosed by angle bracket. | ||
2854 | </para> | ||
2855 | |||
2856 | <para> | ||
2857 | <command>mailimf_message_id_new()</command> This function | ||
2858 | creates and initializes a data structure with a value. | ||
2859 | Structures given as argument are referenced by the created | ||
2860 | object and will be freed if the object is released. | ||
2861 | </para> | ||
2862 | |||
2863 | <para> | ||
2864 | The given string is allocated with | ||
2865 | <command>malloc()</command> and is not enclosed by angle bracket. | ||
2866 | </para> | ||
2867 | |||
2868 | <para> | ||
2869 | <command>mailimf_message_id_free()</command> frees memory | ||
2870 | used by the structure and substructures will also be | ||
2871 | released. | ||
2872 | </para> | ||
2873 | |||
2874 | <example> | ||
2875 | <title>creation and display of Message-ID field</title> | ||
2876 | <programlisting role="C"> | ||
2877 | #include <libetpan/libetpan.h> | ||
2878 | |||
2879 | int main(int argc, char ** argv) | ||
2880 | { | ||
2881 | struct mailimf_message_id * msg_id; | ||
2882 | char * id; | ||
2883 | |||
2884 | id = strdup("1037197913.3dd26259752fa@imp.free.fr"); | ||
2885 | msg_id = mailimf_message_id_new(id); | ||
2886 | /* do the things */ | ||
2887 | mailimf_message_id_free(msg_id); | ||
2888 | |||
2889 | return 0; | ||
2890 | } | ||
2891 | |||
2892 | /* display message id */ | ||
2893 | |||
2894 | #include <libetpan/libetpan.h> | ||
2895 | #include <stdio.h> | ||
2896 | |||
2897 | void display_message_id(struct mailimf_message_id * msg_id) | ||
2898 | { | ||
2899 | printf("%s\n", msg_id->mid_value); | ||
2900 | } | ||
2901 | </programlisting> | ||
2902 | </example> | ||
2903 | </sect2> | ||
2904 | |||
2905 | <!-- mailimf_in_reply_to --> | ||
2906 | <sect2 id="mailimf-in-reply-to"> | ||
2907 | <title>mailimf_in_reply_to - parsed content of In-Reply-To | ||
2908 | field</title> | ||
2909 | |||
2910 | <programlisting role="C"> | ||
2911 | #include <libetpan/libetpan.h> | ||
2912 | |||
2913 | struct mailimf_in_reply_to { | ||
2914 | clist * mid_list; /* list of (char *), != NULL */ | ||
2915 | }; | ||
2916 | |||
2917 | struct mailimf_in_reply_to * mailimf_in_reply_to_new(clist * mid_list); | ||
2918 | |||
2919 | void mailimf_in_reply_to_free(struct mailimf_in_reply_to * in_reply_to); | ||
2920 | </programlisting> | ||
2921 | |||
2922 | <para> | ||
2923 | content of a header <command>In-Reply-To</command>. | ||
2924 | For example : | ||
2925 | </para> | ||
2926 | |||
2927 | <programlisting> | ||
2928 | In-Reply-To: <etPan.3fd5fa29.4c3901c1.6b39@homer> | ||
2929 | </programlisting> | ||
2930 | |||
2931 | <para> | ||
2932 | <command>mid_list</command> is a <command>clist</command> | ||
2933 | in which elements are message identifiers. | ||
2934 | their types are <command>(char *)</command> and they are | ||
2935 | allocated with <command>malloc()</command>. | ||
2936 | </para> | ||
2937 | |||
2938 | <para> | ||
2939 | <command>mailimf_in_reply_to_new()</command> creates and | ||
2940 | initializes a data structure with a value. Structures given | ||
2941 | as argument are referenced by the created object and will be | ||
2942 | freed if the object is released. | ||
2943 | </para> | ||
2944 | |||
2945 | <para> | ||
2946 | <command>mailimf_in_reply_to_free()</command> frees memory | ||
2947 | used by the structure and substructures will also be | ||
2948 | released. | ||
2949 | </para> | ||
2950 | |||
2951 | <example> | ||
2952 | <title>creation and display of In-Reply-To field</title> | ||
2953 | <programlisting> | ||
2954 | #include <libetpan/libetpan.h> | ||
2955 | |||
2956 | int main(int argc, char ** argv) | ||
2957 | { | ||
2958 | struct mailimf_in_reply_to * in_reply_to; | ||
2959 | clist * msg_id_list; | ||
2960 | |||
2961 | msg_id_list = clist_new(); | ||
2962 | clist_append(msg_id_list, | ||
2963 | strdup("etPan.3ebbcc18.4014197f.bc1@homer.invalid")); | ||
2964 | |||
2965 | in_reply_to = mailimf_in_reply_to_new(msg_id_list); | ||
2966 | /* do the things */ | ||
2967 | mailimf_in_reply_to_free(in_reply_to); | ||
2968 | |||
2969 | return 0; | ||
2970 | } | ||
2971 | |||
2972 | /* display the content of mailimf_in_reply_to */ | ||
2973 | |||
2974 | #include <libetpan/libetpan.h> | ||
2975 | #include <stdio.h> | ||
2976 | |||
2977 | void display_in_reply_to(struct mailimf_in_reply_to * in_reply_to) | ||
2978 | { | ||
2979 | clistiter * cur; | ||
2980 | |||
2981 | for(cur = clist_begin(in_reply_to->mid_list) ; cur != NULL ; | ||
2982 | cur = clist_next(cur)) { | ||
2983 | char * str; | ||
2984 | |||
2985 | str = clist_content(cur); | ||
2986 | |||
2987 | printf("%s\n", str); | ||
2988 | } | ||
2989 | } | ||
2990 | </programlisting> | ||
2991 | </example> | ||
2992 | </sect2> | ||
2993 | |||
2994 | <!-- mailimf_references --> | ||
2995 | <sect2 id="mailimf-references"> | ||
2996 | <title>mailimf_references - parsed content of References field</title> | ||
2997 | |||
2998 | <programlisting role="C"> | ||
2999 | #include <libetpan/libetpan.h> | ||
3000 | |||
3001 | struct mailimf_references { | ||
3002 | clist * mid_list; /* list of (char *) */ | ||
3003 | /* != NULL */ | ||
3004 | }; | ||
3005 | |||
3006 | struct mailimf_references * mailimf_references_new(clist * mid_list); | ||
3007 | |||
3008 | void mailimf_references_free(struct mailimf_references * references); | ||
3009 | </programlisting> | ||
3010 | |||
3011 | <para> | ||
3012 | This is the content of a header <command>References</command>. | ||
3013 | For example : | ||
3014 | </para> | ||
3015 | <programlisting> | ||
3016 | In-Reply-To: <etPan.3fd5fa29.4c3901c1.6b39@homer> | ||
3017 | <3FD5FA78.A1D98E7@oleane.net> | ||
3018 | <etPan.3fd5fc69.2b349482.730e@homer> | ||
3019 | </programlisting> | ||
3020 | |||
3021 | <para> | ||
3022 | <command>mid_list</command> is a <command>clist</command> | ||
3023 | in which elements are message identifiers. | ||
3024 | their types are <command>(char *)</command> and they are | ||
3025 | allocated with <command>malloc()</command>. | ||
3026 | </para> | ||
3027 | |||
3028 | <para> | ||
3029 | <command>mailimf_references_new()</command> creates and | ||
3030 | initializes a data structure with a value. Structures given | ||
3031 | as argument are referenced by the created object and will be | ||
3032 | freed if the object is released. | ||
3033 | </para> | ||
3034 | |||
3035 | <para> | ||
3036 | <command>mailimf_references_free()</command> frees memory | ||
3037 | used by the structure and substructures will also be | ||
3038 | released. | ||
3039 | </para> | ||
3040 | |||
3041 | <example> | ||
3042 | <title>creation and display of References field</title> | ||
3043 | <programlisting role="C"> | ||
3044 | #include <libetpan/libetpan.h> | ||
3045 | |||
3046 | int main(int argc, char ** argv) | ||
3047 | { | ||
3048 | struct mailimf_references * ref; | ||
3049 | clist * msg_id_list; | ||
3050 | |||
3051 | msg_id_list = clist_new(); | ||
3052 | clist_append(msg_id_list, | ||
3053 | strdup("200304280144.23633.wim.delvaux@adaptiveplanet.com")); | ||
3054 | clist_append(msg_id_list, | ||
3055 | strdup("200304301153.19688.wim.delvaux@adaptiveplanet.com")); | ||
3056 | clist_append(msg_id_list, | ||
3057 | strdup("etPan.3eb29de4.5fc4d652.3f83@homer")); | ||
3058 | |||
3059 | ref = mailimf_references_new(msg_id_list); | ||
3060 | /* do the things */ | ||
3061 | mailimf_in_reply_to_free(ref); | ||
3062 | |||
3063 | return 0; | ||
3064 | } | ||
3065 | |||
3066 | /* display references */ | ||
3067 | |||
3068 | #include <libetpan/libetpan.h> | ||
3069 | #include <stdio.h> | ||
3070 | |||
3071 | void display_references(struct mailimf_references * ref) | ||
3072 | { | ||
3073 | clistiter * cur; | ||
3074 | |||
3075 | for(cur = clist_begin(ref->mid_list) ; cur != NULL ; | ||
3076 | cur = clist_next(cur)) { | ||
3077 | char * msg_id; | ||
3078 | |||
3079 | msg_id = clist_content(cur); | ||
3080 | |||
3081 | printf("%s\n", msg_id); | ||
3082 | } | ||
3083 | } | ||
3084 | </programlisting> | ||
3085 | </example> | ||
3086 | </sect2> | ||
3087 | |||
3088 | <!-- mailimf_subject --> | ||
3089 | <sect2 id="mailimf-subject"> | ||
3090 | <title>mailimf_subject - parsed content of Subject field</title> | ||
3091 | |||
3092 | <programlisting role="C"> | ||
3093 | #include <libetpan/libetpan.h> | ||
3094 | |||
3095 | struct mailimf_subject { | ||
3096 | char * sbj_value; /* != NULL */ | ||
3097 | }; | ||
3098 | |||
3099 | struct mailimf_subject * mailimf_subject_new(char * sbj_value); | ||
3100 | |||
3101 | void mailimf_subject_free(struct mailimf_subject * subject); | ||
3102 | </programlisting> | ||
3103 | |||
3104 | <para> | ||
3105 | This is the content of a header <command>Subject</command>. | ||
3106 | </para> | ||
3107 | |||
3108 | <para> | ||
3109 | <command>sbj_value</command> is the value of the field. | ||
3110 | </para> | ||
3111 | |||
3112 | <para> | ||
3113 | <command>mailimf_subject_new()</command> creates and | ||
3114 | initializes a data structure with a value. | ||
3115 | Structures given as argument are referenced by the created | ||
3116 | object and will be freed if the object is released. | ||
3117 | </para> | ||
3118 | |||
3119 | <para> | ||
3120 | <command>mailimf_subject_free</command> frees memory used by | ||
3121 | the structure and substructures will also be released. | ||
3122 | </para> | ||
3123 | |||
3124 | <example> | ||
3125 | <title>creation and display of Subject field</title> | ||
3126 | <programlisting role="C"> | ||
3127 | #include <libetpan/libetpan.h> | ||
3128 | |||
3129 | int main(int argc, char ** argv) | ||
3130 | { | ||
3131 | struct mailimf_subject * subject; | ||
3132 | |||
3133 | subject = mailimf_subject_new(strdup("example of subject")); | ||
3134 | /* do the things */ | ||
3135 | mailimf_subject_free(subject); | ||
3136 | |||
3137 | return 0; | ||
3138 | } | ||
3139 | |||
3140 | /* display subject header */ | ||
3141 | |||
3142 | #include <libetpan/libetpan.h> | ||
3143 | #include <stdio.h> | ||
3144 | |||
3145 | void display_subject(struct mailimf_subject * subject) | ||
3146 | { | ||
3147 | printf("%s\n", subject->value); | ||
3148 | } | ||
3149 | </programlisting> | ||
3150 | </example> | ||
3151 | </sect2> | ||
3152 | |||
3153 | <!-- mailimf_comments --> | ||
3154 | <sect2 id="mailimf-comments"> | ||
3155 | <title>mailimf_comments - parsed content of Comments field</title> | ||
3156 | |||
3157 | <programlisting role="C"> | ||
3158 | #include <libetpan/libetpan.h> | ||
3159 | |||
3160 | struct mailimf_comments { | ||
3161 | char * cm_value; /* != NULL */ | ||
3162 | }; | ||
3163 | |||
3164 | struct mailimf_comments * mailimf_comments_new(char * cm_value); | ||
3165 | |||
3166 | void mailimf_comments_free(struct mailimf_comments * comments); | ||
3167 | </programlisting> | ||
3168 | |||
3169 | <para> | ||
3170 | This is the content of a header <command>Comments</command>. | ||
3171 | </para> | ||
3172 | |||
3173 | <para> | ||
3174 | <command>cm_value</command> is the value of the field. | ||
3175 | </para> | ||
3176 | |||
3177 | <para> | ||
3178 | <command>mailimf_comments_new()</command> creates and | ||
3179 | initializes a data structure with a value. | ||
3180 | Structures given as argument are referenced by the created | ||
3181 | object and will be freed if the object is released. | ||
3182 | </para> | ||
3183 | |||
3184 | <para> | ||
3185 | <command>mailimf_comments_free()</command> frees memory used | ||
3186 | by the structure and substructures will also be released. | ||
3187 | </para> | ||
3188 | |||
3189 | <example> | ||
3190 | <title>creation and display of Comment field</title> | ||
3191 | <programlisting role="C"> | ||
3192 | #include <libetpan/libetpan.h> | ||
3193 | |||
3194 | int main(int argc, char ** argv) | ||
3195 | { | ||
3196 | struct mailimf_comments * comments; | ||
3197 | |||
3198 | comments = mailimf_comments_new(strdup("example of comment")); | ||
3199 | /* do the things */ | ||
3200 | mailimf_comments_free(comments); | ||
3201 | |||
3202 | return 0; | ||
3203 | } | ||
3204 | |||
3205 | /* display the content of a comments */ | ||
3206 | |||
3207 | #include <libetpan/libetpan.h> | ||
3208 | #include <stdio.h> | ||
3209 | |||
3210 | void display_comments(struct mailimf_comments * comments) | ||
3211 | { | ||
3212 | printf("%s\n", comments->cm_value); | ||
3213 | } | ||
3214 | </programlisting> | ||
3215 | </example> | ||
3216 | </sect2> | ||
3217 | |||
3218 | <!-- mailimf_keywords --> | ||
3219 | <sect2 id="mailimf-keywords"> | ||
3220 | <title>mailimf_keywords - parsed content of Keywords field</title> | ||
3221 | |||
3222 | <programlisting role="C"> | ||
3223 | #include <libetpan/libetpan.h> | ||
3224 | |||
3225 | struct mailimf_keywords { | ||
3226 | clist * kw_list; /* list of (char *), != NULL */ | ||
3227 | }; | ||
3228 | |||
3229 | struct mailimf_keywords * mailimf_keywords_new(clist * kw_list); | ||
3230 | |||
3231 | void mailimf_keywords_free(struct mailimf_keywords * keywords); | ||
3232 | </programlisting> | ||
3233 | |||
3234 | <para> | ||
3235 | This is the content of a header <command>Keywords</command>. | ||
3236 | </para> | ||
3237 | |||
3238 | <para> | ||
3239 | <command>kw_list</command> is the list of keywords. This is | ||
3240 | a list of <command>(char *)</command> allocated with malloc(). | ||
3241 | </para> | ||
3242 | |||
3243 | <para> | ||
3244 | <command>mailimf_keywords_new()</command> creates and | ||
3245 | initializes a data structure with a value. | ||
3246 | Structures given as argument are referenced by the created | ||
3247 | object and will be freed if the object is released. | ||
3248 | </para> | ||
3249 | |||
3250 | <para> | ||
3251 | <command>mailimf_keywords_free()</command> frees memory used | ||
3252 | by the structure and substructures will also be released. | ||
3253 | </para> | ||
3254 | |||
3255 | <example> | ||
3256 | <title>creation and display of Keywords field</title> | ||
3257 | <programlisting role="C"> | ||
3258 | #include <libetpan/libetpan.h> | ||
3259 | |||
3260 | int main(int argc, char ** argv) | ||
3261 | { | ||
3262 | struct mailimf_keywords * keywords; | ||
3263 | clist * list; | ||
3264 | |||
3265 | list = clist_new(); | ||
3266 | clist_append(list, strdup("sauerkraut")); | ||
3267 | clist_append(list, strdup("potatoes")); | ||
3268 | clist_append(list, strdup("cooking")); | ||
3269 | |||
3270 | keywords = mailimf_keywords_new(list); | ||
3271 | /* do the things */ | ||
3272 | mailimf_keywords_free(keywords); | ||
3273 | |||
3274 | return 0; | ||
3275 | } | ||
3276 | |||
3277 | /* display the content of mailimf_in_reply_to */ | ||
3278 | |||
3279 | #include <libetpan/libetpan.h> | ||
3280 | #include <stdio.h> | ||
3281 | |||
3282 | void display_keywords(struct mailimf_keywords * kw) | ||
3283 | { | ||
3284 | clistiter * cur; | ||
3285 | |||
3286 | for(cur = clist_begin(kw->kw_list) ; cur != NULL ; | ||
3287 | cur = clist_next(cur)) { | ||
3288 | char * str; | ||
3289 | |||
3290 | str = clist_content(cur); | ||
3291 | |||
3292 | printf("%s\n", str); | ||
3293 | } | ||
3294 | } | ||
3295 | </programlisting> | ||
3296 | </example> | ||
3297 | </sect2> | ||
3298 | |||
3299 | <!-- mailimf_return --> | ||
3300 | <sect2 id="mailimf-return"> | ||
3301 | <title>mailimf_return - parsed content of Return-Path field</title> | ||
3302 | |||
3303 | <programlisting role="C"> | ||
3304 | #include <libetpan/libetpan.h> | ||
3305 | |||
3306 | struct mailimf_return { | ||
3307 | struct mailimf_path * ret_path; /* != NULL */ | ||
3308 | }; | ||
3309 | |||
3310 | struct mailimf_return * | ||
3311 | mailimf_return_new(struct mailimf_path * ret_path); | ||
3312 | |||
3313 | void mailimf_return_free(struct mailimf_return * return_path); | ||
3314 | </programlisting> | ||
3315 | |||
3316 | <para> | ||
3317 | This is the content of a header | ||
3318 | <command>Return-Path</command>. | ||
3319 | </para> | ||
3320 | |||
3321 | <para> | ||
3322 | <command>ret_path</command> is the parsed value of Return-Path | ||
3323 | (see <xref linkend="mailimf-path">). | ||
3324 | </para> | ||
3325 | |||
3326 | <para> | ||
3327 | <command>mailimf_return_new()</command> creates and | ||
3328 | initializes a data structure with a value. | ||
3329 | Structures given as argument are referenced by the created | ||
3330 | object and will be freed if the object is released. | ||
3331 | </para> | ||
3332 | |||
3333 | <para> | ||
3334 | <command>mailimf_return_free()</command> frees memory used | ||
3335 | by the structure and substructures will also be released. | ||
3336 | </para> | ||
3337 | |||
3338 | <example> | ||
3339 | <title>creation and display of Return-Path field</title> | ||
3340 | <programlisting role="C"> | ||
3341 | #include <libetpan/libetpan.h> | ||
3342 | |||
3343 | int main(int argc, char ** argv) | ||
3344 | { | ||
3345 | struct mailimf_path * path; | ||
3346 | struct mailimf_return * r; | ||
3347 | |||
3348 | path = mailimf_path_new(strdup("dinh.viet.hoa@free.fr")); | ||
3349 | r = mailimf_return_new(path); | ||
3350 | /* do the things */ | ||
3351 | mailimf_return_free(r); | ||
3352 | |||
3353 | return 0; | ||
3354 | } | ||
3355 | |||
3356 | /* display return path */ | ||
3357 | |||
3358 | #include <libetpan/libetpan.h> | ||
3359 | |||
3360 | void display_return(struct mailimf_return * r) | ||
3361 | { | ||
3362 | display_path(r->ret_path); | ||
3363 | } | ||
3364 | </programlisting> | ||
3365 | </example> | ||
3366 | </sect2> | ||
3367 | |||
3368 | <!-- mailimf_path --> | ||
3369 | <sect2 id="mailimf-path"> | ||
3370 | <title>mailimf_path - address in Return-Path field</title> | ||
3371 | |||
3372 | <programlisting role="C"> | ||
3373 | #include <libetpan/libetpan.h> | ||
3374 | |||
3375 | struct mailimf_path { | ||
3376 | char * pt_addr_spec; /* can be NULL */ | ||
3377 | }; | ||
3378 | |||
3379 | struct mailimf_path * mailimf_path_new(char * pt_addr_spec); | ||
3380 | |||
3381 | void mailimf_path_free(struct mailimf_path * path); | ||
3382 | </programlisting> | ||
3383 | |||
3384 | <para> | ||
3385 | This is the encapsulation of address specifier for | ||
3386 | <command>Return-Path</command> content. | ||
3387 | </para> | ||
3388 | |||
3389 | <para> | ||
3390 | <command>pt_addr_spec</command> is a mailbox destination. | ||
3391 | </para> | ||
3392 | |||
3393 | <para> | ||
3394 | <command>mailimf_path_new()</command> creates and | ||
3395 | initializes a data structure with a value. | ||
3396 | Structures given as argument are referenced by the created | ||
3397 | object and will be freed if the object is released. | ||
3398 | </para> | ||
3399 | |||
3400 | <para> | ||
3401 | The given string is allocated with | ||
3402 | <command>malloc()</command>. This is a address | ||
3403 | specifier. | ||
3404 | </para> | ||
3405 | |||
3406 | <para> | ||
3407 | <command>mailimf_path_free()</command> frees memory used by | ||
3408 | the structure and substructures will also be released. | ||
3409 | </para> | ||
3410 | |||
3411 | <example> | ||
3412 | <title>Creation and display of return path</title> | ||
3413 | <programlisting role="C"> | ||
3414 | #include <libetpan/libetpan.h> | ||
3415 | |||
3416 | int main(int argc, char ** argv) | ||
3417 | { | ||
3418 | struct mailimf_path * path; | ||
3419 | |||
3420 | path = mailimf_path_new(strdup("dinh.viet.hoa@free.fr")); | ||
3421 | /* do the things */ | ||
3422 | mailimf_path_free(r); | ||
3423 | |||
3424 | return 0; | ||
3425 | } | ||
3426 | |||
3427 | /* display return path */ | ||
3428 | |||
3429 | #include <libetpan/libetpan.h> | ||
3430 | #include <stdio.h> | ||
3431 | |||
3432 | void display_path(struct mailimf_path * path) | ||
3433 | { | ||
3434 | printf("%s\n", path->pt_addr_spec); | ||
3435 | } | ||
3436 | </programlisting> | ||
3437 | </example> | ||
3438 | </sect2> | ||
3439 | |||
3440 | <!-- mailimf_optional_field --> | ||
3441 | <sect2 id="mailimf-optional-field"> | ||
3442 | <title>mailimf_optional_field - non-standard header</title> | ||
3443 | |||
3444 | <programlisting> | ||
3445 | #include <libetpan/libetpan.h> | ||
3446 | |||
3447 | struct mailimf_optional_field { | ||
3448 | char * fld_name; /* != NULL */ | ||
3449 | char * fld_value; /* != NULL */ | ||
3450 | }; | ||
3451 | |||
3452 | struct mailimf_optional_field * | ||
3453 | mailimf_optional_field_new(char * fld_name, char * fld_value); | ||
3454 | |||
3455 | void mailimf_optional_field_free(struct mailimf_optional_field * opt_field); | ||
3456 | </programlisting> | ||
3457 | |||
3458 | <para> | ||
3459 | This is a non-standard header or unparsed header. | ||
3460 | </para> | ||
3461 | |||
3462 | <itemizedlist> | ||
3463 | <listitem> | ||
3464 | <para> | ||
3465 | <command>fld_name</command> is the name of the header | ||
3466 | field. | ||
3467 | </para> | ||
3468 | </listitem> | ||
3469 | <listitem> | ||
3470 | <para> | ||
3471 | <command>fld_value</command> is the value of the header | ||
3472 | field. | ||
3473 | </para> | ||
3474 | </listitem> | ||
3475 | </itemizedlist> | ||
3476 | |||
3477 | <para> | ||
3478 | <command>mailimf_optional_field_new()</command> This | ||
3479 | function creates and initializes a data structure with a | ||
3480 | value. Structures given as argument are referenced by the | ||
3481 | created object and will be freed if the object is released. | ||
3482 | </para> | ||
3483 | |||
3484 | <para> | ||
3485 | field name and field value have to be allocated with | ||
3486 | <command>malloc()</command>. | ||
3487 | </para> | ||
3488 | |||
3489 | <para> | ||
3490 | <command>mailimf_optional_field_free()</command> This | ||
3491 | function frees memory used by the structure and | ||
3492 | substructures will also be released. | ||
3493 | </para> | ||
3494 | |||
3495 | <example> | ||
3496 | <title>creation and display of non-standard fields</title> | ||
3497 | <programlisting role="C"> | ||
3498 | #include <libetpan/libetpan.h> | ||
3499 | |||
3500 | int main(int argc, char ** argv) | ||
3501 | { | ||
3502 | struct mailimf_optional_field * opt; | ||
3503 | |||
3504 | opt = mailimf_optional_field_new(strdup("X-My-Field"), strdup("my value")); | ||
3505 | /* do the things */ | ||
3506 | mailimf_optional_field_free(opt); | ||
3507 | |||
3508 | return 0; | ||
3509 | } | ||
3510 | |||
3511 | /* display the optional field */ | ||
3512 | |||
3513 | #include <libetpan/libetpan.h> | ||
3514 | #include <stdio.h> | ||
3515 | |||
3516 | void display_optional_field(struct mailimf_optional_field * opt) | ||
3517 | { | ||
3518 | printf("%s: %s\n", opt->fld_name, opt->fld_value); | ||
3519 | } | ||
3520 | </programlisting> | ||
3521 | </example> | ||
3522 | </sect2> | ||
3523 | |||
3524 | <!-- mailimf_field --> | ||
3525 | <sect2 id="mailimf-field"> | ||
3526 | <title>mailimf_field - header field</title> | ||
3527 | |||
3528 | <programlisting role="C"> | ||
3529 | #include <libetpan/libetpan.h> | ||
3530 | |||
3531 | enum { | ||
3532 | MAILIMF_FIELD_NONE, /* on parse error */ | ||
3533 | MAILIMF_FIELD_RETURN_PATH, /* Return-Path */ | ||
3534 | MAILIMF_FIELD_RESENT_DATE, /* Resent-Date */ | ||
3535 | MAILIMF_FIELD_RESENT_FROM, /* Resent-From */ | ||
3536 | MAILIMF_FIELD_RESENT_SENDER, /* Resent-Sender */ | ||
3537 | MAILIMF_FIELD_RESENT_TO, /* Resent-To */ | ||
3538 | MAILIMF_FIELD_RESENT_CC, /* Resent-Cc */ | ||
3539 | MAILIMF_FIELD_RESENT_BCC, /* Resent-Bcc */ | ||
3540 | MAILIMF_FIELD_RESENT_MSG_ID, /* Resent-Message-ID */ | ||
3541 | MAILIMF_FIELD_ORIG_DATE, /* Date */ | ||
3542 | MAILIMF_FIELD_FROM, /* From */ | ||
3543 | MAILIMF_FIELD_SENDER, /* Sender */ | ||
3544 | MAILIMF_FIELD_REPLY_TO, /* Reply-To */ | ||
3545 | MAILIMF_FIELD_TO, /* To */ | ||
3546 | MAILIMF_FIELD_CC, /* Cc */ | ||
3547 | MAILIMF_FIELD_BCC, /* Bcc */ | ||
3548 | MAILIMF_FIELD_MESSAGE_ID, /* Message-ID */ | ||
3549 | MAILIMF_FIELD_IN_REPLY_TO, /* In-Reply-To */ | ||
3550 | MAILIMF_FIELD_REFERENCES, /* References */ | ||
3551 | MAILIMF_FIELD_SUBJECT, /* Subject */ | ||
3552 | MAILIMF_FIELD_COMMENTS, /* Comments */ | ||
3553 | MAILIMF_FIELD_KEYWORDS, /* Keywords */ | ||
3554 | MAILIMF_FIELD_OPTIONAL_FIELD, /* other field */ | ||
3555 | }; | ||
3556 | |||
3557 | struct mailimf_field { | ||
3558 | int fld_type; | ||
3559 | union { | ||
3560 | struct mailimf_return * fld_return_path; /* can be NULL */ | ||
3561 | struct mailimf_orig_date * fld_resent_date; /* can be NULL */ | ||
3562 | struct mailimf_from * fld_resent_from; /* can be NULL */ | ||
3563 | struct mailimf_sender * fld_resent_sender; /* can be NULL */ | ||
3564 | struct mailimf_to * fld_resent_to; /* can be NULL */ | ||
3565 | struct mailimf_cc * fld_resent_cc; /* can be NULL */ | ||
3566 | struct mailimf_bcc * fld_resent_bcc; /* can be NULL */ | ||
3567 | struct mailimf_message_id * fld_resent_msg_id; /* can be NULL */ | ||
3568 | struct mailimf_orig_date * fld_orig_date; /* can be NULL */ | ||
3569 | struct mailimf_from * fld_from; /* can be NULL */ | ||
3570 | struct mailimf_sender * fld_sender; /* can be NULL */ | ||
3571 | struct mailimf_reply_to * fld_reply_to; /* can be NULL */ | ||
3572 | struct mailimf_to * fld_to; /* can be NULL */ | ||
3573 | struct mailimf_cc * fld_cc; /* can be NULL */ | ||
3574 | struct mailimf_bcc * fld_bcc; /* can be NULL */ | ||
3575 | struct mailimf_message_id * fld_message_id; /* can be NULL */ | ||
3576 | struct mailimf_in_reply_to * fld_in_reply_to; /* can be NULL */ | ||
3577 | struct mailimf_references * fld_references; /* can be NULL */ | ||
3578 | struct mailimf_subject * fld_subject; /* can be NULL */ | ||
3579 | struct mailimf_comments * fld_comments; /* can be NULL */ | ||
3580 | struct mailimf_keywords * fld_keywords; /* can be NULL */ | ||
3581 | struct mailimf_optional_field * fld_optional_field; /* can be NULL */ | ||
3582 | } fld_data; | ||
3583 | }; | ||
3584 | |||
3585 | struct mailimf_field * | ||
3586 | mailimf_field_new(int fld_type, | ||
3587 | struct mailimf_return * fld_return_path, | ||
3588 | struct mailimf_orig_date * fld_resent_date, | ||
3589 | struct mailimf_from * fld_resent_from, | ||
3590 | struct mailimf_sender * fld_resent_sender, | ||
3591 | struct mailimf_to * fld_resent_to, | ||
3592 | struct mailimf_cc * fld_resent_cc, | ||
3593 | struct mailimf_bcc * fld_resent_bcc, | ||
3594 | struct mailimf_message_id * fld_resent_msg_id, | ||
3595 | struct mailimf_orig_date * fld_orig_date, | ||
3596 | struct mailimf_from * fld_from, | ||
3597 | struct mailimf_sender * fld_sender, | ||
3598 | struct mailimf_reply_to * fld_reply_to, | ||
3599 | struct mailimf_to * fld_to, | ||
3600 | struct mailimf_cc * fld_cc, | ||
3601 | struct mailimf_bcc * fld_bcc, | ||
3602 | struct mailimf_message_id * fld_message_id, | ||
3603 | struct mailimf_in_reply_to * fld_in_reply_to, | ||
3604 | struct mailimf_references * fld_references, | ||
3605 | struct mailimf_subject * fld_subject, | ||
3606 | struct mailimf_comments * fld_comments, | ||
3607 | struct mailimf_keywords * fld_keywords, | ||
3608 | struct mailimf_optional_field * fld_optional_field); | ||
3609 | |||
3610 | void mailimf_field_free(struct mailimf_field * field); | ||
3611 | </programlisting> | ||
3612 | |||
3613 | <para> | ||
3614 | This is one header field of a message. | ||
3615 | </para> | ||
3616 | |||
3617 | <itemizedlist> | ||
3618 | <listitem> | ||
3619 | <para> | ||
3620 | <command>type</command> is the type of the field. This define the | ||
3621 | type of the field. | ||
3622 | Only the corresponding field should be, then, | ||
3623 | filled. The value of this field can be one of : | ||
3624 | <command>MAILIMF_FIELD_RETURN_PATH</command>, | ||
3625 | <command>MAILIMF_FIELD_RESENT_DATE</command>, | ||
3626 | <command>MAILIMF_FIELD_RESENT_FROM</command>, | ||
3627 | <command>MAILIMF_FIELD_RESENT_SENDER</command>, | ||
3628 | <command>MAILIMF_FIELD_RESENT_TO</command>, | ||
3629 | <command>MAILIMF_FIELD_RESENT_CC</command>, | ||
3630 | <command>MAILIMF_FIELD_RESENT_BCC</command>, | ||
3631 | <command>MAILIMF_FIELD_RESENT_MSG_ID</command>, | ||
3632 | <command>MAILIMF_FIELD_ORIG_DATE</command>, | ||
3633 | <command>MAILIMF_FIELD_FROM</command>, | ||
3634 | <command>MAILIMF_FIELD_SENDER</command>, | ||
3635 | <command>MAILIMF_FIELD_REPLY_TO</command>, | ||
3636 | <command>MAILIMF_FIELD_TO</command>, | ||
3637 | <command>MAILIMF_FIELD_CC</command>, | ||
3638 | <command>MAILIMF_FIELD_BCC</command>, | ||
3639 | <command>MAILIMF_FIELD_MESSAGE_ID</command>, | ||
3640 | <command>MAILIMF_FIELD_IN_REPLY_TO</command>, | ||
3641 | <command>MAILIMF_FIELD_REFERENCES</command>, | ||
3642 | <command>MAILIMF_FIELD_SUBJECT</command>, | ||
3643 | <command>MAILIMF_FIELD_COMMENTS</command>, | ||
3644 | <command>MAILIMF_FIELD_KEYWORDS</command>, | ||
3645 | <command>MAILIMF_FIELD_OPTIONAL_FIELD</command>. | ||
3646 | </para> | ||
3647 | </listitem> | ||
3648 | <listitem> | ||
3649 | <para> | ||
3650 | <command>fld_data.fld_return_path</command> is the | ||
3651 | parsed content of the Return-Path field | ||
3652 | if type is <command>MAILIMF_FIELD_RETURN_PATH</command> | ||
3653 | (see <xref linkend="mailimf-return">). | ||
3654 | </para> | ||
3655 | </listitem> | ||
3656 | <listitem> | ||
3657 | <para> | ||
3658 | <command>fld_data.fld_resent_date</command> is the | ||
3659 | parsed content of the Resent-Date field | ||
3660 | if type is <command>MAILIMF_FIELD_RESENT_DATE</command> | ||
3661 | (see <xref linkend="mailimf-orig-date">). | ||
3662 | </para> | ||
3663 | </listitem> | ||
3664 | <listitem> | ||
3665 | <para> | ||
3666 | <command>fld_data.fld_resent_from</command> is the | ||
3667 | parsed content of the Resent-From field | ||
3668 | if type is <command>MAILIMF_FIELD_RESENT_FROM</command> | ||
3669 | (see <xref linkend="mailimf-from">). | ||
3670 | </para> | ||
3671 | </listitem> | ||
3672 | <listitem> | ||
3673 | <para> | ||
3674 | <command>fld_data.fld_resent_sender</command> is the | ||
3675 | parsed content of the Resent-Sender field | ||
3676 | if type is <command>MAILIMF_FIELD_RESENT_SENDER</command> | ||
3677 | (see <xref linkend="mailimf-sender">). | ||
3678 | </para> | ||
3679 | </listitem> | ||
3680 | <listitem> | ||
3681 | <para> | ||
3682 | <command>fld_data.fld_resent_to</command> is the parsed | ||
3683 | content of the Resent-To field | ||
3684 | if type is <command>MAILIMF_FIELD_RESENT_TO</command> | ||
3685 | (see <xref linkend="mailimf-to">). | ||
3686 | </para> | ||
3687 | </listitem> | ||
3688 | <listitem> | ||
3689 | <para> | ||
3690 | <command>fld_data.fld_resent_cc</command> is the parsed | ||
3691 | content of the Resent-Cc field | ||
3692 | if type is <command>MAILIMF_FIELD_CC</command> | ||
3693 | (see <xref linkend="mailimf-cc">). | ||
3694 | </para> | ||
3695 | </listitem> | ||
3696 | <listitem> | ||
3697 | <para> | ||
3698 | <command>fld_data.fld_resent_bcc</command> is the parsed | ||
3699 | content of the Resent-Bcc field | ||
3700 | if type is <command>MAILIMF_FIELD_BCC</command> | ||
3701 | (see <xref linkend="mailimf-bcc">). | ||
3702 | </para> | ||
3703 | </listitem> | ||
3704 | <listitem> | ||
3705 | <para> | ||
3706 | <command>fld_data.fld_resent_msg_id</command> is the | ||
3707 | parsed content of the Resent-Message-ID field | ||
3708 | if type is <command>MAILIMF_FIELD_RESENT_MSG_ID</command> | ||
3709 | (see <xref linkend="mailimf-message-id">). | ||
3710 | </para> | ||
3711 | </listitem> | ||
3712 | <listitem> | ||
3713 | <para> | ||
3714 | <command>fld_data.fld_orig_date</command> is the parsed | ||
3715 | content of the Date field | ||
3716 | if type is <command>MAILIMF_FIELD_ORIG_DATE</command> | ||
3717 | (see <xref linkend="mailimf-orig-date">). | ||
3718 | </para> | ||
3719 | </listitem> | ||
3720 | <listitem> | ||
3721 | <para> | ||
3722 | <command>fld_data.fld_from</command> is the parsed | ||
3723 | content of the From field | ||
3724 | if type is <command>MAILIMF_FIELD_FROM</command> | ||
3725 | (see <xref linkend="mailimf-from">). | ||
3726 | </para> | ||
3727 | </listitem> | ||
3728 | <listitem> | ||
3729 | <para> | ||
3730 | <command>fld_data.fld_sender</command> is the parsed | ||
3731 | content of the Sender field | ||
3732 | if type is <command>MAILIMF_FIELD_SENDER</command> | ||
3733 | (see <xref linkend="mailimf-sender">). | ||
3734 | </para> | ||
3735 | </listitem> | ||
3736 | <listitem> | ||
3737 | <para> | ||
3738 | <command>fld_data.fld_reply_to</command> is the parsed | ||
3739 | content of the Reply-To field | ||
3740 | if type is <command>MAILIMF_FIELD_REPLY_TO</command> | ||
3741 | (see <xref linkend="mailimf-reply-to">). | ||
3742 | </para> | ||
3743 | </listitem> | ||
3744 | <listitem> | ||
3745 | <para> | ||
3746 | <command>fld_data.fld_to</command> is the parsed content | ||
3747 | of the To field if type is | ||
3748 | <command>MAILIMF_FIELD_TO</command> | ||
3749 | (see <xref linkend="mailimf-to">). | ||
3750 | </para> | ||
3751 | </listitem> | ||
3752 | <listitem> | ||
3753 | <para> | ||
3754 | <command>fld_data.fld_cc</command> is the parsed content | ||
3755 | of the Cc field if type is | ||
3756 | <command>MAILIMF_FIELD_CC</command> | ||
3757 | (see <xref linkend="mailimf-cc">). | ||
3758 | </para> | ||
3759 | </listitem> | ||
3760 | <listitem> | ||
3761 | <para> | ||
3762 | <command>fld_data.fld_bcc</command> is the parsed | ||
3763 | content of the Bcc field if type is | ||
3764 | <command>MAILIMF_FIELD_BCC</command> | ||
3765 | (see <xref linkend="mailimf-bcc">). | ||
3766 | </para> | ||
3767 | </listitem> | ||
3768 | <listitem> | ||
3769 | <para> | ||
3770 | <command>fld_data.fld_message_id</command> is the parsed | ||
3771 | content of the Message-ID field | ||
3772 | if type is <command>MAILIMF_FIELD_MESSAGE_ID</command> | ||
3773 | (see <xref linkend="mailimf-message-id">). | ||
3774 | </para> | ||
3775 | </listitem> | ||
3776 | <listitem> | ||
3777 | <para> | ||
3778 | <command>fld_data.fld_in_reply_to</command> is the | ||
3779 | parsed content of the In-Reply-To field | ||
3780 | if type is <command>MAILIMF_FIELD_IN_REPLY_TO</command> | ||
3781 | (see <xref linkend="mailimf-in-reply-to">). | ||
3782 | </para> | ||
3783 | </listitem> | ||
3784 | <listitem> | ||
3785 | <para> | ||
3786 | <command>fld_data.fld_references</command> is the parsed | ||
3787 | content of the References field | ||
3788 | if type is <command>MAILIMF_FIELD_REFERENCES</command> | ||
3789 | (see <xref linkend="mailimf-references">). | ||
3790 | </para> | ||
3791 | </listitem> | ||
3792 | <listitem> | ||
3793 | <para> | ||
3794 | <command>fld_data.fld_subject</command> is the content | ||
3795 | of the Subject field | ||
3796 | if type is <command>MAILIMF_FIELD_SUBJECT</command> | ||
3797 | (see <xref linkend="mailimf-subject">). | ||
3798 | </para> | ||
3799 | </listitem> | ||
3800 | <listitem> | ||
3801 | <para> | ||
3802 | <command>fld_data.fld_comments</command> is the content of the | ||
3803 | Comments field | ||
3804 | if type is <command>MAILIMF_FIELD_COMMENTS</command> | ||
3805 | (see <xref linkend="mailimf-comments">). | ||
3806 | </para> | ||
3807 | </listitem> | ||
3808 | <listitem> | ||
3809 | <para> | ||
3810 | <command>fld_data.fld_keywords</command> is the parsed | ||
3811 | content of the Keywords field | ||
3812 | if type is <command>MAILIMF_FIELD_KEYWORDS</command> | ||
3813 | (see <xref linkend="mailimf-keywords">). | ||
3814 | </para> | ||
3815 | </listitem> | ||
3816 | <listitem> | ||
3817 | <para> | ||
3818 | <command>fld_data.fld_optional_field</command> is an | ||
3819 | other field and is not parsed | ||
3820 | if type is <command>MAILIMF_FIELD_OPTIONAL_FIELD</command> | ||
3821 | (see <xref linkend="mailimf-optional-field">). | ||
3822 | </para> | ||
3823 | </listitem> | ||
3824 | </itemizedlist> | ||
3825 | |||
3826 | <para> | ||
3827 | <command>mailimf_field_new()</command> creates and | ||
3828 | initializes a data structure with a value. | ||
3829 | Structures given as argument are referenced by the created | ||
3830 | object and will be freed if the object is released. | ||
3831 | </para> | ||
3832 | |||
3833 | <para> | ||
3834 | <command>mailimf_field_free()</command> frees memory used by | ||
3835 | the structure and substructures will also be released. | ||
3836 | </para> | ||
3837 | |||
3838 | <example> | ||
3839 | <title>creation and display of field</title> | ||
3840 | <programlisting role="C"> | ||
3841 | #include <libetpan/libetpan.h> | ||
3842 | |||
3843 | int main(int argc, char ** argv) | ||
3844 | { | ||
3845 | struct mailimf_field * f; | ||
3846 | struct mailimf_mailbox * mb; | ||
3847 | struct mailimf_mailbox_list * mb_list; | ||
3848 | struct mailimf_from * from; | ||
3849 | |||
3850 | /* build header 'From' */ | ||
3851 | |||
3852 | list = clist_new(); | ||
3853 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
3854 | strdup("dinh.viet.hoa@free.fr")); | ||
3855 | clist_append(list, mb); | ||
3856 | mb_list = mailimf_mailbox_list_new(list); | ||
3857 | |||
3858 | from = mailimf_from_new(mb_list); | ||
3859 | |||
3860 | f = mailimf_field_new(MAILIMF_FIELD_FROM, | ||
3861 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
3862 | from, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
3863 | NULL, NULL, NULL, NULL); | ||
3864 | /* do the things */ | ||
3865 | mailimf_field_free(f); | ||
3866 | |||
3867 | return 0; | ||
3868 | } | ||
3869 | |||
3870 | /* display content of the header */ | ||
3871 | |||
3872 | #include <libetpan/libetpan.h> | ||
3873 | #include <stdio.h> | ||
3874 | |||
3875 | void display_field(struct mailimf_field * field) | ||
3876 | { | ||
3877 | switch (field->type) { | ||
3878 | case MAILIMF_FIELD_RETURN_PATH: | ||
3879 | printf("Return-Path:\n"); | ||
3880 | display_return(field->fld_data.fld_return_path); | ||
3881 | break; | ||
3882 | case MAILIMF_FIELD_RESENT_DATE: | ||
3883 | printf("Resent-Date:\n"); | ||
3884 | display_orig_date(field->fld_data.fld_orig_date); | ||
3885 | break; | ||
3886 | case MAILIMF_FIELD_RESENT_FROM: | ||
3887 | printf("Resent-From:\n"); | ||
3888 | display_from(field->fld_data.fld_orig_date); | ||
3889 | break; | ||
3890 | case MAILIMF_FIELD_RESENT_SENDER: | ||
3891 | printf("Resent-Sender:\n"); | ||
3892 | display_sender(field->fld_data.fld_resent_sender); | ||
3893 | break; | ||
3894 | case MAILIMF_FIELD_RESENT_TO: | ||
3895 | printf("Resent-To:\n"); | ||
3896 | display_to(field->fld_data.fld_resent_to); | ||
3897 | break; | ||
3898 | case MAILIMF_FIELD_RESENT_CC: | ||
3899 | printf("Resent-Cc:\n"); | ||
3900 | display_from(field->fld_data.fld_resent_cc); | ||
3901 | break; | ||
3902 | case MAILIMF_FIELD_RESENT_BCC: | ||
3903 | printf("Resent-Bcc:\n"); | ||
3904 | display_from(field->fld_data.fld_resent_bcc); | ||
3905 | break; | ||
3906 | case MAILIMF_FIELD_RESENT_MSG_ID: | ||
3907 | printf("Resent-Message-ID:\n"); | ||
3908 | display_message_id(field->fld_data.fld_resent_msg_id); | ||
3909 | break; | ||
3910 | case MAILIMF_FIELD_ORIG_DATE: | ||
3911 | printf("Date:\n"); | ||
3912 | display_orig_date(field->fld_data.fld_orig_date); | ||
3913 | break; | ||
3914 | case MAILIMF_FIELD_FROM: | ||
3915 | printf("From:\n"); | ||
3916 | display_from(field->fld_data.fld_from); | ||
3917 | break; | ||
3918 | case MAILIMF_FIELD_SENDER: | ||
3919 | printf("Sender:\n"); | ||
3920 | display_sender(field->fld_data.fld_sender); | ||
3921 | break; | ||
3922 | case MAILIMF_FIELD_REPLY_TO: | ||
3923 | printf("Reply-To:\n"); | ||
3924 | display_reply_to(field->fld_data.fld_reply_to); | ||
3925 | break; | ||
3926 | case MAILIMF_FIELD_TO: | ||
3927 | printf("To:\n"); | ||
3928 | display_to(field->fld_data.fld_to); | ||
3929 | break; | ||
3930 | case MAILIMF_FIELD_CC: | ||
3931 | printf("Cc:\n"); | ||
3932 | display_cc(field->fld_data.fld_cc); | ||
3933 | break; | ||
3934 | case MAILIMF_FIELD_BCC: | ||
3935 | printf("Bcc:\n"); | ||
3936 | display_bcc(field->fld_data.fld_bcc); | ||
3937 | break; | ||
3938 | case MAILIMF_FIELD_MESSAGE_ID: | ||
3939 | printf("Message-ID:\n"); | ||
3940 | display_message_id(field->fld_data.fld_message_id); | ||
3941 | break; | ||
3942 | case MAILIMF_FIELD_IN_REPLY_TO: | ||
3943 | printf("In-Reply-To:\n"); | ||
3944 | display_in_reply_to(field->fld_data.fld_in_reply_to); | ||
3945 | break; | ||
3946 | case MAILIMF_FIELD_REFERENCES: | ||
3947 | printf("References:\n"); | ||
3948 | display_references(field->fld_data.fld_references_to); | ||
3949 | break; | ||
3950 | case MAILIMF_FIELD_SUBJECT: | ||
3951 | printf("Subject:\n"); | ||
3952 | display_subject(field->fld_data.fld_subject); | ||
3953 | break; | ||
3954 | case MAILIMF_FIELD_COMMENTS: | ||
3955 | printf("Comments:\n"); | ||
3956 | display_comments(field->fld_data.fld_comments); | ||
3957 | break; | ||
3958 | case MAILIMF_FIELD_KEYWORDS: | ||
3959 | printf("Keywords:\n"); | ||
3960 | display_keywords(field->fld_data.fld_keywords); | ||
3961 | break; | ||
3962 | case MAILIMF_FIELD_OPTIONAL_FIELD: | ||
3963 | printf("[optional field]:\n"); | ||
3964 | display_optional_field(field->fld_data.fld_optional_field); | ||
3965 | break; | ||
3966 | } | ||
3967 | } | ||
3968 | </programlisting> | ||
3969 | </example> | ||
3970 | </sect2> | ||
3971 | |||
3972 | <!-- mailimf_fields --> | ||
3973 | <sect2 id="mailimf-fields"> | ||
3974 | <title>mailimf_fields - list of header fields</title> | ||
3975 | |||
3976 | <programlisting role="C"> | ||
3977 | #include <libetpan/libetpan.h> | ||
3978 | |||
3979 | struct mailimf_fields { | ||
3980 | clist * fld_list; /* list of (struct mailimf_field *), != NULL */ | ||
3981 | }; | ||
3982 | |||
3983 | struct mailimf_fields * mailimf_fields_new(clist * fld_list); | ||
3984 | |||
3985 | void mailimf_fields_free(struct mailimf_fields * fields); | ||
3986 | </programlisting> | ||
3987 | |||
3988 | <para> | ||
3989 | This is the list of header fields of a message. | ||
3990 | </para> | ||
3991 | |||
3992 | <para> | ||
3993 | <command>fld_list</command> is a list of header fields. This | ||
3994 | is a <command>clist</command> which elements are | ||
3995 | of type <command>mailimf_field</command> (see <xref | ||
3996 | linkend="mailimf-field">). | ||
3997 | </para> | ||
3998 | |||
3999 | <para> | ||
4000 | <command>mailimf_fields_new()</command> creates and | ||
4001 | initializes a data structure with a value. | ||
4002 | Structures given as argument are referenced by the created | ||
4003 | object and will be freed if the object is released. | ||
4004 | </para> | ||
4005 | |||
4006 | <para> | ||
4007 | <command>mailimf_fields_free()</command> frees memory used | ||
4008 | by the structure and substructures will also be released. | ||
4009 | </para> | ||
4010 | |||
4011 | <example> | ||
4012 | <title>creation and display of header fields</title> | ||
4013 | <programlisting role="C"> | ||
4014 | #include <libetpan/libetpan.h> | ||
4015 | |||
4016 | int main(int argc, char ** argv) | ||
4017 | { | ||
4018 | struct mailimf_fields * fields; | ||
4019 | struct mailimf_field * f; | ||
4020 | clist * list; | ||
4021 | struct mailimf_from * from; | ||
4022 | struct mailimf_to * to | ||
4023 | struct mailimf_mailbox * mb; | ||
4024 | struct mailimf_address * addr; | ||
4025 | struct mailimf_mailbox_list * mb_list; | ||
4026 | struct mailimf_address_list * addr_list; | ||
4027 | clist * fields_list; | ||
4028 | |||
4029 | /* build headers */ | ||
4030 | |||
4031 | fields_list = clist_new(); | ||
4032 | |||
4033 | /* build header 'From' */ | ||
4034 | |||
4035 | list = clist_new(); | ||
4036 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4037 | strdup("dinh.viet.hoa@free.fr")); | ||
4038 | clist_append(list, mb); | ||
4039 | mb_list = mailimf_mailbox_list_new(list); | ||
4040 | |||
4041 | from = mailimf_from_new(mb_list); | ||
4042 | |||
4043 | f = mailimf_field_new(MAILIMF_FIELD_FROM, | ||
4044 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4045 | from, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4046 | NULL, NULL, NULL, NULL); | ||
4047 | |||
4048 | clist_append(fields_list, f); | ||
4049 | |||
4050 | /* build header To */ | ||
4051 | |||
4052 | list = clist_new(); | ||
4053 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4054 | strdup("dinh.viet.hoa@free.fr")); | ||
4055 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
4056 | clist_append(list, addr); | ||
4057 | addr_list = mailimf_address_list_new(list); | ||
4058 | |||
4059 | to = mailimf_to_new(addr_list); | ||
4060 | |||
4061 | f = mailimf_field_new(MAILIMF_FIELD_TO, | ||
4062 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4063 | NULL, NULL, NULL, to, NULL, NULL, NULL, NULL, NULL, | ||
4064 | NULL, NULL, NULL, NULL); | ||
4065 | |||
4066 | clist_append(fields_list, f); | ||
4067 | |||
4068 | fields = mailimf_fields_new(fields_list); | ||
4069 | /* do the things */ | ||
4070 | mailimf_fields_free(fields); | ||
4071 | |||
4072 | return 0; | ||
4073 | } | ||
4074 | |||
4075 | /* display list of headers */ | ||
4076 | |||
4077 | #include <libetpan/libetpan.h> | ||
4078 | #include <stdio.h> | ||
4079 | |||
4080 | void display_fields(struct mailimf_fields * fields) | ||
4081 | { | ||
4082 | clistiter * cur; | ||
4083 | |||
4084 | for(cur = clist_begin(field->fld_list) ; cur != NULL ; | ||
4085 | cur = clist_next(cur)) { | ||
4086 | struct mailimf_field * f; | ||
4087 | |||
4088 | f = clist_content(cur); | ||
4089 | |||
4090 | display_field(f); | ||
4091 | printf("\n"); | ||
4092 | } | ||
4093 | } | ||
4094 | </programlisting> | ||
4095 | </example> | ||
4096 | </sect2> | ||
4097 | |||
4098 | <!-- mailimf_body --> | ||
4099 | <sect2 id="mailimf-body"> | ||
4100 | <title>mailimf_body - message body without headers</title> | ||
4101 | |||
4102 | <programlisting role="C"> | ||
4103 | #include <libetpan/libetpan.h> | ||
4104 | |||
4105 | struct mailimf_body { | ||
4106 | const char * bd_text; /* != NULL */ | ||
4107 | size_t bd_size; | ||
4108 | }; | ||
4109 | |||
4110 | struct mailimf_body * mailimf_body_new(const char * bd_text, size_t bd_size); | ||
4111 | |||
4112 | void mailimf_body_free(struct mailimf_body * body); | ||
4113 | </programlisting> | ||
4114 | |||
4115 | <para> | ||
4116 | This is the text content of a message (without headers). | ||
4117 | </para> | ||
4118 | <para> | ||
4119 | <itemizedlist> | ||
4120 | <listitem> | ||
4121 | <para> | ||
4122 | <command>bd_text</command> is the beginning of the | ||
4123 | text part, it is a substring of an other string. | ||
4124 | It is not necessarily zero terminated. | ||
4125 | </para> | ||
4126 | </listitem> | ||
4127 | <listitem> | ||
4128 | <para> | ||
4129 | <command>bd_size</command> is the size of the text part | ||
4130 | </para> | ||
4131 | </listitem> | ||
4132 | </itemizedlist> | ||
4133 | </para> | ||
4134 | |||
4135 | <para> | ||
4136 | <command>mailimf_body_new()</command> creates and | ||
4137 | initializes a data structure with a value. | ||
4138 | Text given as argument will <emphasis>NOT</emphasis> be released. | ||
4139 | </para> | ||
4140 | |||
4141 | <para> | ||
4142 | <command>mailimf_body_free()</command> frees memory used by | ||
4143 | the structure. | ||
4144 | </para> | ||
4145 | |||
4146 | <example> | ||
4147 | <title>creation and display of message body</title> | ||
4148 | <programlisting role="C"> | ||
4149 | #include <libetpan/libetpan.h> | ||
4150 | |||
4151 | int main(int argc, char ** argv) | ||
4152 | { | ||
4153 | struct mailimf_body * b; | ||
4154 | |||
4155 | b = mailimf_body_new("this is the content of the message", 34); | ||
4156 | /* do the things */ | ||
4157 | mailimf_body_free(b); | ||
4158 | |||
4159 | return 0; | ||
4160 | } | ||
4161 | |||
4162 | #include <libetpan/libetpan.h> | ||
4163 | #include <stdio.h> | ||
4164 | |||
4165 | void display_body(struct mailimf_body * b) | ||
4166 | { | ||
4167 | char * text; | ||
4168 | |||
4169 | text = malloc(b->size + 1); | ||
4170 | strncpy(text, b->bd_text, b->bd_size); | ||
4171 | text[b->size] = 0; | ||
4172 | |||
4173 | puts(text); | ||
4174 | printf("\n"); | ||
4175 | |||
4176 | free(text); | ||
4177 | |||
4178 | return 0; | ||
4179 | } | ||
4180 | </programlisting> | ||
4181 | </example> | ||
4182 | </sect2> | ||
4183 | |||
4184 | <!-- mailimf_message --> | ||
4185 | <sect2 id="mailimf-message"> | ||
4186 | <title>mailimf_message - parsed message</title> | ||
4187 | |||
4188 | <programlisting role="C"> | ||
4189 | #include <libetpan/libetpan.h> | ||
4190 | |||
4191 | struct mailimf_message { | ||
4192 | struct mailimf_fields * msg_fields; /* != NULL */ | ||
4193 | struct mailimf_body * msg_body; /* != NULL */ | ||
4194 | }; | ||
4195 | |||
4196 | struct mailimf_message * | ||
4197 | mailimf_message_new(struct mailimf_fields * msg_fields, | ||
4198 | struct mailimf_body * msg_body); | ||
4199 | |||
4200 | void mailimf_message_free(struct mailimf_message * message); | ||
4201 | </programlisting> | ||
4202 | |||
4203 | <para> | ||
4204 | This is the message content (text and headers). | ||
4205 | </para> | ||
4206 | |||
4207 | <itemizedlist> | ||
4208 | <listitem> | ||
4209 | <para> | ||
4210 | <command>msg_fields</command> is the header fields of | ||
4211 | the message | ||
4212 | (see <xref linkend="mailimf-fields">). | ||
4213 | </para> | ||
4214 | </listitem> | ||
4215 | <listitem> | ||
4216 | <para> | ||
4217 | <command>msg_body</command> is the text part of the message | ||
4218 | (see <xref linkend="mailimf-body">). | ||
4219 | </para> | ||
4220 | </listitem> | ||
4221 | </itemizedlist> | ||
4222 | |||
4223 | <para> | ||
4224 | <command>mailimf_message_new()</command> creates and | ||
4225 | initializes a data structure with a value. | ||
4226 | Structures given as argument are referenced by the created | ||
4227 | object and will be freed if the object is released. | ||
4228 | </para> | ||
4229 | |||
4230 | <para> | ||
4231 | <command>mailimf_message_free()</command> frees memory used | ||
4232 | by the structure and substructures will also be released. | ||
4233 | </para> | ||
4234 | |||
4235 | <example> | ||
4236 | <title>creation and display of message</title> | ||
4237 | <programlisting> | ||
4238 | #include <libetpan/libetpan.h> | ||
4239 | |||
4240 | int main(int argc, char ** argv) | ||
4241 | { | ||
4242 | struct mailimf_body * b; | ||
4243 | struct mailimf_message * m; | ||
4244 | struct mailimf_fields * fields; | ||
4245 | struct mailimf_fields * f; | ||
4246 | clist * list; | ||
4247 | struct mailimf_from * from; | ||
4248 | struct mailimf_to * to | ||
4249 | struct mailimf_mailbox * mb; | ||
4250 | struct mailimf_address * addr; | ||
4251 | struct mailimf_mailbox_list * mb_list; | ||
4252 | struct mailimf_address_list * addr_list; | ||
4253 | clist * fields_list; | ||
4254 | |||
4255 | /* build text content */ | ||
4256 | |||
4257 | b = mailimf_body_new("this is the content of the message", 34); | ||
4258 | |||
4259 | /* build headers */ | ||
4260 | |||
4261 | fields_list = clist_new(); | ||
4262 | |||
4263 | /* build header 'From' */ | ||
4264 | |||
4265 | list = clist_new(); | ||
4266 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4267 | strdup("dinh.viet.hoa@free.fr")); | ||
4268 | clist_append(list, mb); | ||
4269 | mb_list = mailimf_mailbox_list_new(list); | ||
4270 | |||
4271 | from = mailimf_from_new(mb_list); | ||
4272 | |||
4273 | f = mailimf_field_new(MAILIMF_FIELD_FROM, | ||
4274 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4275 | from, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4276 | NULL, NULL, NULL, NULL); | ||
4277 | |||
4278 | clist_append(fields_list, f); | ||
4279 | |||
4280 | /* build header To */ | ||
4281 | |||
4282 | list = clist_new(); | ||
4283 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4284 | strdup("dinh.viet.hoa@free.fr")); | ||
4285 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
4286 | clist_append(list, addr); | ||
4287 | addr_list = mailimf_address_list_new(list); | ||
4288 | |||
4289 | to = mailimf_to_new(addr_list); | ||
4290 | |||
4291 | f = mailimf_field_new(MAILIMF_FIELD_TO, | ||
4292 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4293 | NULL, NULL, NULL, to, NULL, NULL, NULL, NULL, NULL, | ||
4294 | NULL, NULL, NULL, NULL); | ||
4295 | |||
4296 | clist_append(fields_list, f); | ||
4297 | |||
4298 | fields = mailimf_fields_new(fields_list); | ||
4299 | |||
4300 | /* build message */ | ||
4301 | |||
4302 | m = mailimf_message_new(fields, b); | ||
4303 | /* do the things */ | ||
4304 | mailimf_message_free(m); | ||
4305 | |||
4306 | return 0; | ||
4307 | } | ||
4308 | |||
4309 | /* display the message */ | ||
4310 | |||
4311 | #include <libetpan/libetpan.h> | ||
4312 | #include <stdio.h> | ||
4313 | |||
4314 | void display_message(struct mailimf_message * msg) | ||
4315 | { | ||
4316 | display_fields(msg->msg_fields); | ||
4317 | printf("\n"); | ||
4318 | display_body(msg->msg_body); | ||
4319 | printf("\n"); | ||
4320 | } | ||
4321 | </programlisting> | ||
4322 | </example> | ||
4323 | </sect2> | ||
4324 | |||
4325 | <!-- mailimf_single_fields --> | ||
4326 | <sect2 id="mailimf-single-fields"> | ||
4327 | <title>mailimf_single_fields - simplified fields</title> | ||
4328 | |||
4329 | <programlisting role="C"> | ||
4330 | #include <libetpan/libetpan.h> | ||
4331 | |||
4332 | struct mailimf_single_fields { | ||
4333 | struct mailimf_orig_date * fld_orig_date; /* can be NULL */ | ||
4334 | struct mailimf_from * fld_from; /* can be NULL */ | ||
4335 | struct mailimf_sender * fld_sender; /* can be NULL */ | ||
4336 | struct mailimf_reply_to * fld_reply_to; /* can be NULL */ | ||
4337 | struct mailimf_to * fld_to; /* can be NULL */ | ||
4338 | struct mailimf_cc * fld_cc; /* can be NULL */ | ||
4339 | struct mailimf_bcc * fld_bcc; /* can be NULL */ | ||
4340 | struct mailimf_message_id * fld_message_id; /* can be NULL */ | ||
4341 | struct mailimf_in_reply_to * fld_in_reply_to; /* can be NULL */ | ||
4342 | struct mailimf_references * fld_references; /* can be NULL */ | ||
4343 | struct mailimf_subject * fld_subject; /* can be NULL */ | ||
4344 | struct mailimf_comments * fld_comments; /* can be NULL */ | ||
4345 | struct mailimf_keywords * fld_keywords; /* can be NULL */ | ||
4346 | }; | ||
4347 | |||
4348 | struct mailimf_single_fields * | ||
4349 | mailimf_single_fields_new(struct mailimf_fields * fields); | ||
4350 | |||
4351 | void mailimf_single_fields_free(struct mailimf_single_fields * | ||
4352 | single_fields); | ||
4353 | |||
4354 | void mailimf_single_fields_init(struct mailimf_single_fields * single_fields, | ||
4355 | struct mailimf_fields * fields); | ||
4356 | </programlisting> | ||
4357 | |||
4358 | <para> | ||
4359 | Structure that contains some standard fields and allows access | ||
4360 | to a given header without running through the list. | ||
4361 | </para> | ||
4362 | |||
4363 | <para> | ||
4364 | mailimf_fields is the native structure that IMF module will use, | ||
4365 | this module will provide an easier structure to use when | ||
4366 | parsing fields. | ||
4367 | mailimf_single_fields is an easier structure to get parsed fields, | ||
4368 | rather than iteration over the list of fields | ||
4369 | </para> | ||
4370 | |||
4371 | <itemizedlist> | ||
4372 | <listitem> | ||
4373 | <para> | ||
4374 | <command>fld_orig_date</command> is the parsed "Date" | ||
4375 | field | ||
4376 | (see <xref linkend="mailimf-orig-date">). | ||
4377 | </para> | ||
4378 | </listitem> | ||
4379 | <listitem> | ||
4380 | <para> | ||
4381 | <command>fld_from</command> is the parsed "From" field | ||
4382 | (see <xref linkend="mailimf-from">). | ||
4383 | </para> | ||
4384 | </listitem> | ||
4385 | <listitem> | ||
4386 | <para> | ||
4387 | <command>fld_sender</command> is the parsed "Sender "field | ||
4388 | (see <xref linkend="mailimf-sender">). | ||
4389 | </para> | ||
4390 | </listitem> | ||
4391 | <listitem> | ||
4392 | <para> | ||
4393 | <command>reply_to</command> is the parsed "Reply-To" field | ||
4394 | (see <xref linkend="mailimf-reply-to">). | ||
4395 | </para> | ||
4396 | </listitem> | ||
4397 | <listitem> | ||
4398 | <para> | ||
4399 | <command>fld_to</command> is the parsed "To" field | ||
4400 | (see <xref linkend="mailimf-to">). | ||
4401 | </para> | ||
4402 | </listitem> | ||
4403 | <listitem> | ||
4404 | <para> | ||
4405 | <command>fld_cc</command> is the parsed "Cc" field | ||
4406 | (see <xref linkend="mailimf-cc">). | ||
4407 | </para> | ||
4408 | </listitem> | ||
4409 | <listitem> | ||
4410 | <para> | ||
4411 | <command>fld_bcc</command> is the parsed "Bcc" field | ||
4412 | (see <xref linkend="mailimf-bcc">). | ||
4413 | </para> | ||
4414 | </listitem> | ||
4415 | <listitem> | ||
4416 | <para> | ||
4417 | <command>fld_message_id</command> is the parsed | ||
4418 | "Message-ID" field. | ||
4419 | (see <xref linkend="mailimf-message-id">). | ||
4420 | </para> | ||
4421 | </listitem> | ||
4422 | <listitem> | ||
4423 | <para> | ||
4424 | <command>fld_in_reply_to</command> is the parsed | ||
4425 | "In-Reply-To" field. | ||
4426 | (see <xref linkend="mailimf-in-reply-to">). | ||
4427 | </para> | ||
4428 | </listitem> | ||
4429 | <listitem> | ||
4430 | <para> | ||
4431 | <command>fld_references</command> is the parsed | ||
4432 | "References" field. | ||
4433 | (see <xref linkend="mailimf-references">). | ||
4434 | </para> | ||
4435 | </listitem> | ||
4436 | <listitem> | ||
4437 | <para> | ||
4438 | <command>fld_subject</command> is the parsed "Subject" field | ||
4439 | (see <xref linkend="mailimf-subject">). | ||
4440 | </para> | ||
4441 | </listitem> | ||
4442 | <listitem> | ||
4443 | <para> | ||
4444 | <command>fld_comments</command> is the parsed "Comments" field | ||
4445 | (see <xref linkend="mailimf-comments">). | ||
4446 | </para> | ||
4447 | </listitem> | ||
4448 | <listitem> | ||
4449 | <para> | ||
4450 | <command>fld_keywords</command> is the parsed "Keywords" field | ||
4451 | (see <xref linkend="mailimf-keywords">). | ||
4452 | </para> | ||
4453 | </listitem> | ||
4454 | </itemizedlist> | ||
4455 | |||
4456 | <para> | ||
4457 | <command>mailimf_single_fields_new()</command> creates and | ||
4458 | initializes a data structure with a value. | ||
4459 | Structures given as argument are referenced by the created | ||
4460 | object and will <emphasis>NOT</emphasis> be freed if the | ||
4461 | object is released. | ||
4462 | </para> | ||
4463 | |||
4464 | <para> | ||
4465 | <command>mailimf_single_fields_free()</command> frees memory | ||
4466 | used by the structure and | ||
4467 | substructures will <emphasis>NOT</emphasis> be | ||
4468 | released. They should be released by the application. | ||
4469 | </para> | ||
4470 | |||
4471 | <para> | ||
4472 | <command>mailimf_single_fields_init()</command> will | ||
4473 | initialize fill the data structure, using | ||
4474 | the given argument (<command>fields</command>). The | ||
4475 | interesting fields will be filled into | ||
4476 | <command>single_fields</command>. | ||
4477 | </para> | ||
4478 | |||
4479 | <example> | ||
4480 | <title>using mailimf_single_fields</title> | ||
4481 | <programlisting role="C"> | ||
4482 | #include <libetpan/libetpan.h> | ||
4483 | |||
4484 | int main(int argc, char ** argv) | ||
4485 | { | ||
4486 | struct mailimf_single_fields * single_fields; | ||
4487 | struct mailimf_fields * fields; | ||
4488 | struct mailimf_field * f; | ||
4489 | clist * list; | ||
4490 | struct mailimf_from * from; | ||
4491 | struct mailimf_to * to | ||
4492 | struct mailimf_mailbox * mb; | ||
4493 | struct mailimf_address * addr; | ||
4494 | struct mailimf_mailbox_list * mb_list; | ||
4495 | struct mailimf_address_list * addr_list; | ||
4496 | clist * fields_list; | ||
4497 | |||
4498 | /* build headers */ | ||
4499 | |||
4500 | fields_list = clist_new(); | ||
4501 | |||
4502 | /* build header 'From' */ | ||
4503 | |||
4504 | list = clist_new(); | ||
4505 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4506 | strdup("dinh.viet.hoa@free.fr")); | ||
4507 | clist_append(list, mb); | ||
4508 | mb_list = mailimf_mailbox_list_new(list); | ||
4509 | |||
4510 | from = mailimf_from_new(mb_list); | ||
4511 | |||
4512 | f = mailimf_field_new(MAILIMF_FIELD_FROM, | ||
4513 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4514 | from, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4515 | NULL, NULL, NULL, NULL); | ||
4516 | |||
4517 | clist_append(fields_list, f); | ||
4518 | |||
4519 | /* build header To */ | ||
4520 | |||
4521 | list = clist_new(); | ||
4522 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4523 | strdup("dinh.viet.hoa@free.fr")); | ||
4524 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
4525 | clist_append(list, addr); | ||
4526 | addr_list = mailimf_address_list_new(list); | ||
4527 | |||
4528 | to = mailimf_to_new(addr_list); | ||
4529 | |||
4530 | f = mailimf_field_new(MAILIMF_FIELD_TO, | ||
4531 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4532 | NULL, NULL, NULL, to, NULL, NULL, NULL, NULL, NULL, | ||
4533 | NULL, NULL, NULL, NULL); | ||
4534 | |||
4535 | clist_append(fields_list, f); | ||
4536 | |||
4537 | fields = mailimf_fields_new(fields_list); | ||
4538 | |||
4539 | /* create the single fields */ | ||
4540 | single_fields = mailimf_single_fields_new(fields); | ||
4541 | /* do the things */ | ||
4542 | mailimf_single_fields_free(single_fields); | ||
4543 | mailimf_fields_free(fields); | ||
4544 | |||
4545 | return 0; | ||
4546 | } | ||
4547 | </programlisting> | ||
4548 | </example> | ||
4549 | |||
4550 | <example> | ||
4551 | <title>using mailimf_single_fields without memory allocation</title> | ||
4552 | <programlisting> | ||
4553 | #include <libetpan/libetpan.h> | ||
4554 | |||
4555 | int main(int argc, char ** argv) | ||
4556 | { | ||
4557 | struct mailimf_single_fields single_fields; | ||
4558 | struct mailimf_fields * fields; | ||
4559 | struct mailimf_field * f; | ||
4560 | clist * list; | ||
4561 | struct mailimf_from * from; | ||
4562 | struct mailimf_to * to | ||
4563 | struct mailimf_mailbox * mb; | ||
4564 | struct mailimf_address * addr; | ||
4565 | struct mailimf_mailbox_list * mb_list; | ||
4566 | struct mailimf_address_list * addr_list; | ||
4567 | clist * fields_list; | ||
4568 | |||
4569 | /* build headers */ | ||
4570 | |||
4571 | fields_list = clist_new(); | ||
4572 | |||
4573 | /* build header 'From' */ | ||
4574 | |||
4575 | list = clist_new(); | ||
4576 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4577 | strdup("dinh.viet.hoa@free.fr")); | ||
4578 | clist_append(list, mb); | ||
4579 | mb_list = mailimf_mailbox_list_new(list); | ||
4580 | |||
4581 | from = mailimf_from_new(mb_list); | ||
4582 | |||
4583 | f = mailimf_field_new(MAILIMF_FIELD_FROM, | ||
4584 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4585 | from, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4586 | NULL, NULL, NULL, NULL); | ||
4587 | |||
4588 | clist_append(fields_list, f); | ||
4589 | |||
4590 | /* build header To */ | ||
4591 | |||
4592 | list = clist_new(); | ||
4593 | mb = mailimf_mailbox_new(strdup("DINH =?iso-8859-1?Q?Vi=EAt_Ho=E0?="), | ||
4594 | strdup("dinh.viet.hoa@free.fr")); | ||
4595 | addr = mailimf_address_new(MAILIMF_ADDRESS_MAILBOX, mb, NULL); | ||
4596 | clist_append(list, addr); | ||
4597 | addr_list = mailimf_address_list_new(list); | ||
4598 | |||
4599 | to = mailimf_to_new(addr_list); | ||
4600 | |||
4601 | f = mailimf_field_new(MAILIMF_FIELD_TO, | ||
4602 | NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, | ||
4603 | NULL, NULL, NULL, to, NULL, NULL, NULL, NULL, NULL, | ||
4604 | NULL, NULL, NULL, NULL); | ||
4605 | |||
4606 | clist_append(fields_list, f); | ||
4607 | |||
4608 | fields = mailimf_fields_new(fields_list); | ||
4609 | |||
4610 | /* fill the single fields */ | ||
4611 | mailimf_fields_fields_init(&single_fields, fields); | ||
4612 | /* do the things */ | ||
4613 | mailimf_fields_free(fields); | ||
4614 | |||
4615 | return 0; | ||
4616 | } | ||
4617 | </programlisting> | ||
4618 | </example> | ||
4619 | </sect2> | ||
4620 | </sect1> | ||
4621 | |||
4622 | <!-- parser functions --> | ||
4623 | <sect1> | ||
4624 | <title>Parser functions</title> | ||
4625 | |||
4626 | <!-- mailimf_address_list_parse --> | ||
4627 | <sect2 id="mailimf-address-list-parse"> | ||
4628 | <title>mailimf_address_list_parse</title> | ||
4629 | <programlisting role="C"> | ||
4630 | int | ||
4631 | mailimf_address_list_parse(char * message, size_t length, | ||
4632 | size_t * index, | ||
4633 | struct mailimf_address_list ** result); | ||
4634 | </programlisting> | ||
4635 | |||
4636 | <para> | ||
4637 | <command>mailimf_address_list_parse()</command> parse a list | ||
4638 | of addresses in RFC 2822 form. | ||
4639 | </para> | ||
4640 | |||
4641 | <itemizedlist> | ||
4642 | <listitem> | ||
4643 | <para> | ||
4644 | <command>message</command> this is a string containing | ||
4645 | the list of addresses. | ||
4646 | </para> | ||
4647 | </listitem> | ||
4648 | <listitem> | ||
4649 | <para> | ||
4650 | <command>length</command> this is the size of the given string | ||
4651 | </para> | ||
4652 | </listitem> | ||
4653 | <listitem> | ||
4654 | <para> | ||
4655 | <command>index</command> this is a pointer to the | ||
4656 | start of the list of | ||
4657 | addresses in the given string, | ||
4658 | <command>(* index)</command> is modified to point | ||
4659 | at the end of the parsed data. | ||
4660 | </para> | ||
4661 | </listitem> | ||
4662 | <listitem> | ||
4663 | <para> | ||
4664 | <command>result</command> the result of the parse | ||
4665 | operation is stored in | ||
4666 | <command>(* result)</command> | ||
4667 | (see <xref linkend="mailimf-address-list">). | ||
4668 | </para> | ||
4669 | </listitem> | ||
4670 | </itemizedlist> | ||
4671 | |||
4672 | <para> | ||
4673 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
4674 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
4675 | </para> | ||
4676 | |||
4677 | <example> | ||
4678 | <title>parsing a list of addresses</title> | ||
4679 | <programlisting role="C"> | ||
4680 | #include <libetpan/libetpan.h> | ||
4681 | #include <sys/stat.h> | ||
4682 | #include <sys/mman.h> | ||
4683 | |||
4684 | int main(int argc, char ** argv) | ||
4685 | { | ||
4686 | int fd; | ||
4687 | int r; | ||
4688 | |||
4689 | status = EXIT_FAILURE; | ||
4690 | |||
4691 | fd = open("message.rfc2822", O_RDONLY); | ||
4692 | if (fd >= 0) { | ||
4693 | void * mem; | ||
4694 | struct stat stat_info; | ||
4695 | |||
4696 | r = fstat(fd, &stat_info); | ||
4697 | if (r >= 0) { | ||
4698 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
4699 | if (mem != MAP_FAILED) { | ||
4700 | struct mailimf_address_list * addr_list; | ||
4701 | size_t current_index; | ||
4702 | |||
4703 | current_index = 0; | ||
4704 | r = mailimf_address_list_parse(mem, stat_info.st_size, | ||
4705 | &current_index, &addr_list); | ||
4706 | if (r == MAILIMF_NO_ERROR) { | ||
4707 | display_address_list(addr_list); | ||
4708 | /* do the things */ | ||
4709 | status = EXIT_SUCCESS; | ||
4710 | mailimf_address_list_free(addr_list); | ||
4711 | } | ||
4712 | } | ||
4713 | munmap(mem, stat_info.st_size); | ||
4714 | } | ||
4715 | |||
4716 | close(fd); | ||
4717 | } | ||
4718 | |||
4719 | exit(status); | ||
4720 | } | ||
4721 | </programlisting> | ||
4722 | </example> | ||
4723 | </sect2> | ||
4724 | |||
4725 | <!-- mailimf_address_parse --> | ||
4726 | <sect2 id="mailimf-address-parse"> | ||
4727 | <title>mailimf_address_parse</title> | ||
4728 | |||
4729 | <programlisting role="C"> | ||
4730 | #include <libetpan/libetpan.h> | ||
4731 | |||
4732 | int | ||
4733 | mailimf_address_parse(char * message, size_t length, | ||
4734 | size_t * index, | ||
4735 | struct mailimf_address ** result); | ||
4736 | </programlisting> | ||
4737 | |||
4738 | <para> | ||
4739 | <command>mailimf_address_parse()</command> parse an address | ||
4740 | in RFC 2822 form. | ||
4741 | </para> | ||
4742 | |||
4743 | <itemizedlist> | ||
4744 | <listitem> | ||
4745 | <para> | ||
4746 | <command>message</command> this is a string containing the | ||
4747 | address. | ||
4748 | </para> | ||
4749 | </listitem> | ||
4750 | <listitem> | ||
4751 | <para> | ||
4752 | <command>length</command> this is the size of the given | ||
4753 | string. | ||
4754 | </para> | ||
4755 | </listitem> | ||
4756 | <listitem> | ||
4757 | <para> | ||
4758 | <command>index</command> index this is a pointer to the | ||
4759 | start of the address in the given string, <command>(* | ||
4760 | index)</command> is modified to point at the end of the | ||
4761 | parsed data. | ||
4762 | </para> | ||
4763 | </listitem> | ||
4764 | <listitem> | ||
4765 | <para> | ||
4766 | <command>result</command> the result of the parse operation | ||
4767 | is stored in <command>(* result)</command> | ||
4768 | (see <xref linkend="mailimf-address">). | ||
4769 | </para> | ||
4770 | </listitem> | ||
4771 | </itemizedlist> | ||
4772 | |||
4773 | <para> | ||
4774 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
4775 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
4776 | </para> | ||
4777 | |||
4778 | <example> | ||
4779 | <title>parsing an address</title> | ||
4780 | <programlisting role="C"> | ||
4781 | #include <libetpan/libetpan.h> | ||
4782 | #include <sys/stat.h> | ||
4783 | #include <sys/mman.h> | ||
4784 | |||
4785 | int main(int argc, char ** argv) | ||
4786 | { | ||
4787 | int fd; | ||
4788 | int r; | ||
4789 | |||
4790 | status = EXIT_FAILURE; | ||
4791 | |||
4792 | fd = open("message.rfc2822", O_RDONLY); | ||
4793 | if (fd >= 0) { | ||
4794 | void * mem; | ||
4795 | struct stat stat_info; | ||
4796 | |||
4797 | r = fstat(fd, &stat_info); | ||
4798 | if (r >= 0) { | ||
4799 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
4800 | if (mem != MAP_FAILED) { | ||
4801 | struct mailimf_address * addr; | ||
4802 | size_t current_index; | ||
4803 | |||
4804 | current_index = 0; | ||
4805 | r = mailimf_address_parse(mem, stat_info.st_size, | ||
4806 | &current_index, &addr); | ||
4807 | if (r == MAILIMF_NO_ERROR) { | ||
4808 | display_address(addr); | ||
4809 | /* do the things */ | ||
4810 | status = EXIT_SUCCESS; | ||
4811 | mailimf_address_free(addr); | ||
4812 | } | ||
4813 | } | ||
4814 | munmap(mem, stat_info.st_size); | ||
4815 | } | ||
4816 | |||
4817 | close(fd); | ||
4818 | } | ||
4819 | |||
4820 | exit(status); | ||
4821 | } | ||
4822 | </programlisting> | ||
4823 | </example> | ||
4824 | |||
4825 | </sect2> | ||
4826 | |||
4827 | <!-- mailimf_body_parse --> | ||
4828 | <sect2 id="mailimf-body-parse"> | ||
4829 | <title>mailimf_body_parse</title> | ||
4830 | |||
4831 | <programlisting role="C"> | ||
4832 | #include <libetpan/libetpan.h> | ||
4833 | |||
4834 | int mailimf_body_parse(char * message, size_t length, | ||
4835 | size_t * index, | ||
4836 | struct mailimf_body ** result); | ||
4837 | </programlisting> | ||
4838 | |||
4839 | <para> | ||
4840 | <command>mailimf_body_parse()</command> parse text body of a | ||
4841 | message. | ||
4842 | </para> | ||
4843 | |||
4844 | <itemizedlist> | ||
4845 | <listitem> | ||
4846 | <para> | ||
4847 | <command>message</command> this is a string containing | ||
4848 | the message body part. | ||
4849 | </para> | ||
4850 | </listitem> | ||
4851 | <listitem> | ||
4852 | <para> | ||
4853 | <command>length</command> this is the size of the given | ||
4854 | string. | ||
4855 | </para> | ||
4856 | </listitem> | ||
4857 | <listitem> | ||
4858 | <para> | ||
4859 | <command>index</command> this is a pointer to the start | ||
4860 | of the message text part in | ||
4861 | the given string, <command>(* index)</command> is | ||
4862 | modified to point at the end | ||
4863 | of the parsed data. | ||
4864 | </para> | ||
4865 | </listitem> | ||
4866 | <listitem> | ||
4867 | <para> | ||
4868 | <command>result</command> the result of the parse | ||
4869 | operation is stored in | ||
4870 | <command>(* result)</command> | ||
4871 | (see <xref linkend="mailimf-body">). | ||
4872 | </para> | ||
4873 | </listitem> | ||
4874 | </itemizedlist> | ||
4875 | |||
4876 | <para> | ||
4877 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
4878 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
4879 | </para> | ||
4880 | |||
4881 | <example> | ||
4882 | <title>parsing a message body</title> | ||
4883 | <programlisting role="C"> | ||
4884 | #include <libetpan/libetpan.h> | ||
4885 | #include <sys/stat.h> | ||
4886 | #include <sys/mman.h> | ||
4887 | |||
4888 | int main(int argc, char ** argv) | ||
4889 | { | ||
4890 | int fd; | ||
4891 | int r; | ||
4892 | |||
4893 | status = EXIT_FAILURE; | ||
4894 | |||
4895 | fd = open("message.rfc2822", O_RDONLY); | ||
4896 | if (fd >= 0) { | ||
4897 | void * mem; | ||
4898 | struct stat stat_info; | ||
4899 | |||
4900 | r = fstat(fd, &stat_info); | ||
4901 | if (r >= 0) { | ||
4902 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
4903 | if (mem != MAP_FAILED) { | ||
4904 | struct mailimf_body * b; | ||
4905 | struct mailimf_fields * f; | ||
4906 | size_t current_index; | ||
4907 | size_t size; | ||
4908 | |||
4909 | size = stat_info.st_size; | ||
4910 | current_index = 0; | ||
4911 | r = mailimf_fields_parse(mem, size, &current_index, &f); | ||
4912 | if (r == MAILIMF_NO_ERROR) { | ||
4913 | r = mailimf_crlf_parse(mem, size, &current_index); | ||
4914 | /* ignore parse error of crlf */ | ||
4915 | |||
4916 | r = mailimf_body_parse(mem, size, &current_index, &b); | ||
4917 | if (r == MAILIMF_NO_ERROR) { | ||
4918 | |||
4919 | display_body(b); | ||
4920 | /* do the things */ | ||
4921 | status = EXIT_SUCCESS; | ||
4922 | mailimf_body_free(b); | ||
4923 | } | ||
4924 | mailimf_fields_free(f); | ||
4925 | } | ||
4926 | } | ||
4927 | munmap(mem, stat_info.st_size); | ||
4928 | } | ||
4929 | |||
4930 | close(fd); | ||
4931 | } | ||
4932 | |||
4933 | exit(status); | ||
4934 | } | ||
4935 | </programlisting> | ||
4936 | </example> | ||
4937 | |||
4938 | </sect2> | ||
4939 | |||
4940 | <!-- mailimf_envelope_and_optional_fields_parse --> | ||
4941 | <sect2 id="mailimf-envelope-and-optional-fields-parse"> | ||
4942 | <title>mailimf_envelope_and_optional_fields_parse</title> | ||
4943 | |||
4944 | <programlisting role="C"> | ||
4945 | #include <libetpan/libetpan.h> | ||
4946 | |||
4947 | int | ||
4948 | mailimf_envelope_and_optional_fields_parse(char * message, size_t length, | ||
4949 | size_t * index, | ||
4950 | struct mailimf_fields ** result); | ||
4951 | </programlisting> | ||
4952 | |||
4953 | <para> | ||
4954 | <command>mailimf_envelope_and_optional_fields_parse()</command> | ||
4955 | returns a list of most useful headers (parsed). The other | ||
4956 | headers will be placed in the list in a non-parsed form. | ||
4957 | </para> | ||
4958 | |||
4959 | <itemizedlist> | ||
4960 | <listitem> | ||
4961 | <para> | ||
4962 | <command>message</command> this is a string containing the header. | ||
4963 | </para> | ||
4964 | </listitem> | ||
4965 | <listitem> | ||
4966 | <para> | ||
4967 | <command>length</command> this is the size of the given string | ||
4968 | </para> | ||
4969 | </listitem> | ||
4970 | <listitem> | ||
4971 | <para> | ||
4972 | <command>index</command> index this is a pointer to the | ||
4973 | start of the header in the given string, <command>(* | ||
4974 | index)</command> is modified to point at the end | ||
4975 | of the parsed data | ||
4976 | </para> | ||
4977 | </listitem> | ||
4978 | <listitem> | ||
4979 | <para> | ||
4980 | <command>result</command> the result of the parse | ||
4981 | operation is stored in <command>(* result)</command> | ||
4982 | (see <xref linkend="mailimf-fields">). | ||
4983 | </para> | ||
4984 | </listitem> | ||
4985 | </itemizedlist> | ||
4986 | |||
4987 | <para> | ||
4988 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
4989 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
4990 | </para> | ||
4991 | |||
4992 | <example> | ||
4993 | <title>parsing commonly used fields and return other fields | ||
4994 | in a non-parsed form</title> | ||
4995 | <programlisting role="C"> | ||
4996 | #include <libetpan/libetpan.h> | ||
4997 | #include <sys/stat.h> | ||
4998 | #include <sys/mman.h> | ||
4999 | |||
5000 | int main(int argc, char ** argv) | ||
5001 | { | ||
5002 | int fd; | ||
5003 | int r; | ||
5004 | |||
5005 | status = EXIT_FAILURE; | ||
5006 | |||
5007 | fd = open("message.rfc2822", O_RDONLY); | ||
5008 | if (fd >= 0) { | ||
5009 | void * mem; | ||
5010 | struct stat stat_info; | ||
5011 | |||
5012 | r = fstat(fd, &stat_info); | ||
5013 | if (r >= 0) { | ||
5014 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5015 | if (mem != MAP_FAILED) { | ||
5016 | struct mailimf_fields * f; | ||
5017 | size_t current_index; | ||
5018 | |||
5019 | current_index = 0; | ||
5020 | r = mailimf_envelope_and_optional_fields_parse(mem, stat_info.st_size, | ||
5021 | &current_index, &f); | ||
5022 | if (r == MAILIMF_NO_ERROR) { | ||
5023 | display_fields(m); | ||
5024 | /* do the things */ | ||
5025 | status = EXIT_SUCCESS; | ||
5026 | mailimf_fields_free(f); | ||
5027 | } | ||
5028 | } | ||
5029 | munmap(mem, stat_info.st_size); | ||
5030 | } | ||
5031 | |||
5032 | close(fd); | ||
5033 | } | ||
5034 | |||
5035 | exit(status); | ||
5036 | } | ||
5037 | </programlisting> | ||
5038 | </example> | ||
5039 | |||
5040 | </sect2> | ||
5041 | |||
5042 | <!-- mailimf_envelope_fields_parse --> | ||
5043 | <sect2 id="mailimf-envelope-fields-parse"> | ||
5044 | <title>mailimf_envelope_fields_parse</title> | ||
5045 | |||
5046 | <programlisting role="C"> | ||
5047 | #include <libetpan/libetpan.h> | ||
5048 | |||
5049 | int mailimf_envelope_fields_parse(char * message, size_t length, | ||
5050 | size_t * index, | ||
5051 | struct mailimf_fields ** result); | ||
5052 | </programlisting> | ||
5053 | |||
5054 | <para> | ||
5055 | <command>mailimf_envelope_fields_parse()</command> return a | ||
5056 | list of most useful headers (parsed). | ||
5057 | </para> | ||
5058 | |||
5059 | <itemizedlist> | ||
5060 | <listitem> | ||
5061 | <para> | ||
5062 | <command>message</command> this is a string containing the header | ||
5063 | </para> | ||
5064 | </listitem> | ||
5065 | <listitem> | ||
5066 | <para> | ||
5067 | <command>length</command> this is the size of the given string | ||
5068 | </para> | ||
5069 | </listitem> | ||
5070 | <listitem> | ||
5071 | <para> | ||
5072 | <command>index</command> index this is a pointer to the | ||
5073 | start of the header in | ||
5074 | the given string, <command>(* index)</command> is | ||
5075 | modified to point at the end | ||
5076 | of the parsed data | ||
5077 | </para> | ||
5078 | </listitem> | ||
5079 | <listitem> | ||
5080 | <para> | ||
5081 | <command>result</command> the result of the parse | ||
5082 | operation is stored in | ||
5083 | <command>(* result)</command> | ||
5084 | (see <xref linkend="mailimf-fields">). | ||
5085 | </para> | ||
5086 | </listitem> | ||
5087 | </itemizedlist> | ||
5088 | |||
5089 | <para> | ||
5090 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
5091 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
5092 | </para> | ||
5093 | |||
5094 | <example> | ||
5095 | <title>parsing commonly used fields</title> | ||
5096 | <programlisting role="C"> | ||
5097 | #include <libetpan/libetpan.h> | ||
5098 | #include <sys/stat.h> | ||
5099 | #include <sys/mman.h> | ||
5100 | |||
5101 | int main(int argc, char ** argv) | ||
5102 | { | ||
5103 | int fd; | ||
5104 | int r; | ||
5105 | |||
5106 | status = EXIT_FAILURE; | ||
5107 | |||
5108 | fd = open("message.rfc2822", O_RDONLY); | ||
5109 | if (fd >= 0) { | ||
5110 | void * mem; | ||
5111 | struct stat stat_info; | ||
5112 | |||
5113 | r = fstat(fd, &stat_info); | ||
5114 | if (r >= 0) { | ||
5115 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5116 | if (mem != MAP_FAILED) { | ||
5117 | struct mailimf_fields * f; | ||
5118 | size_t current_index; | ||
5119 | |||
5120 | current_index = 0; | ||
5121 | r = mailimf_envelope_fields_parse(mem, stat_info.st_size, | ||
5122 | &current_index, &f); | ||
5123 | if (r == MAILIMF_NO_ERROR) { | ||
5124 | display_fields(m); | ||
5125 | /* do the things */ | ||
5126 | status = EXIT_SUCCESS; | ||
5127 | mailimf_fields_free(f); | ||
5128 | } | ||
5129 | } | ||
5130 | munmap(mem, stat_info.st_size); | ||
5131 | } | ||
5132 | |||
5133 | close(fd); | ||
5134 | } | ||
5135 | |||
5136 | exit(status); | ||
5137 | } | ||
5138 | </programlisting> | ||
5139 | </example> | ||
5140 | |||
5141 | </sect2> | ||
5142 | |||
5143 | <!-- mailimf_optional_fields_parse --> | ||
5144 | <sect2 id="mailimf-optional-fields-parse"> | ||
5145 | <title>mailimf_optional_fields_parse</title> | ||
5146 | |||
5147 | <programlisting role="C"> | ||
5148 | #include <libetpan/libetpan.h> | ||
5149 | |||
5150 | int | ||
5151 | mailimf_envelope_and_optional_fields_parse(char * message, size_t length, | ||
5152 | size_t * index, | ||
5153 | struct mailimf_fields ** result); | ||
5154 | </programlisting> | ||
5155 | |||
5156 | <para> | ||
5157 | <command>mailimf_optional_fields_parse</command> return a | ||
5158 | list of non-parsed headers. | ||
5159 | </para> | ||
5160 | |||
5161 | <itemizedlist> | ||
5162 | <listitem> | ||
5163 | <para> | ||
5164 | <command>message</command> this is a string containing the header | ||
5165 | </para> | ||
5166 | </listitem> | ||
5167 | <listitem> | ||
5168 | <para> | ||
5169 | <command>length</command> this is the size of the given string | ||
5170 | </para> | ||
5171 | </listitem> | ||
5172 | <listitem> | ||
5173 | <para> | ||
5174 | <command>index</command> index this is a pointer to the | ||
5175 | start of the header in | ||
5176 | the given string, <command>(* index)</command> is | ||
5177 | modified to point at the end | ||
5178 | of the parsed data | ||
5179 | </para> | ||
5180 | </listitem> | ||
5181 | <listitem> | ||
5182 | <para> | ||
5183 | <command>result</command> the result of the parse | ||
5184 | operation is stored in | ||
5185 | <command>(* result)</command> | ||
5186 | (see <xref linkend="mailimf-fields">). | ||
5187 | </para> | ||
5188 | </listitem> | ||
5189 | </itemizedlist> | ||
5190 | |||
5191 | <para> | ||
5192 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
5193 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
5194 | </para> | ||
5195 | |||
5196 | <example> | ||
5197 | <title>parsing optional fields</title> | ||
5198 | <programlisting role="C"> | ||
5199 | #include <libetpan/libetpan.h> | ||
5200 | #include <sys/stat.h> | ||
5201 | #include <sys/mman.h> | ||
5202 | |||
5203 | int main(int argc, char ** argv) | ||
5204 | { | ||
5205 | int fd; | ||
5206 | int r; | ||
5207 | |||
5208 | status = EXIT_FAILURE; | ||
5209 | |||
5210 | fd = open("message.rfc2822", O_RDONLY); | ||
5211 | if (fd >= 0) { | ||
5212 | void * mem; | ||
5213 | struct stat stat_info; | ||
5214 | |||
5215 | r = fstat(fd, &stat_info); | ||
5216 | if (r >= 0) { | ||
5217 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5218 | if (mem != MAP_FAILED) { | ||
5219 | struct mailimf_fields * f; | ||
5220 | size_t current_index; | ||
5221 | |||
5222 | current_index = 0; | ||
5223 | r = mailimf_optional_fields_parse(mem, stat_info.st_size, | ||
5224 | &current_index, &f); | ||
5225 | if (r == MAILIMF_NO_ERROR) { | ||
5226 | display_fields(m); | ||
5227 | /* do the things */ | ||
5228 | status = EXIT_SUCCESS; | ||
5229 | mailimf_fields_free(f); | ||
5230 | } | ||
5231 | } | ||
5232 | munmap(mem, stat_info.st_size); | ||
5233 | } | ||
5234 | |||
5235 | close(fd); | ||
5236 | } | ||
5237 | |||
5238 | exit(status); | ||
5239 | } | ||
5240 | </programlisting> | ||
5241 | </example> | ||
5242 | </sect2> | ||
5243 | |||
5244 | <!-- mailimf_fields_parse --> | ||
5245 | <sect2 id="mailimf-fields-parse"> | ||
5246 | <title>mailimf_fields_parse</title> | ||
5247 | |||
5248 | <programlisting role="C"> | ||
5249 | #include <libetpan/libetpan.h> | ||
5250 | |||
5251 | int mailimf_fields_parse(char * message, size_t length, | ||
5252 | size_t * index, | ||
5253 | struct mailimf_fields ** result); | ||
5254 | </programlisting> | ||
5255 | |||
5256 | <para> | ||
5257 | <command>mailimf_fields_parse()</command> parse headers of a | ||
5258 | message. | ||
5259 | </para> | ||
5260 | |||
5261 | <itemizedlist> | ||
5262 | <listitem> | ||
5263 | <para> | ||
5264 | <command>message</command> this is a string containing the header | ||
5265 | </para> | ||
5266 | </listitem> | ||
5267 | <listitem> | ||
5268 | <para> | ||
5269 | <command>length</command> this is the size of the given string | ||
5270 | </para> | ||
5271 | </listitem> | ||
5272 | <listitem> | ||
5273 | <para> | ||
5274 | <command>index</command> index this is a pointer to the | ||
5275 | start of the header in | ||
5276 | the given string, <command>(* index)</command> is | ||
5277 | modified to point at the end | ||
5278 | of the parsed data | ||
5279 | </para> | ||
5280 | </listitem> | ||
5281 | <listitem> | ||
5282 | <para> | ||
5283 | <command>result</command> the result of the parse | ||
5284 | operation is stored in | ||
5285 | <command>(* result)</command> | ||
5286 | (see <xref linkend="mailimf-fields">). | ||
5287 | </para> | ||
5288 | </listitem> | ||
5289 | </itemizedlist> | ||
5290 | |||
5291 | <para> | ||
5292 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
5293 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
5294 | </para> | ||
5295 | |||
5296 | <example> | ||
5297 | <title>parsing header fields</title> | ||
5298 | <programlisting role="C"> | ||
5299 | #include <libetpan/libetpan.h> | ||
5300 | #include <sys/stat.h> | ||
5301 | #include <sys/mman.h> | ||
5302 | |||
5303 | int main(int argc, char ** argv) | ||
5304 | { | ||
5305 | int fd; | ||
5306 | int r; | ||
5307 | |||
5308 | status = EXIT_FAILURE; | ||
5309 | |||
5310 | fd = open("message.rfc2822", O_RDONLY); | ||
5311 | if (fd >= 0) { | ||
5312 | void * mem; | ||
5313 | struct stat stat_info; | ||
5314 | |||
5315 | r = fstat(fd, &stat_info); | ||
5316 | if (r >= 0) { | ||
5317 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5318 | if (mem != MAP_FAILED) { | ||
5319 | struct mailimf_fields * f; | ||
5320 | size_t current_index; | ||
5321 | |||
5322 | current_index = 0; | ||
5323 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
5324 | &current_index, &f); | ||
5325 | if (r == MAILIMF_NO_ERROR) { | ||
5326 | display_fields(f); | ||
5327 | /* do the things */ | ||
5328 | status = EXIT_SUCCESS; | ||
5329 | mailimf_fields_free(f); | ||
5330 | } | ||
5331 | } | ||
5332 | munmap(mem, stat_info.st_size); | ||
5333 | } | ||
5334 | |||
5335 | close(fd); | ||
5336 | } | ||
5337 | |||
5338 | exit(status); | ||
5339 | } | ||
5340 | </programlisting> | ||
5341 | </example> | ||
5342 | </sect2> | ||
5343 | |||
5344 | <!-- mailimf_ignore_field_parse --> | ||
5345 | <sect2 id="mailimf-ignore-field-parse"> | ||
5346 | <title>mailimf_ignore_field_parse</title> | ||
5347 | |||
5348 | <programlisting role="C"> | ||
5349 | #include <libetpan/libetpan.h> | ||
5350 | |||
5351 | int mailimf_ignore_field_parse(char * message, size_t length, | ||
5352 | size_t * index); | ||
5353 | </programlisting> | ||
5354 | |||
5355 | <para> | ||
5356 | <command>mailimf_ignore_field_parse()</command> skip the | ||
5357 | next header. | ||
5358 | </para> | ||
5359 | |||
5360 | <itemizedlist> | ||
5361 | <listitem> | ||
5362 | <para> | ||
5363 | <command>message</command> this is a string containing the header | ||
5364 | </para> | ||
5365 | </listitem> | ||
5366 | <listitem> | ||
5367 | <para> | ||
5368 | <command>length</command> this is the size of the given string | ||
5369 | </para> | ||
5370 | </listitem> | ||
5371 | <listitem> | ||
5372 | <para> | ||
5373 | <command>index</command> index this is a pointer to the | ||
5374 | start of the field to skip in | ||
5375 | the given string, <command>(* index)</command> is | ||
5376 | modified to point at the end | ||
5377 | of the parsed data | ||
5378 | </para> | ||
5379 | </listitem> | ||
5380 | </itemizedlist> | ||
5381 | |||
5382 | <para> | ||
5383 | return <command>MAILIMF_NO_ERROR</command> on success, | ||
5384 | <command>MAILIMF_ERROR_XXX</command> on error. | ||
5385 | </para> | ||
5386 | |||
5387 | <example> | ||
5388 | <title>skipping fields</title> | ||
5389 | <programlisting> | ||
5390 | #include <libetpan/libetpan.h> | ||
5391 | #include <sys/stat.h> | ||
5392 | #include <sys/mman.h> | ||
5393 | |||
5394 | int main(int argc, char ** argv) | ||
5395 | { | ||
5396 | int fd; | ||
5397 | int r; | ||
5398 | |||
5399 | status = EXIT_FAILURE; | ||
5400 | |||
5401 | fd = open("message.rfc2822", O_RDONLY); | ||
5402 | if (fd >= 0) { | ||
5403 | void * mem; | ||
5404 | struct stat stat_info; | ||
5405 | |||
5406 | r = fstat(fd, &stat_info); | ||
5407 | if (r >= 0) { | ||
5408 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5409 | if (mem != MAP_FAILED) { | ||
5410 | size_t current_index; | ||
5411 | |||
5412 | current_index = 0; | ||
5413 | r = mailimf_ignore_field_parse(mem, stat_info.st_size, | ||
5414 | &current_index); | ||
5415 | if (r == MAILIMF_NO_ERROR) { | ||
5416 | /* do the things */ | ||
5417 | status = EXIT_SUCCESS; | ||
5418 | } | ||
5419 | } | ||
5420 | munmap(mem, stat_info.st_size); | ||
5421 | } | ||
5422 | |||
5423 | close(fd); | ||
5424 | } | ||
5425 | |||
5426 | exit(status); | ||
5427 | } | ||
5428 | </programlisting> | ||
5429 | </example> | ||
5430 | </sect2> | ||
5431 | |||
5432 | <!-- mailimf_mailbox_list_parse --> | ||
5433 | <sect2 id="mailimf-mailbox-list-parse"> | ||
5434 | <title>mailimf_mailbox_list_parse</title> | ||
5435 | |||
5436 | <programlisting role="C"> | ||
5437 | #include <libetpan/libetpan.h> | ||
5438 | |||
5439 | int | ||
5440 | mailimf_mailbox_list_parse(char * message, size_t length, | ||
5441 | size_t * index, | ||
5442 | struct mailimf_mailbox_list ** result); | ||
5443 | </programlisting> | ||
5444 | |||
5445 | <para> | ||
5446 | <command>mailimf_mailbox_list_parse()</command> parse a list | ||
5447 | of mailboxes in RFC 2822 form. | ||
5448 | </para> | ||
5449 | |||
5450 | <itemizedlist> | ||
5451 | <listitem> | ||
5452 | <para> | ||
5453 | <command>message</command> this is a string containing the | ||
5454 | list of mailboxes. | ||
5455 | </para> | ||
5456 | </listitem> | ||
5457 | <listitem> | ||
5458 | <para> | ||
5459 | <command>length</command> this is the size of the given | ||
5460 | string. | ||
5461 | </para> | ||
5462 | </listitem> | ||
5463 | <listitem> | ||
5464 | <para> | ||
5465 | <command>index</command> index this is a pointer to the | ||
5466 | start of the list of | ||
5467 | mailboxes in the given string, | ||
5468 | <command>(* index)</command> is modified to point | ||
5469 | at the end of the parsed data. | ||
5470 | </para> | ||
5471 | </listitem> | ||
5472 | <listitem> | ||
5473 | <para> | ||
5474 | <command>result</command> the result of the parse | ||
5475 | operation is stored in | ||
5476 | <command>(* result)</command>. | ||
5477 | (see <xref linkend="mailimf-mailbox-list">) | ||
5478 | </para> | ||
5479 | </listitem> | ||
5480 | </itemizedlist> | ||
5481 | |||
5482 | <para> | ||
5483 | return MAILIMF_NO_ERROR on success, MAILIMF_ERROR_XXX on | ||
5484 | error. | ||
5485 | </para> | ||
5486 | |||
5487 | <example> | ||
5488 | <title>parsing a list of mailboxes</title> | ||
5489 | <programlisting> | ||
5490 | #include <libetpan/libetpan.h> | ||
5491 | #include <sys/stat.h> | ||
5492 | #include <sys/mman.h> | ||
5493 | |||
5494 | int main(int argc, char ** argv) | ||
5495 | { | ||
5496 | int fd; | ||
5497 | int r; | ||
5498 | |||
5499 | status = EXIT_FAILURE; | ||
5500 | |||
5501 | fd = open("message.rfc2822", O_RDONLY); | ||
5502 | if (fd >= 0) { | ||
5503 | void * mem; | ||
5504 | struct stat stat_info; | ||
5505 | |||
5506 | r = fstat(fd, &stat_info); | ||
5507 | if (r >= 0) { | ||
5508 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5509 | if (mem != MAP_FAILED) { | ||
5510 | struct mailimf_mailbox_list * mb_list; | ||
5511 | size_t current_index; | ||
5512 | |||
5513 | current_index = 0; | ||
5514 | r = mailimf_mailbox_list_parse(mem, stat_info.st_size, | ||
5515 | &current_index, &mb_list); | ||
5516 | if (r == MAILIMF_NO_ERROR) { | ||
5517 | display_mailbox_list(mb_list); | ||
5518 | /* do the things */ | ||
5519 | status = EXIT_SUCCESS; | ||
5520 | mailimf_mailbox_list_free(mb_list); | ||
5521 | } | ||
5522 | } | ||
5523 | munmap(mem, stat_info.st_size); | ||
5524 | } | ||
5525 | |||
5526 | close(fd); | ||
5527 | } | ||
5528 | |||
5529 | exit(status); | ||
5530 | } | ||
5531 | </programlisting> | ||
5532 | </example> | ||
5533 | |||
5534 | </sect2> | ||
5535 | |||
5536 | <!-- mailimf_mailbox_parse --> | ||
5537 | <sect2 id="mailimf-mailbox-parse"> | ||
5538 | <title>mailimf_mailbox_parse</title> | ||
5539 | |||
5540 | <programlisting role="C"> | ||
5541 | #include <libetpan/libetpan.h> | ||
5542 | |||
5543 | int mailimf_mailbox_parse(char * message, size_t length, | ||
5544 | size_t * index, | ||
5545 | struct mailimf_mailbox ** result); | ||
5546 | </programlisting> | ||
5547 | |||
5548 | <para> | ||
5549 | <command>mailimf_mailbox_parse</command> parse a mailbox in | ||
5550 | RFC 2822 form. | ||
5551 | </para> | ||
5552 | |||
5553 | <itemizedlist> | ||
5554 | <listitem> | ||
5555 | <para> | ||
5556 | <command>message</command> this is a string containing the | ||
5557 | mailbox. | ||
5558 | </para> | ||
5559 | </listitem> | ||
5560 | <listitem> | ||
5561 | <para> | ||
5562 | <command>length</command> this is the size of the given | ||
5563 | string. | ||
5564 | </para> | ||
5565 | </listitem> | ||
5566 | <listitem> | ||
5567 | <para> | ||
5568 | <command>index</command> index this is a pointer to the | ||
5569 | start of the mailbox in the given string, | ||
5570 | <command>(* index)</command> is modified to point | ||
5571 | at the end of the parsed data. | ||
5572 | </para> | ||
5573 | </listitem> | ||
5574 | <listitem> | ||
5575 | <para> | ||
5576 | <command>result</command> the result of the parse | ||
5577 | operation is stored in | ||
5578 | <command>(* result)</command>. | ||
5579 | (see <xref linkend="mailimf-mailbox">) | ||
5580 | </para> | ||
5581 | </listitem> | ||
5582 | </itemizedlist> | ||
5583 | |||
5584 | <para> | ||
5585 | return MAILIMF_NO_ERROR on success, MAILIMF_ERROR_XXX on | ||
5586 | error. | ||
5587 | </para> | ||
5588 | |||
5589 | <example> | ||
5590 | <title>parsing a mailbox</title> | ||
5591 | <programlisting role="C"> | ||
5592 | #include <libetpan/libetpan.h> | ||
5593 | #include <sys/stat.h> | ||
5594 | #include <sys/mman.h> | ||
5595 | |||
5596 | int main(int argc, char ** argv) | ||
5597 | { | ||
5598 | int fd; | ||
5599 | int r; | ||
5600 | |||
5601 | status = EXIT_FAILURE; | ||
5602 | |||
5603 | fd = open("message.rfc2822", O_RDONLY); | ||
5604 | if (fd >= 0) { | ||
5605 | void * mem; | ||
5606 | struct stat stat_info; | ||
5607 | |||
5608 | r = fstat(fd, &stat_info); | ||
5609 | if (r >= 0) { | ||
5610 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5611 | if (mem != MAP_FAILED) { | ||
5612 | struct mailimf_mailbox_list * mb_list; | ||
5613 | size_t current_index; | ||
5614 | |||
5615 | current_index = 0; | ||
5616 | r = mailimf_mailbox_parse(mem, stat_info.st_size, | ||
5617 | &current_index, &mb_list); | ||
5618 | if (r == MAILIMF_NO_ERROR) { | ||
5619 | display_mailbox_list(mb_list); | ||
5620 | /* do the things */ | ||
5621 | status = EXIT_SUCCESS; | ||
5622 | mailimf_mailbox_free(mb_list); | ||
5623 | } | ||
5624 | } | ||
5625 | munmap(mem, stat_info.st_size); | ||
5626 | } | ||
5627 | |||
5628 | close(fd); | ||
5629 | } | ||
5630 | |||
5631 | exit(status); | ||
5632 | } | ||
5633 | </programlisting> | ||
5634 | </example> | ||
5635 | |||
5636 | </sect2> | ||
5637 | |||
5638 | <!-- mailimf_message_parse --> | ||
5639 | <sect2 id="mailimf-message-parse"> | ||
5640 | <title>mailimf_message_parse</title> | ||
5641 | |||
5642 | <programlisting> | ||
5643 | #include <libetpan/libetpan.h> | ||
5644 | |||
5645 | int mailimf_message_parse(char * message, size_t length, | ||
5646 | size_t * index, | ||
5647 | struct mailimf_message ** result); | ||
5648 | </programlisting> | ||
5649 | |||
5650 | <para> | ||
5651 | <command>mailimf_message_parse</command> parse message | ||
5652 | (headers and body). | ||
5653 | </para> | ||
5654 | |||
5655 | <itemizedlist> | ||
5656 | <listitem> | ||
5657 | <para> | ||
5658 | <command>message</command> this is a string containing | ||
5659 | the message content. | ||
5660 | </para> | ||
5661 | </listitem> | ||
5662 | <listitem> | ||
5663 | <para> | ||
5664 | <command>param</command> length this is the size of the given | ||
5665 | string. | ||
5666 | </para> | ||
5667 | </listitem> | ||
5668 | <listitem> | ||
5669 | <para> | ||
5670 | <command>param</command> index this is a pointer to the | ||
5671 | start of the message in | ||
5672 | the given string, <command>(* index)</command> is | ||
5673 | modified to point at the end | ||
5674 | of the parsed data. | ||
5675 | </para> | ||
5676 | </listitem> | ||
5677 | <listitem> | ||
5678 | <para> | ||
5679 | <command>param</command> result the result of the parse | ||
5680 | operation is stored in | ||
5681 | <command>(* result)</command> | ||
5682 | (see <xref linkend="mailimf-message">). | ||
5683 | </para> | ||
5684 | </listitem> | ||
5685 | </itemizedlist> | ||
5686 | |||
5687 | <example> | ||
5688 | <title>parsing a message</title> | ||
5689 | <programlisting role="C"> | ||
5690 | #include <libetpan/libetpan.h> | ||
5691 | #include <sys/stat.h> | ||
5692 | #include <sys/mman.h> | ||
5693 | |||
5694 | int main(int argc, char ** argv) | ||
5695 | { | ||
5696 | int fd; | ||
5697 | int r; | ||
5698 | |||
5699 | status = EXIT_FAILURE; | ||
5700 | |||
5701 | fd = open("message.rfc2822", O_RDONLY); | ||
5702 | if (fd >= 0) { | ||
5703 | void * mem; | ||
5704 | struct stat stat_info; | ||
5705 | |||
5706 | r = fstat(fd, &stat_info); | ||
5707 | if (r >= 0) { | ||
5708 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
5709 | if (mem != MAP_FAILED) { | ||
5710 | struct mailimf_message * m; | ||
5711 | size_t current_index; | ||
5712 | |||
5713 | current_index = 0; | ||
5714 | r = mailimf_message_parse(mem, stat_info.st_size, | ||
5715 | &current_index, &m); | ||
5716 | if (r == MAILIMF_NO_ERROR) { | ||
5717 | display_message(m); | ||
5718 | /* do the things */ | ||
5719 | status = EXIT_SUCCESS; | ||
5720 | mailimf_message_free(m); | ||
5721 | } | ||
5722 | } | ||
5723 | munmap(mem, stat_info.st_size); | ||
5724 | } | ||
5725 | |||
5726 | close(fd); | ||
5727 | } | ||
5728 | |||
5729 | exit(status); | ||
5730 | } | ||
5731 | </programlisting> | ||
5732 | </example> | ||
5733 | |||
5734 | </sect2> | ||
5735 | </sect1> | ||
5736 | |||
5737 | <!-- helper functions --> | ||
5738 | <sect1> | ||
5739 | <title>Creation functions</title> | ||
5740 | <sect2 id="mailimf-mailbox-list-add"> | ||
5741 | <title>mailimf_mailbox_list</title> | ||
5742 | <programlisting role="C"> | ||
5743 | #include <libetpan/libetpan.h> | ||
5744 | |||
5745 | struct mailimf_mailbox_list * | ||
5746 | mailimf_mailbox_list_new_empty(); | ||
5747 | |||
5748 | int mailimf_mailbox_list_add(struct mailimf_mailbox_list * mailbox_list, | ||
5749 | struct mailimf_mailbox * mb); | ||
5750 | |||
5751 | int mailimf_mailbox_list_add_parse(struct mailimf_mailbox_list * mailbox_list, | ||
5752 | char * mb_str); | ||
5753 | |||
5754 | int mailimf_mailbox_list_add_mb(struct mailimf_mailbox_list * mailbox_list, | ||
5755 | char * display_name, char * address); | ||
5756 | </programlisting> | ||
5757 | |||
5758 | <!-- mailimf_mailbox_list_new_empty --> | ||
5759 | <para> | ||
5760 | <command>mailimf_mailbox_list_new_empty()</command> creates a | ||
5761 | new empty list of mailboxes. | ||
5762 | </para> | ||
5763 | |||
5764 | <!-- mailimf_mailbox_list_add --> | ||
5765 | <para> | ||
5766 | <command>mailimf_mailbox_list_add</command> adds a mailbox | ||
5767 | to the list of mailboxes. | ||
5768 | </para> | ||
5769 | |||
5770 | <!-- mailimf_mailbox_list_add_parse --> | ||
5771 | <para> | ||
5772 | <command>mailimf_mailbox_list_add_parse</command> adds a | ||
5773 | mailbox given in form of a string to the list of mailboxes. | ||
5774 | </para> | ||
5775 | |||
5776 | <!-- mailimf_mailbox_list_add_mb --> | ||
5777 | <para> | ||
5778 | <command>mailimf_mailbox_list_add_mb</command> adds a | ||
5779 | mailbox given in form of a couple : display name, mailbox | ||
5780 | address. | ||
5781 | </para> | ||
5782 | |||
5783 | <itemizedlist> | ||
5784 | <listitem> | ||
5785 | <para> | ||
5786 | <command>mailbox_list</command> is the list of mailboxes. | ||
5787 | </para> | ||
5788 | </listitem> | ||
5789 | <listitem> | ||
5790 | <para> | ||
5791 | <command>mb</command> is a mailbox | ||
5792 | (see <xref linkend="mailimf-mailbox">). | ||
5793 | </para> | ||
5794 | </listitem> | ||
5795 | <listitem> | ||
5796 | <para> | ||
5797 | <command>mb_str</command> is a mailbox given in the form | ||
5798 | of a string. | ||
5799 | </para> | ||
5800 | </listitem> | ||
5801 | <listitem> | ||
5802 | <para> | ||
5803 | <command>display_name</command> is the display name. | ||
5804 | </para> | ||
5805 | </listitem> | ||
5806 | <listitem> | ||
5807 | <para> | ||
5808 | <command>address</command> is the mailbox address. | ||
5809 | </para> | ||
5810 | </listitem> | ||
5811 | </itemizedlist> | ||
5812 | |||
5813 | <example> | ||
5814 | <title>creating a list of mailboxes</title> | ||
5815 | <programlisting role="C"> | ||
5816 | #include <libetpan/libetpan.h> | ||
5817 | |||
5818 | int main(int argc, char ** argv) | ||
5819 | { | ||
5820 | struct mailimf_mailbox_list * mb_list; | ||
5821 | struct mailimf_mailbox * mb; | ||
5822 | |||
5823 | mb_list = mailimf_mailbox_list_new_empty(); | ||
5824 | |||
5825 | mb = mailimf_mailbox_new(strdup("DINH Viet Hoa"), | ||
5826 | strdup("dinh.viet.hoa@free.fr")); | ||
5827 | mailimf_mailbox_list_add(mb_list, mb); | ||
5828 | |||
5829 | mailimf_mailbox_list_add_parse(mb_list, "foo bar <foo@bar.org>"); | ||
5830 | |||
5831 | mailimf_mailbox_list_add_mb(mb_list, strdup("bar foo"), strdup("bar@foo.com")); | ||
5832 | |||
5833 | mailimf_mailbox_list_free(mb_list); | ||
5834 | } | ||
5835 | </programlisting> | ||
5836 | </example> | ||
5837 | |||
5838 | </sect2> | ||
5839 | <sect2 id="mailimf-address-list-add"> | ||
5840 | <title>mailimf_address_list</title> | ||
5841 | <programlisting role="C"> | ||
5842 | #include <libetpan/libetpan.h> | ||
5843 | |||
5844 | struct mailimf_address_list * mailimf_address_list_new_empty(); | ||
5845 | |||
5846 | int mailimf_address_list_add(struct mailimf_address_list * address_list, | ||
5847 | struct mailimf_address * addr); | ||
5848 | |||
5849 | int mailimf_address_list_add_parse(struct mailimf_address_list * address_list, | ||
5850 | char * addr_str); | ||
5851 | |||
5852 | int mailimf_address_list_add_mb(struct mailimf_address_list * address_list, | ||
5853 | char * display_name, char * address); | ||
5854 | </programlisting> | ||
5855 | |||
5856 | <!-- mailimf_address_list_new_empty --> | ||
5857 | <para> | ||
5858 | <command>mailimf_address_list_new_empty()</command> creates a | ||
5859 | new empty list of addresses. | ||
5860 | </para> | ||
5861 | |||
5862 | <!-- mailimf_address_list_add --> | ||
5863 | <para> | ||
5864 | <command>mailimf_address_list_add</command> adds an address | ||
5865 | to the list of addresses. | ||
5866 | </para> | ||
5867 | |||
5868 | <!-- mailimf_address_list_add_parse --> | ||
5869 | <para> | ||
5870 | <command>mailimf_address_list_add_parse</command> adds an | ||
5871 | address given in form of a string to the list of addresses. | ||
5872 | </para> | ||
5873 | |||
5874 | <!-- mailimf_address_list_add_mb --> | ||
5875 | <para> | ||
5876 | <command>mailimf_address_list_add_mb</command> adds a | ||
5877 | mailbox given in form of a couple : display name, mailbox | ||
5878 | address. | ||
5879 | </para> | ||
5880 | |||
5881 | <itemizedlist> | ||
5882 | <listitem> | ||
5883 | <para> | ||
5884 | <command>address_list</command> is the list of mailboxes. | ||
5885 | </para> | ||
5886 | </listitem> | ||
5887 | <listitem> | ||
5888 | <para> | ||
5889 | <command>addr</command> is an address. | ||
5890 | (see <xref linkend="mailimf-address">). | ||
5891 | </para> | ||
5892 | </listitem> | ||
5893 | <listitem> | ||
5894 | <para> | ||
5895 | <command>addr_str</command> is an address given in the form of a | ||
5896 | string. | ||
5897 | </para> | ||
5898 | </listitem> | ||
5899 | <listitem> | ||
5900 | <para> | ||
5901 | <command>display_name</command> is the display name. | ||
5902 | </para> | ||
5903 | </listitem> | ||
5904 | <listitem> | ||
5905 | <para> | ||
5906 | <command>address</command> is the mailbox address. | ||
5907 | </para> | ||
5908 | </listitem> | ||
5909 | </itemizedlist> | ||
5910 | |||
5911 | </sect2> | ||
5912 | <sect2 id="mailimf-fields-add"> | ||
5913 | <title>mailimf_fields</title> | ||
5914 | <programlisting role="C"> | ||
5915 | #include <libetpan/libetpan.h> | ||
5916 | |||
5917 | struct mailimf_fields * | ||
5918 | mailimf_fields_new_empty(void); | ||
5919 | |||
5920 | struct mailimf_field * mailimf_field_new_custom(char * name, char * value); | ||
5921 | |||
5922 | int mailimf_fields_add(struct mailimf_fields * fields, | ||
5923 | struct mailimf_field * field); | ||
5924 | |||
5925 | int mailimf_fields_add_data(struct mailimf_fields * fields, | ||
5926 | struct mailimf_date_time * date, | ||
5927 | struct mailimf_mailbox_list * from, | ||
5928 | struct mailimf_mailbox * sender, | ||
5929 | struct mailimf_address_list * reply_to, | ||
5930 | struct mailimf_address_list * to, | ||
5931 | struct mailimf_address_list * cc, | ||
5932 | struct mailimf_address_list * bcc, | ||
5933 | char * msg_id, | ||
5934 | clist * in_reply_to, | ||
5935 | clist * references, | ||
5936 | char * subject); | ||
5937 | |||
5938 | struct mailimf_fields * | ||
5939 | mailimf_fields_new_with_data_all(struct mailimf_date_time * date, | ||
5940 | struct mailimf_mailbox_list * from, | ||
5941 | struct mailimf_mailbox * sender, | ||
5942 | struct mailimf_address_list * reply_to, | ||
5943 | struct mailimf_address_list * to, | ||
5944 | struct mailimf_address_list * cc, | ||
5945 | struct mailimf_address_list * bcc, | ||
5946 | char * message_id, | ||
5947 | clist * in_reply_to, | ||
5948 | clist * references, | ||
5949 | char * subject); | ||
5950 | |||
5951 | struct mailimf_fields * | ||
5952 | mailimf_fields_new_with_data(struct mailimf_mailbox_list * from, | ||
5953 | struct mailimf_mailbox * sender, | ||
5954 | struct mailimf_address_list * reply_to, | ||
5955 | struct mailimf_address_list * to, | ||
5956 | struct mailimf_address_list * cc, | ||
5957 | struct mailimf_address_list * bcc, | ||
5958 | clist * in_reply_to, | ||
5959 | clist * references, | ||
5960 | char * subject); | ||
5961 | |||
5962 | char * mailimf_get_message_id(void); | ||
5963 | |||
5964 | struct mailimf_date_time * mailimf_get_current_date(void); | ||
5965 | |||
5966 | int | ||
5967 | mailimf_resent_fields_add_data(struct mailimf_fields * fields, | ||
5968 | struct mailimf_date_time * resent_date, | ||
5969 | struct mailimf_mailbox_list * resent_from, | ||
5970 | struct mailimf_mailbox * resent_sender, | ||
5971 | struct mailimf_address_list * resent_to, | ||
5972 | struct mailimf_address_list * resent_cc, | ||
5973 | struct mailimf_address_list * resent_bcc, | ||
5974 | char * resent_msg_id); | ||
5975 | |||
5976 | struct mailimf_fields * | ||
5977 | mailimf_resent_fields_new_with_data_all(struct mailimf_date_time * | ||
5978 | resent_date, struct mailimf_mailbox_list * resent_from, | ||
5979 | struct mailimf_mailbox * resent_sender, | ||
5980 | struct mailimf_address_list * resent_to, | ||
5981 | struct mailimf_address_list * resent_cc, | ||
5982 | struct mailimf_address_list * resent_bcc, | ||
5983 | char * resent_msg_id); | ||
5984 | |||
5985 | struct mailimf_fields * | ||
5986 | mailimf_resent_fields_new_with_data(struct mailimf_mailbox_list * from, | ||
5987 | struct mailimf_mailbox * resent_sender, | ||
5988 | struct mailimf_address_list * resent_to, | ||
5989 | struct mailimf_address_list * resent_cc, | ||
5990 | struct mailimf_address_list * resent_bcc); | ||
5991 | </programlisting> | ||
5992 | |||
5993 | <itemizedlist> | ||
5994 | <listitem> | ||
5995 | <para> | ||
5996 | <command>from</command> is the parsed content of the | ||
5997 | From field | ||
5998 | (see <xref linkend="mailimf-from">). | ||
5999 | </para> | ||
6000 | </listitem> | ||
6001 | <listitem> | ||
6002 | <para> | ||
6003 | <command>sender</command> is the parsed content of the | ||
6004 | Sender field | ||
6005 | (see <xref linkend="mailimf-sender">). | ||
6006 | </para> | ||
6007 | </listitem> | ||
6008 | <listitem> | ||
6009 | <para> | ||
6010 | <command>reply_to</command> is the parsed content of the | ||
6011 | <command>Reply-To</command> field | ||
6012 | (see <xref linkend="mailimf-reply-to">). | ||
6013 | </para> | ||
6014 | </listitem> | ||
6015 | <listitem> | ||
6016 | <para> | ||
6017 | <command>to</command> is the parsed content of the | ||
6018 | <command>To</command> field | ||
6019 | (see <xref linkend="mailimf-to">). | ||
6020 | </para> | ||
6021 | </listitem> | ||
6022 | <listitem> | ||
6023 | <para> | ||
6024 | <command>cc</command> is the parsed content of the | ||
6025 | <command>Cc</command> field | ||
6026 | (see <xref linkend="mailimf-cc">). | ||
6027 | </para> | ||
6028 | </listitem> | ||
6029 | <listitem> | ||
6030 | <para> | ||
6031 | <command>bcc</command> is the parsed content of the | ||
6032 | <command>Bcc</command> field | ||
6033 | (see <xref linkend="mailimf-bcc">). | ||
6034 | </para> | ||
6035 | </listitem> | ||
6036 | <listitem> | ||
6037 | <para> | ||
6038 | <command>message_id</command> is the parsed content of | ||
6039 | the <command>Message-ID</command> field | ||
6040 | (see <xref linkend="mailimf-message-id">). | ||
6041 | </para> | ||
6042 | </listitem> | ||
6043 | <listitem> | ||
6044 | <para> | ||
6045 | <command>in_reply_to</command> is the parsed content of | ||
6046 | the <command>In-Reply-To</command> field | ||
6047 | (see <xref linkend="mailimf-in-reply-to">). | ||
6048 | </para> | ||
6049 | </listitem> | ||
6050 | <listitem> | ||
6051 | <para> | ||
6052 | <command>references</command> is the parsed content of | ||
6053 | the <command>References</command> field | ||
6054 | (see <xref linkend="mailimf-references">). | ||
6055 | </para> | ||
6056 | </listitem> | ||
6057 | <listitem> | ||
6058 | <para> | ||
6059 | <command>subject</command> is the content of the | ||
6060 | <command>Subject</command> field | ||
6061 | (see <xref linkend="mailimf-subject">). | ||
6062 | </para> | ||
6063 | </listitem> | ||
6064 | <listitem> | ||
6065 | <para> | ||
6066 | <command>resent_date</command> is the parsed content of | ||
6067 | the <command>Resent-Date</command> field | ||
6068 | (see <xref linkend="mailimf-orig-date">). | ||
6069 | </para> | ||
6070 | </listitem> | ||
6071 | <listitem> | ||
6072 | <para> | ||
6073 | <command>resent_from</command> is the parsed content of | ||
6074 | the <command>Resent-From</command> field | ||
6075 | (see <xref linkend="mailimf-from">). | ||
6076 | </para> | ||
6077 | </listitem> | ||
6078 | <listitem> | ||
6079 | <para> | ||
6080 | <command>resent_sender</command> is the parsed content of the | ||
6081 | <command>Resent-Sender</command> field | ||
6082 | (see <xref linkend="mailimf-sender">). | ||
6083 | </para> | ||
6084 | </listitem> | ||
6085 | <listitem> | ||
6086 | <para> | ||
6087 | <command>resent_to</command> is the parsed content of | ||
6088 | the <command>Resent-To</command> field | ||
6089 | (see <xref linkend="mailimf-to">). | ||
6090 | </para> | ||
6091 | </listitem> | ||
6092 | <listitem> | ||
6093 | <para> | ||
6094 | <command>resent_cc</command> is the parsed content of | ||
6095 | the <command>Resent-Cc</command> field | ||
6096 | (see <xref linkend="mailimf-cc">). | ||
6097 | </para> | ||
6098 | </listitem> | ||
6099 | <listitem> | ||
6100 | <para> | ||
6101 | <command>resent_bcc</command> is the parsed content of the | ||
6102 | <command>Resent-Bcc</command> field | ||
6103 | (see <xref linkend="mailimf-bcc">). | ||
6104 | </para> | ||
6105 | </listitem> | ||
6106 | <listitem> | ||
6107 | <para> | ||
6108 | <command>resent_msg_id</command> is the parsed content of the | ||
6109 | <command>Resent-Message-ID</command> field | ||
6110 | (see <xref linkend="mailimf-message-id">). | ||
6111 | </para> | ||
6112 | </listitem> | ||
6113 | </itemizedlist> | ||
6114 | |||
6115 | <!-- mailimf_fields_new_empty --> | ||
6116 | <para> | ||
6117 | <command>mailimf_fields_new_empty()</command> creates a new | ||
6118 | empty set of headers. | ||
6119 | </para> | ||
6120 | |||
6121 | <!-- mailimf_fields_new_custom --> | ||
6122 | <para> | ||
6123 | <command>mailimf_field_new_custom()</command> creates a new | ||
6124 | custom header. | ||
6125 | </para> | ||
6126 | |||
6127 | <!-- mailimf_fields_add --> | ||
6128 | <para> | ||
6129 | <command>mailimf_fields_add()</command> adds a header to the | ||
6130 | set of headers. | ||
6131 | </para> | ||
6132 | |||
6133 | <!-- mailimf_fields_add_data --> | ||
6134 | <para> | ||
6135 | <command>mailimf_fields_add_data()</command> adds some headers | ||
6136 | to the set of headers. | ||
6137 | </para> | ||
6138 | |||
6139 | <!-- mailimf_fields_new_with_data_all --> | ||
6140 | <para> | ||
6141 | <command>mailimf_fields_new_with_data_all()</command> creates | ||
6142 | a set of headers with some headers (including Date and | ||
6143 | Message-ID). | ||
6144 | </para> | ||
6145 | |||
6146 | <!-- mailimf_fields_new_with_data --> | ||
6147 | <para> | ||
6148 | <command>mailimf_fields_new_with_data()</command> creates a | ||
6149 | set of headers with some headers (Date and Message-ID will | ||
6150 | be generated). | ||
6151 | </para> | ||
6152 | |||
6153 | <!-- mailimf_get_message_id --> | ||
6154 | <para> | ||
6155 | <command>mailimf_get_message_id()</command> generates a | ||
6156 | Message-ID. The result must be freed using | ||
6157 | <command>free()</command>. | ||
6158 | </para> | ||
6159 | |||
6160 | <!-- mailimf_get_current_date --> | ||
6161 | <para> | ||
6162 | <command>mailimf_get_current_date()</command> generates a | ||
6163 | Date. The result must be freed using | ||
6164 | <command>mailimf_date_time_free</command>. | ||
6165 | </para> | ||
6166 | |||
6167 | <!-- mailimf_resent_fields_add_data --> | ||
6168 | <para> | ||
6169 | <command>mailimf_resent_fields_add_data()</command> adds some | ||
6170 | resent headers to the set of headers. | ||
6171 | </para> | ||
6172 | |||
6173 | <!-- mailimf_resent_fields_new_with_data_all --> | ||
6174 | <para> | ||
6175 | <command>mailimf_resent_fields_new_with_data_all()</command> | ||
6176 | creates a set of headers with some resent headers (including | ||
6177 | Resent-Date and Resent-Message-ID). | ||
6178 | </para> | ||
6179 | |||
6180 | <!-- mailimf_resent_fields_new_with_data --> | ||
6181 | <para> | ||
6182 | <command>mailimf_resent_fields_new_with_data()</command> | ||
6183 | creates a set of headers with some resent headers | ||
6184 | (Resent-Date and Resent-Message-ID will be generated) | ||
6185 | </para> | ||
6186 | |||
6187 | <example> | ||
6188 | <title>creation of header fields</title> | ||
6189 | <programlisting role="C"> | ||
6190 | #include <libetpan/libetpan.h> | ||
6191 | |||
6192 | int main(int argc, char ** argv) | ||
6193 | { | ||
6194 | struct mailimf_fields * fields; | ||
6195 | struct mailimf_field * field; | ||
6196 | struct mailimf_date_time * date; | ||
6197 | char * msg_id; | ||
6198 | struct mailimf_mailbox_list * from; | ||
6199 | struct mailimf_address_list * to; | ||
6200 | |||
6201 | fields = mailimf_fields_new_empty(); | ||
6202 | field = mailimf_field_new_custom(strdup("X-Mailer"), strdup("my-mailer")); | ||
6203 | mailimf_fields_add(fields, field); | ||
6204 | |||
6205 | from = mailimf_mailbox_list_new_empty(); | ||
6206 | mailimf_mailbox_list_add_mb(from, strdup("DINH Viet Hoa"), strdup("dinh.viet.hoa@free.fr"); | ||
6207 | date = mailimf_get_current_date(); | ||
6208 | msg_id = mailimf_get_message_id(); | ||
6209 | to = mailimf_address_list_new_empty(); | ||
6210 | mailimf_address_list_add_mb(to, strdup("FOO Bar"), strdup("foo@bar.org"); | ||
6211 | |||
6212 | mailimf_fields_add_data(fields, date, from, NULL, NULL, to, NULL, NULL, | ||
6213 | msg_id, NULL, NULL, strdup("hello")); | ||
6214 | |||
6215 | /* do the things */ | ||
6216 | |||
6217 | mailimf_fields_free(fields); | ||
6218 | } | ||
6219 | |||
6220 | #include <libetpan/libetpan.h> | ||
6221 | |||
6222 | int main(int argc, char ** argv) | ||
6223 | { | ||
6224 | struct mailimf_fields * fields; | ||
6225 | struct mailimf_mailbox_list * from; | ||
6226 | struct mailimf_address_list * to; | ||
6227 | struct mailimf_date_time * date; | ||
6228 | char * msg_id; | ||
6229 | |||
6230 | from = mailimf_mailbox_list_new_empty(); | ||
6231 | mailimf_mailbox_list_add_mb(from, strdup("DINH Viet Hoa"), strdup("dinh.viet.hoa@free.fr"); | ||
6232 | to = mailimf_address_list_new_empty(); | ||
6233 | mailimf_address_list_add_mb(to, strdup("FOO Bar"), strdup("foo@bar.org"); | ||
6234 | date = mailimf_get_current_date(); | ||
6235 | msg_id = mailimf_get_message_id(); | ||
6236 | |||
6237 | fields = mailimf_fields_new_with_all_data(date, from, NULL, NULL, to, NULL, NULL, | ||
6238 | msg_id, NULL, NULL, strdup("hello")); | ||
6239 | |||
6240 | /* do the things */ | ||
6241 | |||
6242 | mailimf_fields_free(fields); | ||
6243 | } | ||
6244 | |||
6245 | #include <libetpan/libetpan.h> | ||
6246 | |||
6247 | int main(int argc, char ** argv) | ||
6248 | { | ||
6249 | struct mailimf_fields * fields; | ||
6250 | struct mailimf_mailbox_list * from; | ||
6251 | struct mailimf_address_list * to; | ||
6252 | |||
6253 | from = mailimf_mailbox_list_new_empty(); | ||
6254 | mailimf_mailbox_list_add_mb(from, strdup("DINH Viet Hoa"), strdup("dinh.viet.hoa@free.fr"); | ||
6255 | to = mailimf_address_list_new_empty(); | ||
6256 | mailimf_address_list_add_mb(to, strdup("FOO Bar"), strdup("foo@bar.org"); | ||
6257 | |||
6258 | fields = mailimf_fields_new_with_data(from, NULL, NULL, to, NULL, NULL, | ||
6259 | NULL, NULL, strdup("hello")); | ||
6260 | |||
6261 | /* do the things */ | ||
6262 | |||
6263 | mailimf_fields_free(fields); | ||
6264 | } | ||
6265 | </programlisting> | ||
6266 | </example> | ||
6267 | </sect2> | ||
6268 | </sect1> | ||
6269 | |||
6270 | <!-- rendering functions --> | ||
6271 | <sect1> | ||
6272 | <title>Rendering of messages</title> | ||
6273 | <sect2 id="mailimf-fields-write"> | ||
6274 | <title>Header fields</title> | ||
6275 | <programlisting> | ||
6276 | #include <libetpan/libetpan.h> | ||
6277 | |||
6278 | int mailimf_fields_write(FILE * f, int * col, | ||
6279 | struct mailimf_fields * fields); | ||
6280 | |||
6281 | int mailimf_envelope_fields_write(FILE * f, int * col, | ||
6282 | struct mailimf_fields * fields); | ||
6283 | |||
6284 | int mailimf_field_write(FILE * f, int * col, | ||
6285 | struct mailimf_field * field); | ||
6286 | </programlisting> | ||
6287 | |||
6288 | <itemizedlist> | ||
6289 | <listitem> | ||
6290 | <para> | ||
6291 | <command>col</command> current column is given for wrapping | ||
6292 | purpose in <command>(* col)</command>, | ||
6293 | the resulting columns will be returned.. | ||
6294 | </para> | ||
6295 | </listitem> | ||
6296 | <listitem> | ||
6297 | <para> | ||
6298 | <command>f</command> is the file descriptor. It can be | ||
6299 | stdout for example. | ||
6300 | </para> | ||
6301 | </listitem> | ||
6302 | <listitem> | ||
6303 | <para> | ||
6304 | <command>fields</command> is the header fields | ||
6305 | (see <xref linkend="mailimf-fields">). | ||
6306 | </para> | ||
6307 | </listitem> | ||
6308 | <listitem> | ||
6309 | <para> | ||
6310 | <command>field</command> is a field | ||
6311 | (see <xref linkend="mailimf-field">). | ||
6312 | </para> | ||
6313 | </listitem> | ||
6314 | </itemizedlist> | ||
6315 | |||
6316 | <!-- mailimf_fields_write --> | ||
6317 | <para> | ||
6318 | <command>mailimf_fields_write</command> outputs the set of | ||
6319 | header fields. | ||
6320 | </para> | ||
6321 | |||
6322 | <!-- mailimf_envelope_fields_write --> | ||
6323 | <para> | ||
6324 | <command>mailimf_envelope_fields_write</command> outputs the | ||
6325 | set of header fields except the optional fields. | ||
6326 | </para> | ||
6327 | |||
6328 | <!-- mailimf_field_write --> | ||
6329 | <para> | ||
6330 | <command>mailimf_field_write</command> outputs a header. | ||
6331 | </para> | ||
6332 | |||
6333 | <example> | ||
6334 | <title>rendering of fields</title> | ||
6335 | <programlisting role="C"> | ||
6336 | int main(int argc, char ** argv) | ||
6337 | { | ||
6338 | struct mailimf_fields * fields; | ||
6339 | int col; | ||
6340 | |||
6341 | /* look at the example in mailimf_fields to see how to | ||
6342 | build a mailimf_fields */ | ||
6343 | fields = build_imf_fields(); | ||
6344 | |||
6345 | col = 0; | ||
6346 | mailimf_fields_write(stdout, &col, fields); | ||
6347 | |||
6348 | mailimf_fields_free(fields); | ||
6349 | } | ||
6350 | |||
6351 | int main(int argc, char ** argv) | ||
6352 | { | ||
6353 | struct mailimf_fields * fields; | ||
6354 | int col; | ||
6355 | |||
6356 | /* look at the example in mailimf_fields to see how to | ||
6357 | build a mailimf_fields */ | ||
6358 | fields = build_imf_fields(); | ||
6359 | |||
6360 | col = 0; | ||
6361 | mailimf_envelope_fields_write(stdout, &col, fields); | ||
6362 | |||
6363 | mailimf_fields_free(fields); | ||
6364 | } | ||
6365 | |||
6366 | int main(int argc, char ** argv) | ||
6367 | { | ||
6368 | struct mailimf_field * field; | ||
6369 | int col; | ||
6370 | |||
6371 | field = mailimf_field_new_custom(strdup("X-Mailer"), strdup("my mailer")); | ||
6372 | |||
6373 | col = 0; | ||
6374 | mailimf_field_write(stdout, &col, field); | ||
6375 | |||
6376 | mailimf_field_free(field); | ||
6377 | } | ||
6378 | </programlisting> | ||
6379 | </example> | ||
6380 | </sect2> | ||
6381 | </sect1> | ||
6382 | </chapter> | ||
6383 | |||
6384 | |||
6385 | <!-- MIME --> | ||
6386 | <chapter> | ||
6387 | <title>MIME</title> | ||
6388 | |||
6389 | <para> | ||
6390 | libEtPan! implements a MIME message parser (also known as | ||
6391 | messages with attachments or | ||
6392 | multipart messages). This also allows to generate MIME messages. | ||
6393 | </para> | ||
6394 | |||
6395 | <warning> | ||
6396 | <para> | ||
6397 | All allocation functions will take as argument allocated data | ||
6398 | and will store these data in the structure they will allocate. | ||
6399 | Data should be persistant during all the use of the structure | ||
6400 | and will be freed by the free function of the structure | ||
6401 | </para> | ||
6402 | |||
6403 | <para> | ||
6404 | allocation functions will return <command>NULL</command> on failure | ||
6405 | |||
6406 | functions returning integer will be returning one of the | ||
6407 | following error code: | ||
6408 | <command>MAILIMF_NO_ERROR</command>, | ||
6409 | <command>MAILIMF_ERROR_PARSE</command>, | ||
6410 | <command>MAILIMF_ERROR_MEMORY</command>, | ||
6411 | <command>MAILIMF_ERROR_INVAL</command>, | ||
6412 | or <command>MAILIMF_ERROR_FILE</command>. | ||
6413 | </para> | ||
6414 | </warning> | ||
6415 | |||
6416 | <sect1> | ||
6417 | <title>Quick start</title> | ||
6418 | |||
6419 | <para> | ||
6420 | You will need this module when you want to parse a MIME | ||
6421 | message. | ||
6422 | </para> | ||
6423 | |||
6424 | <sect2> | ||
6425 | <title>Parse MIME message</title> | ||
6426 | <para> | ||
6427 | You will use the following function : | ||
6428 | </para> | ||
6429 | <itemizedlist> | ||
6430 | <listitem> | ||
6431 | <para> | ||
6432 | <command>mailmime_parse</command> | ||
6433 | (<xref linkend="mailimf-envelope-and-optional-fields-parse">) | ||
6434 | </para> | ||
6435 | </listitem> | ||
6436 | </itemizedlist> | ||
6437 | </sect2> | ||
6438 | |||
6439 | <sect2> | ||
6440 | <title>Render the MIME message</title> | ||
6441 | <para> | ||
6442 | Build your MIME message, then use | ||
6443 | <command>mailmime_write</command> | ||
6444 | (<xref linkend="mailmime-write">) | ||
6445 | to render a MIME message. | ||
6446 | </sect2> | ||
6447 | </sect1> | ||
6448 | |||
6449 | <!-- Data types--> | ||
6450 | <sect1> | ||
6451 | <title>Data types</title> | ||
6452 | <!-- mailmime_composite_type --> | ||
6453 | <sect2 id="mailmime-composite-type"> | ||
6454 | <title>mailmime_composite_type - Composite MIME type</title> | ||
6455 | |||
6456 | <programlisting role="C"> | ||
6457 | #include <libetpan/libetpan.h> | ||
6458 | |||
6459 | enum { | ||
6460 | MAILMIME_COMPOSITE_TYPE_ERROR, | ||
6461 | MAILMIME_COMPOSITE_TYPE_MESSAGE, | ||
6462 | MAILMIME_COMPOSITE_TYPE_MULTIPART, | ||
6463 | MAILMIME_COMPOSITE_TYPE_EXTENSION | ||
6464 | }; | ||
6465 | |||
6466 | struct mailmime_composite_type { | ||
6467 | int ct_type; | ||
6468 | char * ct_token; | ||
6469 | }; | ||
6470 | |||
6471 | struct mailmime_composite_type * | ||
6472 | mailmime_composite_type_new(int ct_type, char * ct_token); | ||
6473 | |||
6474 | void mailmime_composite_type_free(struct mailmime_composite_type * ct); | ||
6475 | </programlisting> | ||
6476 | |||
6477 | <para> | ||
6478 | This is a MIME composite type such as <command>message</command> or | ||
6479 | <command>multipart</command>. | ||
6480 | </para> | ||
6481 | |||
6482 | <para> | ||
6483 | <command>ct_type</command> can have one of the 3 following values : | ||
6484 | <command>MAILMIME_COMPOSITE_TYPE_MESSAGE</command> when the | ||
6485 | composite MIME type | ||
6486 | is <command>message</command>, | ||
6487 | <command>MAILMIME_COMPOSITE_TYPE_MULTIPART</command> when | ||
6488 | the composite MIME type | ||
6489 | is <command> multipart</command>, | ||
6490 | <command>MAILMIME_COMPOSITE_TYPE_EXTENSION</command> for | ||
6491 | other and <command>ct_token</command> is set | ||
6492 | in this case. | ||
6493 | <command>MAILMIME_COMPOSITE_TYPE_ERROR</command> is used | ||
6494 | internally on parse error. | ||
6495 | </para> | ||
6496 | |||
6497 | <para> | ||
6498 | <command>mailmime_composite_type_new()</command> creates and | ||
6499 | initializes | ||
6500 | a data structure with a value. | ||
6501 | Structures given as argument are referenced by the created | ||
6502 | object and will be freed if the object is released. | ||
6503 | </para> | ||
6504 | |||
6505 | <para> | ||
6506 | <command>mailmime_composite_type_free()</command> frees | ||
6507 | memory used by | ||
6508 | the structure and substructures will also be released. | ||
6509 | </para> | ||
6510 | |||
6511 | <example> | ||
6512 | <title>create and display MIME composite type</title> | ||
6513 | <programlisting role="C"> | ||
6514 | #include <libetpan/libetpan.h> | ||
6515 | |||
6516 | int main(void) | ||
6517 | { | ||
6518 | struct mailmime_composite_type * ct; | ||
6519 | |||
6520 | ct = mailmime_composite_type_new(MAILMIME_COMPOSITE_TYPE_MULTIPART, NULL); | ||
6521 | |||
6522 | /* do your things ... */ | ||
6523 | |||
6524 | mailmime_composite_type_free(ct); | ||
6525 | |||
6526 | exit(EXIT_SUCCESS); | ||
6527 | } | ||
6528 | |||
6529 | void display_composite_type() | ||
6530 | { | ||
6531 | switch (ct->type) { | ||
6532 | case MAILMIME_COMPOSITE_TYPE_MESSAGE: | ||
6533 | printf("composite type is message\n"); | ||
6534 | break; | ||
6535 | case MAILMIME_COMPOSITE_TYPE_MULTIPART: | ||
6536 | printf("composite type is multipart\n"); | ||
6537 | break; | ||
6538 | case MAILMIME_COMPOSITE_TYPE_EXTENSION: | ||
6539 | printf("composite type: %s\n", ct->ct_token); | ||
6540 | break; | ||
6541 | } | ||
6542 | } | ||
6543 | </programlisting> | ||
6544 | </example> | ||
6545 | |||
6546 | </sect2> | ||
6547 | |||
6548 | <!-- mailmime_content --> | ||
6549 | <sect2 id="mailmime-content"> | ||
6550 | <title>mailmime_content - MIME content type (Content-Type)</title> | ||
6551 | |||
6552 | <programlisting role="C"> | ||
6553 | #include <libetpan/libetpan.h> | ||
6554 | |||
6555 | struct mailmime_content { | ||
6556 | struct mailmime_type * ct_type; | ||
6557 | char * ct_subtype; | ||
6558 | clist * ct_parameters; /* elements are (struct mailmime_parameter *) */ | ||
6559 | }; | ||
6560 | |||
6561 | struct mailmime_content * | ||
6562 | mailmime_content_new(struct mailmime_type * ct_type, | ||
6563 | char * ct_subtype, | ||
6564 | clist * ct_parameters); | ||
6565 | |||
6566 | void mailmime_content_free(struct mailmime_content * content); | ||
6567 | </programlisting> | ||
6568 | |||
6569 | <para> | ||
6570 | This is a MIME content type such as <command>message/rfc822</command> or | ||
6571 | <command>text/plain</command>. | ||
6572 | </para> | ||
6573 | |||
6574 | <itemizedlist> | ||
6575 | <listitem> | ||
6576 | <para> | ||
6577 | <command>ct_type</command> is the main MIME type, | ||
6578 | for example <command>text</command> in | ||
6579 | <command>plain/text</command> | ||
6580 | (see <xref linkend="mailmime-type">). | ||
6581 | </para> | ||
6582 | <para> | ||
6583 | <command>ct_subtype</command> is the MIME subtype, | ||
6584 | for example <command>plain</command> in | ||
6585 | <command>plain/text</command>. | ||
6586 | </para> | ||
6587 | </listitem> | ||
6588 | <listitem> | ||
6589 | <para> | ||
6590 | <command>ct_parameters</command> is the list of parameters for | ||
6591 | the given MIME type. For example, for <command>plain/text</command>, | ||
6592 | we can find <command>charset=iso-8859-1</command>, | ||
6593 | <command>format=flowed</command>. Each element of the list | ||
6594 | if of type <command>struct mailmime_parameter *</command> | ||
6595 | (see <xref linkend="mailmime-parameter">). | ||
6596 | </para> | ||
6597 | </listitem> | ||
6598 | </itemizedlist> | ||
6599 | |||
6600 | <para> | ||
6601 | <command>mailmime_content_new()</command> creates and initializes | ||
6602 | a data structure with a value. | ||
6603 | Structures given as argument are referenced by the created | ||
6604 | object and will be freed if the object is released. | ||
6605 | </para> | ||
6606 | |||
6607 | <para> | ||
6608 | <command>mailmime_content_free()</command> frees memory used by | ||
6609 | the structure and substructures will also be released. | ||
6610 | </para> | ||
6611 | |||
6612 | <example> | ||
6613 | <title>Creation and display of MIME content type</title> | ||
6614 | <programlisting role="C"> | ||
6615 | #include <libetpan/libetpan.h> | ||
6616 | |||
6617 | int main(void) | ||
6618 | { | ||
6619 | struct mailmime_content * content; | ||
6620 | struct mailmime_type * type; | ||
6621 | struct mailmime_discrete_type * dt; | ||
6622 | struct mailmime_parameter * param; | ||
6623 | clist * param_list; | ||
6624 | |||
6625 | dt = mailmime_discrete_type_new(MAILMIME_DISCRETE_TYPE_TEXT, NULL); | ||
6626 | type = mailmime_type_new(MAILMIME_TYPE_DISCRETE_TYPE, dt, NUL); | ||
6627 | param_list = clist_new(); | ||
6628 | param = mailmime_parameter_new(strdup("charset"), strdup("iso-8859-1")); | ||
6629 | clist_append(param_list, param); | ||
6630 | |||
6631 | content = mailmime_content_new(type, strdup("plain"), param_list); | ||
6632 | |||
6633 | /* do your things */ | ||
6634 | |||
6635 | exit(EXIT_SUCCESS); | ||
6636 | } | ||
6637 | |||
6638 | void display_mime_content(struct mailmime_content * content_type) | ||
6639 | { | ||
6640 | clistiter * cur; | ||
6641 | |||
6642 | printf("type:\n"); | ||
6643 | display_type(content_type->ct_type); | ||
6644 | printf("\n"); | ||
6645 | printf("subtype: %s\n", content_type->ct_subtype); | ||
6646 | printf("\n"); | ||
6647 | |||
6648 | for(cur = clist_begin(content_type->ct_parameters) ; cur != NULL ; | ||
6649 | cur = clist_next(cur)) { | ||
6650 | struct mailmime_parameter * param; | ||
6651 | |||
6652 | param = clist_content(cur); | ||
6653 | display_mime_parameter(param); | ||
6654 | printf("\n"); | ||
6655 | } | ||
6656 | printf("\n"); | ||
6657 | } | ||
6658 | </programlisting> | ||
6659 | </example> | ||
6660 | |||
6661 | </sect2> | ||
6662 | |||
6663 | <!-- mailmime_discrete_type --> | ||
6664 | <sect2 id="mailmime-discrete-type"> | ||
6665 | <title>mailmime_discrete_type - MIME discrete type</title> | ||
6666 | |||
6667 | <programlisting role="C"> | ||
6668 | #include <libetpan/libetpan.h> | ||
6669 | |||
6670 | enum { | ||
6671 | MAILMIME_DISCRETE_TYPE_ERROR, | ||
6672 | MAILMIME_DISCRETE_TYPE_TEXT, | ||
6673 | MAILMIME_DISCRETE_TYPE_IMAGE, | ||
6674 | MAILMIME_DISCRETE_TYPE_AUDIO, | ||
6675 | MAILMIME_DISCRETE_TYPE_VIDEO, | ||
6676 | MAILMIME_DISCRETE_TYPE_APPLICATION, | ||
6677 | MAILMIME_DISCRETE_TYPE_EXTENSION | ||
6678 | }; | ||
6679 | |||
6680 | struct mailmime_discrete_type { | ||
6681 | int dt_type; | ||
6682 | char * dt_extension; | ||
6683 | }; | ||
6684 | |||
6685 | struct mailmime_discrete_type * | ||
6686 | mailmime_discrete_type_new(int dt_type, char * dt_extension); | ||
6687 | |||
6688 | void mailmime_discrete_type_free(struct mailmime_discrete_type * | ||
6689 | discrete_type); | ||
6690 | </programlisting> | ||
6691 | |||
6692 | <para> | ||
6693 | This is a MIME discrete type such as <command>text</command> or | ||
6694 | <command>image</command>. This is also known as single part. This kind | ||
6695 | of part does not have any child. | ||
6696 | </para> | ||
6697 | |||
6698 | <para> | ||
6699 | <command>dt_type</command> is one of the given values : | ||
6700 | <command>MAILMIME_DISCRETE_TYPE_TEXT</command> if part is text, | ||
6701 | <command>MAILMIME_DISCRETE_TYPE_IMAGE</command> if part is an image, | ||
6702 | <command>MAILMIME_DISCRETE_TYPE_AUDIO</command> if part is | ||
6703 | audio data, | ||
6704 | <command>MAILMIME_DISCRETE_TYPE_VIDEO</command> if part is video, | ||
6705 | <command>MAILMIME_DISCRETE_TYPE_APPLICATION</command> if | ||
6706 | part is application data or | ||
6707 | <command>MAILMIME_DISCRETE_TYPE_EXTENSION</command> for other. | ||
6708 | In the case of <command>MAILMIME_DISCRETE_TYPE_EXTENSION</command>, | ||
6709 | <command>dt_extension</command> is filled in. | ||
6710 | <command>MAILMIME_DISCRETE_TYPE_ERROR</command> is used internally. | ||
6711 | </para> | ||
6712 | |||
6713 | <para> | ||
6714 | <command>mailmime_discrete_type_new()</command> creates and | ||
6715 | initializes | ||
6716 | a data structure with a value. | ||
6717 | Structures given as argument are referenced by the created | ||
6718 | object and will be freed if the object is released. | ||
6719 | </para> | ||
6720 | |||
6721 | <para> | ||
6722 | <command>mailmime_discrete_type_free()</command> frees | ||
6723 | memory used by | ||
6724 | the structure and substructures will also be released. | ||
6725 | </para> | ||
6726 | |||
6727 | <example> | ||
6728 | <title>Creation and display of MIME discrete type</title> | ||
6729 | <programlisting role="C"> | ||
6730 | #include <libetpan/libetpan.h> | ||
6731 | |||
6732 | /* standard type */ | ||
6733 | |||
6734 | int main(int argc, char ** argv) | ||
6735 | { | ||
6736 | struct mailmime_discrete_type * discrete_type; | ||
6737 | |||
6738 | discrete_type = mailmime_discrete_type_new(MAILMIME_DISCRETE_TYPE_TEXT, | ||
6739 | NULL); | ||
6740 | |||
6741 | /* do the things */ | ||
6742 | |||
6743 | mailmime_discrete_type_free(discrete_type); | ||
6744 | } | ||
6745 | |||
6746 | /* extension */ | ||
6747 | |||
6748 | int main(int argc, char ** argv) | ||
6749 | { | ||
6750 | struct mailmime_discrete_type * discrete_type; | ||
6751 | |||
6752 | discrete_type = mailmime_discrete_type_new(MAILMIME_DISCRETE_TYPE_EXTENSION, | ||
6753 | strdup("my-type")); | ||
6754 | |||
6755 | /* do the things */ | ||
6756 | |||
6757 | mailmime_discrete_type_free(discrete_type); | ||
6758 | } | ||
6759 | |||
6760 | void display_mime_discrete_type(struct mailmime_discrete_type * discrete_type) | ||
6761 | { | ||
6762 | switch (discrete_type->dt_type) { | ||
6763 | case MAILMIME_DISCRETE_TYPE_TEXT: | ||
6764 | printf("text\n"); | ||
6765 | break; | ||
6766 | case MAILMIME_DISCRETE_TYPE_IMAGE: | ||
6767 | printf("image\n"); | ||
6768 | break; | ||
6769 | case MAILMIME_DISCRETE_TYPE_AUDIO: | ||
6770 | printf("audio\n"); | ||
6771 | break; | ||
6772 | case MAILMIME_DISCRETE_TYPE_VIDEO: | ||
6773 | printf("video\n"); | ||
6774 | break; | ||
6775 | case MAILMIME_DISCRETE_TYPE_APPLICATION: | ||
6776 | printf("application\n"); | ||
6777 | break; | ||
6778 | case MAILMIME_DISCRETE_TYPE_EXTENSION: | ||
6779 | printf("extension : %s\n", discrete_type->dt_extension); | ||
6780 | break; | ||
6781 | } | ||
6782 | } | ||
6783 | </programlisting> | ||
6784 | </example> | ||
6785 | |||
6786 | </sect2> | ||
6787 | |||
6788 | <!-- mailmime_field --> | ||
6789 | <sect2 id="mailmime-field"> | ||
6790 | <title>mailmime_field - MIME header field</title> | ||
6791 | |||
6792 | <programlisting role="C"> | ||
6793 | #include <libetpan/libetpan.h> | ||
6794 | |||
6795 | enum { | ||
6796 | MAILMIME_FIELD_NONE, | ||
6797 | MAILMIME_FIELD_TYPE, | ||
6798 | MAILMIME_FIELD_TRANSFER_ENCODING, | ||
6799 | MAILMIME_FIELD_ID, | ||
6800 | MAILMIME_FIELD_DESCRIPTION, | ||
6801 | MAILMIME_FIELD_VERSION, | ||
6802 | MAILMIME_FIELD_DISPOSITION, | ||
6803 | MAILMIME_FIELD_LANGUAGE, | ||
6804 | }; | ||
6805 | |||
6806 | struct mailmime_field { | ||
6807 | int fld_type; | ||
6808 | union { | ||
6809 | struct mailmime_content * fld_content; | ||
6810 | struct mailmime_mechanism * fld_encoding; | ||
6811 | char * fld_id; | ||
6812 | char * fld_description; | ||
6813 | uint32_t fld_version; | ||
6814 | struct mailmime_disposition * fld_disposition; | ||
6815 | struct mailmime_language * fld_language; | ||
6816 | } fld_data; | ||
6817 | }; | ||
6818 | |||
6819 | struct mailmime_field * | ||
6820 | mailmime_field_new(int fld_type, | ||
6821 | struct mailmime_content * fld_content, | ||
6822 | struct mailmime_mechanism * fld_encoding, | ||
6823 | char * fld_id, | ||
6824 | char * fld_description, | ||
6825 | uint32_t fld_version, | ||
6826 | struct mailmime_disposition * fld_disposition, | ||
6827 | struct mailmime_language * fld_language); | ||
6828 | |||
6829 | void mailmime_field_free(struct mailmime_field * field); | ||
6830 | </programlisting> | ||
6831 | |||
6832 | <para> | ||
6833 | This is a parsed MIME header field; | ||
6834 | </para> | ||
6835 | |||
6836 | <itemizedlist> | ||
6837 | <listitem> | ||
6838 | <para> | ||
6839 | <command>fld_type</command> is the type of MIME header field. The value can | ||
6840 | be | ||
6841 | <command>MAILMIME_FIELD_TYPE</command> | ||
6842 | if field is <command>Content-Type</command>, | ||
6843 | <command>MAILMIME_FIELD_TRANSFER_ENCODING</command> | ||
6844 | if field is <command>Content-Transfer-Encoding</command>, | ||
6845 | <command>MAILMIME_FIELD_ID</command> | ||
6846 | if field is <command>Content-ID</command>, | ||
6847 | <command>MAILMIME_FIELD_DESCRIPTION</command> | ||
6848 | if field is <command>Content-Description</command>, | ||
6849 | <command>MAILMIME_FIELD_VERSION</command> | ||
6850 | if field is <command>MIME-Version</command>, | ||
6851 | <command>MAILMIME_FIELD_DISPOSITION</command> | ||
6852 | if field is <command>Content-Disposition</command> or | ||
6853 | <command>MAILMIME_FIELD_LANGUAGE</command> | ||
6854 | if field is <command>Content-Language</command>. | ||
6855 | <command>MAILMIME_FIELD_NONE</command> is used internally. | ||
6856 | </para> | ||
6857 | </listitem> | ||
6858 | <listitem> | ||
6859 | <para> | ||
6860 | <command>fld_data.fld_content</command> is set in case of | ||
6861 | <command>Content-Type</command>. | ||
6862 | (see <xref linkend="mailmime-content">). | ||
6863 | </para> | ||
6864 | </listitem> | ||
6865 | <listitem> | ||
6866 | <para> | ||
6867 | <command>fld_data.fld_encoding</command> is set in case of | ||
6868 | <command>Content-Transfer-Encoding</command>. | ||
6869 | (see <xref linkend="mailmime-mechanism">). | ||
6870 | </para> | ||
6871 | </listitem> | ||
6872 | <listitem> | ||
6873 | <para> | ||
6874 | <command>fld_data.fld_id</command> is set in case of | ||
6875 | <command>Content-ID</command>. This is a string. | ||
6876 | </para> | ||
6877 | </listitem> | ||
6878 | <listitem> | ||
6879 | <para> | ||
6880 | <command>fld_data.fld_description</command> is set in case of | ||
6881 | <command>Content-Description</command>. This is a string. | ||
6882 | </para> | ||
6883 | </listitem> | ||
6884 | <listitem> | ||
6885 | <para> | ||
6886 | <command>fld_data.fld_version</command> is set in case of | ||
6887 | <command>MIME-Version</command>. This is an integer built | ||
6888 | using the following formula : | ||
6889 | <command>fld_version = major * 2^16 + minor</command>. | ||
6890 | Currenly MIME-Version is always <command>1.0</command>, this means that | ||
6891 | fld_version will always be <command>2^16</command> (in C language, | ||
6892 | this is <command>1 << 16</command>). | ||
6893 | </para> | ||
6894 | </listitem> | ||
6895 | <listitem> | ||
6896 | <para> | ||
6897 | <command>fld_data.fld_disposition</command> is set in case of | ||
6898 | <command>Content-Disposition</command>. | ||
6899 | (see <xref linkend="mailmime-disposition">). | ||
6900 | </para> | ||
6901 | </listitem> | ||
6902 | <listitem> | ||
6903 | <para> | ||
6904 | <command>fld_data.fld_language</command> is set in case of | ||
6905 | <command>Content-Language</command>. | ||
6906 | (see <xref linkend="mailmime-language">). | ||
6907 | </para> | ||
6908 | </listitem> | ||
6909 | </itemizedlist> | ||
6910 | |||
6911 | <para> | ||
6912 | <command>mailmime_field_new()</command> creates and initializes | ||
6913 | a data structure with a value. | ||
6914 | Structures given as argument are referenced by the created | ||
6915 | object and will be freed if the object is released. | ||
6916 | </para> | ||
6917 | |||
6918 | <para> | ||
6919 | <command>mailmime_field_free()</command> frees memory used by | ||
6920 | the structure and substructures will also be released. | ||
6921 | </para> | ||
6922 | |||
6923 | <example> | ||
6924 | <title>Creation and display of MIME header field</title> | ||
6925 | <programlisting role="C"> | ||
6926 | #include <libetpan/libetpan.h> | ||
6927 | |||
6928 | int main(int argc, char ** argv) | ||
6929 | { | ||
6930 | struct mailmime_field * field; | ||
6931 | struct mailmime_mechanism * encoding; | ||
6932 | |||
6933 | encoding = mailmime_mechanism_new(MAILMIME_MECHANISM_BASE64, NULL); | ||
6934 | |||
6935 | field = mailmime_field_new(MAILMIME_FIELD_TRANSFER_ENCODING, | ||
6936 | NULL, encoding, NULL, NULL, 0, NULL, NULL); | ||
6937 | |||
6938 | /* do the things */ | ||
6939 | |||
6940 | mailmime_field_free(field); | ||
6941 | } | ||
6942 | |||
6943 | void display_mime_field(struct mailmime_field * field) | ||
6944 | { | ||
6945 | switch (field->fld_type) { | ||
6946 | case MAILMIME_FIELD_TYPE: | ||
6947 | printf("content-type:"); | ||
6948 | display_mime_content(field->fld_data.fld_content); | ||
6949 | break; | ||
6950 | case MAILMIME_FIELD_TRANSFER_ENCODING: | ||
6951 | printf("content-transfer-encoding:"); | ||
6952 | display_mime_mechanism(field->fld_data.fld_encoding); | ||
6953 | break; | ||
6954 | case MAILMIME_FIELD_ID: | ||
6955 | printf("content-id: %s\n", field->fld_data.fld_id); | ||
6956 | break; | ||
6957 | case MAILMIME_FIELD_DESCRIPTION: | ||
6958 | printf("content-description: %s\n", field->fld_data.fld_description); | ||
6959 | break; | ||
6960 | case MAILMIME_FIELD_VERSION: | ||
6961 | printf("mime-version: %i.%i\n", | ||
6962 | field->version>> 16, field->fld_data.fld_version & 0xFFFF); | ||
6963 | break; | ||
6964 | case MAILMIME_FIELD_DISPOSITION: | ||
6965 | printf("content-disposition:"); | ||
6966 | display_mime_disposition(field->fld_data.fld_disposition); | ||
6967 | break; | ||
6968 | case MAILMIME_FIELD_LANGUAGE: | ||
6969 | printf("content-language:"); | ||
6970 | display_mime_language(field->fld_data.fld_language); | ||
6971 | break; | ||
6972 | } | ||
6973 | } | ||
6974 | </programlisting> | ||
6975 | </example> | ||
6976 | </sect2> | ||
6977 | |||
6978 | <!-- mailmime_mechanism --> | ||
6979 | <sect2 id="mailmime-mechanism"> | ||
6980 | <title>mailmime_mechanism - MIME transfer encoding mechanism (Content-Transfer-Encoding)</title> | ||
6981 | |||
6982 | <programlisting role="C"> | ||
6983 | #include <libetpan/libetpan.h> | ||
6984 | |||
6985 | enum { | ||
6986 | MAILMIME_MECHANISM_ERROR, | ||
6987 | MAILMIME_MECHANISM_7BIT, | ||
6988 | MAILMIME_MECHANISM_8BIT, | ||
6989 | MAILMIME_MECHANISM_BINARY, | ||
6990 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, | ||
6991 | MAILMIME_MECHANISM_BASE64, | ||
6992 | MAILMIME_MECHANISM_TOKEN | ||
6993 | }; | ||
6994 | |||
6995 | struct mailmime_mechanism { | ||
6996 | int enc_type; | ||
6997 | char * enc_token; | ||
6998 | }; | ||
6999 | |||
7000 | struct mailmime_mechanism * mailmime_mechanism_new(int enc_type, char * enc_token); | ||
7001 | |||
7002 | void mailmime_mechanism_free(struct mailmime_mechanism * mechanism); | ||
7003 | </programlisting> | ||
7004 | |||
7005 | <para> | ||
7006 | This is a MIME transfer encoding mechanism description. | ||
7007 | </para> | ||
7008 | |||
7009 | <para> | ||
7010 | <command>enc_type</command> is an encoding type. The value of this field | ||
7011 | can be | ||
7012 | <command>MAILMIME_MECHANISM_7BIT</command> | ||
7013 | if mechanism is <command>7bit</command>, | ||
7014 | <command>MAILMIME_MECHANISM_8BIT</command> | ||
7015 | if mechanism is <command>8bit</command>, | ||
7016 | <command>MAILMIME_MECHANISM_BINARY</command> | ||
7017 | if mechanism is <command>binary</command>, | ||
7018 | <command>MAILMIME_MECHANISM_QUOTED_PRINTABLE</command> | ||
7019 | if mechanism is <command>quoted-printable</command>, | ||
7020 | <command>MAILMIME_MECHANISM_BASE64</command> | ||
7021 | if mechanism is <command>base64</command> or | ||
7022 | <command>MAILMIME_MECHANISM_TOKEN</command> for other. | ||
7023 | In case of <command>MAILMIME_MECHANISM_TOKEN</command>, | ||
7024 | field <command>enc_token</command> is filled in. | ||
7025 | <command>MAILMIME_MECHANISM_ERROR</command> is used internally. | ||
7026 | </para> | ||
7027 | |||
7028 | <para> | ||
7029 | <command>mailmime_mechanism_new()</command> creates and initializes | ||
7030 | a data structure with a value. | ||
7031 | Structures given as argument are referenced by the created | ||
7032 | object and will be freed if the object is released. | ||
7033 | </para> | ||
7034 | |||
7035 | <para> | ||
7036 | <command>mailmime_mechanism_free()</command> frees memory used by | ||
7037 | the structure and substructures will also be released. | ||
7038 | </para> | ||
7039 | |||
7040 | <example> | ||
7041 | <title>Creation and display of MIME transfer encoding mechanism</title> | ||
7042 | <programlisting role="C"> | ||
7043 | #include <libetpan/libetpan.h> | ||
7044 | |||
7045 | int main(int argc, char ** argv) | ||
7046 | { | ||
7047 | struct mailmime_mechanism * encoding; | ||
7048 | |||
7049 | encoding = mailmime_mechanism_new(MAILMIME_MECHANISM_QUOTED_PRINTABLE, NULL); | ||
7050 | |||
7051 | /* do the things */ | ||
7052 | |||
7053 | mailmime_mechanism_free(encoding); | ||
7054 | } | ||
7055 | |||
7056 | int main(int argc, char ** argv) | ||
7057 | { | ||
7058 | struct mailmime_mechanism * encoding; | ||
7059 | |||
7060 | encoding = mailmime_mechanism_new(MAILMIME_MECHANISM_TOKEN, | ||
7061 | strdup("uuencoding")); | ||
7062 | |||
7063 | /* do the things */ | ||
7064 | |||
7065 | mailmime_mechanism_free(encoding); | ||
7066 | } | ||
7067 | |||
7068 | void display_mime_mechanism(struct mailmime_mechanism * encoding) | ||
7069 | { | ||
7070 | switch (encoding->enc_type) { | ||
7071 | case MAILMIME_MECHANISM_7BIT: | ||
7072 | printf("7bit\n"); | ||
7073 | break; | ||
7074 | case MAILMIME_MECHANISM_8BIT: | ||
7075 | printf("8bit\n"); | ||
7076 | break; | ||
7077 | case MAILMIME_MECHANISM_BINARY: | ||
7078 | printf("binary\n"); | ||
7079 | break; | ||
7080 | case MAILMIME_MECHANISM_QUOTED_PRINTABLE: | ||
7081 | printf("quoted-printable\n"); | ||
7082 | break; | ||
7083 | case MAILMIME_MECHANISM_BASE64: | ||
7084 | printf("base64\n"); | ||
7085 | break; | ||
7086 | case MAILMIME_MECHANISM_TOKEN: | ||
7087 | printf("extension : %s\n", encoding->enc_token); | ||
7088 | break; | ||
7089 | } | ||
7090 | } | ||
7091 | </programlisting> | ||
7092 | </example> | ||
7093 | </sect2> | ||
7094 | |||
7095 | <!-- mailmime_fields --> | ||
7096 | <sect2 id="mailmime-fields"> | ||
7097 | <title>mailmime_fields - header fields</title> | ||
7098 | |||
7099 | <programlisting role="C"> | ||
7100 | #include <libetpan/libetpan.h> | ||
7101 | |||
7102 | struct mailmime_fields { | ||
7103 | clist * fld_list; /* list of (struct mailmime_field *) */ | ||
7104 | }; | ||
7105 | |||
7106 | struct mailmime_fields * mailmime_fields_new(clist * fld_list); | ||
7107 | |||
7108 | void mailmime_fields_free(struct mailmime_fields * fields); | ||
7109 | </programlisting> | ||
7110 | |||
7111 | <para> | ||
7112 | This is the header fields of a MIME part. | ||
7113 | </para> | ||
7114 | |||
7115 | <para> | ||
7116 | <command>fld_list</command> is the list of the header fields. | ||
7117 | Each element of the list is a <command>mailmime_field</command> | ||
7118 | (See <xref linkend="mailmime-field">). | ||
7119 | </para> | ||
7120 | |||
7121 | <para> | ||
7122 | <command>mailmime_fields_new()</command> creates and initializes | ||
7123 | a data structure with a value. | ||
7124 | Structures given as argument are referenced by the created | ||
7125 | object and will be freed if the object is released. | ||
7126 | </para> | ||
7127 | |||
7128 | <para> | ||
7129 | <command>mailmime_fields_free()</command> frees memory used by | ||
7130 | the structure and substructures will also be released. | ||
7131 | </para> | ||
7132 | |||
7133 | <example> | ||
7134 | <title>Creation and display of MIME fields</title> | ||
7135 | <programlisting role="C"> | ||
7136 | #include <libetpan/libetpan.h> | ||
7137 | |||
7138 | int main(int argc, char ** argv) | ||
7139 | { | ||
7140 | struct mailmime_field * field; | ||
7141 | struct mailmime_fields * fields; | ||
7142 | clist * list; | ||
7143 | struct mailmime_mechanism * encoding; | ||
7144 | struct mailmime_disposition * disposition; | ||
7145 | |||
7146 | list = clist_new(); | ||
7147 | |||
7148 | encoding = mailmime_mechanism_new(MAILMIME_MECHANISM_BASE64, NULL); | ||
7149 | field = mailmime_field_new(MAILMIME_FIELD_TRANSFER_ENCODING, | ||
7150 | NULL, encoding, NULL, NULL, 0, NULL, NULL); | ||
7151 | clist_append(list, field); | ||
7152 | |||
7153 | field = mailmime_field_new(MAILMIME_FIELD_VERSION, | ||
7154 | NULL, NULL, NULL, NULL, 1 << 16, NULL, NULL); | ||
7155 | clist_append(list, field); | ||
7156 | |||
7157 | /* look at the example in mailmime_disposition to see how to | ||
7158 | build a mailmime_disposition */ | ||
7159 | disposition = build_mime_disposition(); | ||
7160 | field = mailmime_field_new(MAILMIME_FIELD_DISPOSITION, | ||
7161 | NULL, NULL, NULL, NULL, 0, disposition, NULL); | ||
7162 | clist_append(list, field); | ||
7163 | |||
7164 | fields = mailmime_fields_new(list); | ||
7165 | |||
7166 | /* do the things */ | ||
7167 | |||
7168 | mailmime_fields_free(fields); | ||
7169 | } | ||
7170 | |||
7171 | void display_mime_fields(struct mailmime_fields * fields) | ||
7172 | { | ||
7173 | clistiter * cur; | ||
7174 | |||
7175 | for(cur = clist_begin(fields->fld_list ; cur != NULL ; | ||
7176 | cur = clist_next(cur)) { | ||
7177 | struct mailmime_field * field; | ||
7178 | |||
7179 | field = clist_content(cur); | ||
7180 | display_field(field); | ||
7181 | } | ||
7182 | } | ||
7183 | </programlisting> | ||
7184 | </example> | ||
7185 | </sect2> | ||
7186 | |||
7187 | <!-- mailmime_parameter --> | ||
7188 | <sect2 id="mailmime-parameter"> | ||
7189 | <title>mailmime_parameter - MIME type parameter</title> | ||
7190 | |||
7191 | <programlisting role="C"> | ||
7192 | struct mailmime_parameter { | ||
7193 | char * pa_name; | ||
7194 | char * pa_value; | ||
7195 | }; | ||
7196 | </programlisting> | ||
7197 | |||
7198 | <para> | ||
7199 | This is the MIME type parameter in | ||
7200 | <command>Content-Type</command> MIME header | ||
7201 | field. For example, this can be | ||
7202 | <command>charset="iso-8859-1"</command>. | ||
7203 | </para> | ||
7204 | |||
7205 | <itemizedlist> | ||
7206 | <listitem> | ||
7207 | <para> | ||
7208 | <command>pa_name</command> is the name of the parameter, | ||
7209 | for example : <command>charset</command>. | ||
7210 | </para> | ||
7211 | </listitem> | ||
7212 | <listitem> | ||
7213 | <para> | ||
7214 | <command>pa_value</command> is the value of the parameter, | ||
7215 | for example : <command>iso-8859-1</command>. | ||
7216 | </para> | ||
7217 | </listitem> | ||
7218 | </itemizedlist> | ||
7219 | |||
7220 | <para> | ||
7221 | <command>mailmime_parameter_new()</command> creates and initializes | ||
7222 | a data structure with a value. | ||
7223 | Structures given as argument are referenced by the created | ||
7224 | object and will be freed if the object is released. | ||
7225 | </para> | ||
7226 | |||
7227 | <para> | ||
7228 | <command>mailmime_parameter_free()</command> frees memory used by | ||
7229 | the structure and substructures will also be released. | ||
7230 | </para> | ||
7231 | |||
7232 | <example> | ||
7233 | <title>Creation and display of MIME type parameter</title> | ||
7234 | <programlisting role="C"> | ||
7235 | #include <libetpan/libetpan.h> | ||
7236 | |||
7237 | int main(int argc, char ** argv) | ||
7238 | { | ||
7239 | struct mailmime_parameter * param; | ||
7240 | |||
7241 | param = mailmime_parameter_new(strdup("charset"), strdup("iso-8859-1")); | ||
7242 | |||
7243 | /* do the things */ | ||
7244 | |||
7245 | mailmime_parameter_free(param); | ||
7246 | } | ||
7247 | |||
7248 | void display_mime_parameter(struct mailmime_parameter * param) | ||
7249 | { | ||
7250 | printf("%s = %s\n", param->pa_name, param->pa_value); | ||
7251 | } | ||
7252 | </programlisting> | ||
7253 | </example> | ||
7254 | |||
7255 | </sect2> | ||
7256 | |||
7257 | <!-- mailmime_type --> | ||
7258 | <sect2 id="mailmime-type"> | ||
7259 | <title>mailmime_type - MIME main type</title> | ||
7260 | |||
7261 | <programlisting role="C"> | ||
7262 | #include <libetpan/libetpan.h> | ||
7263 | |||
7264 | enum { | ||
7265 | MAILMIME_TYPE_ERROR, | ||
7266 | MAILMIME_TYPE_DISCRETE_TYPE, | ||
7267 | MAILMIME_TYPE_COMPOSITE_TYPE | ||
7268 | }; | ||
7269 | |||
7270 | struct mailmime_type { | ||
7271 | int tp_type; | ||
7272 | union { | ||
7273 | struct mailmime_discrete_type * tp_discrete_type; | ||
7274 | struct mailmime_composite_type * tp_composite_type; | ||
7275 | } tp_data; | ||
7276 | }; | ||
7277 | |||
7278 | struct mailmime_type * | ||
7279 | mailmime_type_new(int tp_type, | ||
7280 | struct mailmime_discrete_type * tp_discrete_type, | ||
7281 | struct mailmime_composite_type * tp_composite_type); | ||
7282 | |||
7283 | void mailmime_type_free(struct mailmime_type * type); | ||
7284 | </programlisting> | ||
7285 | |||
7286 | <para> | ||
7287 | This is the MIME main type (no subtype, no parameter). | ||
7288 | </para> | ||
7289 | |||
7290 | <itemizedlist> | ||
7291 | <listitem> | ||
7292 | <para> | ||
7293 | <command>tp_type</command>. The value of this field | ||
7294 | is either <command>MAILMIME_TYPE_DISCRETE_TYPE</command> for MIME discrete type, | ||
7295 | or <command>MAILMIME_TYPE_COMPOSITE_TYPE</command> for MIME composite type. | ||
7296 | <command>MAILMIME_TYPE_ERROR</command> is used internally. | ||
7297 | </para> | ||
7298 | </listitem> | ||
7299 | <listitem> | ||
7300 | <para> | ||
7301 | <command>tp_data.tp_discrete_type</command> is set when <command>tp_type</command> | ||
7302 | is <command>MAILMIME_TYPE_DISCRETE_TYPE</command> | ||
7303 | (see <xref linkend="mailmime-discrete-type">). | ||
7304 | </para> | ||
7305 | </listitem> | ||
7306 | <listitem> | ||
7307 | <para> | ||
7308 | <command>tp_data.tp_composite_type</command> is set when <command>tp_type</command> | ||
7309 | is <command>MAILMIME_TYPE_COMPOSITE_TYPE</command> | ||
7310 | (see <xref linkend="mailmime-composite-type">). | ||
7311 | </para> | ||
7312 | </listitem> | ||
7313 | </itemizedlist> | ||
7314 | |||
7315 | <para> | ||
7316 | <command>mailmime_discrete_type_new()</command> creates and | ||
7317 | initializes | ||
7318 | a data structure with a value. | ||
7319 | Structures given as argument are referenced by the created | ||
7320 | object and will be freed if the object is released. | ||
7321 | </para> | ||
7322 | |||
7323 | <para> | ||
7324 | <command>mailmime_discrete_type_free()</command> frees | ||
7325 | memory used by | ||
7326 | the structure and substructures will also be released. | ||
7327 | </para> | ||
7328 | |||
7329 | <example> | ||
7330 | <title>Creation and display of MIME main type</title> | ||
7331 | <programlisting role="C"> | ||
7332 | #include <libetpan/libetpan.h> | ||
7333 | |||
7334 | int main(int argc, char ** argv) | ||
7335 | { | ||
7336 | struct mailmime_type * type; | ||
7337 | struct mailmime_discrete_type * discrete_type; | ||
7338 | |||
7339 | discrete_type = | ||
7340 | mailmime_discrete_type_new(MAILMIME_DISCRETE_TYPE_TEXT, NULL); | ||
7341 | type = mailmime_type_new(MAILMIME_TYPE_DISCRETE_TYPE, discrete_type, NULL); | ||
7342 | |||
7343 | /* do the things */ | ||
7344 | |||
7345 | mailmime_type_free(type); | ||
7346 | } | ||
7347 | |||
7348 | int main(int argc, char ** argv) | ||
7349 | { | ||
7350 | struct mailmime_type * type; | ||
7351 | struct mailmime_composite_type * composite_type; | ||
7352 | |||
7353 | composite_type = | ||
7354 | mailmime_composite_type_new(MAILMIME_COMPOSITE_TYPE_MULTIPART, NULL); | ||
7355 | type = mailmime_type_new(MAILMIME_TYPE_COMPOSITE_TYPE, NULL, composite_type); | ||
7356 | |||
7357 | /* do the things */ | ||
7358 | |||
7359 | mailmime_type_free(type); | ||
7360 | } | ||
7361 | |||
7362 | void display_mime_type(struct mailmime_type * type) | ||
7363 | { | ||
7364 | printf("mime type:\n"); | ||
7365 | switch (type->tp_type) { | ||
7366 | case MAILMIME_TYPE_DISCRETE_TYPE: | ||
7367 | printf("discrete type:\n"); | ||
7368 | display_mime_discrete_type(type->tp_data.tp_discrete_type); | ||
7369 | break; | ||
7370 | case MAILMIME_TYPE_COMPOSITE_TYPE: | ||
7371 | printf("composite type:\n"); | ||
7372 | display_mime_composite_type(type->tp_data.tp_composite_type); | ||
7373 | break; | ||
7374 | } | ||
7375 | printf("\n"); | ||
7376 | } | ||
7377 | </programlisting> | ||
7378 | </example> | ||
7379 | </sect2> | ||
7380 | |||
7381 | <!-- mailmime_discrete_type --> | ||
7382 | <sect2 id="mailmime-language"> | ||
7383 | <title>mailmime_language - Language of MIME part</title> | ||
7384 | |||
7385 | <programlisting role="C"> | ||
7386 | #include <libetpan/libetpan.h> | ||
7387 | |||
7388 | struct mailmime_language { | ||
7389 | clist * lg_list; /* atom (char *) */ | ||
7390 | }; | ||
7391 | |||
7392 | struct mailmime_language * mailmime_language_new(clist * lg_list); | ||
7393 | |||
7394 | void mailmime_language_free(struct mailmime_language * lang); | ||
7395 | </programlisting> | ||
7396 | |||
7397 | <para> | ||
7398 | This is the language used in the MIME part. | ||
7399 | </para> | ||
7400 | |||
7401 | <para> | ||
7402 | <command>lg_list</command> is the list of codes of languages used | ||
7403 | in the MIME part. This is a list of strings. | ||
7404 | </para> | ||
7405 | |||
7406 | <para> | ||
7407 | <command>mailmime_language_new()</command> creates and | ||
7408 | initializes | ||
7409 | a data structure with a value. | ||
7410 | Structures given as argument are referenced by the created | ||
7411 | object and will be freed if the object is released. | ||
7412 | </para> | ||
7413 | |||
7414 | <para> | ||
7415 | <command>mailmime_language_free()</command> frees | ||
7416 | memory used by | ||
7417 | the structure and substructures will also be released. | ||
7418 | </para> | ||
7419 | |||
7420 | <example> | ||
7421 | <title>Creation and display of language of MIME part</title> | ||
7422 | <programlisting role="C"> | ||
7423 | #include <libetpan/libetpan.h> | ||
7424 | |||
7425 | int main(int argc, char ** argv) | ||
7426 | { | ||
7427 | struct mailmime_language * language; | ||
7428 | clist * list; | ||
7429 | |||
7430 | list = clist_new(); | ||
7431 | |||
7432 | clist_append(list, strdup("fr")); | ||
7433 | clist_append(list, strdup("en")); | ||
7434 | |||
7435 | language = mailmime_language_new(list); | ||
7436 | |||
7437 | /* do the things */ | ||
7438 | |||
7439 | mailmime_language_free(language); | ||
7440 | } | ||
7441 | |||
7442 | void display_mime_language(struct mailmime_language * language) | ||
7443 | { | ||
7444 | clistiter * cur; | ||
7445 | |||
7446 | printf("languages: "); | ||
7447 | for(cur = clist_begin(language->lg_list) ; cur != NULL ; | ||
7448 | cur = clist_next(cur)) { | ||
7449 | char * name; | ||
7450 | |||
7451 | name = clist_content(cur); | ||
7452 | printf("%s ", name); | ||
7453 | } | ||
7454 | printf("\n"); | ||
7455 | } | ||
7456 | </programlisting> | ||
7457 | </example> | ||
7458 | |||
7459 | </sect2> | ||
7460 | |||
7461 | <!-- mailmime_data --> | ||
7462 | <sect2 id="mailmime-data"> | ||
7463 | <title>mailmime_data - Content of MIME part</title> | ||
7464 | |||
7465 | <programlisting role="C"> | ||
7466 | #include <libetpan/libetpan.h> | ||
7467 | |||
7468 | enum { | ||
7469 | MAILMIME_DATA_TEXT, | ||
7470 | MAILMIME_DATA_FILE, | ||
7471 | }; | ||
7472 | |||
7473 | enum { | ||
7474 | MAILMIME_MECHANISM_ERROR, | ||
7475 | MAILMIME_MECHANISM_7BIT, | ||
7476 | MAILMIME_MECHANISM_8BIT, | ||
7477 | MAILMIME_MECHANISM_BINARY, | ||
7478 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, | ||
7479 | MAILMIME_MECHANISM_BASE64, | ||
7480 | MAILMIME_MECHANISM_TOKEN | ||
7481 | }; | ||
7482 | |||
7483 | struct mailmime_data { | ||
7484 | int dt_type; | ||
7485 | int dt_encoding; | ||
7486 | int dt_encoded; | ||
7487 | union { | ||
7488 | struct { | ||
7489 | const char * dt_data; | ||
7490 | size_t dt_length; | ||
7491 | } dt_text; | ||
7492 | char * dt_filename; | ||
7493 | } dt_data; | ||
7494 | }; | ||
7495 | |||
7496 | struct mailmime_data * mailmime_data_new(int dt_type, int dt_encoding, | ||
7497 | int dt_encoded, const char * dt_data, size_t dt_length, | ||
7498 | char * dt_filename); | ||
7499 | |||
7500 | void mailmime_data_free(struct mailmime_data * mime_ </programlisting> | ||
7501 | |||
7502 | <para> | ||
7503 | This is the content of MIME part, content of | ||
7504 | preamble or content of epilogue. | ||
7505 | </para> | ||
7506 | |||
7507 | <para> | ||
7508 | <command>dt_type</command> can be | ||
7509 | <command>MAILMIME_DATA_TEXT</command> if | ||
7510 | the content is a string in memory, | ||
7511 | <command>MAILMIME_DATA_FILE</command> if the | ||
7512 | content is in a file, | ||
7513 | </para> | ||
7514 | |||
7515 | <para> | ||
7516 | <command>dt_encoding</command> is the encoding mechanism | ||
7517 | of the part. The value of this field can be | ||
7518 | <command>MAILMIME_MECHANISM_7BIT</command> if mechanism is | ||
7519 | <command>7bit</command>, | ||
7520 | <command>MAILMIME_MECHANISM_8BIT</command> if mechanism is | ||
7521 | <command>8bit</command>, | ||
7522 | <command>MAILMIME_MECHANISM_BINARY</command> if mechanism is | ||
7523 | <command>binary</command>, | ||
7524 | <command>MAILMIME_MECHANISM_QUOTED_PRINTABLE</command> if | ||
7525 | mechanism is <command>quoted-printable</command>, | ||
7526 | <command>MAILMIME_MECHANISM_BASE64</command> if mechanism is | ||
7527 | <command>base64</command> or | ||
7528 | <command>MAILMIME_MECHANISM_TOKEN</command> for other. If | ||
7529 | <command>MAILMIME_MECHANISM_TOKEN</command>, the part will | ||
7530 | be considered as binary. | ||
7531 | <command>MAILMIME_MECHANISM_ERROR</command> is used internally. | ||
7532 | </para> | ||
7533 | |||
7534 | <para> | ||
7535 | <command>dt_encoded</command> is set to 1 if the part is | ||
7536 | already encoded with the mechanism given in | ||
7537 | <command>dt_encoding</command>. It is set to 0 if the part | ||
7538 | is already decoded or if it is necessary to encode that part | ||
7539 | before rendering it. | ||
7540 | </para> | ||
7541 | |||
7542 | <para> | ||
7543 | <command>dt_data.dt_text.dt_data</command> is a pointer to the | ||
7544 | content of the part and <command>dt_data.dt_text.dt_length</command> | ||
7545 | is the length of the data if <command>dt_type</command> is | ||
7546 | <command>MAILMIME_DATA_TEXT</command>. | ||
7547 | </para> | ||
7548 | |||
7549 | <para> | ||
7550 | <command>dt_data.dt_filename</command> is the name of the file if | ||
7551 | <command>dt_type</command> is <command>MAILMIME_DATA_FILE</command>. | ||
7552 | </para> | ||
7553 | |||
7554 | <para> | ||
7555 | <command>mailmime_data_new()</command> creates and | ||
7556 | initializes | ||
7557 | a data structure with a value. | ||
7558 | Structures given as argument are referenced by the created | ||
7559 | object and will be freed if the object is released. | ||
7560 | </para> | ||
7561 | |||
7562 | <para> | ||
7563 | <command>mailmime_data_free()</command> frees | ||
7564 | memory used by | ||
7565 | the structure and substructures will also be released. | ||
7566 | </para> | ||
7567 | |||
7568 | <example> | ||
7569 | <title>Creation and display of MIME part content</title> | ||
7570 | |||
7571 | <programlisting role="C"> | ||
7572 | #include <libetpan/libetpan.h> | ||
7573 | |||
7574 | /* build data with a string */ | ||
7575 | |||
7576 | int main(int argc, char ** argv) | ||
7577 | { | ||
7578 | struct mailmime_data * data; | ||
7579 | |||
7580 | data = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_BASE64, | ||
7581 | 0, "foo bar", 7, NULL); | ||
7582 | |||
7583 | /* do the things */ | ||
7584 | |||
7585 | mailmime_data_free(data); | ||
7586 | } | ||
7587 | |||
7588 | /* build data with a file */ | ||
7589 | |||
7590 | int main(int argc, char ** argv) | ||
7591 | { | ||
7592 | struct mailmime_data * data; | ||
7593 | |||
7594 | data = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_BASE64, | ||
7595 | 0, NULL, 0, strdup("foo.txt")); | ||
7596 | |||
7597 | /* do the things */ | ||
7598 | |||
7599 | mailmime_data_free(data); | ||
7600 | } | ||
7601 | |||
7602 | void display_mime_data(struct mailmime_data * data) | ||
7603 | { | ||
7604 | switch (data->dt_encoding) { | ||
7605 | case MAILMIME_MECHANISM_7BIT: | ||
7606 | printf("7bit\n"); | ||
7607 | break; | ||
7608 | case MAILMIME_MECHANISM_8BIT: | ||
7609 | printf("8bit\n"); | ||
7610 | break; | ||
7611 | case MAILMIME_MECHANISM_BINARY: | ||
7612 | printf("binary\n"); | ||
7613 | break; | ||
7614 | case MAILMIME_MECHANISM_QUOTED_PRINTABLE: | ||
7615 | printf("quoted-printable\n"); | ||
7616 | break; | ||
7617 | case MAILMIME_MECHANISM_BASE64: | ||
7618 | printf("base64\n"); | ||
7619 | break; | ||
7620 | case MAILMIME_MECHANISM_TOKEN: | ||
7621 | printf("other\n"); | ||
7622 | break; | ||
7623 | } | ||
7624 | |||
7625 | if (data->dt_encoded) | ||
7626 | printf("already encoded\n"); | ||
7627 | else | ||
7628 | printf("not encoded\n"); | ||
7629 | |||
7630 | switch (data->dt_type) { | ||
7631 | MAILMIME_DATA_TEXT: | ||
7632 | printf("data : %p %i\n", data->dt_data.dt_text.dt_data, | ||
7633 | data->dt_data.dt_text.dt_length); | ||
7634 | break; | ||
7635 | MAILMIME_DATA_FILE, | ||
7636 | printf("data (file) : %s\n", data->dt_data.dt_filename); | ||
7637 | break; | ||
7638 | } | ||
7639 | } | ||
7640 | </programlisting> | ||
7641 | </example> | ||
7642 | </sect2> | ||
7643 | |||
7644 | <!-- mailmime --> | ||
7645 | <sect2 id="mailmime"> | ||
7646 | <title>mailmime - MIME part</title> | ||
7647 | |||
7648 | <programlisting role="C"> | ||
7649 | #include <libetpan/libetpan.h> | ||
7650 | |||
7651 | enum { | ||
7652 | MAILMIME_NONE, | ||
7653 | MAILMIME_SINGLE, | ||
7654 | MAILMIME_MULTIPLE, | ||
7655 | MAILMIME_MESSAGE, | ||
7656 | }; | ||
7657 | |||
7658 | struct mailmime { | ||
7659 | /* parent information */ | ||
7660 | int mm_parent_type; | ||
7661 | struct mailmime * mm_parent; | ||
7662 | clistiter * mm_multipart_pos; | ||
7663 | |||
7664 | int mm_type; | ||
7665 | const char * mm_mime_start; | ||
7666 | size_t mm_length; | ||
7667 | |||
7668 | struct mailmime_fields * mm_mime_fields; | ||
7669 | struct mailmime_content * mm_content_type; | ||
7670 | |||
7671 | struct mailmime_data * mm_body; | ||
7672 | union { | ||
7673 | /* single part */ | ||
7674 | struct mailmime_data * mm_single; /* XXX - was body */ | ||
7675 | |||
7676 | /* multi-part */ | ||
7677 | struct { | ||
7678 | struct mailmime_data * mm_preamble; | ||
7679 | struct mailmime_data * mm_epilogue; | ||
7680 | clist * mm_mp_list; | ||
7681 | } mm_multipart; | ||
7682 | |||
7683 | /* message */ | ||
7684 | struct { | ||
7685 | struct mailimf_fields * mm_fields; | ||
7686 | struct mailmime * mm_msg_mime; | ||
7687 | } mm_message; | ||
7688 | |||
7689 | } mm_data; | ||
7690 | }; | ||
7691 | |||
7692 | struct mailmime * mailmime_new(int mm_type, | ||
7693 | const char * mm_mime_start, size_t mm_length, | ||
7694 | struct mailmime_fields * mm_mime_fields, | ||
7695 | struct mailmime_content * mm_content_type, | ||
7696 | struct mailmime_data * mm_body, | ||
7697 | struct mailmime_data * mm_preamble, | ||
7698 | struct mailmime_data * mm_epilogue, | ||
7699 | clist * mm_mp_list, | ||
7700 | struct mailimf_fields * mm_fields, | ||
7701 | struct mailmime * mm_msg_mime); | ||
7702 | |||
7703 | void mailmime_free(struct mailmime * mime); | ||
7704 | </programlisting> | ||
7705 | |||
7706 | <para> | ||
7707 | This describes the MIME structure of a message or a subpart | ||
7708 | of a message. | ||
7709 | </para> | ||
7710 | |||
7711 | <sect3> | ||
7712 | <title>common</title> | ||
7713 | |||
7714 | <itemizedlist> | ||
7715 | <listitem> | ||
7716 | <para> | ||
7717 | <command>mm_parent_type</command>. MIME part type can be | ||
7718 | single part, multipart or message part. This describes the MIME part | ||
7719 | type of the parent. The value can be | ||
7720 | <command>MAILMIME_NONE</command> if there is no parent part, | ||
7721 | <command>MAILMIME_SINGLE</command> if parent is a single part, | ||
7722 | <command>MAILMIME_MULTIPLE</command> if parent is a multipart, | ||
7723 | <command>MAILMIME_MESSAGE</command> if parent is a mesage part. | ||
7724 | </para> | ||
7725 | </listitem> | ||
7726 | |||
7727 | <listitem> | ||
7728 | <para> | ||
7729 | <command>mm_parent</command> is the parent MIME structure. | ||
7730 | </para> | ||
7731 | </listitem> | ||
7732 | |||
7733 | <listitem> | ||
7734 | <para> | ||
7735 | <command>mm_multipart_pos</command>. In the case the parent | ||
7736 | is a multipart. This is the position in the list of children | ||
7737 | of the parent. This position is given by a | ||
7738 | <command>clisiter *</command>. | ||
7739 | </para> | ||
7740 | </listitem> | ||
7741 | |||
7742 | <listitem> | ||
7743 | <para> | ||
7744 | <command>mm_type</command>. This describes the MIME part type | ||
7745 | of this part. The value can be | ||
7746 | <command>MAILMIME_SINGLE</command> if this is a single part, | ||
7747 | <command>MAILMIME_MULTIPLE</command> if this is a multipart, | ||
7748 | <command>MAILMIME_MESSAGE</command> if this is a mesage part. | ||
7749 | </para> | ||
7750 | </listitem> | ||
7751 | |||
7752 | <listitem> | ||
7753 | <para> | ||
7754 | <command>mm_mime_start</command>. This is used mostly internally. | ||
7755 | This gives the beginning of the header of the MIME part, when this | ||
7756 | is parsed from a string in memory. | ||
7757 | </para> | ||
7758 | </listitem> | ||
7759 | |||
7760 | |||
7761 | <listitem> | ||
7762 | <para> | ||
7763 | <command>mm_length</command>. This gives the length of the MIME part, | ||
7764 | including the MIME header fields. | ||
7765 | </para> | ||
7766 | </listitem> | ||
7767 | |||
7768 | <listitem> | ||
7769 | <para> | ||
7770 | <command>mm_mime_fields</command> is the list of parsed MIME headers | ||
7771 | of this part. <command>Content-Type</command> must be excluded and stored | ||
7772 | in <command>mm_content_type</command> instead | ||
7773 | (see <xref linkend="mailmime-fields">). | ||
7774 | </para> | ||
7775 | </listitem> | ||
7776 | |||
7777 | |||
7778 | <listitem> | ||
7779 | <para> | ||
7780 | <command>mm_content_type</command> is the parsed | ||
7781 | <command>Content-Type</command> field | ||
7782 | (see <xref linkend="mailmime-content">). | ||
7783 | </para> | ||
7784 | </listitem> | ||
7785 | |||
7786 | |||
7787 | <listitem> | ||
7788 | <para> | ||
7789 | <command>mm_body</command> is the content of the MIME part | ||
7790 | (excluding MIME header), when it is parsed from a string | ||
7791 | in memory | ||
7792 | (see <xref linkend="mailmime-data">). | ||
7793 | </para> | ||
7794 | </listitem> | ||
7795 | </itemizedlist> | ||
7796 | </sect3> | ||
7797 | |||
7798 | <sect3> | ||
7799 | <title>single part</title> | ||
7800 | |||
7801 | <itemizedlist> | ||
7802 | <listitem> | ||
7803 | <para> | ||
7804 | When the part is a single part (<command>mm_type</command> | ||
7805 | is <command>MAILMIME_SINGLE</command>). The following fields | ||
7806 | are valid. | ||
7807 | </para> | ||
7808 | </listitem> | ||
7809 | |||
7810 | <listitem> | ||
7811 | <para> | ||
7812 | <command>mm_data.mm_single</command> is the content of the | ||
7813 | MIME part (excluding MIME header), when it is parsed from a string | ||
7814 | in memory. This must have the same | ||
7815 | value as <command>mm_body</command> when it is set | ||
7816 | (see <xref linkend="mailmime-data">). | ||
7817 | </para> | ||
7818 | </listitem> | ||
7819 | </itemizedlist> | ||
7820 | </sect3> | ||
7821 | |||
7822 | <sect3> | ||
7823 | <title>multipart</title> | ||
7824 | |||
7825 | <itemizedlist> | ||
7826 | <listitem> | ||
7827 | <para> | ||
7828 | When the part is a multipart (<command>mm_type</command> | ||
7829 | is <command>MAILMIME_MULTIPLE</command>). The following fields | ||
7830 | are valid. | ||
7831 | </para> | ||
7832 | </listitem> | ||
7833 | |||
7834 | <listitem> | ||
7835 | <para> | ||
7836 | <command>mm_data.mm_multipart.mm_preamble</command> | ||
7837 | is the content of the preamble of the multipart | ||
7838 | (see <xref linkend="mailmime-data">). | ||
7839 | </para> | ||
7840 | </listitem> | ||
7841 | |||
7842 | <listitem> | ||
7843 | <para> | ||
7844 | <command>mm_data.mm_multipart.mm_epilogue</command> | ||
7845 | is the content of the epilogue of the multipart | ||
7846 | (see <xref linkend="mailmime-data">). | ||
7847 | </para> | ||
7848 | </listitem> | ||
7849 | |||
7850 | <listitem> | ||
7851 | <para> | ||
7852 | <command>mm_data.mm_multipart.mm_mp_list</command> | ||
7853 | is the list of sub parts | ||
7854 | </para> | ||
7855 | </listitem> | ||
7856 | </itemizedlist> | ||
7857 | </sect3> | ||
7858 | |||
7859 | <sect3> | ||
7860 | <title>message part</title> | ||
7861 | |||
7862 | <itemizedlist> | ||
7863 | <listitem> | ||
7864 | <para> | ||
7865 | When the part is a message (<command>mm_type</command> | ||
7866 | is <command>MAILMIME_MESSAGE</command>). The following fields | ||
7867 | are valid. | ||
7868 | </para> | ||
7869 | </listitem> | ||
7870 | |||
7871 | <listitem> | ||
7872 | <para> | ||
7873 | <command>mm_data.mm_message.mm_fields</command> is the list of | ||
7874 | the header fields of the message | ||
7875 | (see <xref linkend="mailimf-fields">). | ||
7876 | </para> | ||
7877 | </listitem> | ||
7878 | |||
7879 | <listitem> | ||
7880 | <para> | ||
7881 | <command>mm_data.mm_message.mm_msg_mime</command> is | ||
7882 | the subpart | ||
7883 | of the message part. | ||
7884 | </para> | ||
7885 | </listitem> | ||
7886 | </itemizedlist> | ||
7887 | </sect3> | ||
7888 | |||
7889 | <sect3> | ||
7890 | <title>constructor and destructor</title> | ||
7891 | |||
7892 | <para> | ||
7893 | <command>mailmime_new()</command> creates and | ||
7894 | initializes | ||
7895 | a data structure with a value. | ||
7896 | Structures given as argument are referenced by the created | ||
7897 | object and will be freed if the object is released. | ||
7898 | </para> | ||
7899 | |||
7900 | <para> | ||
7901 | <command>mailmime_free()</command> frees | ||
7902 | memory used by | ||
7903 | the structure and substructures will also be released. | ||
7904 | </para> | ||
7905 | |||
7906 | <example> | ||
7907 | <title>Creation and display of MIME part</title> | ||
7908 | |||
7909 | <programlisting role="C"> | ||
7910 | #include <libetpan/libetpan.h> | ||
7911 | |||
7912 | /* build one single MIME part */ | ||
7913 | |||
7914 | int main(int argc, char ** argv) | ||
7915 | { | ||
7916 | struct mailmime * mime; | ||
7917 | struct mailimf_fields * fields; | ||
7918 | struct mailmime_fields * mime_fields; | ||
7919 | struct mailmime_content * content_type; | ||
7920 | struct mailmime_data * body; | ||
7921 | |||
7922 | /* look at the example in mailimf_fields to see how to | ||
7923 | build a mailimf_fields */ | ||
7924 | fields = build_fields(); | ||
7925 | |||
7926 | /* look at the example in mailmime_fields to see how to | ||
7927 | build a mailmime_fields */ | ||
7928 | mime_fields = build_mime_fields(); | ||
7929 | |||
7930 | /* look at the example in mailmime_content to see how to | ||
7931 | build a mailmime_content */ | ||
7932 | content_type = build_mime_content(); | ||
7933 | |||
7934 | body = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_8BIT, 0, | ||
7935 | "foo", 3, NULL); | ||
7936 | |||
7937 | mime = mailmime_new(MAILMIME_SINGLE, | ||
7938 | NULL, 0, fields, mime_fields, content_type, | ||
7939 | body, NULL, NULL, NULL, NULL, NULL); | ||
7940 | |||
7941 | /* do the things */ | ||
7942 | |||
7943 | mailmime_free(mime); | ||
7944 | } | ||
7945 | |||
7946 | /* build one single MIME part */ | ||
7947 | |||
7948 | int main(int argc, char ** argv) | ||
7949 | { | ||
7950 | struct mailmime * mime; | ||
7951 | struct mailimf_fields * fields; | ||
7952 | struct mailmime_fields * mime_fields; | ||
7953 | struct mailmime_content * content_type; | ||
7954 | char * str; | ||
7955 | struct mailmime_data * body; | ||
7956 | |||
7957 | /* look at the example in mailimf_fields to see how to | ||
7958 | build a mailimf_fields */ | ||
7959 | fields = build_fields(); | ||
7960 | |||
7961 | /* look at the example in mailmime_fields to see how to | ||
7962 | build a mailmime_fields */ | ||
7963 | mime_fields = build_mime_fields(); | ||
7964 | |||
7965 | /* look at the example in mailmime_content to see how to | ||
7966 | build a mailmime_content */ | ||
7967 | content_type = build_mime_content(); | ||
7968 | |||
7969 | str = malloc(4); | ||
7970 | strcpy(str, "foo"); | ||
7971 | |||
7972 | body = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_8BIT, 0, | ||
7973 | str, 3, NULL); | ||
7974 | |||
7975 | mime = mailmime_new(MAILMIME_SINGLE, | ||
7976 | NULL, 0, fields, mime_fields, content_type, | ||
7977 | body, NULL, NULL, NULL, NULL, NULL); | ||
7978 | |||
7979 | /* do the things */ | ||
7980 | |||
7981 | mailmime_free(mime); | ||
7982 | free(str); | ||
7983 | } | ||
7984 | |||
7985 | /* build a MIME part with a sub-message */ | ||
7986 | |||
7987 | int main(int argc, char ** argv) | ||
7988 | { | ||
7989 | struct mailmime * mime; | ||
7990 | struct mailimf_fields * fields; | ||
7991 | struct mailmime_fields * mime_fields; | ||
7992 | struct mailmime_content * content_type; | ||
7993 | char * str; | ||
7994 | struct mailmime_type * type; | ||
7995 | struct mailmime_composite_type * composite_type; | ||
7996 | |||
7997 | /* look at the example in mailimf_fields to see how to | ||
7998 | build a mailimf_fields */ | ||
7999 | fields = build_fields(); | ||
8000 | |||
8001 | /* look at the example in mailmime_fields to see how to | ||
8002 | build a mailmime_fields */ | ||
8003 | mime_fields = build_mime_fields(); | ||
8004 | |||
8005 | composite_type = | ||
8006 | mailmime_composite_type_new(MAILMIME_COMPOSITE_TYPE_MESSAGE, NULL); | ||
8007 | type = mailmime_type_new(MAILMIME_TYPE_COMPOSITE_TYPE, NULL, | ||
8008 | composite_type); | ||
8009 | content_type = mailmime_content_new(type, strdup("rfc2822"), NULL); | ||
8010 | |||
8011 | /* build_mime_message() is a function that will build a mime message part */ | ||
8012 | sub_mime = build_mime_message(); | ||
8013 | |||
8014 | mime = mailmime_new(MAILMIME_MESSAGE, | ||
8015 | NULL, 0, fields, mime_fields, content_type, | ||
8016 | NULL, NULL, NULL, NULL, sub_mime, NULL); | ||
8017 | |||
8018 | /* do the things */ | ||
8019 | |||
8020 | mailmime_free(mime); | ||
8021 | } | ||
8022 | |||
8023 | /* build a MIME part with a sub-message (given by a string) */ | ||
8024 | |||
8025 | |||
8026 | int main(int argc, char ** argv) | ||
8027 | { | ||
8028 | struct mailmime * mime; | ||
8029 | struct mailimf_fields * fields; | ||
8030 | struct mailmime_fields * mime_fields; | ||
8031 | struct mailmime_content * content_type; | ||
8032 | char * str; | ||
8033 | struct mailmime_data * msg_content; | ||
8034 | struct mailmime_type * type; | ||
8035 | struct mailmime_composite_type * composite_type; | ||
8036 | |||
8037 | /* look at the example in mailimf_fields to see how to | ||
8038 | build a mailimf_fields */ | ||
8039 | fields = build_fields(); | ||
8040 | |||
8041 | /* look at the example in mailmime_fields to see how to | ||
8042 | build a mailmime_fields */ | ||
8043 | mime_fields = build_mime_fields(); | ||
8044 | |||
8045 | composite_type = | ||
8046 | mailmime_composite_type_new(MAILMIME_COMPOSITE_TYPE_MESSAGE, NULL); | ||
8047 | type = mailmime_type_new(MAILMIME_TYPE_COMPOSITE_TYPE, NULL, | ||
8048 | composite_type); | ||
8049 | content_type = mailmime_content_new(type, strdup("rfc2822"), NULL); | ||
8050 | |||
8051 | str = malloc(sizeof(SUB_MESSAGE)); | ||
8052 | strcpy(str, SUB_MESSAGE); | ||
8053 | |||
8054 | msg_content = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_8BIT, 0, | ||
8055 | str, sizeof(SUB_MESSAGE), NULL); | ||
8056 | |||
8057 | mime = mailmime_new(MAILMIME_MESSAGE, | ||
8058 | NULL, 0, fields, mime_fields, content_type, | ||
8059 | NULL, NULL, NULL, NULL, NULL, msg_content); | ||
8060 | |||
8061 | /* do the things */ | ||
8062 | |||
8063 | mailmime_free(mime); | ||
8064 | free(str); | ||
8065 | } | ||
8066 | |||
8067 | /* build a multipart message */ | ||
8068 | |||
8069 | |||
8070 | |||
8071 | int main(int argc, char ** argv) | ||
8072 | { | ||
8073 | struct mailmime * mime; | ||
8074 | struct mailimf_fields * fields; | ||
8075 | struct mailmime_fields * mime_fields; | ||
8076 | struct mailmime_content * content_type; | ||
8077 | struct mailmime_type * type; | ||
8078 | struct mailmime_composite_type * composite_type; | ||
8079 | struct mailmime_data * body; | ||
8080 | struct mailmime_data * preamble; | ||
8081 | struct mailmime_data * epilogue; | ||
8082 | clist * list; | ||
8083 | |||
8084 | /* look at the example in mailimf_fields to see how to | ||
8085 | build a mailimf_fields */ | ||
8086 | fields = build_fields(); | ||
8087 | |||
8088 | /* look at the example in mailmime_fields to see how to | ||
8089 | build a mailmime_fields */ | ||
8090 | mime_fields = build_mime_fields(); | ||
8091 | |||
8092 | composite_type = | ||
8093 | mailmime_composite_type_new(MAILMIME_COMPOSITE_TYPE_MULTIPART, NULL); | ||
8094 | type = mailmime_type_new(MAILMIME_TYPE_COMPOSITE_TYPE, NULL, | ||
8095 | composite_type); | ||
8096 | content_type = mailmime_content_new(type, strdup("mixed"), NULL); | ||
8097 | |||
8098 | list = clist_new(); | ||
8099 | /* build_mime_message() is a function that will build a mime message part */ | ||
8100 | sub_mime = build_mime_message(); | ||
8101 | clist_append(list, sub_mime); | ||
8102 | sub_mime = build_mime_message(); | ||
8103 | clist_append(list, sub_mime); | ||
8104 | |||
8105 | preamble = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_8BIT, 0, | ||
8106 | PREAMBLE, sizeof(PREAMBLE), NULL); | ||
8107 | |||
8108 | epilogue = mailmime_data_new(MAILMIME_DATA_TEXT, MAILMIME_MECHANISM_8BIT, 0, | ||
8109 | EPILOGUE, sizeof(EPILOGUE), NULL); | ||
8110 | |||
8111 | mime = mailmime_new(MAILMIME_SINGLE, | ||
8112 | NULL, 0, fields, mime_fields, content_type, | ||
8113 | NULL, preamble, epilogue, list, NULL, NULL); | ||
8114 | |||
8115 | /* do the things */ | ||
8116 | |||
8117 | mailmime_free(mime); | ||
8118 | } | ||
8119 | |||
8120 | /* display mime part info */ | ||
8121 | |||
8122 | void display_mime(struct mailmime * mime) | ||
8123 | { | ||
8124 | clistiter * cur; | ||
8125 | |||
8126 | switch (mime->mm_type) { | ||
8127 | case MAILMIME_SINGLE: | ||
8128 | printf("single part\n"); | ||
8129 | break; | ||
8130 | case MAILMIME_MULTIPLE: | ||
8131 | printf("multipart\n"); | ||
8132 | break; | ||
8133 | case MAILMIME_MESSAGE: | ||
8134 | printf("message\n"); | ||
8135 | break; | ||
8136 | } | ||
8137 | |||
8138 | printf("part : %p, length : %i\n", | ||
8139 | mime->mm_mime_start, mime->mm_length); | ||
8140 | printf("\n"); | ||
8141 | |||
8142 | if (mime->mm_mime_fields != NULL) { | ||
8143 | printf("MIME headers :\n"); | ||
8144 | display_mime_fields(mime->mm_mime_fields); | ||
8145 | printf("\n"); | ||
8146 | } | ||
8147 | |||
8148 | printf("content type :\n"); | ||
8149 | display_content(mime->mm_content_type); | ||
8150 | printf("\n"); | ||
8151 | |||
8152 | switch (mime->mm_type) { | ||
8153 | case MAILMIME_SINGLE: | ||
8154 | display_mime_data(mime->mm_data.mm_single); | ||
8155 | break; | ||
8156 | |||
8157 | case MAILMIME_MULTIPLE: | ||
8158 | if (mime->mm_data.mm_multipart.mm_preamble) { | ||
8159 | printf("preamble :\n"); | ||
8160 | display_mime_data(mime->mm_data.mm_multipart.mm_preamble); | ||
8161 | printf("\n"); | ||
8162 | } | ||
8163 | |||
8164 | for(cur = clist_begin(mime->mm_data.mm_multipart.mm_mp_list) ; | ||
8165 | cur != NULL ; cur = clist_next(cur)) { | ||
8166 | display_mime(clist_content(cur)); | ||
8167 | } | ||
8168 | |||
8169 | if (mime->mm_data.mm_multipart.mm_epilogue) { | ||
8170 | printf("epilogue :\n"); | ||
8171 | display_mime_data(mime->mm_data.mm_multipart.mm_epilogue); | ||
8172 | printf("\n"); | ||
8173 | } | ||
8174 | break; | ||
8175 | |||
8176 | case MAILMIME_MESSAGE: | ||
8177 | if (mime->mm_data.mm_message.mm_fields) { | ||
8178 | printf("headers :\n"); | ||
8179 | display_field(mime->mm_data.mm_message.mm_msg_fields); | ||
8180 | printf("\n"); | ||
8181 | |||
8182 | if (mime->mm_data.mm_message.mm_msg_mime != NULL) { | ||
8183 | printf("sub message %p :\n", | ||
8184 | mime->mm_data.mm_message.mm_msg_mime); | ||
8185 | display_mime(mime->mm_data.mm_message.mm_msg_mime); | ||
8186 | printf("end of sub message %p\n", | ||
8187 | mime->mm_data.mm_message.mm_msg_mime); | ||
8188 | } | ||
8189 | break; | ||
8190 | } | ||
8191 | } | ||
8192 | </programlisting> | ||
8193 | </example> | ||
8194 | |||
8195 | </sect3> | ||
8196 | |||
8197 | </sect2> | ||
8198 | |||
8199 | <!-- mailmime_disposition --> | ||
8200 | <sect2 id="mailmime-disposition"> | ||
8201 | <title>mailmime_disposition - MIME disposition information (Content-Disposition)</title> | ||
8202 | |||
8203 | <programlisting role="C"> | ||
8204 | #include <libetpan/libetpan.h> | ||
8205 | |||
8206 | struct mailmime_disposition { | ||
8207 | struct mailmime_disposition_type * dsp_type; | ||
8208 | clist * dsp_parms; /* struct mailmime_disposition_parm */ | ||
8209 | }; | ||
8210 | </programlisting> | ||
8211 | |||
8212 | <para> | ||
8213 | This is the parsed <command>Content-Disposition</command> | ||
8214 | header field. | ||
8215 | </para> | ||
8216 | |||
8217 | <itemizedlist> | ||
8218 | <listitem> | ||
8219 | <para> | ||
8220 | <command>dsp_type</command> is the type of disposition | ||
8221 | (see <xref linkend="mailmime-disposition-type">). | ||
8222 | </para> | ||
8223 | </listitem> | ||
8224 | |||
8225 | <listitem> | ||
8226 | <para> | ||
8227 | <command>dsp_parms</command> is the list of parameters | ||
8228 | of <command>Content-Disposition</command> header field. | ||
8229 | Each element is of type <command>mailmime_disposition_parm</command> | ||
8230 | (see <xref linkend="mailmime-disposition-parm">). | ||
8231 | </para> | ||
8232 | </listitem> | ||
8233 | </itemizedlist> | ||
8234 | |||
8235 | <example> | ||
8236 | <title>Creation and display of MIME disposition information</title> | ||
8237 | <programlisting role="C"> | ||
8238 | #include <libetpan/libetpan.h> | ||
8239 | |||
8240 | int main(int argc, char ** argv) | ||
8241 | { | ||
8242 | struct mailmime_disposition * disposition; | ||
8243 | struct mailmime_disposition_type * disposition_type; | ||
8244 | clist * disposition_parms; | ||
8245 | struct mailmime_disposition_parm * param; | ||
8246 | |||
8247 | disposition_type = | ||
8248 | mailmime_disposition_type_new(MAILMIME_DISPOSITION_TYPE_ATTACHMENT, NULL); | ||
8249 | |||
8250 | disposition_parms = clist_new(); | ||
8251 | param = mailmime_disposition_parm_new(MAILMIME_DISPOSITION_PARM_FILENAME, | ||
8252 | strdup("foo.txt"), NULL, | ||
8253 | NULL, NULL, -1, NULL); | ||
8254 | clist_append(disposition_parms, param); | ||
8255 | |||
8256 | disposition = mailmime_disposition_new(disposition_type, disposition_parms); | ||
8257 | |||
8258 | /* do the things */ | ||
8259 | |||
8260 | mailmime_disposition_free(disposition); | ||
8261 | } | ||
8262 | |||
8263 | void display_mime_disposition(struct mailmime_disposition * disposition) | ||
8264 | { | ||
8265 | clistiter * cur; | ||
8266 | |||
8267 | printf("disposition type:\n"); | ||
8268 | display_mailmime_disposition_type(disposition->dsp_type); | ||
8269 | printf("\n"); | ||
8270 | printf("disposition parameters:\n"); | ||
8271 | for(cur = clist_begin(disposition->dsp_parms) ; | ||
8272 | cur != NULL ; cur = clist_next(cur)) { | ||
8273 | struct mailmime_parm * param; | ||
8274 | |||
8275 | param = clist_content(cur); | ||
8276 | display_mime_disposition_parm(param); | ||
8277 | } | ||
8278 | printf("\n"); | ||
8279 | } | ||
8280 | |||
8281 | </programlisting> | ||
8282 | </example> | ||
8283 | </sect2> | ||
8284 | |||
8285 | <!-- mailmime_disposition_type --> | ||
8286 | <sect2 id="mailmime-disposition-type"> | ||
8287 | <title>mailmime_disposition_type - Type of MIME disposition</title> | ||
8288 | |||
8289 | <programlisting role="C"> | ||
8290 | #include <libetpan/libetpan.h> | ||
8291 | |||
8292 | enum { | ||
8293 | MAILMIME_DISPOSITION_TYPE_ERROR, | ||
8294 | MAILMIME_DISPOSITION_TYPE_INLINE, | ||
8295 | MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
8296 | MAILMIME_DISPOSITION_TYPE_EXTENSION | ||
8297 | }; | ||
8298 | |||
8299 | struct mailmime_disposition_type { | ||
8300 | int dsp_type; | ||
8301 | char * dsp_extension; | ||
8302 | }; | ||
8303 | </programlisting> | ||
8304 | |||
8305 | <para> | ||
8306 | This is the type of MIME disposition. | ||
8307 | Parsed <command>Content-Disposition</command> field without | ||
8308 | parameters. | ||
8309 | </para> | ||
8310 | |||
8311 | <para> | ||
8312 | <command>dsp_type</command> is the type of disposition. | ||
8313 | The value can be | ||
8314 | <command>MAILMIME_DISPOSITION_TYPE_INLINE</command> | ||
8315 | if MIME disposition is inline, | ||
8316 | <command>MAILMIME_DISPOSITION_TYPE_ATTACHMENT</command> | ||
8317 | if MIME disposition is attachment, | ||
8318 | <command>MAILMIME_DISPOSITION_TYPE_EXTENSION</command> | ||
8319 | for other. In this case, <command>dsp_extension</command> must be | ||
8320 | set. | ||
8321 | <command>MAILMIME_DISPOSITION_TYPE_ERROR</command> is used internally. | ||
8322 | </para> | ||
8323 | |||
8324 | <example> | ||
8325 | <title>Creation and display of MIME disposition type</title> | ||
8326 | <programlisting role="C"> | ||
8327 | #include <libetpan/libetpan.h> | ||
8328 | |||
8329 | /* standard disposition type */ | ||
8330 | |||
8331 | int main(int argc, char ** argv) | ||
8332 | { | ||
8333 | struct mailmime_disposition_type * disposition_type; | ||
8334 | |||
8335 | disposition_type = | ||
8336 | mailmime_disposition_type_new(MAILMIME_DISPOSITION_TYPE_ATTACHMENT, NULL); | ||
8337 | |||
8338 | /* do the things */ | ||
8339 | |||
8340 | mailmime_disposition_type_free(disposition_type); | ||
8341 | } | ||
8342 | |||
8343 | /* disposition type extension */ | ||
8344 | |||
8345 | int main(int argc, char ** argv) | ||
8346 | { | ||
8347 | struct mailmime_disposition_type * disposition_type; | ||
8348 | |||
8349 | disposition_type = | ||
8350 | mailmime_disposition_type_new(MAILMIME_DISPOSITION_TYPE_EXTENSION, | ||
8351 | strdup("mydisposition")); | ||
8352 | |||
8353 | /* do the things */ | ||
8354 | |||
8355 | mailmime_disposition_type_free(disposition_type); | ||
8356 | } | ||
8357 | |||
8358 | void display_mime_disposition_type(struct mailmime_disposition_type * disposition_type) | ||
8359 | { | ||
8360 | switch (disposition->dsp_type) { | ||
8361 | case MAILMIME_DISPOSITION_TYPE_INLINE: | ||
8362 | printf("inline\n"); | ||
8363 | break; | ||
8364 | case MAILMIME_DISPOSITION_TYPE_ATTACHMENT: | ||
8365 | printf("attachment\n"); | ||
8366 | break; | ||
8367 | case MAILMIME_DISPOSITION_TYPE_EXTENSION: | ||
8368 | printf("extension : %s\n", disposition_type->dsp_extension); | ||
8369 | break; | ||
8370 | } | ||
8371 | } | ||
8372 | </programlisting> | ||
8373 | </example> | ||
8374 | </sect2> | ||
8375 | |||
8376 | <!-- mailmime_disposition_parm --> | ||
8377 | <sect2 id="mailmime-disposition-parm"> | ||
8378 | <title>mailmime_disposition_parm - MIME disposition parameter</title> | ||
8379 | |||
8380 | <programlisting role="C"> | ||
8381 | #include <libetpan/libetpan.h> | ||
8382 | |||
8383 | enum { | ||
8384 | MAILMIME_DISPOSITION_PARM_FILENAME, | ||
8385 | MAILMIME_DISPOSITION_PARM_CREATION_DATE, | ||
8386 | MAILMIME_DISPOSITION_PARM_MODIFICATION_DATE, | ||
8387 | MAILMIME_DISPOSITION_PARM_READ_DATE, | ||
8388 | MAILMIME_DISPOSITION_PARM_SIZE, | ||
8389 | MAILMIME_DISPOSITION_PARM_PARAMETER | ||
8390 | }; | ||
8391 | |||
8392 | struct mailmime_disposition_parm { | ||
8393 | int pa_type; | ||
8394 | union { | ||
8395 | char * pa_filename; | ||
8396 | char * pa_creation_date; | ||
8397 | char * pa_modification_date; | ||
8398 | char * pa_read_date; | ||
8399 | size_t pa_size; | ||
8400 | struct mailmime_parameter * pa_parameter; | ||
8401 | } pa_data; | ||
8402 | }; | ||
8403 | </programlisting> | ||
8404 | |||
8405 | <para> | ||
8406 | This is a parameter of MIME disposition information. For | ||
8407 | example, this can be | ||
8408 | <command>filename="foo.jpg"</command>. | ||
8409 | </para> | ||
8410 | |||
8411 | <itemizedlist> | ||
8412 | <listitem> | ||
8413 | <para> | ||
8414 | <command>pa_type</command> is the type of | ||
8415 | disposition. The value can be | ||
8416 | <command>MAILMIME_DISPOSITION_PARM_FILENAME</command> | ||
8417 | for a filename parameter, | ||
8418 | <command>MAILMIME_DISPOSITION_PARM_CREATION_DATE</command> | ||
8419 | for a creation date parameter, | ||
8420 | <command>MAILMIME_DISPOSITION_PARM_MODIFICATION_DATE</command> | ||
8421 | for a modification date parameter, | ||
8422 | <command>MAILMIME_DISPOSITION_PARM_READ_DATE</command> | ||
8423 | for a last read date parameter, | ||
8424 | <command>MAILMIME_DISPOSITION_PARM_SIZE</command> | ||
8425 | for a file size parameter or | ||
8426 | <command>MAILMIME_DISPOSITION_PARM_PARAMETER</command> | ||
8427 | for other parameters. | ||
8428 | </para> | ||
8429 | </listitem> | ||
8430 | |||
8431 | <listitem> | ||
8432 | <para> | ||
8433 | <command>pa_data.pa_filename</command> is the filename | ||
8434 | parameter when <command>pa_type</command> is | ||
8435 | <command>MAILMIME_DISPOSITION_PARM_FILENAME</command> | ||
8436 | This is a string containing the name of the | ||
8437 | file. | ||
8438 | </para> | ||
8439 | </listitem> | ||
8440 | <listitem> | ||
8441 | <para> | ||
8442 | <command>pa_data.pa_creation_date</command> is the | ||
8443 | creation date parameter when <command>pa_type</command> is | ||
8444 | <command>MAILMIME_DISPOSITION_PARM_CREATION_DATE</command>. | ||
8445 | This is a string containing the formatted creation date. | ||
8446 | </para> | ||
8447 | </listitem> | ||
8448 | |||
8449 | <listitem> | ||
8450 | <para> | ||
8451 | <command>pa_data.pa_modification_date</command> is the | ||
8452 | modification date parameter when <command>pa_type</command> is | ||
8453 | <command>MAILMIME_DISPOSITION_PARM_MODIFICATION_DATE</command>. | ||
8454 | This is a string containing the formatted modification date. | ||
8455 | </para> | ||
8456 | </listitem> | ||
8457 | |||
8458 | <listitem> | ||
8459 | <para> | ||
8460 | <command>pa_data.pa_read_date</command> is the | ||
8461 | last read date parameter when <command>pa_type</command> is | ||
8462 | <command>MAILMIME_DISPOSITION_PARM_READ_DATE</command>. | ||
8463 | This is a string containing the formatted last read date. | ||
8464 | </para> | ||
8465 | </listitem> | ||
8466 | |||
8467 | <listitem> | ||
8468 | <para> | ||
8469 | <command>pa_data.pa_size</command> is the size | ||
8470 | parameter when <command>pa_type</command> is | ||
8471 | <command>MAILMIME_DISPOSITION_PARM_SIZE</command>. | ||
8472 | This gives the size of the file. | ||
8473 | </para> | ||
8474 | </listitem> | ||
8475 | |||
8476 | <listitem> | ||
8477 | <para> | ||
8478 | <command>pa_data.pa_parameter</command> is the | ||
8479 | name and the value of the parameter when | ||
8480 | <command>pa_type</command> is | ||
8481 | <command>MAILMIME_DISPOSITION_PARM_PARAMETER</command> | ||
8482 | (see <xref linkend="mailmime-parameter">) | ||
8483 | </para> | ||
8484 | </listitem> | ||
8485 | </itemizedlist> | ||
8486 | |||
8487 | <example> | ||
8488 | <title>Creation and display of MIME disposition | ||
8489 | parameter</title> | ||
8490 | |||
8491 | <programlisting role="C"> | ||
8492 | int main(int argc, char ** argv) | ||
8493 | { | ||
8494 | struct mailmime_disposition_parm * param; | ||
8495 | |||
8496 | disposition_parms = clist_new(); | ||
8497 | param = mailmime_disposition_parm_new(MAILMIME_DISPOSITION_PARM_FILENAME, | ||
8498 | strdup("foo.txt"), NULL, | ||
8499 | NULL, NULL, -1, NULL); | ||
8500 | /* do the things */ | ||
8501 | |||
8502 | mailmime_disposition_parm_free(param); | ||
8503 | } | ||
8504 | |||
8505 | void display_mime_dsp_parm(struct mailmime_disposition_parm * param) | ||
8506 | { | ||
8507 | switch (param->pa_type) { | ||
8508 | case MAILMIME_DISPOSITION_PARM_FILENAME: | ||
8509 | printf("filename: %s\n", param->pa_data.pa_filename); | ||
8510 | break; | ||
8511 | case MAILMIME_DISPOSITION_PARM_CREATION_DATE: | ||
8512 | printf("creation date: %s\n", param->pa_data.pa_creation_date); | ||
8513 | break; | ||
8514 | case MAILMIME_DISPOSITION_PARM_MODIFICATION_DATE: | ||
8515 | printf("modification date: %s\n", param->pa_data.pa_modification_date); | ||
8516 | break; | ||
8517 | case MAILMIME_DISPOSITION_PARM_READ_DATE: | ||
8518 | printf("read date: %s\n", param->pa_data.pa_read_date); | ||
8519 | break; | ||
8520 | case MAILMIME_DISPOSITION_PARM_SIZE: | ||
8521 | printf("size: %lu\n", (unsigned long) param->pa_data.pa_size); | ||
8522 | break; | ||
8523 | case MAILMIME_DISPOSITION_PARM_PARAMETER: | ||
8524 | printf("MIME disposition param:\n"); | ||
8525 | display_mime_parameter(param->pa_data.pa_parameter); | ||
8526 | break; | ||
8527 | } | ||
8528 | } | ||
8529 | </programlisting> | ||
8530 | </example> | ||
8531 | </sect2> | ||
8532 | |||
8533 | <!-- mailmime_single_fields --> | ||
8534 | <sect2 id="mailmime-single-fields"> | ||
8535 | <title>mailmime_single_fields - MIME headers</title> | ||
8536 | |||
8537 | |||
8538 | <programlisting role="C"> | ||
8539 | #include <libetpan/libetpan.h> | ||
8540 | |||
8541 | struct mailmime_single_fields { | ||
8542 | struct mailmime_content * fld_content; | ||
8543 | char * fld_content_charset; | ||
8544 | char * fld_content_boundary; | ||
8545 | char * fld_content_name; | ||
8546 | struct mailmime_mechanism * fld_encoding; | ||
8547 | char * fld_id; | ||
8548 | char * fld_description; | ||
8549 | uint32_t fld_version; | ||
8550 | struct mailmime_disposition * fld_disposition; | ||
8551 | char * fld_disposition_filename; | ||
8552 | char * fld_disposition_creation_date; | ||
8553 | char * fld_disposition_modification_date; | ||
8554 | char * fld_disposition_read_date; | ||
8555 | size_t fld_disposition_size; | ||
8556 | struct mailmime_language * fld_language; | ||
8557 | }; | ||
8558 | |||
8559 | struct mailmime_single_fields * | ||
8560 | mailmime_single_fields_new(struct mailmime_fields * fld_fields, | ||
8561 | struct mailmime_content * fld_content); | ||
8562 | |||
8563 | void mailmime_single_fields_free(struct mailmime_single_fields * | ||
8564 | single_fields); | ||
8565 | |||
8566 | void mailmime_single_fields_init(struct mailmime_single_fields * single_fields, | ||
8567 | struct mailmime_fields * fld_fields, | ||
8568 | struct mailmime_content * fld_content); | ||
8569 | </programlisting> | ||
8570 | |||
8571 | <para> | ||
8572 | <command>mailmime_fields</command> (see <xref | ||
8573 | linkend="mailmime-fields">) is the native structure | ||
8574 | that MIME module will use, this module will provide an easier | ||
8575 | structure to use when | ||
8576 | parsing fields. <command>mailmime_single_fields</command> is | ||
8577 | an easier structure to get parsed fields, rather than | ||
8578 | iteration over the list of fields. | ||
8579 | </para> | ||
8580 | |||
8581 | <itemizedlist> | ||
8582 | <listitem> | ||
8583 | <para> | ||
8584 | <command>fld_content</command> is the MIME content type | ||
8585 | (see <xref linkend="mailmime-content">). | ||
8586 | </para> | ||
8587 | </listitem> | ||
8588 | <listitem> | ||
8589 | <para> | ||
8590 | <command>fld_content_charset</command> is the value | ||
8591 | of the MIME type parameter <command>charset</command>. | ||
8592 | </para> | ||
8593 | </listitem> | ||
8594 | <listitem> | ||
8595 | <para> | ||
8596 | <command>fld_content_boundary</command> is the value | ||
8597 | of the MIME type parameter <command>boundary</command>. | ||
8598 | </para> | ||
8599 | </listitem> | ||
8600 | <listitem> | ||
8601 | <para> | ||
8602 | <command>fld_content_name</command> is the value | ||
8603 | of the MIME type parameter <command>name</command>. | ||
8604 | </para> | ||
8605 | </listitem> | ||
8606 | <listitem> | ||
8607 | <para> | ||
8608 | <command>fld_encoding</command> is the MIME encoding | ||
8609 | mechanism used | ||
8610 | (see <xref linkend="mailmime-mechanism">). | ||
8611 | </para> | ||
8612 | </listitem> | ||
8613 | <listitem> | ||
8614 | <para> | ||
8615 | <command>fld_id</command> is the content of the field | ||
8616 | <command>Content-ID</command>. | ||
8617 | </para> | ||
8618 | </listitem> | ||
8619 | <listitem> | ||
8620 | <para> | ||
8621 | <command>fld_description</command> is the content of the field | ||
8622 | <command>Content-Description</command>. | ||
8623 | </para> | ||
8624 | </listitem> | ||
8625 | <listitem> | ||
8626 | <para> | ||
8627 | <command>fld_version</command> is the version of MIME | ||
8628 | in use. | ||
8629 | </para> | ||
8630 | </listitem> | ||
8631 | <listitem> | ||
8632 | <para> | ||
8633 | <command>fld_disposition</command> is the MIME | ||
8634 | disposition information | ||
8635 | (see <xref linkend="mailmime-disposition">). | ||
8636 | </para> | ||
8637 | </listitem> | ||
8638 | <listitem> | ||
8639 | <para> | ||
8640 | <command>fld_disposition_filename</command> is | ||
8641 | the <command>filename</command> parameter of the | ||
8642 | MIME disposition information. | ||
8643 | </para> | ||
8644 | </listitem> | ||
8645 | <listitem> | ||
8646 | <para> | ||
8647 | <command>fld_disposition_creation_date</command> is | ||
8648 | the <command>creation-date</command> parameter of the | ||
8649 | MIME disposition information. | ||
8650 | </para> | ||
8651 | </listitem> | ||
8652 | <listitem> | ||
8653 | <para> | ||
8654 | <command>fld_disposition_modification_date</command> is | ||
8655 | the <command>modification-date</command> parameter of the | ||
8656 | MIME disposition information. | ||
8657 | </para> | ||
8658 | </listitem> | ||
8659 | <listitem> | ||
8660 | <para> | ||
8661 | <command>fld_disposition_read_date</command> is | ||
8662 | the <command>read-date</command> parameter of the | ||
8663 | MIME disposition information. | ||
8664 | </para> | ||
8665 | </listitem> | ||
8666 | <listitem> | ||
8667 | <para> | ||
8668 | <command>fld_disposition_size</command> is | ||
8669 | the <command>size</command> parameter of the | ||
8670 | MIME disposition information. | ||
8671 | </para> | ||
8672 | </listitem> | ||
8673 | <listitem> | ||
8674 | <para> | ||
8675 | <command>fld_language</command> is the language | ||
8676 | of the MIME part | ||
8677 | (see <xref linkend="mailmime-language">). | ||
8678 | </para> | ||
8679 | </listitem> | ||
8680 | <listitem> | ||
8681 | <para> | ||
8682 | <command>single_fields</command> is the structure to fill. | ||
8683 | </para> | ||
8684 | </listitem> | ||
8685 | <listitem> | ||
8686 | <para> | ||
8687 | <command>fld_fields</command> is the MIME fields list to | ||
8688 | use to fill the <command>single_fields</command>. | ||
8689 | </para> | ||
8690 | </listitem> | ||
8691 | </itemizedlist> | ||
8692 | |||
8693 | <para> | ||
8694 | <command>mailmime_single_fields_new()</command> creates and | ||
8695 | initializes a data structure with a | ||
8696 | value. Structures given as argument are referenced by the created | ||
8697 | object and will <emphasis>NOT</emphasis> be freed if the | ||
8698 | object is released. | ||
8699 | </para> | ||
8700 | |||
8701 | <para> | ||
8702 | <command>mailmime_single_fields_free()</command> frees | ||
8703 | memory used by the structure and | ||
8704 | substructures will <emphasis>NOT</emphasis> be | ||
8705 | released. They should be released by | ||
8706 | the application. | ||
8707 | </para> | ||
8708 | |||
8709 | <para> | ||
8710 | <command>mailimf_single_fields_init()</command> will | ||
8711 | initialize fill the data structure, using | ||
8712 | the given argument (<command>fld_fields</command> and | ||
8713 | <command>fld_content</command>). The interesting fields will | ||
8714 | be filled into single_fields. | ||
8715 | </para> | ||
8716 | |||
8717 | <example> | ||
8718 | <title>Creation and display of single fields</title> | ||
8719 | |||
8720 | <programlisting role="C"> | ||
8721 | #include <libetpan/libetpan.h> | ||
8722 | |||
8723 | int main(int argc, char ** argv) | ||
8724 | { | ||
8725 | struct mailmime_single_fields * single_fields; | ||
8726 | struct mailmime_fields * mime_fields; | ||
8727 | struct mailmime_content * content_type; | ||
8728 | |||
8729 | /* look at the example in mailmime_fields to see how to | ||
8730 | build a mailmime_fields */ | ||
8731 | mime_fields = build_mime_fields(); | ||
8732 | |||
8733 | /* look at the example in mailmime_content to see how to | ||
8734 | build a mailmime_content */ | ||
8735 | content_type = build_mime_content(); | ||
8736 | |||
8737 | single_fields = mailmime_single_fields_new(mime_fields, content_type); | ||
8738 | |||
8739 | /* do the things */ | ||
8740 | |||
8741 | mailmime_single_fields_free(single_fields); | ||
8742 | mailmime_fields_free(mime_fields); | ||
8743 | } | ||
8744 | |||
8745 | void display_mime_single_fields(struct mailmime_single_fields * single_fields) | ||
8746 | { | ||
8747 | if (single_fields->fld_content != NULL) { | ||
8748 | printf("content type:\n"); | ||
8749 | display_mime_content(single_fields->fld_content); | ||
8750 | printf("\n"); | ||
8751 | } | ||
8752 | if (single_fields->fld_content_charset != NULL) { | ||
8753 | printf("content type charset: %s\n", | ||
8754 | single_fields->fld_content_charset); | ||
8755 | printf("\n"); | ||
8756 | } | ||
8757 | if (single_fields->fld_content_boundary != NULL) { | ||
8758 | printf("content type boundary: %s\n", | ||
8759 | single_fields->fld_content_boundary); | ||
8760 | printf("\n"); | ||
8761 | } | ||
8762 | if (single_fields->content_name != NULL) { | ||
8763 | printf("content type name: %s\n", single_fields->content_name); | ||
8764 | printf("\n"); | ||
8765 | } | ||
8766 | if (single_fields->fld_encoding != NULL) { | ||
8767 | printf("content transfer encoding:\n"); | ||
8768 | display_mime_mechanism(single_fields->fld_encoding); | ||
8769 | printf("\n"); | ||
8770 | } | ||
8771 | if (single_fields->fld_id != NULL) { | ||
8772 | printf("content id: %s\n", single_fields->fld_id); | ||
8773 | printf("\n"); | ||
8774 | } | ||
8775 | if (single_fields->fld_description != NULL) { | ||
8776 | printf("content description: %s\n", single_fields->fld_description); | ||
8777 | printf("\n"); | ||
8778 | } | ||
8779 | if (single_fields->fld_version != 0) { | ||
8780 | printf("mime version: %i.%i\n", | ||
8781 | single_fields->fld_version>> 16, | ||
8782 | single_fields->fld_version & 0xFFFF); | ||
8783 | printf("\n"); | ||
8784 | } | ||
8785 | if (single_fields->fld_disposition != NULL) { | ||
8786 | printf("content disposition:\n"); | ||
8787 | display_mime_disposition(single_fields->fld_disposition); | ||
8788 | printf("\n"); | ||
8789 | } | ||
8790 | if (single_fields->fld_disposition_filename != NULL) { | ||
8791 | printf("content disposition filename: %s\n", | ||
8792 | single_fields->fld_disposition_filename); | ||
8793 | printf("\n"); | ||
8794 | } | ||
8795 | if (single_fields->fld_disposition_creation_date != NULL) { | ||
8796 | printf("content disposition creation date: %s\n", | ||
8797 | single_fields->fld_disposition_creation_date); | ||
8798 | printf("\n"); | ||
8799 | } | ||
8800 | if (single_fields->fld_disposition_modification_date != NULL) { | ||
8801 | printf("content disposition modification date: %s\n", | ||
8802 | single_fields->fld_disposition_modification_date); | ||
8803 | printf("\n"); | ||
8804 | } | ||
8805 | if (single_fields->fld_disposition_read_date != NULL) { | ||
8806 | printf("content disposition read date: %s\n", | ||
8807 | single_fields->fld_disposition_read_date; | ||
8808 | printf("\n"); | ||
8809 | } | ||
8810 | if (single_fields->fld_disposition_size != (size_t) -1) { | ||
8811 | printf("content disposition size : %i\n", | ||
8812 | single_fields->fld_disposition_size); | ||
8813 | printf("\n"); | ||
8814 | } | ||
8815 | if (single_fields->language != NULL) { | ||
8816 | printf("content language:\n"); | ||
8817 | display_mime_language(single_fields->fld_language); | ||
8818 | printf("\n"); | ||
8819 | } | ||
8820 | } | ||
8821 | </programlisting> | ||
8822 | </example> | ||
8823 | </sect2> | ||
8824 | |||
8825 | </sect1> | ||
8826 | |||
8827 | <!-- Parser functions --> | ||
8828 | <sect1> | ||
8829 | <title>Parser functions</title> | ||
8830 | |||
8831 | <!-- mailmime_content_parse --> | ||
8832 | <sect2 id="mailmime-content-parse"> | ||
8833 | <title>mailmime_content_parse</title> | ||
8834 | |||
8835 | <programlisting role="C"> | ||
8836 | #include <libetpan/libetpan.h> | ||
8837 | |||
8838 | int mailmime_content_parse(const char * message, size_t length, | ||
8839 | size_t * index, | ||
8840 | struct mailmime_content ** result); | ||
8841 | </programlisting> | ||
8842 | |||
8843 | <para> | ||
8844 | This function will parse the content of a | ||
8845 | <command>Content-Type</command> header field. | ||
8846 | </para> | ||
8847 | |||
8848 | <itemizedlist> | ||
8849 | <listitem> | ||
8850 | <para> | ||
8851 | <command>message</command> is a string containing | ||
8852 | the MIME content type. | ||
8853 | </para> | ||
8854 | </listitem> | ||
8855 | <listitem> | ||
8856 | <para> | ||
8857 | <command>length</command> is the size of the given | ||
8858 | string. | ||
8859 | </para> | ||
8860 | </listitem> | ||
8861 | <listitem> | ||
8862 | <para> | ||
8863 | <command>index</command> is a pointer to the start of | ||
8864 | the address in the given string, <command>(* | ||
8865 | index)</command> is modified to point at the end of the | ||
8866 | parsed data. | ||
8867 | </para> | ||
8868 | </listitem> | ||
8869 | <listitem> | ||
8870 | <para> | ||
8871 | <command>result</command>. The result of the parse | ||
8872 | operation is stored in <command>(* result)</command> | ||
8873 | (see <xref linkend="mailmime-content">). | ||
8874 | </para> | ||
8875 | </listitem> | ||
8876 | </itemizedlist> | ||
8877 | |||
8878 | <example> | ||
8879 | <title>Parsing MIME content type</title> | ||
8880 | |||
8881 | <programlisting role="C"> | ||
8882 | #include <libetpan/libetpan.h> | ||
8883 | #include <sys/stat.h> | ||
8884 | #include <sys/mman.h> | ||
8885 | |||
8886 | int main(int argc, char ** argv) | ||
8887 | { | ||
8888 | int fd; | ||
8889 | int r; | ||
8890 | |||
8891 | status = EXIT_FAILURE; | ||
8892 | |||
8893 | fd = open("message.rfc2822", O_RDONLY); | ||
8894 | if (fd >= 0) { | ||
8895 | void * mem; | ||
8896 | struct stat stat_info; | ||
8897 | |||
8898 | r = fstat(fd, &stat_info); | ||
8899 | if (r >= 0) { | ||
8900 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
8901 | if (mem != MAP_FAILED) { | ||
8902 | struct mailimf_fields * f; | ||
8903 | size_t current_index; | ||
8904 | |||
8905 | current_index = 0; | ||
8906 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
8907 | &current_index, &f); | ||
8908 | if (r == MAILIMF_NO_ERROR) { | ||
8909 | clistiter * cur; | ||
8910 | |||
8911 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
8912 | clist_next(cur)) { | ||
8913 | struct mailmime_field * mime_field; | ||
8914 | struct mailimf_field * field; | ||
8915 | |||
8916 | field = clist_content(cur); | ||
8917 | |||
8918 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
8919 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
8920 | "Content-Type") == 0) { | ||
8921 | struct mailmime_content * content_type; | ||
8922 | size_t current_index; | ||
8923 | |||
8924 | current_index = 0; | ||
8925 | r = mailmime_content_parse(field->fld_data.fld_optional_field->fld_value, | ||
8926 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
8927 | &current_index, &content_type); | ||
8928 | if (r == MAILIMF_NO_ERROR) { | ||
8929 | display_mime_content(content_type); | ||
8930 | /* do the things */ | ||
8931 | status = EXIT_SUCCESS; | ||
8932 | mailmime_content_free(content_type); | ||
8933 | } | ||
8934 | } | ||
8935 | } | ||
8936 | } | ||
8937 | mailimf_fields_free(f); | ||
8938 | } | ||
8939 | } | ||
8940 | munmap(mem, stat_info.st_size); | ||
8941 | } | ||
8942 | |||
8943 | close(fd); | ||
8944 | } | ||
8945 | |||
8946 | exit(status); | ||
8947 | } | ||
8948 | </programlisting> | ||
8949 | </example> | ||
8950 | </sect2> | ||
8951 | |||
8952 | <!-- mailmime_description_parse --> | ||
8953 | <sect2 id="mailmime-description-parse"> | ||
8954 | <title>mailmime_description_parse</title> | ||
8955 | |||
8956 | <programlisting role="C"> | ||
8957 | #include >libetpan/libetpan.h< | ||
8958 | |||
8959 | int mailmime_description_parse(const char * message, size_t length, | ||
8960 | size_t * index, | ||
8961 | char ** result); | ||
8962 | </programlisting> | ||
8963 | |||
8964 | <para> | ||
8965 | This will parse the content of | ||
8966 | <command>Content-Description</command> MIME header field. | ||
8967 | </para> | ||
8968 | |||
8969 | <itemizedlist> | ||
8970 | <listitem> | ||
8971 | <para> | ||
8972 | <command>message</command> is a string containing | ||
8973 | the MIME content description. | ||
8974 | </para> | ||
8975 | </listitem> | ||
8976 | <listitem> | ||
8977 | <para> | ||
8978 | <command>length</command> is the size of the given | ||
8979 | string. | ||
8980 | </para> | ||
8981 | </listitem> | ||
8982 | <listitem> | ||
8983 | <para> | ||
8984 | <command>index</command> is a pointer to the start of | ||
8985 | the address in the given string, <command>(* | ||
8986 | index)</command> is modified to point at the end of the | ||
8987 | parsed data. | ||
8988 | </para> | ||
8989 | </listitem> | ||
8990 | <listitem> | ||
8991 | <para> | ||
8992 | <command>result</command>. The result of the parse | ||
8993 | operation is stored in <command>(* result)</command>. | ||
8994 | The result string must be freed with | ||
8995 | <command>free()</command>. | ||
8996 | </para> | ||
8997 | </listitem> | ||
8998 | </itemizedlist> | ||
8999 | |||
9000 | <example> | ||
9001 | <title>Parsing MIME description</title> | ||
9002 | |||
9003 | <programlisting role="C"> | ||
9004 | #include <libetpan/libetpan.h> | ||
9005 | #include <sys/stat.h> | ||
9006 | #include <sys/mman.h> | ||
9007 | |||
9008 | int main(int argc, char ** argv) | ||
9009 | { | ||
9010 | int fd; | ||
9011 | int r; | ||
9012 | |||
9013 | status = EXIT_FAILURE; | ||
9014 | |||
9015 | fd = open("message.rfc2822", O_RDONLY); | ||
9016 | if (fd >= 0) { | ||
9017 | void * mem; | ||
9018 | struct stat stat_info; | ||
9019 | |||
9020 | r = fstat(fd, &stat_info); | ||
9021 | if (r >= 0) { | ||
9022 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9023 | if (mem != MAP_FAILED) { | ||
9024 | struct mailimf_fields * f; | ||
9025 | size_t current_index; | ||
9026 | |||
9027 | current_index = 0; | ||
9028 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9029 | &current_index, &f); | ||
9030 | if (r == MAILIMF_NO_ERROR) { | ||
9031 | clistiter * cur; | ||
9032 | |||
9033 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9034 | clist_next(cur)) { | ||
9035 | struct mailmime_field * mime_field; | ||
9036 | struct mailimf_field * field; | ||
9037 | |||
9038 | field = clist_content(cur); | ||
9039 | |||
9040 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9041 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9042 | "Content-Description") == 0) { | ||
9043 | char * description; | ||
9044 | size_t current_index; | ||
9045 | |||
9046 | current_index = 0; | ||
9047 | r = mailmime_description_parse(field->fld_data.fld_optional_field->fld_value, | ||
9048 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9049 | &current_index, &description); | ||
9050 | if (r == MAILIMF_NO_ERROR) { | ||
9051 | printf("%s\n", description); | ||
9052 | /* do the things */ | ||
9053 | status = EXIT_SUCCESS; | ||
9054 | free(description); | ||
9055 | } | ||
9056 | } | ||
9057 | } | ||
9058 | } | ||
9059 | mailimf_fields_free(f); | ||
9060 | } | ||
9061 | } | ||
9062 | munmap(mem, stat_info.st_size); | ||
9063 | } | ||
9064 | |||
9065 | close(fd); | ||
9066 | } | ||
9067 | |||
9068 | exit(status); | ||
9069 | } | ||
9070 | </programlisting> | ||
9071 | </example> | ||
9072 | |||
9073 | |||
9074 | </sect2> | ||
9075 | |||
9076 | <!-- mailmime_encoding_parse --> | ||
9077 | <sect2 id="mailmime-encoding-parse"> | ||
9078 | <title>mailmime_encoding_parse</title> | ||
9079 | |||
9080 | <programlisting role="C"> | ||
9081 | #include >libetpan/libetpan.h< | ||
9082 | |||
9083 | int mailmime_encoding_parse(const char * message, size_t length, | ||
9084 | size_t * index, | ||
9085 | struct mailmime_mechanism ** result); | ||
9086 | </programlisting> | ||
9087 | |||
9088 | <para> | ||
9089 | This function will parse the content of | ||
9090 | <command>Content-Transfer-Encoding</command> header field. | ||
9091 | </para> | ||
9092 | |||
9093 | <itemizedlist> | ||
9094 | <listitem> | ||
9095 | <para> | ||
9096 | <command>message</command> is a string containing | ||
9097 | the MIME encoding mechanism. | ||
9098 | </para> | ||
9099 | </listitem> | ||
9100 | <listitem> | ||
9101 | <para> | ||
9102 | <command>length</command> is the size of the given | ||
9103 | string. | ||
9104 | </para> | ||
9105 | </listitem> | ||
9106 | <listitem> | ||
9107 | <para> | ||
9108 | <command>index</command> is a pointer to the start of | ||
9109 | the address in the given string, <command>(* | ||
9110 | index)</command> is modified to point at the end of the | ||
9111 | parsed data. | ||
9112 | </para> | ||
9113 | </listitem> | ||
9114 | <listitem> | ||
9115 | <para> | ||
9116 | <command>result</command>. The result of the parse | ||
9117 | operation is stored in <command>(* result)</command> | ||
9118 | (see <xref linkend="mailmime-mechanism">). | ||
9119 | </para> | ||
9120 | </listitem> | ||
9121 | </itemizedlist> | ||
9122 | |||
9123 | <example> | ||
9124 | <title>parsing MIME encoding mechanism</title> | ||
9125 | |||
9126 | <programlisting role="C"> | ||
9127 | #include <libetpan/libetpan.h> | ||
9128 | #include <sys/stat.h> | ||
9129 | #include <sys/mman.h> | ||
9130 | |||
9131 | int main(int argc, char ** argv) | ||
9132 | { | ||
9133 | int fd; | ||
9134 | int r; | ||
9135 | |||
9136 | status = EXIT_FAILURE; | ||
9137 | |||
9138 | fd = open("message.rfc2822", O_RDONLY); | ||
9139 | if (fd >= 0) { | ||
9140 | void * mem; | ||
9141 | struct stat stat_info; | ||
9142 | |||
9143 | r = fstat(fd, &stat_info); | ||
9144 | if (r >= 0) { | ||
9145 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9146 | if (mem != MAP_FAILED) { | ||
9147 | struct mailimf_fields * f; | ||
9148 | size_t current_index; | ||
9149 | |||
9150 | current_index = 0; | ||
9151 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9152 | &current_index, &f); | ||
9153 | if (r == MAILIMF_NO_ERROR) { | ||
9154 | clistiter * cur; | ||
9155 | |||
9156 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9157 | clist_next(cur)) { | ||
9158 | struct mailmime_field * mime_field; | ||
9159 | struct mailimf_field * field; | ||
9160 | |||
9161 | field = clist_content(cur); | ||
9162 | |||
9163 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9164 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9165 | "Content-Transfer-Encoding") == 0) { | ||
9166 | struct mailmime_content * encoding; | ||
9167 | size_t current_index; | ||
9168 | |||
9169 | current_index = 0; | ||
9170 | r = mailmime_encoding_parse(field->fld_data.fld_optional_field->fld_value, | ||
9171 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9172 | &current_index, &encoding); | ||
9173 | if (r == MAILIMF_NO_ERROR) { | ||
9174 | display_mime_mechanism(encoding); | ||
9175 | /* do the things */ | ||
9176 | status = EXIT_SUCCESS; | ||
9177 | mailmime_mechanism_free(encoding); | ||
9178 | } | ||
9179 | } | ||
9180 | } | ||
9181 | } | ||
9182 | mailimf_fields_free(f); | ||
9183 | } | ||
9184 | } | ||
9185 | munmap(mem, stat_info.st_size); | ||
9186 | } | ||
9187 | |||
9188 | close(fd); | ||
9189 | } | ||
9190 | |||
9191 | exit(status); | ||
9192 | } | ||
9193 | </programlisting> | ||
9194 | </example> | ||
9195 | </sect2> | ||
9196 | |||
9197 | <!-- mailmime_field_parse --> | ||
9198 | <sect2 id="mailmime-field-parse"> | ||
9199 | <title>mailmime_field_parse</title> | ||
9200 | |||
9201 | <programlisting role="C"> | ||
9202 | #include <libetpan/libetpan.h> | ||
9203 | |||
9204 | int | ||
9205 | mailmime_field_parse(struct mailimf_optional_field * field, | ||
9206 | struct mailmime_field ** result); | ||
9207 | </programlisting> | ||
9208 | |||
9209 | <para> | ||
9210 | This function will parse a MIME header field. | ||
9211 | </para> | ||
9212 | |||
9213 | <itemizedlist> | ||
9214 | <listitem> | ||
9215 | <para> | ||
9216 | <command>field</command> is a non-parsed field | ||
9217 | (see <xref linkend="mailimf-optional-field">). | ||
9218 | </para> | ||
9219 | |||
9220 | <para> | ||
9221 | <command>result</command>. The result of the parse | ||
9222 | operation is stored in <command>(* result)</command> | ||
9223 | (see <xref linkend="mailmime-field">). | ||
9224 | </para> | ||
9225 | </listitem> | ||
9226 | </itemizedlist> | ||
9227 | |||
9228 | <example> | ||
9229 | <title>parsing MIME header field</title> | ||
9230 | |||
9231 | <programlisting role="C"> | ||
9232 | #include <libetpan/libetpan.h> | ||
9233 | #include <sys/stat.h> | ||
9234 | #include <sys/mman.h> | ||
9235 | |||
9236 | int main(int argc, char ** argv) | ||
9237 | { | ||
9238 | int fd; | ||
9239 | int r; | ||
9240 | |||
9241 | status = EXIT_FAILURE; | ||
9242 | |||
9243 | fd = open("message.rfc2822", O_RDONLY); | ||
9244 | if (fd >= 0) { | ||
9245 | void * mem; | ||
9246 | struct stat stat_info; | ||
9247 | |||
9248 | r = fstat(fd, &stat_info); | ||
9249 | if (r >= 0) { | ||
9250 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9251 | if (mem != MAP_FAILED) { | ||
9252 | struct mailimf_fields * f; | ||
9253 | size_t current_index; | ||
9254 | |||
9255 | current_index = 0; | ||
9256 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9257 | &current_index, &f); | ||
9258 | if (r == MAILIMF_NO_ERROR) { | ||
9259 | clistiter * cur; | ||
9260 | |||
9261 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9262 | clist_next(cur)) { | ||
9263 | struct mailmime_field * mime_field; | ||
9264 | struct mailimf_field * field; | ||
9265 | |||
9266 | field = clist_content(cur); | ||
9267 | |||
9268 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9269 | r = mailmime_field_parse(field->fld_data.fld_optional_field, | ||
9270 | &mime_fields); | ||
9271 | if (r == MAILIMF_NO_ERROR) { | ||
9272 | display_mime_field(mime_field); | ||
9273 | mailmime_field_free(mime_field); | ||
9274 | status = EXIT_SUCCESS; | ||
9275 | } | ||
9276 | } | ||
9277 | } | ||
9278 | |||
9279 | mailimf_fields_free(f); | ||
9280 | } | ||
9281 | } | ||
9282 | munmap(mem, stat_info.st_size); | ||
9283 | } | ||
9284 | |||
9285 | close(fd); | ||
9286 | } | ||
9287 | |||
9288 | exit(status); | ||
9289 | } | ||
9290 | </programlisting> | ||
9291 | </example> | ||
9292 | |||
9293 | </sect2> | ||
9294 | |||
9295 | <!-- mailmime_id_parse --> | ||
9296 | <sect2 id="mailmime-id-parse"> | ||
9297 | <title>mailmime_id_parse</title> | ||
9298 | |||
9299 | <programlisting role="C"> | ||
9300 | #include >libetpan/libetpan.h< | ||
9301 | |||
9302 | int mailmime_id_parse(const char * message, size_t length, | ||
9303 | size_t * index, char ** result); | ||
9304 | </programlisting> | ||
9305 | |||
9306 | <para> | ||
9307 | This will parse the content of | ||
9308 | <command>Content-ID</command> MIME header field. | ||
9309 | </para> | ||
9310 | |||
9311 | <itemizedlist> | ||
9312 | <listitem> | ||
9313 | <para> | ||
9314 | <command>message</command> is a string containing | ||
9315 | the MIME content identifier. | ||
9316 | </para> | ||
9317 | </listitem> | ||
9318 | <listitem> | ||
9319 | <para> | ||
9320 | <command>length</command> is the size of the given | ||
9321 | string. | ||
9322 | </para> | ||
9323 | </listitem> | ||
9324 | <listitem> | ||
9325 | <para> | ||
9326 | <command>index</command> is a pointer to the start of | ||
9327 | the address in the given string, <command>(* | ||
9328 | index)</command> is modified to point at the end of the | ||
9329 | parsed data. | ||
9330 | </para> | ||
9331 | </listitem> | ||
9332 | <listitem> | ||
9333 | <para> | ||
9334 | <command>result</command>. The result of the parse | ||
9335 | operation is stored in <command>(* result)</command>. | ||
9336 | The result string must be freed with | ||
9337 | <command>free()</command>. | ||
9338 | </para> | ||
9339 | </listitem> | ||
9340 | </itemizedlist> | ||
9341 | |||
9342 | <example> | ||
9343 | <title>Parsing MIME content identifier</title> | ||
9344 | |||
9345 | <programlisting role="C"> | ||
9346 | #include <libetpan/libetpan.h> | ||
9347 | #include <sys/stat.h> | ||
9348 | #include <sys/mman.h> | ||
9349 | |||
9350 | int main(int argc, char ** argv) | ||
9351 | { | ||
9352 | int fd; | ||
9353 | int r; | ||
9354 | |||
9355 | status = EXIT_FAILURE; | ||
9356 | |||
9357 | fd = open("message.rfc2822", O_RDONLY); | ||
9358 | if (fd >= 0) { | ||
9359 | void * mem; | ||
9360 | struct stat stat_info; | ||
9361 | |||
9362 | r = fstat(fd, &stat_info); | ||
9363 | if (r >= 0) { | ||
9364 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9365 | if (mem != MAP_FAILED) { | ||
9366 | struct mailimf_fields * f; | ||
9367 | size_t current_index; | ||
9368 | |||
9369 | current_index = 0; | ||
9370 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9371 | &current_index, &f); | ||
9372 | if (r == MAILIMF_NO_ERROR) { | ||
9373 | clistiter * cur; | ||
9374 | |||
9375 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9376 | clist_next(cur)) { | ||
9377 | struct mailmime_field * mime_field; | ||
9378 | struct mailimf_field * field; | ||
9379 | |||
9380 | field = clist_content(cur); | ||
9381 | |||
9382 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9383 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9384 | "Content-ID") == 0) { | ||
9385 | char * id; | ||
9386 | size_t current_index; | ||
9387 | |||
9388 | current_index = 0; | ||
9389 | r = mailmime_id_parse(field->fld_data.fld_optional_field->fld_value, | ||
9390 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9391 | &current_index, &id); | ||
9392 | if (r == MAILIMF_NO_ERROR) { | ||
9393 | printf("%s\n", id); | ||
9394 | /* do the things */ | ||
9395 | status = EXIT_SUCCESS; | ||
9396 | free(id); | ||
9397 | } | ||
9398 | } | ||
9399 | } | ||
9400 | } | ||
9401 | mailimf_fields_free(f); | ||
9402 | } | ||
9403 | } | ||
9404 | munmap(mem, stat_info.st_size); | ||
9405 | } | ||
9406 | |||
9407 | close(fd); | ||
9408 | } | ||
9409 | |||
9410 | exit(status); | ||
9411 | } | ||
9412 | </programlisting> | ||
9413 | </example> | ||
9414 | </sect2> | ||
9415 | |||
9416 | <!-- mailmime_fields_parse --> | ||
9417 | <sect2 id="mailmime-fields-parse"> | ||
9418 | <title>mailmime_fields_parse</title> | ||
9419 | |||
9420 | <programlisting role="C"> | ||
9421 | #include <libetpan/libetpan.h> | ||
9422 | |||
9423 | int | ||
9424 | mailmime_fields_parse(struct mailimf_fields * fields, | ||
9425 | struct mailmime_fields ** result); | ||
9426 | </programlisting> | ||
9427 | |||
9428 | <para> | ||
9429 | This function will parse a MIME header fields. | ||
9430 | </para> | ||
9431 | |||
9432 | <itemizedlist> | ||
9433 | <listitem> | ||
9434 | <para> | ||
9435 | <command>fields</command> is a list of RFC 2822 fields | ||
9436 | (see <xref linkend="mailimf-fields">). | ||
9437 | </para> | ||
9438 | |||
9439 | <para> | ||
9440 | <command>result</command>. The result of the parse | ||
9441 | operation is stored in <command>(* result)</command> | ||
9442 | (see <xref linkend="mailmime-fields">). | ||
9443 | </para> | ||
9444 | </listitem> | ||
9445 | </itemizedlist> | ||
9446 | |||
9447 | <example> | ||
9448 | <title>parsing MIME header fields</title> | ||
9449 | |||
9450 | <programlisting role="C"> | ||
9451 | #include <libetpan/libetpan.h> | ||
9452 | #include <sys/stat.h> | ||
9453 | #include <sys/mman.h> | ||
9454 | |||
9455 | int main(int argc, char ** argv) | ||
9456 | { | ||
9457 | int fd; | ||
9458 | int r; | ||
9459 | |||
9460 | status = EXIT_FAILURE; | ||
9461 | |||
9462 | fd = open("message.rfc2822", O_RDONLY); | ||
9463 | if (fd >= 0) { | ||
9464 | void * mem; | ||
9465 | struct stat stat_info; | ||
9466 | |||
9467 | r = fstat(fd, &stat_info); | ||
9468 | if (r >= 0) { | ||
9469 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9470 | if (mem != MAP_FAILED) { | ||
9471 | struct mailimf_fields * f; | ||
9472 | size_t current_index; | ||
9473 | |||
9474 | current_index = 0; | ||
9475 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9476 | &current_index, &f); | ||
9477 | if (r == MAILIMF_NO_ERROR) { | ||
9478 | struct mailmime_fields * mime_fields; | ||
9479 | |||
9480 | r = mailmime_fields_parse(f, &mime_fields); | ||
9481 | if (r == MAILIMF_NO_ERROR) { | ||
9482 | display_mime_fields(mime_fields); | ||
9483 | mailmime_fields_free(mime_fields); | ||
9484 | status = EXIT_SUCCESS; | ||
9485 | } | ||
9486 | |||
9487 | mailimf_fields_free(f); | ||
9488 | } | ||
9489 | } | ||
9490 | munmap(mem, stat_info.st_size); | ||
9491 | } | ||
9492 | |||
9493 | close(fd); | ||
9494 | } | ||
9495 | |||
9496 | exit(status); | ||
9497 | } | ||
9498 | </programlisting> | ||
9499 | </example> | ||
9500 | |||
9501 | </sect2> | ||
9502 | |||
9503 | <!-- mailmime_version_parse --> | ||
9504 | <sect2 id="mailmime-version-parse"> | ||
9505 | <title>mailmime_version_parse</title> | ||
9506 | |||
9507 | <programlisting role="C"> | ||
9508 | #include <libetpan/libetpan.h> | ||
9509 | |||
9510 | int mailmime_version_parse(const char * message, size_t length, | ||
9511 | size_t * index, | ||
9512 | uint32_t * result); | ||
9513 | </programlisting> | ||
9514 | |||
9515 | <para> | ||
9516 | This will parse the content of | ||
9517 | <command>MIME-Version</command> MIME header field. | ||
9518 | </para> | ||
9519 | |||
9520 | <itemizedlist> | ||
9521 | <listitem> | ||
9522 | <para> | ||
9523 | <command>message</command> is a string containing | ||
9524 | the MIME version. | ||
9525 | </para> | ||
9526 | </listitem> | ||
9527 | <listitem> | ||
9528 | <para> | ||
9529 | <command>length</command> is the size of the given | ||
9530 | string. | ||
9531 | </para> | ||
9532 | </listitem> | ||
9533 | <listitem> | ||
9534 | <para> | ||
9535 | <command>index</command> is a pointer to the start of | ||
9536 | the address in the given string, <command>(* | ||
9537 | index)</command> is modified to point at the end of the | ||
9538 | parsed data. | ||
9539 | </para> | ||
9540 | </listitem> | ||
9541 | <listitem> | ||
9542 | <para> | ||
9543 | <command>result</command>. The result of the parse | ||
9544 | operation is stored in <command>(* result)</command> | ||
9545 | (see <xref linkend="mailmime-field">). | ||
9546 | </para> | ||
9547 | </listitem> | ||
9548 | </itemizedlist> | ||
9549 | |||
9550 | <example> | ||
9551 | <title>parsing MIME version</title> | ||
9552 | |||
9553 | <programlisting role="C"> | ||
9554 | #include <libetpan/libetpan.h> | ||
9555 | #include <sys/stat.h> | ||
9556 | #include <sys/mman.h> | ||
9557 | |||
9558 | int main(int argc, char ** argv) | ||
9559 | { | ||
9560 | int fd; | ||
9561 | int r; | ||
9562 | |||
9563 | status = EXIT_FAILURE; | ||
9564 | |||
9565 | fd = open("message.rfc2822", O_RDONLY); | ||
9566 | if (fd >= 0) { | ||
9567 | void * mem; | ||
9568 | struct stat stat_info; | ||
9569 | |||
9570 | r = fstat(fd, &stat_info); | ||
9571 | if (r >= 0) { | ||
9572 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9573 | if (mem != MAP_FAILED) { | ||
9574 | struct mailimf_fields * f; | ||
9575 | size_t current_index; | ||
9576 | |||
9577 | current_index = 0; | ||
9578 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9579 | &current_index, &f); | ||
9580 | if (r == MAILIMF_NO_ERROR) { | ||
9581 | clistiter * cur; | ||
9582 | |||
9583 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9584 | clist_next(cur)) { | ||
9585 | struct mailmime_field * mime_field; | ||
9586 | struct mailimf_field * field; | ||
9587 | |||
9588 | field = clist_content(cur); | ||
9589 | |||
9590 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9591 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9592 | "MIME-Version") == 0) { | ||
9593 | uint32_t version; | ||
9594 | size_t current_index; | ||
9595 | |||
9596 | current_index = 0; | ||
9597 | r = mailmime_version_parse(field->fld_data.fld_optional_field->fld_value, | ||
9598 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9599 | &current_index, &version); | ||
9600 | if (r == MAILIMF_NO_ERROR) { | ||
9601 | printf("%i.%i\n", version >> 16, version & 0xFFFF); | ||
9602 | /* do the things */ | ||
9603 | status = EXIT_SUCCESS; | ||
9604 | free(description); | ||
9605 | } | ||
9606 | } | ||
9607 | } | ||
9608 | } | ||
9609 | mailimf_fields_free(f); | ||
9610 | } | ||
9611 | } | ||
9612 | munmap(mem, stat_info.st_size); | ||
9613 | } | ||
9614 | |||
9615 | close(fd); | ||
9616 | } | ||
9617 | |||
9618 | exit(status); | ||
9619 | } | ||
9620 | </programlisting> | ||
9621 | </example> | ||
9622 | </sect2> | ||
9623 | |||
9624 | <!-- mailmime_parameter_parse --> | ||
9625 | <sect2 id="mailmime-parameter-parse"> | ||
9626 | <title>mailmime_parameter_parse</title> | ||
9627 | |||
9628 | <programlisting role="C"> | ||
9629 | #include <libetpan/libetpan.h> | ||
9630 | |||
9631 | int mailmime_parameter_parse(const char * message, size_t length, | ||
9632 | size_t * index, | ||
9633 | struct mailmime_parameter ** result); | ||
9634 | </programlisting> | ||
9635 | |||
9636 | <para> | ||
9637 | This will parse a MIME parameter (parameter of | ||
9638 | <command>Content-Type</command> or parameter of | ||
9639 | <command>Content-Disposition</command>). | ||
9640 | </para> | ||
9641 | |||
9642 | <itemizedlist> | ||
9643 | <listitem> | ||
9644 | <para> | ||
9645 | <command>message</command> is a string containing | ||
9646 | the MIME parameter. | ||
9647 | </para> | ||
9648 | </listitem> | ||
9649 | <listitem> | ||
9650 | <para> | ||
9651 | <command>length</command> is the size of the given | ||
9652 | string. | ||
9653 | </para> | ||
9654 | </listitem> | ||
9655 | <listitem> | ||
9656 | <para> | ||
9657 | <command>index</command> is a pointer to the start of | ||
9658 | the address in the given string, <command>(* | ||
9659 | index)</command> is modified to point at the end of the | ||
9660 | parsed data. | ||
9661 | </para> | ||
9662 | </listitem> | ||
9663 | <listitem> | ||
9664 | <para> | ||
9665 | <command>result</command>. The result of the parse | ||
9666 | operation is stored in <command>(* result)</command> | ||
9667 | (see <xref linkend="mailmime-parameter">). | ||
9668 | </para> | ||
9669 | </listitem> | ||
9670 | </itemizedlist> | ||
9671 | |||
9672 | <example> | ||
9673 | <title>parsing a MIME parameter</title> | ||
9674 | |||
9675 | <programlisting role="C"> | ||
9676 | #include <libetpan/libetpan.h> | ||
9677 | |||
9678 | #define PARAM_STR "foo=bar" | ||
9679 | |||
9680 | int main(int argc, char ** argv) | ||
9681 | { | ||
9682 | int fd; | ||
9683 | int r; | ||
9684 | size_t current_index; | ||
9685 | struct mailmime_parameter * param; | ||
9686 | int status; | ||
9687 | |||
9688 | status = EXIT_FAILURE; | ||
9689 | |||
9690 | current_index = 0; | ||
9691 | r = mailmime_parameter_parse(PARAM_STR, sizeof(PARAM_STR) - 1, | ||
9692 | &current_index, &param); | ||
9693 | if (r == MAILIMF_NO_ERROR) { | ||
9694 | display_mime_parameter(param); | ||
9695 | /* do the things */ | ||
9696 | mailmime_parameter_free(param); | ||
9697 | status = EXIT_SUCCESS; | ||
9698 | } | ||
9699 | |||
9700 | exit(status); | ||
9701 | } | ||
9702 | </programlisting> | ||
9703 | </example> | ||
9704 | </sect2> | ||
9705 | |||
9706 | <!-- mailmime_language_parse --> | ||
9707 | <sect2 id="mailmime-language-parse"> | ||
9708 | <title>mailmime_language_parse</title> | ||
9709 | |||
9710 | <programlisting role="C"> | ||
9711 | #include <libetpan/libetpan.h> | ||
9712 | |||
9713 | int mailmime_language_parse(const char * message, size_t length, | ||
9714 | size_t * index, | ||
9715 | struct mailmime_language ** result); | ||
9716 | </programlisting> | ||
9717 | |||
9718 | <para> | ||
9719 | This function will parse the content of a | ||
9720 | <command>Content-Language</command> header. | ||
9721 | </para> | ||
9722 | |||
9723 | <itemizedlist> | ||
9724 | <listitem> | ||
9725 | <para> | ||
9726 | <command>message</command> is a string containing | ||
9727 | the MIME content language. | ||
9728 | </para> | ||
9729 | </listitem> | ||
9730 | <listitem> | ||
9731 | <para> | ||
9732 | <command>length</command> is the size of the given | ||
9733 | string. | ||
9734 | </para> | ||
9735 | </listitem> | ||
9736 | <listitem> | ||
9737 | <para> | ||
9738 | <command>index</command> is a pointer to the start of | ||
9739 | the address in the given string, <command>(* | ||
9740 | index)</command> is modified to point at the end of the | ||
9741 | parsed data. | ||
9742 | </para> | ||
9743 | </listitem> | ||
9744 | <listitem> | ||
9745 | <para> | ||
9746 | <command>result</command>. The result of the parse | ||
9747 | operation is stored in <command>(* result)</command> | ||
9748 | (see <xref linkend="mailmime-language">). | ||
9749 | </para> | ||
9750 | </listitem> | ||
9751 | </itemizedlist> | ||
9752 | |||
9753 | <example> | ||
9754 | <title>Parsing the MIME content langage</title> | ||
9755 | |||
9756 | <programlisting role="C"> | ||
9757 | #include <libetpan/libetpan.h> | ||
9758 | #include <sys/stat.h> | ||
9759 | #include <sys/mman.h> | ||
9760 | |||
9761 | int main(int argc, char ** argv) | ||
9762 | { | ||
9763 | int fd; | ||
9764 | int r; | ||
9765 | |||
9766 | status = EXIT_FAILURE; | ||
9767 | |||
9768 | fd = open("message.rfc2822", O_RDONLY); | ||
9769 | if (fd >= 0) { | ||
9770 | void * mem; | ||
9771 | struct stat stat_info; | ||
9772 | |||
9773 | r = fstat(fd, &stat_info); | ||
9774 | if (r >= 0) { | ||
9775 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9776 | if (mem != MAP_FAILED) { | ||
9777 | struct mailimf_fields * f; | ||
9778 | size_t current_index; | ||
9779 | |||
9780 | current_index = 0; | ||
9781 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9782 | &current_index, &f); | ||
9783 | if (r == MAILIMF_NO_ERROR) { | ||
9784 | clistiter * cur; | ||
9785 | |||
9786 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9787 | clist_next(cur)) { | ||
9788 | struct mailmime_field * mime_field; | ||
9789 | struct mailimf_field * field; | ||
9790 | |||
9791 | field = clist_content(cur); | ||
9792 | |||
9793 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9794 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9795 | "Content-Language") == 0) { | ||
9796 | struct mailmime_language * lang; | ||
9797 | size_t current_index; | ||
9798 | |||
9799 | current_index = 0; | ||
9800 | r = mailmime_id_parse(field->fld_data.fld_optional_field->fld_value, | ||
9801 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9802 | &current_index, &lang); | ||
9803 | if (r == MAILIMF_NO_ERROR) { | ||
9804 | display_mime_language(lang); | ||
9805 | /* do the things */ | ||
9806 | status = EXIT_SUCCESS; | ||
9807 | free(id); | ||
9808 | } | ||
9809 | } | ||
9810 | } | ||
9811 | } | ||
9812 | mailimf_fields_free(f); | ||
9813 | } | ||
9814 | } | ||
9815 | munmap(mem, stat_info.st_size); | ||
9816 | } | ||
9817 | |||
9818 | close(fd); | ||
9819 | } | ||
9820 | |||
9821 | exit(status); | ||
9822 | } | ||
9823 | </programlisting> | ||
9824 | </example> | ||
9825 | </sect2> | ||
9826 | |||
9827 | <!-- mailmime_disposition_parse --> | ||
9828 | <sect2 id="mailmime-disposition-parse"> | ||
9829 | <title>mailmime_disposition_parse</title> | ||
9830 | |||
9831 | <programlisting role="C"> | ||
9832 | #include <libetpan/libetpan.h> | ||
9833 | |||
9834 | int mailmime_disposition_parse(const char * message, size_t length, | ||
9835 | size_t * index, | ||
9836 | struct mailmime_disposition ** result); | ||
9837 | </programlisting> | ||
9838 | |||
9839 | <para> | ||
9840 | This function will parse the content of a | ||
9841 | <command>Content-Disposition</command> MIME header field. | ||
9842 | </para> | ||
9843 | |||
9844 | <itemizedlist> | ||
9845 | <listitem> | ||
9846 | <para> | ||
9847 | <command>message</command> is a string containing | ||
9848 | the MIME content disposition. | ||
9849 | </para> | ||
9850 | </listitem> | ||
9851 | <listitem> | ||
9852 | <para> | ||
9853 | <command>length</command> is the size of the given | ||
9854 | string. | ||
9855 | </para> | ||
9856 | </listitem> | ||
9857 | <listitem> | ||
9858 | <para> | ||
9859 | <command>index</command> is a pointer to the start of | ||
9860 | the address in the given string, <command>(* | ||
9861 | index)</command> is modified to point at the end of the | ||
9862 | parsed data. | ||
9863 | </para> | ||
9864 | </listitem> | ||
9865 | <listitem> | ||
9866 | <para> | ||
9867 | <command>result</command>. The result of the parse | ||
9868 | operation is stored in <command>(* result)</command> | ||
9869 | (see <xref linkend="mailmime-disposition">). | ||
9870 | </para> | ||
9871 | </listitem> | ||
9872 | </itemizedlist> | ||
9873 | |||
9874 | <example> | ||
9875 | <title>Parsing the MIME content disposition</title> | ||
9876 | |||
9877 | <programlisting role="C"> | ||
9878 | #include <libetpan/libetpan.h> | ||
9879 | #include <sys/stat.h> | ||
9880 | #include <sys/mman.h> | ||
9881 | |||
9882 | int main(int argc, char ** argv) | ||
9883 | { | ||
9884 | int fd; | ||
9885 | int r; | ||
9886 | |||
9887 | status = EXIT_FAILURE; | ||
9888 | |||
9889 | fd = open("message.rfc2822", O_RDONLY); | ||
9890 | if (fd >= 0) { | ||
9891 | void * mem; | ||
9892 | struct stat stat_info; | ||
9893 | |||
9894 | r = fstat(fd, &stat_info); | ||
9895 | if (r >= 0) { | ||
9896 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
9897 | if (mem != MAP_FAILED) { | ||
9898 | struct mailimf_fields * f; | ||
9899 | size_t current_index; | ||
9900 | |||
9901 | current_index = 0; | ||
9902 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
9903 | &current_index, &f); | ||
9904 | if (r == MAILIMF_NO_ERROR) { | ||
9905 | clistiter * cur; | ||
9906 | |||
9907 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
9908 | clist_next(cur)) { | ||
9909 | struct mailmime_field * mime_field; | ||
9910 | struct mailimf_field * field; | ||
9911 | |||
9912 | field = clist_content(cur); | ||
9913 | |||
9914 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
9915 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
9916 | "Content-Disposition") == 0) { | ||
9917 | struct mailmime_disposition * dsp; | ||
9918 | size_t current_index; | ||
9919 | |||
9920 | current_index = 0; | ||
9921 | r = mailmime_id_parse(field->fld_data.fld_optional_field->fld_value, | ||
9922 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
9923 | &current_index, &dsp); | ||
9924 | if (r == MAILIMF_NO_ERROR) { | ||
9925 | display_mime_disposition(dsp); | ||
9926 | /* do the things */ | ||
9927 | status = EXIT_SUCCESS; | ||
9928 | free(id); | ||
9929 | } | ||
9930 | } | ||
9931 | } | ||
9932 | } | ||
9933 | mailimf_fields_free(f); | ||
9934 | } | ||
9935 | } | ||
9936 | munmap(mem, stat_info.st_size); | ||
9937 | } | ||
9938 | |||
9939 | close(fd); | ||
9940 | } | ||
9941 | |||
9942 | exit(status); | ||
9943 | } | ||
9944 | </programlisting> | ||
9945 | </example> | ||
9946 | </sect2> | ||
9947 | |||
9948 | <!-- mailmime_disposition_type_parse --> | ||
9949 | <sect2 id="mailmime-disposition-type-parse"> | ||
9950 | <title>mailmime_disposition_type_parse</title> | ||
9951 | |||
9952 | <programlisting role="C"> | ||
9953 | #include <libetpan/libetpan.h> | ||
9954 | |||
9955 | int | ||
9956 | mailmime_disposition_type_parse(const char * message, size_t length, | ||
9957 | size_t * index, | ||
9958 | struct mailmime_disposition_type ** | ||
9959 | result); | ||
9960 | </programlisting> | ||
9961 | |||
9962 | <para> | ||
9963 | This function will parse the type of MIME content | ||
9964 | disposition. | ||
9965 | </para> | ||
9966 | |||
9967 | <itemizedlist> | ||
9968 | <listitem> | ||
9969 | <para> | ||
9970 | <command>message</command> is a string containing | ||
9971 | the MIME content disposition type. | ||
9972 | </para> | ||
9973 | </listitem> | ||
9974 | <listitem> | ||
9975 | <para> | ||
9976 | <command>length</command> is the size of the given | ||
9977 | string. | ||
9978 | </para> | ||
9979 | </listitem> | ||
9980 | <listitem> | ||
9981 | <para> | ||
9982 | <command>index</command> is a pointer to the start of | ||
9983 | the address in the given string, <command>(* | ||
9984 | index)</command> is modified to point at the end of the | ||
9985 | parsed data. | ||
9986 | </para> | ||
9987 | </listitem> | ||
9988 | <listitem> | ||
9989 | <para> | ||
9990 | <command>result</command>. The result of the parse | ||
9991 | operation is stored in <command>(* result)</command> | ||
9992 | (see <xref linkend="mailmime-disposition-type">). | ||
9993 | </para> | ||
9994 | </listitem> | ||
9995 | </itemizedlist> | ||
9996 | |||
9997 | <example> | ||
9998 | <title>parsing a MIME content disposition type</title> | ||
9999 | |||
10000 | <programlisting role="C"> | ||
10001 | #include <libetpan/libetpan.h> | ||
10002 | |||
10003 | #define DSP_TYPE_STR "attachment" | ||
10004 | |||
10005 | int main(int argc, char ** argv) | ||
10006 | { | ||
10007 | int fd; | ||
10008 | int r; | ||
10009 | size_t current_index; | ||
10010 | struct mailmime_disposition_type * dsp_type; | ||
10011 | int status; | ||
10012 | |||
10013 | status = EXIT_FAILURE; | ||
10014 | |||
10015 | current_index = 0; | ||
10016 | r = mailmime_disposition_type_parse(DSP_TYPE_STR, sizeof(DSP_TYPE_STR) - 1, | ||
10017 | &current_index, &dsp_type); | ||
10018 | if (r == MAILIMF_NO_ERROR) { | ||
10019 | display_mime_disposition_type(dsp_type); | ||
10020 | /* do the things */ | ||
10021 | mailmime_disposition_type_free(dsp_type); | ||
10022 | status = EXIT_SUCCESS; | ||
10023 | } | ||
10024 | |||
10025 | exit(status); | ||
10026 | } | ||
10027 | </programlisting> | ||
10028 | </example> | ||
10029 | </sect2> | ||
10030 | |||
10031 | <!-- mailmime_encoded_phrase_parse --> | ||
10032 | <sect2 id="mailmime-encoded-phrase-parse"> | ||
10033 | <title>mailmime_encoded_phrase_parse</title> | ||
10034 | |||
10035 | <programlisting role="C"> | ||
10036 | #include <libetpan/libetpan.h> | ||
10037 | |||
10038 | int mailmime_encoded_phrase_parse(const char * default_fromcode, | ||
10039 | const char * message, size_t length, | ||
10040 | size_t * index, const char * tocode, | ||
10041 | char ** result); | ||
10042 | </programlisting> | ||
10043 | |||
10044 | <para> | ||
10045 | This function will decode a MIME encoded header string, | ||
10046 | encoded with RFC 2047. | ||
10047 | </para> | ||
10048 | |||
10049 | <itemizedlist> | ||
10050 | <listitem> | ||
10051 | <para> | ||
10052 | <command>default_fromcode</command> is the default | ||
10053 | code to use for parts of string that are not marked | ||
10054 | with charset. | ||
10055 | </para> | ||
10056 | </listitem> | ||
10057 | <listitem> | ||
10058 | <para> | ||
10059 | <command>message</command> is the string to decode. | ||
10060 | </para> | ||
10061 | </listitem> | ||
10062 | <listitem> | ||
10063 | <para> | ||
10064 | <command>length</command> is the size of the given | ||
10065 | string. | ||
10066 | </para> | ||
10067 | </listitem> | ||
10068 | <listitem> | ||
10069 | <para> | ||
10070 | <command>index</command> is a pointer to the start of | ||
10071 | the address in the given string, <command>(* | ||
10072 | index)</command> is modified to point at the end of the | ||
10073 | parsed data. | ||
10074 | </para> | ||
10075 | </listitem> | ||
10076 | <listitem> | ||
10077 | <para> | ||
10078 | <command>tocode</command> is the destination charset | ||
10079 | for decoding. | ||
10080 | </para> | ||
10081 | </listitem> | ||
10082 | <listitem> | ||
10083 | <para> | ||
10084 | <command>result</command>. The result of the parse | ||
10085 | operation is stored in <command>(* result)</command>. | ||
10086 | </para> | ||
10087 | </listitem> | ||
10088 | </itemizedlist> | ||
10089 | |||
10090 | <example> | ||
10091 | <title>decoding a MIME encoded header string</title> | ||
10092 | |||
10093 | <programlisting role="C"> | ||
10094 | #include <libetpan/libetpan.h> | ||
10095 | |||
10096 | #define TEST_STRING "=?iso-8859-1?ab?= =?iso-8859-15?cd?=" | ||
10097 | |||
10098 | int main(int argc, char ** argv) | ||
10099 | { | ||
10100 | size_t cur_token; | ||
10101 | char * decoded_subject; | ||
10102 | |||
10103 | cur_token = 0; | ||
10104 | mailmime_encoded_phrase_parse("iso-8859-1", | ||
10105 | TEST_STRING, sizeof(TEST_STRING), | ||
10106 | &cur_token, "iso-8859-1", &decoded_subject); | ||
10107 | |||
10108 | printf("%s\n", decoded_subject); | ||
10109 | |||
10110 | /* do the things */ | ||
10111 | |||
10112 | free(decoded_subject); | ||
10113 | } | ||
10114 | </programlisting> | ||
10115 | </example> | ||
10116 | |||
10117 | </sect2> | ||
10118 | |||
10119 | <!-- mailmime_parse --> | ||
10120 | <sect2 id="mailmime-parse"> | ||
10121 | <title>mailmime_parse</title> | ||
10122 | |||
10123 | <programlisting role="C"> | ||
10124 | #include <libetpan/libetpan.h> | ||
10125 | |||
10126 | int mailmime_parse(const char * message, size_t length, | ||
10127 | size_t * index, struct mailmime ** result); | ||
10128 | </programlisting> | ||
10129 | |||
10130 | <para> | ||
10131 | This will parse a MIME message. | ||
10132 | </para> | ||
10133 | |||
10134 | <itemizedlist> | ||
10135 | <listitem> | ||
10136 | <para> | ||
10137 | <command>message</command> is a string containing | ||
10138 | the MIME message. | ||
10139 | </para> | ||
10140 | </listitem> | ||
10141 | <listitem> | ||
10142 | <para> | ||
10143 | <command>length</command> is the size of the given | ||
10144 | string. | ||
10145 | </para> | ||
10146 | </listitem> | ||
10147 | <listitem> | ||
10148 | <para> | ||
10149 | <command>index</command> is a pointer to the start of | ||
10150 | the address in the given string, <command>(* | ||
10151 | index)</command> is modified to point at the end of the | ||
10152 | parsed data. | ||
10153 | </para> | ||
10154 | </listitem> | ||
10155 | <listitem> | ||
10156 | <para> | ||
10157 | <command>result</command>. The result of the parse | ||
10158 | operation is stored in <command>(* result)</command> | ||
10159 | (see <xref linkend="mailmime">). | ||
10160 | </para> | ||
10161 | </listitem> | ||
10162 | </itemizedlist> | ||
10163 | |||
10164 | <example> | ||
10165 | <title>parsing a MIME message</title> | ||
10166 | |||
10167 | <programlisting role="C"> | ||
10168 | #include <libetpan/libetpan.h> | ||
10169 | #include <sys/stat.h> | ||
10170 | #include <sys/mman.h> | ||
10171 | |||
10172 | int main(int argc, char ** argv) | ||
10173 | { | ||
10174 | int fd; | ||
10175 | int r; | ||
10176 | |||
10177 | status = EXIT_FAILURE; | ||
10178 | |||
10179 | fd = open("message.rfc2822", O_RDONLY); | ||
10180 | if (fd >= 0) { | ||
10181 | void * mem; | ||
10182 | struct stat stat_info; | ||
10183 | |||
10184 | r = fstat(fd, &stat_info); | ||
10185 | if (r >= 0) { | ||
10186 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
10187 | if (mem != MAP_FAILED) { | ||
10188 | struct mailmime * mime; | ||
10189 | size_t current_index; | ||
10190 | |||
10191 | current_index = 0; | ||
10192 | r = mailmime_parse(mem, stat_info.st_size, | ||
10193 | &current_index, &mime); | ||
10194 | if (r == MAILIMF_NO_ERROR) { | ||
10195 | display_mime(mime); | ||
10196 | /* do the things */ | ||
10197 | status = EXIT_SUCCESS; | ||
10198 | mailmime_free(mime); | ||
10199 | } | ||
10200 | } | ||
10201 | munmap(mem, stat_info.st_size); | ||
10202 | } | ||
10203 | |||
10204 | close(fd); | ||
10205 | } | ||
10206 | |||
10207 | exit(status); | ||
10208 | } | ||
10209 | </programlisting> | ||
10210 | </example> | ||
10211 | </sect2> | ||
10212 | |||
10213 | <!-- mailmime_base64_body_parse --> | ||
10214 | <sect2 id="mailmime-base64-body-parse"> | ||
10215 | <title>mailmime_base64_body_parse</title> | ||
10216 | |||
10217 | <programlisting role="C"> | ||
10218 | #include <libetpan/libetpan.h> | ||
10219 | |||
10220 | int mailmime_base64_body_parse(const char * message, size_t length, | ||
10221 | size_t * index, char ** result, | ||
10222 | size_t * result_len); | ||
10223 | </programlisting> | ||
10224 | |||
10225 | <para> | ||
10226 | This function will parse a body part encoded using base64. | ||
10227 | </para> | ||
10228 | |||
10229 | <itemizedlist> | ||
10230 | <listitem> | ||
10231 | <para> | ||
10232 | <command>message</command> is a string encoded using | ||
10233 | base64. | ||
10234 | </para> | ||
10235 | </listitem> | ||
10236 | <listitem> | ||
10237 | <para> | ||
10238 | <command>length</command> is the size of the given | ||
10239 | string. | ||
10240 | </para> | ||
10241 | </listitem> | ||
10242 | <listitem> | ||
10243 | <para> | ||
10244 | <command>index</command> is a pointer to the start of | ||
10245 | the address in the given string, <command>(* | ||
10246 | index)</command> is modified to point at the end of the | ||
10247 | parsed data. | ||
10248 | </para> | ||
10249 | </listitem> | ||
10250 | <listitem> | ||
10251 | <para> | ||
10252 | <command>result</command>. The result of the parse | ||
10253 | operation is stored in <command>(* result)</command> | ||
10254 | The result must be freed with | ||
10255 | <command>mmap_string_unref()</command>. | ||
10256 | </para> | ||
10257 | </listitem> | ||
10258 | </itemizedlist> | ||
10259 | |||
10260 | <example> | ||
10261 | <title>Parsing a base64 encoded part</title> | ||
10262 | |||
10263 | <programlisting role="C"> | ||
10264 | #include <libetpan/libetpan.h> | ||
10265 | #include <sys/stat.h> | ||
10266 | #include <sys/mman.h> | ||
10267 | |||
10268 | int main(int argc, char ** argv) | ||
10269 | { | ||
10270 | int fd; | ||
10271 | int r; | ||
10272 | |||
10273 | status = EXIT_FAILURE; | ||
10274 | |||
10275 | fd = open("message.rfc2822", O_RDONLY); | ||
10276 | if (fd >= 0) { | ||
10277 | void * mem; | ||
10278 | struct stat stat_info; | ||
10279 | |||
10280 | r = fstat(fd, &stat_info); | ||
10281 | if (r >= 0) { | ||
10282 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
10283 | if (mem != MAP_FAILED) { | ||
10284 | struct mailimf_fields * f; | ||
10285 | size_t current_index; | ||
10286 | char * result; | ||
10287 | size_t result_len; | ||
10288 | |||
10289 | current_index = 0; | ||
10290 | r = mailmime_base64_body_parse(mem, stat_info.st_size, | ||
10291 | &current_index, &result, &result_len); | ||
10292 | if (r == MAILIMF_NO_ERROR) { | ||
10293 | |||
10294 | /* do the things */ | ||
10295 | |||
10296 | mailmime_decoded_part_free(mem); | ||
10297 | status = EXIT_SUCCESS; | ||
10298 | } | ||
10299 | } | ||
10300 | munmap(mem, stat_info.st_size); | ||
10301 | } | ||
10302 | |||
10303 | close(fd); | ||
10304 | } | ||
10305 | |||
10306 | exit(status); | ||
10307 | } | ||
10308 | </programlisting> | ||
10309 | </example> | ||
10310 | </sect2> | ||
10311 | |||
10312 | <!-- mailmime_quoted_printable_body_parse --> | ||
10313 | <sect2 id="mailmime-quoted-printable-body-parse"> | ||
10314 | <title>mailmime_quoted_printable_body_parse</title> | ||
10315 | |||
10316 | <programlisting role="C"> | ||
10317 | #include <libetpan/libetpan.h> | ||
10318 | |||
10319 | int mailmime_quoted_printable_body_parse(const char * message, size_t length, | ||
10320 | size_t * index, char ** result, | ||
10321 | size_t * result_len, int in_header); | ||
10322 | </programlisting> | ||
10323 | |||
10324 | <para> | ||
10325 | This function will parse a body part encoded using quoted | ||
10326 | printable. | ||
10327 | </para> | ||
10328 | |||
10329 | <itemizedlist> | ||
10330 | <listitem> | ||
10331 | <para> | ||
10332 | <command>message</command> is a string encoded using | ||
10333 | quoted printable. | ||
10334 | </para> | ||
10335 | </listitem> | ||
10336 | <listitem> | ||
10337 | <para> | ||
10338 | <command>length</command> is the size of the given | ||
10339 | string. | ||
10340 | </para> | ||
10341 | </listitem> | ||
10342 | <listitem> | ||
10343 | <para> | ||
10344 | <command>index</command> is a pointer to the start of | ||
10345 | the address in the given string, <command>(* | ||
10346 | index)</command> is modified to point at the end of the | ||
10347 | parsed data. | ||
10348 | </para> | ||
10349 | </listitem> | ||
10350 | <listitem> | ||
10351 | <para> | ||
10352 | <command>result</command>. The result of the parse | ||
10353 | operation is stored in <command>(* result)</command> | ||
10354 | The result must be freed with | ||
10355 | <command>mmap_string_unref()</command>. | ||
10356 | </para> | ||
10357 | </listitem> | ||
10358 | </itemizedlist> | ||
10359 | |||
10360 | <example> | ||
10361 | <title>Parsing a quoted printable encoded part</title> | ||
10362 | |||
10363 | <programlisting role="C"> | ||
10364 | #include <libetpan/libetpan.h> | ||
10365 | #include <sys/stat.h> | ||
10366 | #include <sys/mman.h> | ||
10367 | |||
10368 | int main(int argc, char ** argv) | ||
10369 | { | ||
10370 | int fd; | ||
10371 | int r; | ||
10372 | |||
10373 | status = EXIT_FAILURE; | ||
10374 | |||
10375 | fd = open("message.rfc2822", O_RDONLY); | ||
10376 | if (fd >= 0) { | ||
10377 | void * mem; | ||
10378 | struct stat stat_info; | ||
10379 | |||
10380 | r = fstat(fd, &stat_info); | ||
10381 | if (r >= 0) { | ||
10382 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
10383 | if (mem != MAP_FAILED) { | ||
10384 | struct mailimf_fields * f; | ||
10385 | size_t current_index; | ||
10386 | char * result; | ||
10387 | size_t result_len; | ||
10388 | |||
10389 | current_index = 0; | ||
10390 | r = mailmime_quoted_printable_body_parse(mem, stat_info.st_size, | ||
10391 | &current_index, &result, &result_len); | ||
10392 | if (r == MAILIMF_NO_ERROR) { | ||
10393 | |||
10394 | /* do the things */ | ||
10395 | |||
10396 | mailmime_decoded_part_free(mem); | ||
10397 | status = EXIT_SUCCESS; | ||
10398 | } | ||
10399 | } | ||
10400 | munmap(mem, stat_info.st_size); | ||
10401 | } | ||
10402 | |||
10403 | close(fd); | ||
10404 | } | ||
10405 | |||
10406 | exit(status); | ||
10407 | } | ||
10408 | </programlisting> | ||
10409 | </example> | ||
10410 | </sect2> | ||
10411 | |||
10412 | <!-- mailmime_binary_body_parse --> | ||
10413 | <sect2 id="mailmime-binary-body-parse"> | ||
10414 | <title>mailmime_binary_body_parse</title> | ||
10415 | |||
10416 | <programlisting role="C"> | ||
10417 | #include <libetpan/libetpan.h> | ||
10418 | |||
10419 | int mailmime_binary_body_parse(const char * message, size_t length, | ||
10420 | size_t * index, char ** result, | ||
10421 | size_t * result_len); | ||
10422 | </programlisting> | ||
10423 | |||
10424 | <para> | ||
10425 | This function will parse a body part encoded using binary | ||
10426 | (no encoding). | ||
10427 | </para> | ||
10428 | |||
10429 | <itemizedlist> | ||
10430 | <listitem> | ||
10431 | <para> | ||
10432 | <command>message</command> is a string encoded using | ||
10433 | binary. | ||
10434 | </para> | ||
10435 | </listitem> | ||
10436 | <listitem> | ||
10437 | <para> | ||
10438 | <command>length</command> is the size of the given | ||
10439 | string. | ||
10440 | </para> | ||
10441 | </listitem> | ||
10442 | <listitem> | ||
10443 | <para> | ||
10444 | <command>index</command> is a pointer to the start of | ||
10445 | the address in the given string, <command>(* | ||
10446 | index)</command> is modified to point at the end of the | ||
10447 | parsed data. | ||
10448 | </para> | ||
10449 | </listitem> | ||
10450 | <listitem> | ||
10451 | <para> | ||
10452 | <command>result</command>. The result of the parse | ||
10453 | operation is stored in <command>(* result)</command> | ||
10454 | The result must be freed with | ||
10455 | <command>mmap_string_unref()</command>. | ||
10456 | </para> | ||
10457 | </listitem> | ||
10458 | </itemizedlist> | ||
10459 | |||
10460 | <example> | ||
10461 | <title>Parsing a binary encoded part</title> | ||
10462 | |||
10463 | <programlisting role="C"> | ||
10464 | #include <libetpan/libetpan.h> | ||
10465 | #include <sys/stat.h> | ||
10466 | #include <sys/mman.h> | ||
10467 | |||
10468 | int main(int argc, char ** argv) | ||
10469 | { | ||
10470 | int fd; | ||
10471 | int r; | ||
10472 | |||
10473 | status = EXIT_FAILURE; | ||
10474 | |||
10475 | fd = open("message.rfc2822", O_RDONLY); | ||
10476 | if (fd >= 0) { | ||
10477 | void * mem; | ||
10478 | struct stat stat_info; | ||
10479 | |||
10480 | r = fstat(fd, &stat_info); | ||
10481 | if (r >= 0) { | ||
10482 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
10483 | if (mem != MAP_FAILED) { | ||
10484 | struct mailimf_fields * f; | ||
10485 | size_t current_index; | ||
10486 | char * result; | ||
10487 | size_t result_len; | ||
10488 | |||
10489 | current_index = 0; | ||
10490 | r = mailmime_binary_body_parse(mem, stat_info.st_size, | ||
10491 | &current_index, &result, &result_len); | ||
10492 | if (r == MAILIMF_NO_ERROR) { | ||
10493 | |||
10494 | /* do the things */ | ||
10495 | |||
10496 | mailmime_decoded_part_free(mem); | ||
10497 | status = EXIT_SUCCESS; | ||
10498 | } | ||
10499 | } | ||
10500 | munmap(mem, stat_info.st_size); | ||
10501 | } | ||
10502 | |||
10503 | close(fd); | ||
10504 | } | ||
10505 | |||
10506 | exit(status); | ||
10507 | } | ||
10508 | </programlisting> | ||
10509 | </example> | ||
10510 | </sect2> | ||
10511 | |||
10512 | <!-- mailmime_part_parse --> | ||
10513 | <sect2 id="mailmime-part-parse"> | ||
10514 | <title>mailmime_part_parse</title> | ||
10515 | |||
10516 | <programlisting role="C"> | ||
10517 | #include <libetpan/libetpan.h> | ||
10518 | |||
10519 | enum { | ||
10520 | MAILMIME_MECHANISM_ERROR, | ||
10521 | MAILMIME_MECHANISM_7BIT, | ||
10522 | MAILMIME_MECHANISM_8BIT, | ||
10523 | MAILMIME_MECHANISM_BINARY, | ||
10524 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, | ||
10525 | MAILMIME_MECHANISM_BASE64, | ||
10526 | MAILMIME_MECHANISM_TOKEN | ||
10527 | }; | ||
10528 | |||
10529 | int mailmime_part_parse(const char * message, size_t length, | ||
10530 | size_t * index, | ||
10531 | int encoding, char ** result, size_t * result_len); | ||
10532 | </programlisting> | ||
10533 | |||
10534 | <para> | ||
10535 | This function will parse a body part encoded using a | ||
10536 | given MIME encoding mechanism. | ||
10537 | </para> | ||
10538 | |||
10539 | <itemizedlist> | ||
10540 | <listitem> | ||
10541 | <para> | ||
10542 | <command>message</command> is a string encoded using | ||
10543 | binary. | ||
10544 | </para> | ||
10545 | </listitem> | ||
10546 | <listitem> | ||
10547 | <para> | ||
10548 | <command>length</command> is the size of the given | ||
10549 | string. | ||
10550 | </para> | ||
10551 | </listitem> | ||
10552 | <listitem> | ||
10553 | <para> | ||
10554 | <command>index</command> is a pointer to the start of | ||
10555 | the address in the given string, <command>(* | ||
10556 | index)</command> is modified to point at the end of the | ||
10557 | parsed data. | ||
10558 | </para> | ||
10559 | </listitem> | ||
10560 | <listitem> | ||
10561 | <para> | ||
10562 | <command>encoding</command> is a MIME encoding | ||
10563 | mechanism. The value can be | ||
10564 | <command>MAILMIME_MECHANISM_7BIT</command>, | ||
10565 | <command>MAILMIME_MECHANISM_8BIT</command>, | ||
10566 | <command>MAILMIME_MECHANISM_BINARY</command>, | ||
10567 | <command>MAILMIME_MECHANISM_QUOTED_PRINTABLE</command>, | ||
10568 | <command>MAILMIME_MECHANISM_BASE64</command> or | ||
10569 | <command>MAILMIME_MECHANISM_TOKEN</command> | ||
10570 | (see <xref linkend="mailmime-mechanism">). | ||
10571 | </para> | ||
10572 | </listitem> | ||
10573 | <listitem> | ||
10574 | <para> | ||
10575 | <command>result</command>. The result of the parse | ||
10576 | operation is stored in <command>(* result)</command> | ||
10577 | The result must be freed with | ||
10578 | <command>mmap_string_unref()</command>. | ||
10579 | </para> | ||
10580 | </listitem> | ||
10581 | </itemizedlist> | ||
10582 | |||
10583 | <example> | ||
10584 | <title>Parsing a MIME encoded part</title> | ||
10585 | |||
10586 | <programlisting role="C"> | ||
10587 | #include <libetpan/libetpan.h> | ||
10588 | #include <sys/stat.h> | ||
10589 | #include <sys/mman.h> | ||
10590 | |||
10591 | int main(int argc, char ** argv) | ||
10592 | { | ||
10593 | int fd; | ||
10594 | int r; | ||
10595 | |||
10596 | status = EXIT_FAILURE; | ||
10597 | |||
10598 | fd = open("message.rfc2822", O_RDONLY); | ||
10599 | if (fd >= 0) { | ||
10600 | void * mem; | ||
10601 | struct stat stat_info; | ||
10602 | |||
10603 | r = fstat(fd, &stat_info); | ||
10604 | if (r >= 0) { | ||
10605 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
10606 | if (mem != MAP_FAILED) { | ||
10607 | struct mailimf_fields * f; | ||
10608 | size_t current_index; | ||
10609 | char * result; | ||
10610 | size_t result_len; | ||
10611 | |||
10612 | current_index = 0; | ||
10613 | r = mailmime_part_parse(mem, stat_info.st_size, &current_index, | ||
10614 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, &result, &result_len); | ||
10615 | if (r == MAILIMF_NO_ERROR) { | ||
10616 | |||
10617 | /* do the things */ | ||
10618 | |||
10619 | mailmime_decoded_part_free(mem); | ||
10620 | status = EXIT_SUCCESS; | ||
10621 | } | ||
10622 | } | ||
10623 | munmap(mem, stat_info.st_size); | ||
10624 | } | ||
10625 | |||
10626 | close(fd); | ||
10627 | } | ||
10628 | |||
10629 | exit(status); | ||
10630 | } | ||
10631 | </programlisting> | ||
10632 | </example> | ||
10633 | </sect2> | ||
10634 | |||
10635 | </sect1> | ||
10636 | |||
10637 | <sect1> | ||
10638 | <title>Rendering of MIME parts</title> | ||
10639 | |||
10640 | <!-- mailmime_fields_write --> | ||
10641 | <sect2 id="mailmime-fields-write"> | ||
10642 | <title>mailmime_fields_write, mailmime_content_write and | ||
10643 | mailmime_content_type_write</title> | ||
10644 | |||
10645 | <programlisting role="C"> | ||
10646 | #include <libetpan/libetpan.h> | ||
10647 | |||
10648 | int mailmime_fields_write(FILE * f, int * col, | ||
10649 | struct mailmime_fields * fields); | ||
10650 | |||
10651 | int mailmime_content_write(FILE * f, int * col, | ||
10652 | struct mailmime_content * content); | ||
10653 | |||
10654 | int mailmime_content_type_write(FILE * f, int * col, | ||
10655 | struct mailmime_content * content); | ||
10656 | </programlisting> | ||
10657 | |||
10658 | <para> | ||
10659 | <command>mailmime_fields_write</command> render the MIME | ||
10660 | header fields. | ||
10661 | </para> | ||
10662 | |||
10663 | <para> | ||
10664 | <command>mailmime_content_write</command> render the MIME | ||
10665 | content type header field. | ||
10666 | </para> | ||
10667 | |||
10668 | <para> | ||
10669 | <command>mailmime_content_write</command> render the | ||
10670 | content of the MIME content type header field. | ||
10671 | </para> | ||
10672 | |||
10673 | <itemizedlist> | ||
10674 | <listitem> | ||
10675 | <para> | ||
10676 | <command>col</command> current column is given for wrapping | ||
10677 | purpose in <command>(* col)</command>, | ||
10678 | the resulting columns will be returned.. | ||
10679 | </para> | ||
10680 | </listitem> | ||
10681 | <listitem> | ||
10682 | <para> | ||
10683 | <command>f</command> is the file descriptor. It can be | ||
10684 | stdout for example. | ||
10685 | </para> | ||
10686 | </listitem> | ||
10687 | <listitem> | ||
10688 | <para> | ||
10689 | <command>fields</command> is the header fields | ||
10690 | (see <xref linkend="mailmime-fields">). | ||
10691 | </para> | ||
10692 | </listitem> | ||
10693 | <listitem> | ||
10694 | <para> | ||
10695 | <command>content</command> is the header fields | ||
10696 | (see <xref linkend="mailmime-content">). | ||
10697 | </para> | ||
10698 | </listitem> | ||
10699 | </itemizedlist> | ||
10700 | |||
10701 | <example> | ||
10702 | <title>rendering MIME header fields</title> | ||
10703 | |||
10704 | <programlisting role="C"> | ||
10705 | #include <libetpan/libetpan.h> | ||
10706 | |||
10707 | int main(int argc, char ** argv) | ||
10708 | { | ||
10709 | struct mailmime_mime * mime_fields; | ||
10710 | int col; | ||
10711 | |||
10712 | /* look at the example in mailmime_fields to see how to | ||
10713 | build a mailmime_fields */ | ||
10714 | mime_fields = build_mime_fields(); | ||
10715 | |||
10716 | col = 0; | ||
10717 | mailmime_fields_write(stdout, &col, mime_fields); | ||
10718 | |||
10719 | mailmime_fields_free(mime_fields); | ||
10720 | } | ||
10721 | |||
10722 | int main(int argc, char ** argv) | ||
10723 | { | ||
10724 | struct mailmime_content * content; | ||
10725 | int col; | ||
10726 | |||
10727 | /* look at the example in mailmime_content to see how to | ||
10728 | build a mailmime_fields */ | ||
10729 | content = build_mime_content(); | ||
10730 | |||
10731 | col = 0; | ||
10732 | mailmime_content_write(stdout, &col, mime_fields); | ||
10733 | |||
10734 | mailmime_content_free(content); | ||
10735 | } | ||
10736 | |||
10737 | int main(int argc, char ** argv) | ||
10738 | { | ||
10739 | struct mailmime_content * content; | ||
10740 | int col; | ||
10741 | |||
10742 | /* look at the example in mailmime_content to see how to | ||
10743 | build a mailmime_fields */ | ||
10744 | content = build_mime_content(); | ||
10745 | |||
10746 | col = 0; | ||
10747 | mailmime_content_type_write(stdout, &col, mime_fields); | ||
10748 | |||
10749 | mailmime_content_free(content); | ||
10750 | } | ||
10751 | </programlisting> | ||
10752 | </example> | ||
10753 | </sect2> | ||
10754 | |||
10755 | <!-- mailmime_write --> | ||
10756 | <sect2 id="mailmime-write"> | ||
10757 | <title>mailmime_write</title> | ||
10758 | |||
10759 | <programlisting role="C"> | ||
10760 | #include <libetpan/libetpan.h> | ||
10761 | |||
10762 | int mailmime_write(FILE * f, int * col, | ||
10763 | struct mailmime * build_info); | ||
10764 | </programlisting> | ||
10765 | |||
10766 | <para> | ||
10767 | This function will render a MIME message. | ||
10768 | </para> | ||
10769 | |||
10770 | <itemizedlist> | ||
10771 | <listitem> | ||
10772 | <para> | ||
10773 | <command>col</command> current column is given for wrapping | ||
10774 | purpose in <command>(* col)</command>, | ||
10775 | the resulting columns will be returned.. | ||
10776 | </para> | ||
10777 | </listitem> | ||
10778 | <listitem> | ||
10779 | <para> | ||
10780 | <command>f</command> is the file descriptor. It can be | ||
10781 | stdout for example. | ||
10782 | </para> | ||
10783 | </listitem> | ||
10784 | <listitem> | ||
10785 | <para> | ||
10786 | <command>build_info</command> is the MIME message to | ||
10787 | render. | ||
10788 | </para> | ||
10789 | </listitem> | ||
10790 | </itemizedlist> | ||
10791 | |||
10792 | </sect2> | ||
10793 | |||
10794 | <!-- mailmime_quoted_printable_write --> | ||
10795 | <sect2 id="mailmime-quoted-printable-write"> | ||
10796 | <title>mailmime_quoted_printable_write | ||
10797 | and mailmime_base64_write</title> | ||
10798 | |||
10799 | <programlisting role="C"> | ||
10800 | #include <libetpan/libetpan.h> | ||
10801 | |||
10802 | int mailmime_quoted_printable_write(FILE * f, int * col, int istext, | ||
10803 | const char * text, size_t size); | ||
10804 | |||
10805 | int mailmime_base64_write(FILE * f, int * col, | ||
10806 | const char * text, size_t size); | ||
10807 | </programlisting> | ||
10808 | |||
10809 | <para> | ||
10810 | <command>mailmime_quoted_printable_write()</command> will | ||
10811 | render a string to quoted printable. | ||
10812 | </para> | ||
10813 | |||
10814 | <para> | ||
10815 | <command>mailmime_base64_write()</command> will | ||
10816 | render a string to base64. | ||
10817 | </para> | ||
10818 | |||
10819 | <itemizedlist> | ||
10820 | <listitem> | ||
10821 | <para> | ||
10822 | <command>col</command> current column is given for wrapping | ||
10823 | purpose in <command>(* col)</command>, | ||
10824 | the resulting columns will be returned.. | ||
10825 | </para> | ||
10826 | </listitem> | ||
10827 | <listitem> | ||
10828 | <para> | ||
10829 | <command>f</command> is the file descriptor. It can be | ||
10830 | stdout for example. | ||
10831 | </para> | ||
10832 | </listitem> | ||
10833 | <listitem> | ||
10834 | <para> | ||
10835 | <command>text</command> is the string to render. | ||
10836 | </para> | ||
10837 | </listitem> | ||
10838 | <listitem> | ||
10839 | <para> | ||
10840 | <command>size</command> is the size of the string to | ||
10841 | render. | ||
10842 | </para> | ||
10843 | </listitem> | ||
10844 | </itemizedlist> | ||
10845 | |||
10846 | <example> | ||
10847 | <title>render base64 or quoted printable</title> | ||
10848 | |||
10849 | <programlisting role="C"> | ||
10850 | #include <libetpan/libetpan.h> | ||
10851 | |||
10852 | int main(int argc, char ** argv) | ||
10853 | { | ||
10854 | int col; | ||
10855 | |||
10856 | col = 0; | ||
10857 | mailmime_quoted_printable_write(stdout, &col, | ||
10858 | "this is a test", 14); | ||
10859 | } | ||
10860 | |||
10861 | #include <libetpan/libetpan.h> | ||
10862 | |||
10863 | int main(int argc, char ** argv) | ||
10864 | { | ||
10865 | int col; | ||
10866 | |||
10867 | col = 0; | ||
10868 | mailmime_base64_write(stdout, &col, "this is a test", 14); | ||
10869 | } | ||
10870 | </programlisting> | ||
10871 | </example> | ||
10872 | </sect2> | ||
10873 | |||
10874 | <!-- mailmime_data_write --> | ||
10875 | <sect2 id="mailmime-data-write"> | ||
10876 | <title>mailmime_data_write</title> | ||
10877 | |||
10878 | <programlisting role="C"> | ||
10879 | #include <libetpan/libetpan.h> | ||
10880 | |||
10881 | int mailmime_data_write(FILE * f, int * col, | ||
10882 | struct mailmime_data * data, | ||
10883 | int istext); | ||
10884 | </programlisting> | ||
10885 | |||
10886 | <para> | ||
10887 | <command>mailmime_data_write</command> will | ||
10888 | render MIME data. | ||
10889 | </para> | ||
10890 | |||
10891 | <itemizedlist> | ||
10892 | <listitem> | ||
10893 | <para> | ||
10894 | <command>col</command> current column is given for wrapping | ||
10895 | purpose in <command>(* col)</command>, | ||
10896 | the resulting columns will be returned.. | ||
10897 | </para> | ||
10898 | </listitem> | ||
10899 | <listitem> | ||
10900 | <para> | ||
10901 | <command>f</command> is the file descriptor. It can be | ||
10902 | stdout for example. | ||
10903 | </para> | ||
10904 | </listitem> | ||
10905 | <listitem> | ||
10906 | <para> | ||
10907 | <command>data</command> is the data to render | ||
10908 | (see <xref linkend="mailmime-data">). | ||
10909 | </para> | ||
10910 | </listitem> | ||
10911 | </itemizedlist> | ||
10912 | </sect2> | ||
10913 | </sect1> | ||
10914 | |||
10915 | <!-- Creation functions --> | ||
10916 | <sect1> | ||
10917 | <title>Creation functions</title> | ||
10918 | |||
10919 | <!-- mailmime_disposition_new_filename --> | ||
10920 | <sect2 id="mailmime-disposition-new-filename"> | ||
10921 | <title>mailmime_disposition_new_filename and | ||
10922 | mailmime_disposition_new_with_data</title> | ||
10923 | |||
10924 | <programlisting role="C"> | ||
10925 | #include <libetpan/libetpan.h> | ||
10926 | |||
10927 | enum { | ||
10928 | MAILMIME_DISPOSITION_TYPE_ERROR, | ||
10929 | MAILMIME_DISPOSITION_TYPE_INLINE, | ||
10930 | MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
10931 | MAILMIME_DISPOSITION_TYPE_EXTENSION | ||
10932 | }; | ||
10933 | |||
10934 | struct mailmime_disposition * | ||
10935 | mailmime_disposition_new_filename(int type, char * filename); | ||
10936 | |||
10937 | struct mailmime_disposition * | ||
10938 | mailmime_disposition_new_with_data(int type, | ||
10939 | char * filename, char * creation_date, char * modification_date, | ||
10940 | char * read_date, size_t size); | ||
10941 | </programlisting> | ||
10942 | |||
10943 | <para> | ||
10944 | These functions will create a MIME content disposition | ||
10945 | information. | ||
10946 | </para> | ||
10947 | |||
10948 | <itemizedlist> | ||
10949 | <listitem> | ||
10950 | <para> | ||
10951 | <command>type</command> a standard MIME disposition : | ||
10952 | <command>MAILMIME_DISPOSITION_TYPE_INLINE</command> or | ||
10953 | <command>MAILMIME_DISPOSITION_TYPE_ATTACHMENT</command>. | ||
10954 | </para> | ||
10955 | <para> | ||
10956 | <command>filename</command> is the filename. | ||
10957 | </para> | ||
10958 | <para> | ||
10959 | <command>creation_date</command> is the creation date. | ||
10960 | </para> | ||
10961 | <para> | ||
10962 | <command>modification_date</command> is the modification | ||
10963 | date. | ||
10964 | </para> | ||
10965 | <para> | ||
10966 | <command>read_date</command> is the last read date. | ||
10967 | </para> | ||
10968 | <para> | ||
10969 | <command>size</command> is the size of the file. | ||
10970 | </para> | ||
10971 | </listitem> | ||
10972 | <listitem> | ||
10973 | <para> | ||
10974 | This will return a MIME content disposition | ||
10975 | (see <xref linkend="mailmime-disposition">). | ||
10976 | </para> | ||
10977 | </listitem> | ||
10978 | </itemizedlist> | ||
10979 | |||
10980 | <example> | ||
10981 | <title>creating a MIME content disposition</title> | ||
10982 | |||
10983 | <programlisting role="C"> | ||
10984 | #include <libetpan/libetpan.h> | ||
10985 | |||
10986 | int main(int argc, char ** argv) | ||
10987 | { | ||
10988 | struct mailmime_disposition * disposition; | ||
10989 | |||
10990 | disposition = | ||
10991 | mailmime_disposition_new_filename(MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
10992 | strdup("foo-bar.txt")); | ||
10993 | |||
10994 | /* do the things */ | ||
10995 | |||
10996 | mailmime_disposition_free(disposition); | ||
10997 | } | ||
10998 | </programlisting> | ||
10999 | </example> | ||
11000 | </sect2> | ||
11001 | |||
11002 | <!-- mailmime_fields_new_empty --> | ||
11003 | <sect2 id="mailmime-fields-new-empty"> | ||
11004 | <title>mailmime_fields_new_empty and mailmime_fields_add</title> | ||
11005 | |||
11006 | <programlisting role="C"> | ||
11007 | #include <libetpan/libetpan.h> | ||
11008 | |||
11009 | struct mailmime_fields * mailmime_fields_new_empty(void); | ||
11010 | |||
11011 | int mailmime_fields_add(struct mailmime_fields * fields, | ||
11012 | struct mailmime_field * field); | ||
11013 | </programlisting> | ||
11014 | |||
11015 | <para> | ||
11016 | <command>mailmime_fields_new_empty()</command> will | ||
11017 | create a new empty MIME header fields list. | ||
11018 | </para> | ||
11019 | |||
11020 | <para> | ||
11021 | <command>mailmime_fields_add()</command> will add | ||
11022 | MIME header fields to the MIME header fields list. | ||
11023 | </para> | ||
11024 | |||
11025 | <itemizedlist> | ||
11026 | <listitem> | ||
11027 | <para> | ||
11028 | <command>fields</command>. The MIME header field will | ||
11029 | be added to this MIME header fields list | ||
11030 | (see <xref linkend="mailmime-fields">). | ||
11031 | </para> | ||
11032 | </listitem> | ||
11033 | <listitem> | ||
11034 | <para> | ||
11035 | <command>field</command> is the MIME header field to add | ||
11036 | (see <xref linkend="mailmime-field">). | ||
11037 | </para> | ||
11038 | </listitem> | ||
11039 | </itemizedlist> | ||
11040 | |||
11041 | <example> | ||
11042 | <title>creating a MIME header fields list</title> | ||
11043 | |||
11044 | <programlisting role="C"> | ||
11045 | #include <libetpan/libetpan.h> | ||
11046 | |||
11047 | int main(int argc, char ** argv) | ||
11048 | { | ||
11049 | struct mailmime_fields * fields; | ||
11050 | struct mailmime_field * field; | ||
11051 | |||
11052 | fields = mailmime_fields_new_empty(); | ||
11053 | field = build_mime_field(); | ||
11054 | |||
11055 | /* do the things */ | ||
11056 | |||
11057 | mailmime_fields_add(fields, field); | ||
11058 | |||
11059 | mailmime_fields_free(fields); | ||
11060 | } | ||
11061 | </programlisting> | ||
11062 | </example> | ||
11063 | </sect2> | ||
11064 | |||
11065 | <!-- mailmime_fields_new_with_data --> | ||
11066 | <sect2 id="mailmime-fields-new-with-data"> | ||
11067 | <title>mailmime_fields_new_with_data and | ||
11068 | mailmime_fields_new_with_version</title> | ||
11069 | |||
11070 | <programlisting role="C"> | ||
11071 | #include <libetpan/libetpan.h> | ||
11072 | |||
11073 | struct mailmime_fields * | ||
11074 | mailmime_fields_new_with_data(struct mailmime_mechanism * encoding, | ||
11075 | char * id, | ||
11076 | char * description, | ||
11077 | struct mailmime_disposition * disposition, | ||
11078 | struct mailmime_language * language); | ||
11079 | |||
11080 | struct mailmime_fields * | ||
11081 | mailmime_fields_new_with_version(struct mailmime_mechanism * encoding, | ||
11082 | char * id, | ||
11083 | char * description, | ||
11084 | struct mailmime_disposition * disposition, | ||
11085 | struct mailmime_language * language); | ||
11086 | </programlisting> | ||
11087 | |||
11088 | <para> | ||
11089 | <command>mailmime_fields_new_with_data()</command> will | ||
11090 | create a MIME header fields list with all the given fields | ||
11091 | (<command>NULL</command> can be used for the value if the | ||
11092 | field must not be present). | ||
11093 | <command>MIME-Version</command> header field will | ||
11094 | <emphasis>not</emphasis> be added. | ||
11095 | </para> | ||
11096 | |||
11097 | <para> | ||
11098 | <command>mailmime_fields_new_with_version()</command> will | ||
11099 | create a MIME header fields list with all the given fields | ||
11100 | (<command>NULL</command> can be used for the value if the | ||
11101 | field must not be present). | ||
11102 | <command>MIME-Version</command> header field will be added. | ||
11103 | </para> | ||
11104 | |||
11105 | <example> | ||
11106 | <title>creating new fields</title> | ||
11107 | |||
11108 | <programlisting role="C"> | ||
11109 | #include <libetpan/libetpan.h> | ||
11110 | |||
11111 | int main(int argc, char ** argv) | ||
11112 | { | ||
11113 | struct mailmime_disposition * disposition; | ||
11114 | struct mailmime_fields * mime_fields; | ||
11115 | struct mailmime_mechanism * encoding; | ||
11116 | |||
11117 | encoding = mailmime_mechanism_new(MAILMIME_MECHANISM_BASE64, NULL); | ||
11118 | |||
11119 | disposition = | ||
11120 | mailmime_disposition_new_filename(MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
11121 | strdup("foo-bar.txt")); | ||
11122 | |||
11123 | mime_fields = mailmime_fields_new_with_version(encoding, NULL, | ||
11124 | NULL, disposition, NULL); | ||
11125 | |||
11126 | /* do the things */ | ||
11127 | |||
11128 | mailmime_fields_free(mime_fields); | ||
11129 | } | ||
11130 | </programlisting> | ||
11131 | </example> | ||
11132 | </sect2> | ||
11133 | |||
11134 | <!-- mailmime_get_content_message --> | ||
11135 | <sect2 id="mailmime-get-content-message"> | ||
11136 | <title>mailmime_get_content_message</title> | ||
11137 | |||
11138 | <programlisting role="C"> | ||
11139 | #include <libetpan/libetpan.h> | ||
11140 | |||
11141 | struct mailmime_content * mailmime_get_content_message(void); | ||
11142 | |||
11143 | struct mailmime_content * mailmime_get_content_text(void); | ||
11144 | |||
11145 | struct mailmime_content * mailmime_content_new_with_str(const char * str); | ||
11146 | </programlisting> | ||
11147 | |||
11148 | <para> | ||
11149 | <command>mailmime_get_content_message()</command> will | ||
11150 | create a MIME content type | ||
11151 | <command>message/rfc822</command>. | ||
11152 | </para> | ||
11153 | |||
11154 | <para> | ||
11155 | <command>mailmime_get_content_text()</command> will | ||
11156 | create a MIME content type | ||
11157 | <command>plain/text</command>. | ||
11158 | </para> | ||
11159 | |||
11160 | <para> | ||
11161 | <command>mailmime_get_content_new_with_str()</command> will | ||
11162 | create a MIME content type given by the string | ||
11163 | <command>plain/text</command>. | ||
11164 | </para> | ||
11165 | |||
11166 | <para> | ||
11167 | <command>str</command>. This string will | ||
11168 | <command>NOT</command> be referenced by any structure. | ||
11169 | This string will only be parsed to create the structure. | ||
11170 | </para> | ||
11171 | |||
11172 | <example> | ||
11173 | <title>Creating a MIME content type</title> | ||
11174 | |||
11175 | <programlisting role="C"> | ||
11176 | #include <libetpan/libetpan.h> | ||
11177 | |||
11178 | int main(int argc, char ** argv) | ||
11179 | { | ||
11180 | struct mailmime_content * content; | ||
11181 | |||
11182 | content = mailmime_get_content_message(); | ||
11183 | |||
11184 | /* do the things */ | ||
11185 | |||
11186 | mailmime_content_free(content); | ||
11187 | } | ||
11188 | |||
11189 | int main(int argc, char ** argv) | ||
11190 | { | ||
11191 | struct mailmime_content * content; | ||
11192 | |||
11193 | content = mailmime_get_content_text(); | ||
11194 | |||
11195 | /* do the things */ | ||
11196 | |||
11197 | mailmime_content_free(content); | ||
11198 | } | ||
11199 | |||
11200 | int main(int argc, char ** argv) | ||
11201 | { | ||
11202 | struct mailmime_content * content; | ||
11203 | |||
11204 | content = mailmime_get_content_new_with_str("multipart/mixed"); | ||
11205 | |||
11206 | /* do the things */ | ||
11207 | |||
11208 | mailmime_content_free(content); | ||
11209 | } | ||
11210 | </programlisting> | ||
11211 | </example> | ||
11212 | </sect2> | ||
11213 | |||
11214 | <!-- mailmime_data_new_data --> | ||
11215 | <sect2 id="mailmime-data-new-data"> | ||
11216 | <title>mailmime_data_new_data and mailmime_data_new_file</title> | ||
11217 | |||
11218 | <programlisting role="C"> | ||
11219 | #include <libetpan/libetpan.h> | ||
11220 | |||
11221 | enum { | ||
11222 | MAILMIME_MECHANISM_ERROR, | ||
11223 | MAILMIME_MECHANISM_7BIT, | ||
11224 | MAILMIME_MECHANISM_8BIT, | ||
11225 | MAILMIME_MECHANISM_BINARY, | ||
11226 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, | ||
11227 | MAILMIME_MECHANISM_BASE64, | ||
11228 | MAILMIME_MECHANISM_TOKEN | ||
11229 | }; | ||
11230 | |||
11231 | struct mailmime_data * | ||
11232 | mailmime_data_new_data(int encoding, int encoded, | ||
11233 | const char * data, size_t length); | ||
11234 | |||
11235 | struct mailmime_data * | ||
11236 | mailmime_data_new_file(int encoding, int encoded, | ||
11237 | char * filename); | ||
11238 | </programlisting> | ||
11239 | |||
11240 | <para> | ||
11241 | <command>mailmime_data_new_data()</command> will create a | ||
11242 | new MIME content, using a string in memory. | ||
11243 | </para> | ||
11244 | |||
11245 | <para> | ||
11246 | <command>mailmime_data_new_file()</command> will create a | ||
11247 | new MIME content, using a file. | ||
11248 | </para> | ||
11249 | |||
11250 | <itemizedlist> | ||
11251 | <listitem> | ||
11252 | <para> | ||
11253 | <command>encoding</command> is the MIME encoding | ||
11254 | mechanism used to encode this part. The value can be | ||
11255 | <command>MAILMIME_MECHANISM_7BIT</command>, | ||
11256 | <command>MAILMIME_MECHANISM_8BIT</command>, | ||
11257 | <command>MAILMIME_MECHANISM_BINARY</command>, | ||
11258 | <command>MAILMIME_MECHANISM_QUOTED_PRINTABLE</command> or | ||
11259 | <command>MAILMIME_MECHANISM_BASE64</command> | ||
11260 | (see <xref linkend="mailmime-mechanism">). | ||
11261 | </para> | ||
11262 | </listitem> | ||
11263 | <listitem> | ||
11264 | <para> | ||
11265 | <command>encoded</command> is set to 1 if the part is | ||
11266 | already encoded with the mechanism given in | ||
11267 | <command>encoding</command>. | ||
11268 | </para> | ||
11269 | </listitem> | ||
11270 | <listitem> | ||
11271 | <para> | ||
11272 | <command>data</command> is a pointer to the | ||
11273 | content of the part. | ||
11274 | </para> | ||
11275 | </listitem> | ||
11276 | <listitem> | ||
11277 | <para> | ||
11278 | <command>length</command> is the length of the data. | ||
11279 | </para> | ||
11280 | </listitem> | ||
11281 | <listitem> | ||
11282 | <para> | ||
11283 | <command>filename</command> is the name of the file. | ||
11284 | </para> | ||
11285 | </listitem> | ||
11286 | </itemizedlist> | ||
11287 | |||
11288 | <example> | ||
11289 | <title>creating MIME content</title> | ||
11290 | |||
11291 | <programlisting role="C"> | ||
11292 | #include <libetpan/libetpan.h> | ||
11293 | |||
11294 | #define DATA_STR "my data" | ||
11295 | |||
11296 | int main(int argc, char ** argv) | ||
11297 | { | ||
11298 | struct mailmime_data * data; | ||
11299 | |||
11300 | data = mailmime_data_new_data(MAILMIME_MECHANISM_BASE64, 0, | ||
11301 | DATA_STR, sizeof(DATA_STR) - 1); | ||
11302 | |||
11303 | /* do the things */ | ||
11304 | |||
11305 | mailmime_data_free(data); | ||
11306 | } | ||
11307 | |||
11308 | int main(int argc, char ** argv) | ||
11309 | { | ||
11310 | struct mailmime_data * data; | ||
11311 | |||
11312 | data = mailmime_data_new_file(MAILMIME_MECHANISM_BASE64, 0, | ||
11313 | strdup("foo-bar.txt")); | ||
11314 | |||
11315 | /* do the things */ | ||
11316 | |||
11317 | mailmime_data_free(data); | ||
11318 | } | ||
11319 | </programlisting> | ||
11320 | </example> | ||
11321 | </sect2> | ||
11322 | |||
11323 | <!-- mailmime_new_message_data --> | ||
11324 | <sect2 id="mailmime-new-message-data"> | ||
11325 | <title>mailmime_new_message_data, mailmime_new_empty and | ||
11326 | mailmime_new_with_content</title> | ||
11327 | |||
11328 | <programlisting role="C"> | ||
11329 | #include <libetpan/libetpan.h> | ||
11330 | |||
11331 | struct mailmime * | ||
11332 | mailmime_new_message_data(struct mailmime * msg_mime); | ||
11333 | |||
11334 | struct mailmime * | ||
11335 | mailmime_new_empty(struct mailmime_content * content, | ||
11336 | struct mailmime_fields * mime_fields); | ||
11337 | |||
11338 | int | ||
11339 | mailmime_new_with_content(const char * content_type, | ||
11340 | struct mailmime_fields * mime_fields, | ||
11341 | struct mailmime ** result); | ||
11342 | |||
11343 | struct mailmime * mailmime_multiple_new(const char * type); | ||
11344 | </programlisting> | ||
11345 | |||
11346 | <para> | ||
11347 | <command>mailmime_new_message_data()</command> will create a | ||
11348 | new MIME message with the given subpart. | ||
11349 | </para> | ||
11350 | |||
11351 | <para> | ||
11352 | <command>mailmime_new_empty()</command> will create a | ||
11353 | new MIME part with the given content type and MIME fields | ||
11354 | but with no content. | ||
11355 | </para> | ||
11356 | |||
11357 | <para> | ||
11358 | <command>mailmime_new_with_content()</command> will create a | ||
11359 | new MIME part with a content type given by a string and a | ||
11360 | given MIME fields list. | ||
11361 | </para> | ||
11362 | |||
11363 | <para> | ||
11364 | <command>mailmime_multiple_new()</command> will create a | ||
11365 | new MIME multipart with a content type given by a string. | ||
11366 | </para> | ||
11367 | |||
11368 | <itemizedlist> | ||
11369 | <listitem> | ||
11370 | <para> | ||
11371 | <command>msg_mime</command> is the sub part to add to the | ||
11372 | MIME message when creating it | ||
11373 | (see <xref linkend="mailmime">). | ||
11374 | </para> | ||
11375 | </listitem> | ||
11376 | <listitem> | ||
11377 | <para> | ||
11378 | <command>content</command> is the content type of the part | ||
11379 | to create | ||
11380 | (see <xref linkend="mailmime-content">). | ||
11381 | </para> | ||
11382 | </listitem> | ||
11383 | <listitem> | ||
11384 | <para> | ||
11385 | <command>content_type</command> is the content type of | ||
11386 | the part to create given by a string. | ||
11387 | </para> | ||
11388 | </listitem> | ||
11389 | <listitem> | ||
11390 | <para> | ||
11391 | <command>mime_fields</command> is the list of MIME | ||
11392 | header fields | ||
11393 | (see <xref linkend="mailmime-fields">). | ||
11394 | </para> | ||
11395 | </listitem> | ||
11396 | </itemizedlist> | ||
11397 | |||
11398 | <example> | ||
11399 | <title>creating a MIME part</title> | ||
11400 | |||
11401 | <programlisting role="C"> | ||
11402 | #include <libetpan/libetpan.h> | ||
11403 | |||
11404 | #define DATA_STR "my data" | ||
11405 | |||
11406 | int main(int argc, char ** argv) | ||
11407 | { | ||
11408 | struct mailmime * mime; | ||
11409 | struct mailmime * single_part; | ||
11410 | |||
11411 | mime_fields = | ||
11412 | mailmime_fields_new_encoding(MAILMIME_MECHANISM_QUOTED_PRINTABLE); | ||
11413 | mailmime_new_with_content("plain/text", mime_fields, &single_part); | ||
11414 | |||
11415 | mailmime_set_body_text(single_part, DATA_STR, sizeof(DATA_STR) - 1); | ||
11416 | |||
11417 | mime = mailmime_new_message_data(single_part); | ||
11418 | |||
11419 | /* do the things */ | ||
11420 | |||
11421 | mailmime_free(mime); | ||
11422 | } | ||
11423 | |||
11424 | int main(int argc, char ** argv) | ||
11425 | { | ||
11426 | struct mailmime * mime; | ||
11427 | struct mailmime * single_part; | ||
11428 | struct mailmime_content * content; | ||
11429 | |||
11430 | mime_fields = | ||
11431 | mailmime_fields_new_encoding(MAILMIME_MECHANISM_QUOTED_PRINTABLE); | ||
11432 | content = mailmime_get_content_text(); | ||
11433 | single_part = mailmime_new_empty(content, mime_fields); | ||
11434 | |||
11435 | mailmime_set_body_text(single_part, DATA_STR, sizeof(DATA_STR) - 1); | ||
11436 | |||
11437 | mime = mailmime_new_message_data(single_part); | ||
11438 | |||
11439 | /* do the things */ | ||
11440 | |||
11441 | mailmime_free(mime); | ||
11442 | } | ||
11443 | |||
11444 | int main(int argc, char ** argv) | ||
11445 | { | ||
11446 | struct mailmime * mime; | ||
11447 | |||
11448 | mime = mailmime_multiple_new("multipart/mixed"); | ||
11449 | |||
11450 | /* do the things */ | ||
11451 | |||
11452 | mailmime_free(mime); | ||
11453 | } | ||
11454 | </programlisting> | ||
11455 | </example> | ||
11456 | </sect2> | ||
11457 | |||
11458 | <!-- mailmime_set_preamble_file --> | ||
11459 | <sect2 id="mailmime-set-preamble-file"> | ||
11460 | <title>mailmime_set_preamble_file, mailmime_set_epilogue_file, | ||
11461 | mailmime_set_preamble_text and mailmime_set_epilogue_text</title> | ||
11462 | |||
11463 | <programlisting role="C"> | ||
11464 | #include <libetpan/libetpan.h> | ||
11465 | |||
11466 | int mailmime_set_preamble_file(struct mailmime * build_info, | ||
11467 | char * filename); | ||
11468 | |||
11469 | int mailmime_set_epilogue_file(struct mailmime * build_info, | ||
11470 | char * filename); | ||
11471 | |||
11472 | int mailmime_set_preamble_text(struct mailmime * build_info, | ||
11473 | char * data_str, size_t length); | ||
11474 | |||
11475 | int mailmime_set_epilogue_text(struct mailmime * build_info, | ||
11476 | char * data_str, size_t length); | ||
11477 | </programlisting> | ||
11478 | |||
11479 | <para> | ||
11480 | <command>mailmime_set_preamble_file()</command> will define | ||
11481 | the preamble of a multipart. | ||
11482 | </para> | ||
11483 | |||
11484 | <para> | ||
11485 | <command>mailmime_set_preamble_text()</command> will define | ||
11486 | the preamble of a multipart. | ||
11487 | </para> | ||
11488 | |||
11489 | <para> | ||
11490 | <command>mailmime_set_epilogue_file()</command> will define | ||
11491 | the epilogue of a multipart. | ||
11492 | </para> | ||
11493 | |||
11494 | <para> | ||
11495 | <command>mailmime_set_preamble_text()</command> will define | ||
11496 | the preamble of a multipart. | ||
11497 | </para> | ||
11498 | |||
11499 | <itemizedlist> | ||
11500 | <listitem> | ||
11501 | <para> | ||
11502 | <command>build_info</command> is the MIME part to modify | ||
11503 | (see <xref linkend="mailmime">). | ||
11504 | </para> | ||
11505 | </listitem> | ||
11506 | <listitem> | ||
11507 | <para> | ||
11508 | <command>data_str</command> is the string to define | ||
11509 | as epilogue or prologue. | ||
11510 | </para> | ||
11511 | </listitem> | ||
11512 | <listitem> | ||
11513 | <para> | ||
11514 | <command>length</command> is the length of the string to | ||
11515 | define as epilogue or prologue. | ||
11516 | </para> | ||
11517 | </listitem> | ||
11518 | <listitem> | ||
11519 | <para> | ||
11520 | <command>filename</command> is the name of the file | ||
11521 | which content will be defined as epilogue or prologue. | ||
11522 | </para> | ||
11523 | </listitem> | ||
11524 | </itemizedlist> | ||
11525 | |||
11526 | <example> | ||
11527 | <title>setting preamble and epilogue</title> | ||
11528 | |||
11529 | <programlisting role="C"> | ||
11530 | #include <libetpan/libetpan.h> | ||
11531 | |||
11532 | #define DATA_STR "test foo bar" | ||
11533 | |||
11534 | int main(int argc, char ** argv) | ||
11535 | { | ||
11536 | struct mailmime * mime; | ||
11537 | |||
11538 | mime = mailmime_multiple_new("multipart/mixed"); | ||
11539 | |||
11540 | mailmime_set_preamble_file(mime, strdup("foo-bar.txt")); | ||
11541 | |||
11542 | mailmime_set_epilogue_data(mime, DATA_STR, sizeof(DATA_STR) - 1); | ||
11543 | |||
11544 | /* do the things */ | ||
11545 | |||
11546 | mailmime_free(mime); | ||
11547 | } | ||
11548 | </programlisting> | ||
11549 | </example> | ||
11550 | </sect2> | ||
11551 | |||
11552 | <!-- mailmime_set_body_file --> | ||
11553 | <sect2 id="mailmime-set-body-file"> | ||
11554 | <title>mailmime_set_body_file and mailmime_set_body_text</title> | ||
11555 | |||
11556 | <programlisting role="C"> | ||
11557 | #include <libetpan/libetpan.h> | ||
11558 | |||
11559 | int mailmime_set_body_file(struct mailmime * build_info, | ||
11560 | char * filename); | ||
11561 | |||
11562 | int mailmime_set_body_text(struct mailmime * build_info, | ||
11563 | char * data_str, size_t length); | ||
11564 | </programlisting> | ||
11565 | |||
11566 | <para> | ||
11567 | <command>mailmime_set_body_file()</command> will define | ||
11568 | the body of a single part. | ||
11569 | </para> | ||
11570 | |||
11571 | <para> | ||
11572 | <command>mailmime_set_body_text()</command> will define | ||
11573 | the body of a single part. | ||
11574 | </para> | ||
11575 | |||
11576 | <itemizedlist> | ||
11577 | <listitem> | ||
11578 | <para> | ||
11579 | <command>build_info</command> is the MIME part to modify | ||
11580 | (see <xref linkend="mailmime">). | ||
11581 | </para> | ||
11582 | </listitem> | ||
11583 | <listitem> | ||
11584 | <para> | ||
11585 | <command>data_str</command> is the string to define | ||
11586 | as the body of the part. | ||
11587 | </para> | ||
11588 | </listitem> | ||
11589 | <listitem> | ||
11590 | <para> | ||
11591 | <command>length</command> is the length of the string to | ||
11592 | define as the body of the part. | ||
11593 | </para> | ||
11594 | </listitem> | ||
11595 | <listitem> | ||
11596 | <para> | ||
11597 | <command>filename</command> is the name of the file | ||
11598 | which content will be defined as the body of the part. | ||
11599 | </para> | ||
11600 | </listitem> | ||
11601 | </itemizedlist> | ||
11602 | |||
11603 | <example> | ||
11604 | <title>creating a MIME part</title> | ||
11605 | |||
11606 | <programlisting role="C"> | ||
11607 | #include <libetpan/libetpan.h> | ||
11608 | |||
11609 | #define DATA_STR "my data" | ||
11610 | |||
11611 | int main(int argc, char ** argv) | ||
11612 | { | ||
11613 | struct mailmime * mime; | ||
11614 | |||
11615 | mime_fields = | ||
11616 | mailmime_fields_new_encoding(MAILMIME_MECHANISM_QUOTED_PRINTABLE); | ||
11617 | mailmime_new_with_content("plain/text", mime_fields, &mime); | ||
11618 | |||
11619 | mailmime_set_body_text(mime, DATA_STR, sizeof(DATA_STR) - 1); | ||
11620 | |||
11621 | |||
11622 | |||
11623 | /* do the things */ | ||
11624 | |||
11625 | mailmime_free(mime); | ||
11626 | } | ||
11627 | </programlisting> | ||
11628 | </example> | ||
11629 | |||
11630 | </sect2> | ||
11631 | |||
11632 | <!-- mailmime_add_part --> | ||
11633 | <sect2 id="mailmime-add-part"> | ||
11634 | <title>mailmime_add_part, mailmime_remove_part, | ||
11635 | mailmime_smart_add_part and mailmime_smart_remove_part</title> | ||
11636 | |||
11637 | <programlisting role="C"> | ||
11638 | #include <libetpan/libetpan.h> | ||
11639 | |||
11640 | int mailmime_add_part(struct mailmime * build_info, | ||
11641 | struct mailmime * part); | ||
11642 | |||
11643 | void mailmime_remove_part(struct mailmime * mime); | ||
11644 | |||
11645 | int mailmime_smart_add_part(struct mailmime * mime, | ||
11646 | struct mailmime * mime_sub); | ||
11647 | |||
11648 | int mailmime_smart_remove_part(struct mailmime * mime); | ||
11649 | </programlisting> | ||
11650 | |||
11651 | <para> | ||
11652 | <command>mailmime_add_part()</command> will add a sub MIME | ||
11653 | part. | ||
11654 | </para> | ||
11655 | |||
11656 | <para> | ||
11657 | <command>mailmime_remove_part()</command> will detach the | ||
11658 | given sub part from its parent. | ||
11659 | </para> | ||
11660 | |||
11661 | <para> | ||
11662 | <command>mailmime_smart_add_part()</command> will add a sub | ||
11663 | MIME part. If the parent part is a message and no child | ||
11664 | exist, the part is set as the child. If the parent part is a | ||
11665 | message and a child already exists, if the child is | ||
11666 | multipart, the part to add is added as child of this | ||
11667 | multipart, else a multipart is added and the part is added | ||
11668 | as child of the multipart. | ||
11669 | </para> | ||
11670 | |||
11671 | <para> | ||
11672 | <command>mailmime_smart_remove_part()</command> will detach | ||
11673 | the given sub part from its parent. The sub part will be | ||
11674 | freed. | ||
11675 | </para> | ||
11676 | |||
11677 | <itemizedlist> | ||
11678 | <listitem> | ||
11679 | <para> | ||
11680 | <command>build_info</command> is the parent MIME part | ||
11681 | (see <xref linkend="mailmime">). | ||
11682 | </para> | ||
11683 | </listitem> | ||
11684 | <listitem> | ||
11685 | <para> | ||
11686 | <command>part</command> is the part to add | ||
11687 | (see <xref linkend="mailmime">). | ||
11688 | </para> | ||
11689 | </listitem> | ||
11690 | <listitem> | ||
11691 | <para> | ||
11692 | <command>mime</command> is the parent MIME part | ||
11693 | (see <xref linkend="mailmime">). | ||
11694 | </para> | ||
11695 | </listitem> | ||
11696 | <listitem> | ||
11697 | <para> | ||
11698 | <command>mime_sub</command> is the part to add or to | ||
11699 | detach | ||
11700 | (see <xref linkend="mailmime">). | ||
11701 | </para> | ||
11702 | </listitem> | ||
11703 | </itemizedlist> | ||
11704 | |||
11705 | <example> | ||
11706 | <title>modifying MIME structure</title> | ||
11707 | |||
11708 | <programlisting role="C"> | ||
11709 | #include <libetpan/libetpan.h> | ||
11710 | |||
11711 | int main(int argc, char ** argv) | ||
11712 | { | ||
11713 | struct mailmime * sub_mime; | ||
11714 | struct mailmime_fields * mime_fields; | ||
11715 | struct mailmime_content * content; | ||
11716 | |||
11717 | content = mailmime_get_content_text(); | ||
11718 | |||
11719 | mime_fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_BASE64); | ||
11720 | |||
11721 | sub_mime = mailmime_new_empty(content, mime_fields); | ||
11722 | |||
11723 | mime = mailmime_new_message_data(NULL); | ||
11724 | |||
11725 | mailmime_add_part(mime, sub_mime); | ||
11726 | |||
11727 | /* do the things */ | ||
11728 | |||
11729 | mailmime_free(mime); | ||
11730 | |||
11731 | int main(int argc, char ** argv) | ||
11732 | { | ||
11733 | struct mailmime * sub_mime; | ||
11734 | struct mailmime * other_sub_mime; | ||
11735 | struct mailmime_fields * mime_fields; | ||
11736 | struct mailmime_content * content; | ||
11737 | |||
11738 | content = mailmime_get_content_text(); | ||
11739 | mime_fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_BASE64); | ||
11740 | sub_mime = mailmime_new_empty(content, mime_fields); | ||
11741 | |||
11742 | content = mailmime_get_content_text(); | ||
11743 | mime_fields = | ||
11744 | mailmime_fields_new_encoding(MAILMIME_MECHANISM_QUOTED_PRINTABLE); | ||
11745 | other_sub_mime = mailmime_new_empty(content, mime_fields); | ||
11746 | |||
11747 | mime = mailmime_new_message_data(NULL); | ||
11748 | |||
11749 | mailmime_smart_add_part(mime, sub_mime); | ||
11750 | mailmime_smart_add_part(mime, other_sub_mime); | ||
11751 | |||
11752 | /* do the things */ | ||
11753 | |||
11754 | mailmime_free(mime); | ||
11755 | |||
11756 | int main(int argc, char ** argv) | ||
11757 | { | ||
11758 | struct mailmime * sub_mime; | ||
11759 | struct mailmime_fields * mime_fields; | ||
11760 | struct mailmime_content * content; | ||
11761 | |||
11762 | content = mailmime_get_content_text(); | ||
11763 | |||
11764 | mime_fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_BASE64); | ||
11765 | |||
11766 | sub_mime = mailmime_new_empty(content, mime_fields); | ||
11767 | |||
11768 | mime = mailmime_new_message_data(NULL); | ||
11769 | |||
11770 | mailmime_add_part(mime, sub_mime); | ||
11771 | |||
11772 | mailmime_remove_part(sub_mime); | ||
11773 | |||
11774 | /* do the things */ | ||
11775 | |||
11776 | mailmime_free(sub_mime); | ||
11777 | mailmime_free(mime); | ||
11778 | |||
11779 | int main(int argc, char ** argv) | ||
11780 | { | ||
11781 | struct mailmime * sub_mime; | ||
11782 | struct mailmime_fields * mime_fields; | ||
11783 | struct mailmime_content * content; | ||
11784 | |||
11785 | content = mailmime_get_content_text(); | ||
11786 | |||
11787 | mime_fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_BASE64); | ||
11788 | |||
11789 | sub_mime = mailmime_new_empty(content, mime_fields); | ||
11790 | |||
11791 | mime = mailmime_new_message_data(NULL); | ||
11792 | |||
11793 | mailmime_add_part(mime, sub_mime); | ||
11794 | |||
11795 | mailmime_smart_remove_part(sub_mime); | ||
11796 | |||
11797 | /* do the things */ | ||
11798 | |||
11799 | mailmime_free(mime); | ||
11800 | } | ||
11801 | </programlisting> | ||
11802 | </example> | ||
11803 | </sect2> | ||
11804 | |||
11805 | <!-- mailmime_set_imf_fields --> | ||
11806 | <sect2 id="mailmime-set-imf-fields"> | ||
11807 | <title>mailmime_set_imf_fields</title> | ||
11808 | |||
11809 | <programlisting role="C"> | ||
11810 | #include <libetpan/libetpan.h> | ||
11811 | |||
11812 | void mailmime_set_imf_fields(struct mailmime * build_info, | ||
11813 | struct mailimf_fields * fields); | ||
11814 | </programlisting> | ||
11815 | |||
11816 | <para> | ||
11817 | <command>mailmime_set_imf_fields()</command> will set the | ||
11818 | fields of the given MIME message. | ||
11819 | </para> | ||
11820 | |||
11821 | <itemizedlist> | ||
11822 | <listitem> | ||
11823 | <para> | ||
11824 | <command>build_info</command> is the MIME message to | ||
11825 | modify | ||
11826 | (see <xref linkend="mailmime">). | ||
11827 | </para> | ||
11828 | </listitem> | ||
11829 | <listitem> | ||
11830 | <para> | ||
11831 | <command>fields</command> is the header fields to set | ||
11832 | for the message | ||
11833 | (see <xref linkend="mailimf-fields">). | ||
11834 | </para> | ||
11835 | </listitem> | ||
11836 | </itemizedlist> | ||
11837 | |||
11838 | <example> | ||
11839 | <title>modifying MIME structure</title> | ||
11840 | |||
11841 | <programlisting role="C"> | ||
11842 | #include <libetpan/libetpan.h> | ||
11843 | |||
11844 | #define DATA_STR "test foo bar" | ||
11845 | |||
11846 | int main(int argc, char ** argv) | ||
11847 | { | ||
11848 | struct mailmime * mime; | ||
11849 | struct mailmime_fields * mime_fields; | ||
11850 | struct mailimf_fields * imf_fields; | ||
11851 | |||
11852 | mime_fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_8BIT); | ||
11853 | |||
11854 | mailmime_new_with_content("text/plain", mime_fields, &mime); | ||
11855 | |||
11856 | mailmime_set_body_text(mime, DATA_STR, sizeof(DATA_STR) - 1); | ||
11857 | |||
11858 | /* look at the example in mailimf_fields to see how to | ||
11859 | build a mailimf_fields */ | ||
11860 | imf_fields = build_fields(); | ||
11861 | |||
11862 | mailmime_set_imf_fields(mime, imf_fields); | ||
11863 | |||
11864 | /* do the things */ | ||
11865 | |||
11866 | mailmime_free(mime); | ||
11867 | } | ||
11868 | </programlisting> | ||
11869 | </example> | ||
11870 | </sect2> | ||
11871 | |||
11872 | <!-- mailmime_fields_new_encoding --> | ||
11873 | <sect2 id="mailmime-fields-new-encoding"> | ||
11874 | <title>mailmime_fields_new_encoding and | ||
11875 | mailmime_fields_new_filename</title> | ||
11876 | |||
11877 | <programlisting role="C"> | ||
11878 | #include <libetpan/libetpan.h> | ||
11879 | |||
11880 | enum { | ||
11881 | MAILMIME_MECHANISM_ERROR, | ||
11882 | MAILMIME_MECHANISM_7BIT, | ||
11883 | MAILMIME_MECHANISM_8BIT, | ||
11884 | MAILMIME_MECHANISM_BINARY, | ||
11885 | MAILMIME_MECHANISM_QUOTED_PRINTABLE, | ||
11886 | MAILMIME_MECHANISM_BASE64, | ||
11887 | MAILMIME_MECHANISM_TOKEN | ||
11888 | }; | ||
11889 | |||
11890 | enum { | ||
11891 | MAILMIME_DISPOSITION_TYPE_ERROR, | ||
11892 | MAILMIME_DISPOSITION_TYPE_INLINE, | ||
11893 | MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
11894 | MAILMIME_DISPOSITION_TYPE_EXTENSION | ||
11895 | }; | ||
11896 | |||
11897 | struct mailmime_fields * mailmime_fields_new_encoding(int encoding_type); | ||
11898 | |||
11899 | struct mailmime_fields * mailmime_fields_new_filename(int dsp_type, | ||
11900 | char * filename, int encoding_type); | ||
11901 | </programlisting> | ||
11902 | |||
11903 | <para> | ||
11904 | <command>mailmime_fields_new_encoding()</command> will | ||
11905 | create a list of MIME header fields with only | ||
11906 | <command>Content-Transfer-Encoding</command>. | ||
11907 | </para> | ||
11908 | |||
11909 | <para> | ||
11910 | <command>mailmime_fields_new_filename()</command> will | ||
11911 | create a list of MIME header fields with | ||
11912 | <command>Content-Transfer-Encoding</command> and | ||
11913 | <command>Content-Disposition</command>. | ||
11914 | </para> | ||
11915 | |||
11916 | <para> | ||
11917 | The result will be a list of MIME header fields | ||
11918 | (see <xref linkend="mailmime-fields">). | ||
11919 | </para> | ||
11920 | |||
11921 | <itemizedlist> | ||
11922 | <listitem> | ||
11923 | <para> | ||
11924 | <command>encoding_type</command> is the MIME encoding | ||
11925 | mechanism. The value can be | ||
11926 | <command>MAILMIME_MECHANISM_7BIT</command>, | ||
11927 | <command>MAILMIME_MECHANISM_8BIT</command>, | ||
11928 | <command>MAILMIME_MECHANISM_BINARY</command>, | ||
11929 | <command>MAILMIME_MECHANISM_QUOTED_PRINTABLE</command> or | ||
11930 | <command>MAILMIME_MECHANISM_BASE64</command> | ||
11931 | (see <xref linkend="mailmime-mechanism">). | ||
11932 | </para> | ||
11933 | </listitem> | ||
11934 | <listitem> | ||
11935 | <para> | ||
11936 | <command>dsp_type</command> is the disposition type. | ||
11937 | The value can be | ||
11938 | <command>MAILMIME_DISPOSITION_TYPE_INLINE</command> or | ||
11939 | <command>MAILMIME_DISPOSITION_TYPE_ATTACHMENT</command> | ||
11940 | (see <xref linkend="mailmime-disposition-type">). | ||
11941 | </para> | ||
11942 | </listitem> | ||
11943 | <listitem> | ||
11944 | <para> | ||
11945 | <command>filename</command> is the filename for MIME | ||
11946 | content disposition. | ||
11947 | </para> | ||
11948 | </listitem> | ||
11949 | </itemizedlist> | ||
11950 | |||
11951 | <example> | ||
11952 | <title>creating MIME fields with only Content-Transfer-Encoding</title> | ||
11953 | |||
11954 | <programlisting role="C"> | ||
11955 | #include <libetpan/libetpan.h> | ||
11956 | |||
11957 | int main(void) | ||
11958 | { | ||
11959 | struct mailmime_fields * fields; | ||
11960 | |||
11961 | fields = mailmime_fields_new_encoding(MAILMIME_MECHANISM_BASE64); | ||
11962 | |||
11963 | /* do the things */ | ||
11964 | |||
11965 | mailmime_fields_free(fields); | ||
11966 | } | ||
11967 | |||
11968 | int main(void) | ||
11969 | { | ||
11970 | struct mailmime_fields * fields; | ||
11971 | |||
11972 | fields = | ||
11973 | mailmime_fields_new_filename(MAILMIME_DISPOSITION_TYPE_ATTACHMENT, | ||
11974 | strdup("foo-bar.txt"), MAILMIME_MECHANISM_BASE64); | ||
11975 | |||
11976 | /* do the things */ | ||
11977 | |||
11978 | mailmime_fields_free(fields); | ||
11979 | } | ||
11980 | </programlisting> | ||
11981 | </example> | ||
11982 | </sect2> | ||
11983 | </sect1> | ||
11984 | |||
11985 | <!-- Helper functions --> | ||
11986 | <sect1> | ||
11987 | <title>Helper functions</title> | ||
11988 | |||
11989 | <!-- mailmime_transfer_encoding_get --> | ||
11990 | <sect2 id="mailmime-transfer-encoding-get"> | ||
11991 | <title>mailmime_transfer_encoding_get</title> | ||
11992 | |||
11993 | <programlisting role="C"> | ||
11994 | #include <libetpan/libetpan.h> | ||
11995 | |||
11996 | int mailmime_transfer_encoding_get(struct mailmime_fields * fields); | ||
11997 | </programlisting> | ||
11998 | |||
11999 | <para> | ||
12000 | <command>mailmime_transfer_encoding_get()</command> will | ||
12001 | return the standard MIME encoding mechanism. | ||
12002 | </para> | ||
12003 | |||
12004 | <itemizedlist> | ||
12005 | <listitem> | ||
12006 | <para> | ||
12007 | <command>fields</command> is the list of MIME header | ||
12008 | fields. | ||
12009 | </para> | ||
12010 | </listitem> | ||
12011 | <listitem> | ||
12012 | <para> | ||
12013 | An integer representing the MIME encoding mechanism will | ||
12014 | be returned | ||
12015 | (see <xref linkend="mailmime-mechanism">). | ||
12016 | </para> | ||
12017 | </listitem> | ||
12018 | </itemizedlist> | ||
12019 | |||
12020 | <example> | ||
12021 | <title>extracting MIME encoding mechanism</title> | ||
12022 | |||
12023 | <programlisting role="C"> | ||
12024 | #include <libetpan/libetpan.h> | ||
12025 | #include <sys/stat.h> | ||
12026 | #include <sys/mman.h> | ||
12027 | |||
12028 | int main(int argc, char ** argv) | ||
12029 | { | ||
12030 | int fd; | ||
12031 | int r; | ||
12032 | |||
12033 | status = EXIT_FAILURE; | ||
12034 | |||
12035 | fd = open("message.rfc2822", O_RDONLY); | ||
12036 | if (fd >= 0) { | ||
12037 | void * mem; | ||
12038 | struct stat stat_info; | ||
12039 | |||
12040 | r = fstat(fd, &stat_info); | ||
12041 | if (r >= 0) { | ||
12042 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
12043 | if (mem != MAP_FAILED) { | ||
12044 | struct mailimf_fields * f; | ||
12045 | size_t current_index; | ||
12046 | |||
12047 | current_index = 0; | ||
12048 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
12049 | &current_index, &f); | ||
12050 | if (r == MAILIMF_NO_ERROR) { | ||
12051 | struct mailmime_fields * mime_fields; | ||
12052 | |||
12053 | r = mailmime_fields_parse(f, &mime_fields); | ||
12054 | if (r == MAILIMF_NO_ERROR) { | ||
12055 | int encoding; | ||
12056 | |||
12057 | encoding = mailmime_transfer_encoding_get(mime_fields); | ||
12058 | |||
12059 | /* do the things */ | ||
12060 | |||
12061 | mailmime_fields_free(mime_fields); | ||
12062 | status = EXIT_SUCCESS; | ||
12063 | } | ||
12064 | |||
12065 | mailimf_fields_free(f); | ||
12066 | } | ||
12067 | } | ||
12068 | munmap(mem, stat_info.st_size); | ||
12069 | } | ||
12070 | |||
12071 | close(fd); | ||
12072 | } | ||
12073 | |||
12074 | exit(status); | ||
12075 | } | ||
12076 | </programlisting> | ||
12077 | </example> | ||
12078 | |||
12079 | </sect2> | ||
12080 | |||
12081 | <!-- mailmime_content_charset_get --> | ||
12082 | <sect2 id="mailmime-content-charset-get"> | ||
12083 | <title>mailmime_content_charset_get and | ||
12084 | mailmime_content_param_get</title> | ||
12085 | |||
12086 | <programlisting role="C"> | ||
12087 | #include <libetpan/libetpan.h> | ||
12088 | |||
12089 | char * mailmime_content_charset_get(struct mailmime_content * content); | ||
12090 | |||
12091 | char * mailmime_content_param_get(struct mailmime_content * content, | ||
12092 | char * name); | ||
12093 | |||
12094 | char * mailmime_extract_boundary(struct mailmime_content * content_type); | ||
12095 | </programlisting> | ||
12096 | |||
12097 | <para> | ||
12098 | <command>mailmime_content_charset_get()</command> will | ||
12099 | return the <command>charset</command> parameter of | ||
12100 | MIME content type. | ||
12101 | </para> | ||
12102 | |||
12103 | <para> | ||
12104 | <command>mailmime_content_param_get()</command> will | ||
12105 | return the value of a given parameter of | ||
12106 | MIME content type. | ||
12107 | </para> | ||
12108 | |||
12109 | <para> | ||
12110 | <command>mailmime_extract_boundary()</command> will | ||
12111 | return the <command>charset</command> parameter of | ||
12112 | MIME content type. | ||
12113 | </para> | ||
12114 | |||
12115 | <itemizedlist> | ||
12116 | <listitem> | ||
12117 | <para> | ||
12118 | <command>content</command> is the MIME content type. | ||
12119 | </para> | ||
12120 | </listitem> | ||
12121 | <listitem> | ||
12122 | <para> | ||
12123 | <command>name</command> is the name of the parameter to | ||
12124 | extract. | ||
12125 | </para> | ||
12126 | </listitem> | ||
12127 | <listitem> | ||
12128 | <para> | ||
12129 | With <command>mailmime_extract_boundary()</command>, the | ||
12130 | returned value must be freed with | ||
12131 | <command>free()</command>. | ||
12132 | </para> | ||
12133 | </listitem> | ||
12134 | </itemizedlist> | ||
12135 | |||
12136 | <example> | ||
12137 | <title>extracting information from MIME content type</title> | ||
12138 | |||
12139 | <programlisting role="C"> | ||
12140 | #include <libetpan/libetpan.h> | ||
12141 | #include <sys/stat.h> | ||
12142 | #include <sys/mman.h> | ||
12143 | |||
12144 | int main(int argc, char ** argv) | ||
12145 | { | ||
12146 | int fd; | ||
12147 | int r; | ||
12148 | |||
12149 | status = EXIT_FAILURE; | ||
12150 | |||
12151 | fd = open("message.rfc2822", O_RDONLY); | ||
12152 | if (fd >= 0) { | ||
12153 | void * mem; | ||
12154 | struct stat stat_info; | ||
12155 | |||
12156 | r = fstat(fd, &stat_info); | ||
12157 | if (r >= 0) { | ||
12158 | mem = mmap(NULL, stat_info.st_size, PROT_READ, MAP_PRIVATE); | ||
12159 | if (mem != MAP_FAILED) { | ||
12160 | struct mailimf_fields * f; | ||
12161 | size_t current_index; | ||
12162 | |||
12163 | current_index = 0; | ||
12164 | r = mailimf_fields_parse(mem, stat_info.st_size, | ||
12165 | &current_index, &f); | ||
12166 | if (r == MAILIMF_NO_ERROR) { | ||
12167 | clistiter * cur; | ||
12168 | |||
12169 | for(cur = clist_begin(f->fld_list) ; cur != NULL ; cur = | ||
12170 | clist_next(cur)) { | ||
12171 | struct mailmime_field * mime_field; | ||
12172 | struct mailimf_field * field; | ||
12173 | |||
12174 | field = clist_content(cur); | ||
12175 | |||
12176 | if (field->fld_type == MAILIMF_FIELD_OPTIONAL_FIELD) { | ||
12177 | if (strcasecmp(field->fld_data.fld_optional_field->fld_name, | ||
12178 | "Content-Type") == 0) { | ||
12179 | struct mailmime_content * content_type; | ||
12180 | size_t current_index; | ||
12181 | |||
12182 | current_index = 0; | ||
12183 | r = mailmime_content_parse(field->fld_data.fld_optional_field->fld_value, | ||
12184 | strlen(field->fld_data.fld_optional_field->fld_value), | ||
12185 | &current_index, &content_type); | ||
12186 | if (r == MAILIMF_NO_ERROR) { | ||
12187 | char * charset; | ||
12188 | char * name; | ||
12189 | char * boundary; | ||
12190 | |||
12191 | charset = mailmime_content_charset_get(content_type); | ||
12192 | name = mailmime_content_param_get(content_type, "name"); | ||
12193 | boundary = mailmime_extract_boundary(content_type); | ||
12194 | |||
12195 | /* do the things */ | ||
12196 | |||
12197 | free(boundary); | ||
12198 | |||
12199 | status = EXIT_SUCCESS; | ||
12200 | mailmime_content_free(content_type); | ||
12201 | } | ||
12202 | } | ||
12203 | } | ||
12204 | } | ||
12205 | mailimf_fields_free(f); | ||
12206 | } | ||
12207 | } | ||
12208 | munmap(mem, stat_info.st_size); | ||
12209 | } | ||
12210 | |||
12211 | close(fd); | ||
12212 | } | ||
12213 | |||
12214 | exit(status); | ||
12215 | } | ||
12216 | </programlisting> | ||
12217 | </example> | ||
12218 | </sect2> | ||
12219 | </sect1> | ||
12220 | </chapter> | ||
12221 | |||
12222 | <!-- Storages, folders, messages --> | ||
12223 | <chapter> | ||
12224 | <title>Storages, folders, messages</title> | ||
12225 | |||
12226 | <!-- Introduction --> | ||
12227 | <sect1> | ||
12228 | <title>Introduction</title> | ||
12229 | |||
12230 | <para> | ||
12231 | This part will give the definition of some objects. | ||
12232 | </para> | ||
12233 | |||
12234 | <sect2> | ||
12235 | <title>Message</title> | ||
12236 | |||
12237 | <para> | ||
12238 | A message is the common e-mail message or news message you | ||
12239 | read or send. | ||
12240 | </para> | ||
12241 | </sect2> | ||
12242 | |||
12243 | <sect2> | ||
12244 | <title>MIME part</title> | ||
12245 | |||
12246 | <para> | ||
12247 | A message can have attachment such as images or other documents. | ||
12248 | The attachment are organized into a tree structure. Each | ||
12249 | node of this structure is a MIME part. | ||
12250 | </para> | ||
12251 | </sect2> | ||
12252 | |||
12253 | <sect2> | ||
12254 | <title>Mailbox</title> | ||
12255 | |||
12256 | <para> | ||
12257 | A mailbox will contain a given number of messages. | ||
12258 | </para> | ||
12259 | </sect2> | ||
12260 | |||
12261 | <sect2> | ||
12262 | <title>Storage</title> | ||
12263 | |||
12264 | <para> | ||
12265 | A storage is a "physical" localisation of your mailbox. This | ||
12266 | can be on a filesystem (local or remote disk, this is the | ||
12267 | case of MH, mbox and maildir), or this can be on a remote | ||
12268 | host (this is the case for POP3, IMAP or NNTP). | ||
12269 | </para> | ||
12270 | </sect2> | ||
12271 | |||
12272 | <sect2> | ||
12273 | <title>Folder</title> | ||
12274 | |||
12275 | <para> | ||
12276 | A storage, for the same user, can contain a given number of | ||
12277 | mailboxes, depending the storage capabilities, then, the | ||
12278 | storage driver capabilities. With etPan!, MH, IMAP and NNTP | ||
12279 | storages can have more than one mailbox. The mailboxes will | ||
12280 | be called folders. On storage where we only have one | ||
12281 | mailbox, the unique mailbox is the unique folder. | ||
12282 | </para> | ||
12283 | </sect2> | ||
12284 | |||
12285 | <sect2> | ||
12286 | <title>Session</title> | ||
12287 | |||
12288 | <para> | ||
12289 | The session is the network connection or the entity to which | ||
12290 | the commands of the drivers are given. | ||
12291 | </para> | ||
12292 | </sect2> | ||
12293 | </sect1> | ||
12294 | |||
12295 | <sect1> | ||
12296 | <title>Error codes</title> | ||
12297 | |||
12298 | <para> | ||
12299 | Error codes returned as integers can be one of the following : | ||
12300 | </para> | ||
12301 | |||
12302 | <programlisting role="C"> | ||
12303 | enum { | ||
12304 | MAIL_NO_ERROR = 0, | ||
12305 | MAIL_NO_ERROR_AUTHENTICATED, | ||
12306 | MAIL_NO_ERROR_NON_AUTHENTICATED, | ||
12307 | MAIL_ERROR_NOT_IMPLEMENTED, | ||
12308 | MAIL_ERROR_UNKNOWN, | ||
12309 | MAIL_ERROR_CONNECT, | ||
12310 | MAIL_ERROR_BAD_STATE, | ||
12311 | MAIL_ERROR_FILE, | ||
12312 | MAIL_ERROR_STREAM, | ||
12313 | MAIL_ERROR_LOGIN, | ||
12314 | MAIL_ERROR_CREATE, /* 10 */ | ||
12315 | MAIL_ERROR_DELETE, | ||
12316 | MAIL_ERROR_LOGOUT, | ||
12317 | MAIL_ERROR_NOOP, | ||
12318 | MAIL_ERROR_RENAME, | ||
12319 | MAIL_ERROR_CHECK, | ||
12320 | MAIL_ERROR_EXAMINE, | ||
12321 | MAIL_ERROR_SELECT, | ||
12322 | MAIL_ERROR_MEMORY, | ||
12323 | MAIL_ERROR_STATUS, | ||
12324 | MAIL_ERROR_SUBSCRIBE, /* 20 */ | ||
12325 | MAIL_ERROR_UNSUBSCRIBE, | ||
12326 | MAIL_ERROR_LIST, | ||
12327 | MAIL_ERROR_LSUB, | ||
12328 | MAIL_ERROR_APPEND, | ||
12329 | MAIL_ERROR_COPY, | ||
12330 | MAIL_ERROR_FETCH, | ||
12331 | MAIL_ERROR_STORE, | ||
12332 | MAIL_ERROR_SEARCH, | ||
12333 | MAIL_ERROR_DISKSPACE, | ||
12334 | MAIL_ERROR_MSG_NOT_FOUND, /* 30 */ | ||
12335 | MAIL_ERROR_PARSE, | ||
12336 | MAIL_ERROR_INVAL, | ||
12337 | MAIL_ERROR_PART_NOT_FOUND, | ||
12338 | MAIL_ERROR_REMOVE, | ||
12339 | MAIL_ERROR_FOLDER_NOT_FOUND, | ||
12340 | MAIL_ERROR_MOVE, | ||
12341 | MAIL_ERROR_STARTTLS, | ||
12342 | MAIL_ERROR_CACHE_MISS, | ||
12343 | MAIL_ERROR_NO_TLS, | ||
12344 | MAIL_ERROR_EXPUNGE, | ||
12345 | /* misc errors */ | ||
12346 | MAIL_ERROR_MISC, | ||
12347 | MAIL_ERROR_PROTOCOL, | ||
12348 | MAIL_ERROR_CAPABILITY, | ||
12349 | MAIL_ERROR_CLOSE, | ||
12350 | MAIL_ERROR_FATAL, | ||
12351 | MAIL_ERROR_READONLY, | ||
12352 | MAIL_ERROR_NO_APOP, | ||
12353 | MAIL_ERROR_COMMAND_NOT_SUPPORTED, | ||
12354 | MAIL_ERROR_NO_PERMISSION, | ||
12355 | MAIL_ERROR_PROGRAM_ERROR, | ||
12356 | MAIL_ERROR_SUBJECT_NOT_FOUND, | ||
12357 | MAIL_ERROR_CHAR_ENCODING_FAILED, | ||
12358 | MAIL_ERROR_SEND, | ||
12359 | MAIL_ERROR_COMMAND, | ||
12360 | }; | ||
12361 | </programlisting> | ||
12362 | </sect1> | ||
12363 | |||
12364 | <!-- Storage --> | ||
12365 | <sect1> | ||
12366 | <title>Storage</title> | ||
12367 | |||
12368 | <sect2 id="mailstorage-driver"> | ||
12369 | <title>Storage driver</title> | ||
12370 | |||
12371 | <programlisting role="C"> | ||
12372 | #include <libetpan/libetpan.h> | ||
12373 | |||
12374 | typedef struct mailstorage_driver mailstorage_driver; | ||
12375 | |||
12376 | struct mailstorage_driver { | ||
12377 | char * sto_name; | ||
12378 | int (* sto_connect)(struct mailstorage * storage); | ||
12379 | int (* sto_get_folder_session)(struct mailstorage * storage, | ||
12380 | char * pathname, mailsession ** result); | ||
12381 | void (* sto_uninitialize)(struct mailstorage * storage); | ||
12382 | }; | ||
12383 | </programlisting> | ||
12384 | |||
12385 | <para> | ||
12386 | This is the driver for a storage. | ||
12387 | </para> | ||
12388 | |||
12389 | <itemizedlist> | ||
12390 | <listitem> | ||
12391 | <para> | ||
12392 | <command>sto_name</command> is the name of the driver. | ||
12393 | </para> | ||
12394 | </listitem> | ||
12395 | <listitem> | ||
12396 | <para> | ||
12397 | <command>sto_connect()</command> connects the storage to | ||
12398 | the remote access or to the path in the local filesystem. | ||
12399 | </para> | ||
12400 | </listitem> | ||
12401 | <listitem> | ||
12402 | <para> | ||
12403 | <command>sto_get_folder_session()</command> can have two | ||
12404 | kinds of behaviour. Either it creates a new session and | ||
12405 | independant from the session used by the storage and | ||
12406 | select the given mailbox or it selects the given mailbox | ||
12407 | in the current session. It depends on the efficiency of | ||
12408 | the mail access. | ||
12409 | </para> | ||
12410 | <para> | ||
12411 | <emphasis>XXX - in the future, this will be moved to the | ||
12412 | folder driver</emphasis> | ||
12413 | </para> | ||
12414 | </listitem> | ||
12415 | <listitem> | ||
12416 | <para> | ||
12417 | <command>sto_uninitialize()</command> frees the data | ||
12418 | created with mailstorage constructor. | ||
12419 | </para> | ||
12420 | </listitem> | ||
12421 | </itemizedlist> | ||
12422 | </sect2> | ||
12423 | |||
12424 | <sect2 id="mailstorage"> | ||
12425 | <title>Storage</title> | ||
12426 | |||
12427 | <programlisting role="C"> | ||
12428 | #include <libetpan/libetpan.h> | ||
12429 | |||
12430 | struct mailstorage { | ||
12431 | char * sto_id; | ||
12432 | void * sto_data; | ||
12433 | mailsession * sto_session; | ||
12434 | mailstorage_driver * sto_driver; | ||
12435 | clist * sto_shared_folders; /* list of (struct mailfolder *) */ | ||
12436 | |||
12437 | void * sto_user_data; | ||
12438 | }; | ||
12439 | </programlisting> | ||
12440 | |||
12441 | <itemizedlist> | ||
12442 | <listitem> | ||
12443 | <para> | ||
12444 | <command>sto_id</command> is an identifier for the | ||
12445 | storage. This can be <command>NULL</command>. | ||
12446 | </para> | ||
12447 | </listitem> | ||
12448 | <listitem> | ||
12449 | <para> | ||
12450 | <command>sto_data</command> is the internal data | ||
12451 | of the storage. This can only be changed by the driver. | ||
12452 | </para> | ||
12453 | </listitem> | ||
12454 | <listitem> | ||
12455 | <para> | ||
12456 | <command>sto_session</command> is the session used by | ||
12457 | the storage. The session can be used to send commands. | ||
12458 | </para> | ||
12459 | </listitem> | ||
12460 | <listitem> | ||
12461 | <para> | ||
12462 | <command>sto_driver</command> is the driver of the | ||
12463 | storage. | ||
12464 | </para> | ||
12465 | </listitem> | ||
12466 | <listitem> | ||
12467 | <para> | ||
12468 | <command>sto_shared_folders</command> is the list of | ||
12469 | folders that share the session with the storage. | ||
12470 | This is used internally. | ||
12471 | </para> | ||
12472 | </listitem> | ||
12473 | <listitem> | ||
12474 | <para> | ||
12475 | <command>sto_user_data</command> is a field for free | ||
12476 | use. The user can store any data in that field. | ||
12477 | </para> | ||
12478 | </listitem> | ||
12479 | </itemizedlist> | ||
12480 | </sect2> | ||
12481 | |||
12482 | <sect2 id="mailstorage-new"> | ||
12483 | <title>mailstorage_new and mailstorage_free</title> | ||
12484 | |||
12485 | <programlisting role="C"> | ||
12486 | #include <libetpan/libetpan.h> | ||
12487 | |||
12488 | struct mailstorage * mailstorage_new(char * sto_id); | ||
12489 | |||
12490 | void mailstorage_free(struct mailstorage * storage); | ||
12491 | </programlisting> | ||
12492 | |||
12493 | <para> | ||
12494 | <command>mailstorage_new()</command> initializes a storage | ||
12495 | structure with an identifier (<command>sto_id</command>) and | ||
12496 | with no driver. | ||
12497 | </para> | ||
12498 | |||
12499 | <para> | ||
12500 | <command>mailstorage_free()</command> free the memory used | ||
12501 | by a storage. | ||
12502 | </para> | ||
12503 | </sect2> | ||
12504 | |||
12505 | <sect2 id="mailstorage-connect"> | ||
12506 | <title>mailstorage_connect and mailstorage_disconnect</title> | ||
12507 | |||
12508 | <programlisting role="C"> | ||
12509 | #include <libetpan/libetpan.h> | ||
12510 | |||
12511 | int mailstorage_connect(struct mailstorage * storage); | ||
12512 | |||
12513 | void mailstorage_disconnect(struct mailstorage * storage); | ||
12514 | </programlisting> | ||
12515 | |||
12516 | <para> | ||
12517 | <command>mailstorage_connect()</command> connects the storage. | ||
12518 | This function can also be used to confirm that a storage | ||
12519 | connection is valid when the storage is already connected. | ||
12520 | </para> | ||
12521 | |||
12522 | <para> | ||
12523 | <command>mailstorage_disconnect()</command> disconnects the | ||
12524 | storage. | ||
12525 | </para> | ||
12526 | </sect2> | ||
12527 | |||
12528 | <sect2> | ||
12529 | <title>IMAP storage</title> | ||
12530 | |||
12531 | <programlisting role="C"> | ||
12532 | int imap_mailstorage_init(struct mailstorage * storage, | ||
12533 | char * imap_servername, uint16_t imap_port, | ||
12534 | char * imap_command, | ||
12535 | int imap_connection_type, int imap_auth_type, | ||
12536 | char * imap_login, char * imap_password, | ||
12537 | int imap_cached, char * imap_cache_directory); | ||
12538 | </programlisting> | ||
12539 | </sect2> | ||
12540 | |||
12541 | <sect2> | ||
12542 | <title>Example</title> | ||
12543 | |||
12544 | <example> | ||
12545 | <title>use of storage</title> | ||
12546 | |||
12547 | <programlisting role="C"> | ||
12548 | int main(void) | ||
12549 | { | ||
12550 | struct mailstorage * storage; | ||
12551 | int r; | ||
12552 | |||
12553 | storage = mailstorage_new(NULL); | ||
12554 | |||
12555 | imap_mailstorage_init(storage, "imap.my-servers.org", 0, | ||
12556 | NULL, CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN, | ||
12557 | "my-login", "my-password", 1, "/home/login/.libetpan/cache"); | ||
12558 | |||
12559 | r = mailstorage_connect(storage); | ||
12560 | if (r == MAIL_NO_ERROR) { | ||
12561 | mailstorage_disconnect(storage); | ||
12562 | } | ||
12563 | |||
12564 | mailstorage_free(storage); | ||
12565 | } | ||
12566 | </programlisting> | ||
12567 | </example> | ||
12568 | </sect2> | ||
12569 | </sect1> | ||
12570 | |||
12571 | <!-- Folder --> | ||
12572 | <sect1> | ||
12573 | <title>Folder</title> | ||
12574 | |||
12575 | <sect2 id="mailfolder-driver"> | ||
12576 | <title>Folder driver</title> | ||
12577 | |||
12578 | <programlisting role="C"> | ||
12579 | #include <libetpan/libetpan.h> | ||
12580 | |||
12581 | typedef struct mailfolder_driver mailfolder_driver; | ||
12582 | |||
12583 | struct mailfolder_driver { | ||
12584 | int (* fld_get_session)(struct mailfolder * folder, | ||
12585 | mailsession ** result); | ||
12586 | |||
12587 | int (* fld_noop)(struct mailfolder * folder); | ||
12588 | |||
12589 | int (* fld_check)(struct mailfolder * folder); | ||
12590 | |||
12591 | int (* fld_expunge)(struct mailfolder * folder); | ||
12592 | |||
12593 | int (* fld_status)(struct mailfolder * folder, | ||
12594 | uint32_t * result_messages, uint32_t * result_recent, | ||
12595 | uint32_t * result_unseen); | ||
12596 | |||
12597 | int (* fld_append_message)(struct mailfolder * folder, | ||
12598 | char * message, size_t size); | ||
12599 | |||
12600 | int (* fld_get_messages_list)(struct mailfolder * folder, | ||
12601 | struct mailmessage_list ** result); | ||
12602 | |||
12603 | int (* fld_get_envelopes_list)(struct mailfolder * folder, | ||
12604 | struct mailmessage_list * result); | ||
12605 | |||
12606 | int (* fld_get_message)(struct mailfolder * folder, | ||
12607 | uint32_t num, mailmessage ** result); | ||
12608 | |||
12609 | int (* fld_get_message_by_uid)(struct mailfolder * folder, | ||
12610 | const char * uid, mailmessage ** result); | ||
12611 | } | ||
12612 | </programlisting> | ||
12613 | |||
12614 | <para> | ||
12615 | XXX - this will be implemented in the future. | ||
12616 | </para> | ||
12617 | |||
12618 | <itemizedlist> | ||
12619 | <listitem> | ||
12620 | <para> | ||
12621 | <command>fld_get_session()</command> will return the session | ||
12622 | this folder should use. | ||
12623 | </para> | ||
12624 | </listitem> | ||
12625 | <listitem> | ||
12626 | <para> | ||
12627 | For other method, you should see <xref | ||
12628 | linkend="mailsession-driver">. | ||
12629 | </para> | ||
12630 | </listitem> | ||
12631 | </itemizedlist> | ||
12632 | </sect2> | ||
12633 | |||
12634 | <sect2> | ||
12635 | <title>Folder</title> | ||
12636 | |||
12637 | <programlisting role="C"> | ||
12638 | #include <libetpan/libetpan.h> | ||
12639 | |||
12640 | struct mailfolder { | ||
12641 | char * fld_pathname; | ||
12642 | char * fld_virtual_name; | ||
12643 | |||
12644 | struct mailstorage * fld_storage; | ||
12645 | |||
12646 | mailsession * fld_session; | ||
12647 | int fld_shared_session; | ||
12648 | clistiter * fld_pos; | ||
12649 | |||
12650 | struct mailfolder * fld_parent; | ||
12651 | unsigned int fld_sibling_index; | ||
12652 | carray * fld_children; /* array of (struct mailfolder *) */ | ||
12653 | |||
12654 | void * fld_user_data; | ||
12655 | }; | ||
12656 | </programlisting> | ||
12657 | |||
12658 | <itemizedlist> | ||
12659 | <listitem> | ||
12660 | <para> | ||
12661 | <command>fld_pathname</command> is the pathname specific to | ||
12662 | the driver. | ||
12663 | </para> | ||
12664 | </listitem> | ||
12665 | |||
12666 | <listitem> | ||
12667 | <para> | ||
12668 | <command>fld_virtual_name</command> is the identifier of | ||
12669 | this folder. This can be <command>NULL</command>. | ||
12670 | </para> | ||
12671 | </listitem> | ||
12672 | |||
12673 | <listitem> | ||
12674 | <para> | ||
12675 | <command>fld_storage</command> is the storage used for this | ||
12676 | folder (see <xref linkend="mailstorage">). | ||
12677 | </para> | ||
12678 | </listitem> | ||
12679 | |||
12680 | <listitem> | ||
12681 | <para> | ||
12682 | <command>fld_session</command> is the session used for this | ||
12683 | folder. | ||
12684 | </para> | ||
12685 | </listitem> | ||
12686 | |||
12687 | <listitem> | ||
12688 | <para> | ||
12689 | <command>fld_shared_session</command> is set to 1 if the | ||
12690 | folder use the same session as the storage. This is used | ||
12691 | internally. | ||
12692 | </para> | ||
12693 | </listitem> | ||
12694 | |||
12695 | <listitem> | ||
12696 | <para> | ||
12697 | <command>fld_pos</command> is the | ||
12698 | position in the list of folders of the storage. | ||
12699 | This is used internally. | ||
12700 | </para> | ||
12701 | </listitem> | ||
12702 | |||
12703 | <listitem> | ||
12704 | <para> | ||
12705 | use of <command>fld_parent</command>, | ||
12706 | <command>fld_sibling_index</command> and | ||
12707 | <command>fld_children</command> is deprecated. | ||
12708 | </para> | ||
12709 | </listitem> | ||
12710 | |||
12711 | <listitem> | ||
12712 | <para> | ||
12713 | <command>fld_user_data</command> is a field for free | ||
12714 | use. The user can store any data in that field. | ||
12715 | </para> | ||
12716 | </listitem> | ||
12717 | </itemizedlist> | ||
12718 | </sect2> | ||
12719 | |||
12720 | <sect2 id="mailfolder-new"> | ||
12721 | <title>mailfolder_new and mail_folder_free</title> | ||
12722 | |||
12723 | <programlisting role="C"> | ||
12724 | #include <libetpan/libetpan.h> | ||
12725 | |||
12726 | struct mailfolder * mailfolder_new(struct mailstorage * fld_storage, | ||
12727 | char * fld_pathname, char * fld_virtual_name); | ||
12728 | |||
12729 | void mailfolder_free(struct mailfolder * folder); | ||
12730 | </programlisting> | ||
12731 | |||
12732 | <para> | ||
12733 | <command>mailfolder_new()</command> initializes a folder | ||
12734 | structure with an identifier | ||
12735 | (<command>fld_virtual_name</command>) with path name | ||
12736 | (<command>fld_pathname</command>). The folder will be owned | ||
12737 | by the given storage (<command>fld_storage</command>). | ||
12738 | </para> | ||
12739 | |||
12740 | <para> | ||
12741 | <command>mailfolder_free()</command> free the memory used | ||
12742 | by the folder. | ||
12743 | </para> | ||
12744 | </sect2> | ||
12745 | |||
12746 | <sect2 id="mailfolder-connect"> | ||
12747 | <title>mailfolder_connect and mailfolder_disconnect</title> | ||
12748 | |||
12749 | <programlisting role="C"> | ||
12750 | #include <libetpan/libetpan.h> | ||
12751 | |||
12752 | int mailfolder_connect(struct mailfolder * folder); | ||
12753 | |||
12754 | void mailfolder_disconnect(struct mailfolder * folder); | ||
12755 | </programlisting> | ||
12756 | |||
12757 | <para> | ||
12758 | <command>mailfolder_connect()</command> connects the folder. | ||
12759 | This function can also be used to confirm that a folder | ||
12760 | connection is valid when the folder is already connected. | ||
12761 | When doing operations with several folders, you have to be | ||
12762 | sure that this function has been called before making calls | ||
12763 | on folder. | ||
12764 | </para> | ||
12765 | |||
12766 | <para> | ||
12767 | <command>mailfolder_disconnect()</command> disconnects the | ||
12768 | folder. | ||
12769 | </para> | ||
12770 | </sect2> | ||
12771 | |||
12772 | <sect2 id="mailfolder-noop"> | ||
12773 | <title>mailfolder_noop</title> | ||
12774 | |||
12775 | <programlisting role="C"> | ||
12776 | #include <libetpan/libetpan.h> | ||
12777 | |||
12778 | int mailfolder_noop(struct mailfolder * folder); | ||
12779 | </programlisting> | ||
12780 | |||
12781 | <para> | ||
12782 | This function will only send noop to the mail access. | ||
12783 | </para> | ||
12784 | </sect2> | ||
12785 | |||
12786 | <sect2 id="mailfolder-check"> | ||
12787 | <title>mailfolder_check</title> | ||
12788 | |||
12789 | <programlisting role="C"> | ||
12790 | #include <libetpan/libetpan.h> | ||
12791 | |||
12792 | int mailfolder_check(struct mailfolder * folder); | ||
12793 | </programlisting> | ||
12794 | |||
12795 | <para> | ||
12796 | A call to this function will save to disk the internal state | ||
12797 | of the selected mailbox (such as flags). | ||
12798 | </para> | ||
12799 | </sect2> | ||
12800 | |||
12801 | <sect2 id="mailfolder-expunge"> | ||
12802 | <title>mailfolder_expunge</title> | ||
12803 | |||
12804 | <programlisting role="C"> | ||
12805 | #include <libetpan/libetpan.h> | ||
12806 | |||
12807 | int mailfolder_expunge(struct mailfolder * folder); | ||
12808 | </programlisting> | ||
12809 | |||
12810 | <para> | ||
12811 | A call to this function will delete all messages marked for | ||
12812 | deletion. | ||
12813 | </para> | ||
12814 | </sect2> | ||
12815 | |||
12816 | <sect2 id="mailfolder-status"> | ||
12817 | <title>mailfolder_status</title> | ||
12818 | |||
12819 | <programlisting role="C"> | ||
12820 | int mailfolder_status(struct mailfolder * folder, | ||
12821 | uint32_t * result_messages, uint32_t * result_recent, | ||
12822 | uint32_t * result_unseen); | ||
12823 | </programlisting> | ||
12824 | |||
12825 | <para> | ||
12826 | A call to this function will return some counts of messages | ||
12827 | in the mailbox. | ||
12828 | </para> | ||
12829 | </sect2> | ||
12830 | |||
12831 | <sect2 id="mailfolder-append-message"> | ||
12832 | <title>mailfolder_append_message</title> | ||
12833 | |||
12834 | <programlisting role="C"> | ||
12835 | int mailfolder_append_message(struct mailfolder * folder, | ||
12836 | char * message, size_t size); | ||
12837 | </programlisting> | ||
12838 | |||
12839 | <para> | ||
12840 | This function will store a new message in the given folder. | ||
12841 | The message is given by a string in memory | ||
12842 | (<command>message</command>) and a size | ||
12843 | (<command>size</command>). | ||
12844 | </para> | ||
12845 | </sect2> | ||
12846 | |||
12847 | <sect2 id="mailfolder-get-messages-list"> | ||
12848 | <title>mailfolder_get_messages_list</title> | ||
12849 | |||
12850 | <programlisting role="C"> | ||
12851 | int mailfolder_get_messages_list(struct mailfolder * folder, | ||
12852 | struct mailmessage_list ** result); | ||
12853 | </programlisting> | ||
12854 | |||
12855 | <para> | ||
12856 | This function will return the list of messages in the given | ||
12857 | folder (see <xref linkend="mailmessage-list">). | ||
12858 | </para> | ||
12859 | </sect2> | ||
12860 | |||
12861 | <sect2 id="mailfolder-get-envelopes-list"> | ||
12862 | <title>mailfolder_get_envelopes_list</title> | ||
12863 | |||
12864 | <programlisting role="C"> | ||
12865 | int mailfolder_get_envelopes_list(struct mailfolder * folder, | ||
12866 | struct mailmessage_list * result); | ||
12867 | </programlisting> | ||
12868 | |||
12869 | <para> | ||
12870 | This function will fill the list of parsed header fields | ||
12871 | structure in the <command>mailmessage</command> structures | ||
12872 | of the given list of messages (<command>result</command>). | ||
12873 | </para> | ||
12874 | </sect2> | ||
12875 | |||
12876 | <sect2 id="mailfolder-get-message"> | ||
12877 | <title>mailfolder_get_message</title> | ||
12878 | |||
12879 | <programlisting role="C"> | ||
12880 | int mailfolder_get_message(struct mailfolder * folder, | ||
12881 | uint32_t num, mailmessage ** result); | ||
12882 | </programlisting> | ||
12883 | |||
12884 | <para> | ||
12885 | This function will return the message identified by a | ||
12886 | message index (<command>num</command>) | ||
12887 | This will return a <command>mailmessage</command> structure | ||
12888 | in <command>(* result)</command> (see <xref | ||
12889 | linkend="mailmessage">). | ||
12890 | </para> | ||
12891 | </sect2> | ||
12892 | |||
12893 | <sect2 id="mailfolder-get-message-by-uid"> | ||
12894 | <title>mailfolder_get_message_by_uid</title> | ||
12895 | |||
12896 | <programlisting role="C"> | ||
12897 | int mailfolder_get_message_by_uid(struct mailfolder * folder, | ||
12898 | const char * uid, mailmessage ** result); | ||
12899 | </programlisting> | ||
12900 | |||
12901 | <para> | ||
12902 | This function will return the message identified by a | ||
12903 | unique identifier (<command>uid</command>) | ||
12904 | This will return a <command>mailmessage</command> structure | ||
12905 | in <command>(* result)</command> (see <xref | ||
12906 | linkend="mailmessage">). | ||
12907 | </para> | ||
12908 | </sect2> | ||
12909 | |||
12910 | <sect2> | ||
12911 | <title>Example</title> | ||
12912 | |||
12913 | <example> | ||
12914 | <title>use of folder</title> | ||
12915 | |||
12916 | <programlisting role="C"> | ||
12917 | int main(void) | ||
12918 | { | ||
12919 | struct mailstorage * storage; | ||
12920 | int r; | ||
12921 | |||
12922 | storage = mailstorage_new(NULL); | ||
12923 | |||
12924 | imap_mailstorage_init(storage, "imap.my-servers.org", 0, | ||
12925 | NULL, CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN, | ||
12926 | "my-login", "my-password", 1, "/home/login/.libetpan/cache"); | ||
12927 | |||
12928 | r = mailstorage_connect(storage); | ||
12929 | if (r == MAIL_NO_ERROR) { | ||
12930 | struct mailfolder * folder; | ||
12931 | |||
12932 | folder = mailfolder_new(storage, "INBOX", NULL); | ||
12933 | |||
12934 | r = mailfolder_connect(folder); | ||
12935 | if (r == MAIL_NO_ERROR) { | ||
12936 | struct mailmessage_list * msg_list; | ||
12937 | |||
12938 | mailfolder_get_messages_list(folder, &msg_list); | ||
12939 | |||
12940 | /* do the things */ | ||
12941 | |||
12942 | mailmessage_list_free(msg_list); | ||
12943 | |||
12944 | mailfolder_disconnect(folder); | ||
12945 | } | ||
12946 | |||
12947 | mailstorage_disconnect(storage); | ||
12948 | } | ||
12949 | |||
12950 | mailstorage_free(storage); | ||
12951 | } | ||
12952 | </programlisting> | ||
12953 | </example> | ||
12954 | </sect2> | ||
12955 | |||
12956 | </sect1> | ||
12957 | |||
12958 | <!-- Message --> | ||
12959 | <sect1> | ||
12960 | <title>Message</title> | ||
12961 | |||
12962 | <sect2 id="mailmessage-driver"> | ||
12963 | <title>Message driver</title> | ||
12964 | |||
12965 | <programlisting role="C"> | ||
12966 | #include <libetpan/libetpan.h> | ||
12967 | |||
12968 | struct mailmessage_driver { | ||
12969 | char * msg_name; | ||
12970 | |||
12971 | int (* msg_initialize)(mailmessage * msg_info); | ||
12972 | |||
12973 | void (* msg_uninitialize)(mailmessage * msg_info); | ||
12974 | |||
12975 | void (* msg_flush)(mailmessage * msg_info); | ||
12976 | |||
12977 | void (* msg_check)(mailmessage * msg_info); | ||
12978 | |||
12979 | void (* msg_fetch_result_free)(mailmessage * msg_info, | ||
12980 | char * msg); | ||
12981 | |||
12982 | int (* msg_fetch)(mailmessage * msg_info, | ||
12983 | char ** result, | ||
12984 | size_t * result_len); | ||
12985 | |||
12986 | int (* msg_fetch_header)(mailmessage * msg_info, | ||
12987 | char ** result, | ||
12988 | size_t * result_len); | ||
12989 | |||
12990 | int (* msg_fetch_body)(mailmessage * msg_info, | ||
12991 | char ** result, size_t * result_len); | ||
12992 | |||
12993 | int (* msg_fetch_size)(mailmessage * msg_info, | ||
12994 | size_t * result); | ||
12995 | |||
12996 | int (* msg_get_bodystructure)(mailmessage * msg_info, | ||
12997 | struct mailmime ** result); | ||
12998 | |||
12999 | int (* msg_fetch_section)(mailmessage * msg_info, | ||
13000 | struct mailmime * mime, | ||
13001 | char ** result, size_t * result_len); | ||
13002 | |||
13003 | int (* msg_fetch_section_header)(mailmessage * msg_info, | ||
13004 | struct mailmime * mime, | ||
13005 | char ** result, | ||
13006 | size_t * result_len); | ||
13007 | |||
13008 | int (* msg_fetch_section_mime)(mailmessage * msg_info, | ||
13009 | struct mailmime * mime, | ||
13010 | char ** result, | ||
13011 | size_t * result_len); | ||
13012 | |||
13013 | int (* msg_fetch_section_body)(mailmessage * msg_info, | ||
13014 | struct mailmime * mime, | ||
13015 | char ** result, | ||
13016 | size_t * result_len); | ||
13017 | |||
13018 | int (* msg_fetch_envelope)(mailmessage * msg_info, | ||
13019 | struct mailimf_fields ** result); | ||
13020 | |||
13021 | int (* msg_get_flags)(mailmessage * msg_info, | ||
13022 | struct mail_flags ** result); | ||
13023 | }; | ||
13024 | </programlisting> | ||
13025 | |||
13026 | <itemizedlist> | ||
13027 | <listitem> | ||
13028 | <para> | ||
13029 | <command>msg_name</command> is the name of the driver. | ||
13030 | </para> | ||
13031 | </listitem> | ||
13032 | |||
13033 | <listitem> | ||
13034 | <para> | ||
13035 | <command>msg_initialize()</command> will initialize the | ||
13036 | internal message state (field | ||
13037 | <command>msg_data</command> of | ||
13038 | <command>mailmessage</command> structure (see <xref | ||
13039 | linkend="mailmessage">). | ||
13040 | </para> | ||
13041 | </listitem> | ||
13042 | |||
13043 | <listitem> | ||
13044 | <para> | ||
13045 | <command>msg_uninitialize()</command> will free the | ||
13046 | internal message state. | ||
13047 | </para> | ||
13048 | </listitem> | ||
13049 | |||
13050 | <listitem> | ||
13051 | <para> | ||
13052 | <command>msg_flush()</command> will release memory used | ||
13053 | by the MIME structure of the message. | ||
13054 | </para> | ||
13055 | </listitem> | ||
13056 | |||
13057 | <listitem> | ||
13058 | <para> | ||
13059 | <command>msg_check()</command> will store the flags of | ||
13060 | the message into the session, so that the message can be | ||
13061 | released without the flags are lost. | ||
13062 | </para> | ||
13063 | </listitem> | ||
13064 | |||
13065 | <listitem> | ||
13066 | <para> | ||
13067 | <command>msg_fetch_result_free()</command> will free a | ||
13068 | string returned by any fetch_XXX() function. | ||
13069 | </para> | ||
13070 | </listitem> | ||
13071 | |||
13072 | <listitem> | ||
13073 | <para> | ||
13074 | <command>msg_fetch()</command> will fetch a message. | ||
13075 | </para> | ||
13076 | </listitem> | ||
13077 | |||
13078 | <listitem> | ||
13079 | <para> | ||
13080 | <command>msg_fetch_header()</command> will fetch the | ||
13081 | header fields of a message. | ||
13082 | </para> | ||
13083 | </listitem> | ||
13084 | |||
13085 | <listitem> | ||
13086 | <para> | ||
13087 | <command>msg_fetch_body()</command> will fetch a message | ||
13088 | without its main header. | ||
13089 | </para> | ||
13090 | </listitem> | ||
13091 | |||
13092 | <listitem> | ||
13093 | <para> | ||
13094 | <command>msg_fetch_size()</command> will return the size | ||
13095 | of a message. | ||
13096 | </para> | ||
13097 | </listitem> | ||
13098 | |||
13099 | <listitem> | ||
13100 | <para> | ||
13101 | <command>msg_get_bodystructure</command> will retrieve | ||
13102 | the MIME structure of the message. The returned | ||
13103 | structure must <emphasis>NOT</emphasis> be freed. | ||
13104 | </para> | ||
13105 | </listitem> | ||
13106 | |||
13107 | <listitem> | ||
13108 | <para> | ||
13109 | <command>msg_fetch_section()</command> will fetch the | ||
13110 | content of the section of the message. | ||
13111 | </para> | ||
13112 | </listitem> | ||
13113 | |||
13114 | <listitem> | ||
13115 | <para> | ||
13116 | <command>msg_fetch_section_header()</command> will fetch | ||
13117 | the header of a section of the message if the content of | ||
13118 | the section is a message. | ||
13119 | </para> | ||
13120 | </listitem> | ||
13121 | |||
13122 | <listitem> | ||
13123 | <para> | ||
13124 | <command>msg_fetch_section_mime()</command> will fetch | ||
13125 | the MIME header of a section of the message. | ||
13126 | </para> | ||
13127 | </listitem> | ||
13128 | |||
13129 | <listitem> | ||
13130 | <para> | ||
13131 | <command>msg_fetch_section_body()</command> will fetch | ||
13132 | the body of a section (without the headers) of the | ||
13133 | message if the content of the section is a message. | ||
13134 | </para> | ||
13135 | </listitem> | ||
13136 | |||
13137 | <listitem> | ||
13138 | <para> | ||
13139 | <command>msg_fetch_envelope()</command> will return | ||
13140 | a given number of parsed header fields. | ||
13141 | </para> | ||
13142 | </listitem> | ||
13143 | |||
13144 | <listitem> | ||
13145 | <para> | ||
13146 | <command>msg_get_flags()</command> will return the | ||
13147 | flags of the message. | ||
13148 | The returned structure must <emphasis>NOT</emphasis> be | ||
13149 | freed. | ||
13150 | </para> | ||
13151 | </listitem> | ||
13152 | </itemizedlist> | ||
13153 | </sect2> | ||
13154 | |||
13155 | <sect2 id="mailmessage"> | ||
13156 | <title>Message</title> | ||
13157 | |||
13158 | <programlisting role="C"> | ||
13159 | #include <libetpan/libetpan.h> | ||
13160 | |||
13161 | struct mailmessage { | ||
13162 | mailsession * msg_session; | ||
13163 | mailmessage_driver * msg_driver; | ||
13164 | uint32_t msg_index; | ||
13165 | char * msg_uid; | ||
13166 | |||
13167 | size_t msg_size; | ||
13168 | struct mailimf_fields * msg_fields; | ||
13169 | struct mail_flags * msg_flags; | ||
13170 | |||
13171 | int msg_resolved; | ||
13172 | struct mailimf_single_fields msg_single_fields; | ||
13173 | struct mailmime * msg_mime; | ||
13174 | |||
13175 | /* internal data */ | ||
13176 | |||
13177 | int msg_cached; | ||
13178 | void * msg_data; | ||
13179 | |||
13180 | /* | ||
13181 | msg_folder field : | ||
13182 | used to reference the mailfolder, this is a workaround due | ||
13183 | to the problem with initial conception, where folder notion | ||
13184 | did not exist. | ||
13185 | */ | ||
13186 | void * msg_folder; | ||
13187 | /* user data */ | ||
13188 | void * msg_user_data; | ||
13189 | }; | ||
13190 | </programlisting> | ||
13191 | |||
13192 | <itemizedlist> | ||
13193 | <listitem> | ||
13194 | <para> | ||
13195 | <command>msg_session</command> is the session related to | ||
13196 | the message | ||
13197 | (see <xref linkend="mailsession">). | ||
13198 | </para> | ||
13199 | </listitem> | ||
13200 | |||
13201 | <listitem> | ||
13202 | <para> | ||
13203 | <command>msg_driver</command> is the driver used for the | ||
13204 | message | ||
13205 | (see <xref linkend="mailmessage-driver">). | ||
13206 | </para> | ||
13207 | </listitem> | ||
13208 | |||
13209 | <listitem> | ||
13210 | <para> | ||
13211 | <command>msg_index</command> is an index to indentify | ||
13212 | the message. | ||
13213 | </para> | ||
13214 | </listitem> | ||
13215 | |||
13216 | <listitem> | ||
13217 | <para> | ||
13218 | <command>msg_uid</command> is the unique identifier of | ||
13219 | the message, valid accross disconnections. | ||
13220 | </para> | ||
13221 | </listitem> | ||
13222 | |||
13223 | <listitem> | ||
13224 | <para> | ||
13225 | <command>msg_size</command> is the size of the message. | ||
13226 | </para> | ||
13227 | </listitem> | ||
13228 | |||
13229 | <listitem> | ||
13230 | <para> | ||
13231 | <command>msg_fields</command> is the list of parsed | ||
13232 | header fields of the message. This can be | ||
13233 | <command>NULL</command> | ||
13234 | (see <xref linkend="mailimf-fields">). | ||
13235 | </para> | ||
13236 | </listitem> | ||
13237 | |||
13238 | <listitem> | ||
13239 | <para> | ||
13240 | <command>msg_flags</command> is the flags of the | ||
13241 | message. This can be <command>NULL</command> | ||
13242 | (see <xref linkend="mail-flags">). | ||
13243 | </para> | ||
13244 | </listitem> | ||
13245 | |||
13246 | <listitem> | ||
13247 | <para> | ||
13248 | <command>msg_resolved</command> will tell if the field | ||
13249 | <command>msg_single_fields</command> has been initialized. | ||
13250 | </para> | ||
13251 | </listitem> | ||
13252 | |||
13253 | <listitem> | ||
13254 | <para> | ||
13255 | <command>msg_single_fields</command> will be filled | ||
13256 | using <command>msg_fields</command> | ||
13257 | (see <xref linkend="mailimf-single-fields">). | ||
13258 | </para> | ||
13259 | </listitem> | ||
13260 | |||
13261 | <listitem> | ||
13262 | <para> | ||
13263 | <command>msg_mime</command> is the MIME structure of the | ||
13264 | message. It is intialized at least when | ||
13265 | <command>get_bodystructure()</command> is called once. | ||
13266 | </para> | ||
13267 | </listitem> | ||
13268 | |||
13269 | <listitem> | ||
13270 | <para> | ||
13271 | <command>msg_cached</command> is 1 when the message was | ||
13272 | cached. This is used internally. | ||
13273 | </para> | ||
13274 | </listitem> | ||
13275 | |||
13276 | <listitem> | ||
13277 | <para> | ||
13278 | <command>msg_data</command> is the internal state of the | ||
13279 | message. The content depends on the driver. | ||
13280 | </para> | ||
13281 | </listitem> | ||
13282 | |||
13283 | <listitem> | ||
13284 | <para> | ||
13285 | <command>msg_folder</command> is used to reference the | ||
13286 | mailfolder, this is a workaround due to the problem with | ||
13287 | initial conception, where folder notion did not exist. | ||
13288 | </para> | ||
13289 | </listitem> | ||
13290 | |||
13291 | <listitem> | ||
13292 | <para> | ||
13293 | <command>msg_user_data</command> is a field for free | ||
13294 | use. The user can store any data in that field. | ||
13295 | </para> | ||
13296 | </listitem> | ||
13297 | </itemizedlist> | ||
13298 | </sect2> | ||
13299 | |||
13300 | <sect2 id="mailmessage-new"> | ||
13301 | <title>mailmessage_new</title> | ||
13302 | |||
13303 | <programlisting role="C"> | ||
13304 | #include <libetpan/libetpan.h> | ||
13305 | |||
13306 | mailmessage * mailmessage_new(void); | ||
13307 | |||
13308 | void mailmessage_free(mailmessage * info); | ||
13309 | </programlisting> | ||
13310 | |||
13311 | <para> | ||
13312 | <command>mailmessage_new()</command> will create a new | ||
13313 | message (without driver). This is used internally by | ||
13314 | drivers. | ||
13315 | </para> | ||
13316 | |||
13317 | <para> | ||
13318 | <command>mailmessage_free()</command> will free the memory | ||
13319 | used by the given message. | ||
13320 | </para> | ||
13321 | </sect2> | ||
13322 | |||
13323 | <sect2 id="mailmessage-init"> | ||
13324 | <title>mailmessage_init</title> | ||
13325 | |||
13326 | <programlisting role="C"> | ||
13327 | #include <libetpan/libetpan.h> | ||
13328 | |||
13329 | int mailmessage_init(mailmessage * msg_info, | ||
13330 | mailsession * session, | ||
13331 | mailmessage_driver * driver, | ||
13332 | uint32_t index, size_t size); | ||
13333 | </programlisting> | ||
13334 | |||
13335 | <para> | ||
13336 | <command>mailmessage_init()</command> will initialize a | ||
13337 | message with a driver. | ||
13338 | </para> | ||
13339 | |||
13340 | <itemizedlist> | ||
13341 | <listitem> | ||
13342 | <para> | ||
13343 | <command>msg_info</command> is the message to initialize | ||
13344 | (see <xref linkend="mailmessage">). | ||
13345 | </para> | ||
13346 | </listitem> | ||
13347 | |||
13348 | <listitem> | ||
13349 | <para> | ||
13350 | <command>session</command> is the session related to the | ||
13351 | message | ||
13352 | (see <xref linkend="mailsession">). | ||
13353 | </para> | ||
13354 | </listitem> | ||
13355 | |||
13356 | <listitem> | ||
13357 | <para> | ||
13358 | <command>driver</command> is the driver to use for the | ||
13359 | message | ||
13360 | (see <xref linkend="mailmessage-driver">). | ||
13361 | </para> | ||
13362 | </listitem> | ||
13363 | |||
13364 | <listitem> | ||
13365 | <para> | ||
13366 | <command>index</command> is the index of the message. | ||
13367 | </para> | ||
13368 | </listitem> | ||
13369 | |||
13370 | <listitem> | ||
13371 | <para> | ||
13372 | <command>size</command> is the size of the message. | ||
13373 | </para> | ||
13374 | </listitem> | ||
13375 | </itemizedlist> | ||
13376 | </sect2> | ||
13377 | |||
13378 | <sect2 id="mailmessage-flush"> | ||
13379 | <title>mailmessage_flush</title> | ||
13380 | |||
13381 | <programlisting role="C"> | ||
13382 | #include <libetpan/libetpan.h> | ||
13383 | |||
13384 | int mailmessage_flush(mailmessage * info); | ||
13385 | </programlisting> | ||
13386 | |||
13387 | <para> | ||
13388 | This function will release the memory used by the MIME | ||
13389 | structure of the message. | ||
13390 | </para> | ||
13391 | </sect2> | ||
13392 | |||
13393 | <sect2 id="mailmessage-check"> | ||
13394 | <title>mailmessage_check</title> | ||
13395 | |||
13396 | <programlisting role="C"> | ||
13397 | #include <libetpan/libetpan.h> | ||
13398 | |||
13399 | int mailmessage_check(mailmessage * info); | ||
13400 | </programlisting> | ||
13401 | |||
13402 | <para> | ||
13403 | After you set some flags, if you want to notify them to the | ||
13404 | session before destroying the message, you can use this function. | ||
13405 | </para> | ||
13406 | </sect2> | ||
13407 | |||
13408 | <sect2 id="mailmessage-fetch-result-free"> | ||
13409 | <title>mailmessage_fetch_result_free</title> | ||
13410 | |||
13411 | <programlisting role="C"> | ||
13412 | #include <libetpan/libetpan.h> | ||
13413 | |||
13414 | int mailmessage_fetch_result_free(mailmessage * msg_info, | ||
13415 | char * msg); | ||
13416 | </programlisting> | ||
13417 | |||
13418 | <para> | ||
13419 | This function will free a string returned by any | ||
13420 | mailmessage_fetch_XXX() function. | ||
13421 | </para> | ||
13422 | </sect2> | ||
13423 | |||
13424 | <sect2 id="mailmessage-fetch"> | ||
13425 | <title>mailmessage_fetch</title> | ||
13426 | |||
13427 | <programlisting role="C"> | ||
13428 | #include <libetpan/libetpan.h> | ||
13429 | |||
13430 | int mailmessage_fetch(mailmessage * msg_info, | ||
13431 | char ** result, | ||
13432 | size_t * result_len); | ||
13433 | </programlisting> | ||
13434 | |||
13435 | <para> | ||
13436 | This function returns the content of the message (headers | ||
13437 | and text). | ||
13438 | </para> | ||
13439 | </sect2> | ||
13440 | |||
13441 | <sect2 id="mailmessage-fetch-header"> | ||
13442 | <title>mailmessage_fetch_header</title> | ||
13443 | |||
13444 | <programlisting role="C"> | ||
13445 | #include <libetpan/libetpan.h> | ||
13446 | |||
13447 | int mailmessage_fetch_header(mailmessage * msg_info, | ||
13448 | char ** result, | ||
13449 | size_t * result_len); | ||
13450 | </programlisting> | ||
13451 | |||
13452 | <para> | ||
13453 | This function returns the header of the message as a string. | ||
13454 | </para> | ||
13455 | |||
13456 | </sect2> | ||
13457 | |||
13458 | <sect2 id="mailmessage-fetch-body"> | ||
13459 | <title>mailmessage_fetch_body</title> | ||
13460 | |||
13461 | <programlisting role="C"> | ||
13462 | #include <libetpan/libetpan.h> | ||
13463 | |||
13464 | int mailmessage_fetch_body(mailmessage * msg_info, | ||
13465 | char ** result, size_t * result_len); | ||
13466 | </programlisting> | ||
13467 | |||
13468 | <para> | ||
13469 | This function returns the content of the message (without | ||
13470 | headers). | ||
13471 | </para> | ||
13472 | </sect2> | ||
13473 | |||
13474 | <sect2 id="mailmessage-fetch-size"> | ||
13475 | <title>mailmessage_fetch_size</title> | ||
13476 | |||
13477 | <programlisting role="C"> | ||
13478 | #include <libetpan/libetpan.h> | ||
13479 | |||
13480 | int mailmessage_fetch_size(mailmessage * msg_info, | ||
13481 | size_t * result); | ||
13482 | </programlisting> | ||
13483 | |||
13484 | <para> | ||
13485 | This function returns the size of the message content. | ||
13486 | </para> | ||
13487 | </sect2> | ||
13488 | |||
13489 | <sect2 id="mailmessage-get-bodystructure"> | ||
13490 | <title>mailmessage_get_bodystructure</title> | ||
13491 | |||
13492 | <programlisting role="C"> | ||
13493 | #include <libetpan/libetpan.h> | ||
13494 | |||
13495 | int mailmessage_get_bodystructure(mailmessage * msg_info, | ||
13496 | struct mailmime ** result); | ||
13497 | </programlisting> | ||
13498 | |||
13499 | <para> | ||
13500 | This functions returns the MIME structure of the message. | ||
13501 | The returned information <emphasis>MUST</emphasis> not be | ||
13502 | freed by hand. It is freed by | ||
13503 | <command>mailmessage_flush()</command> or | ||
13504 | <command>mailmessage_free()</command> | ||
13505 | (see <xref linkend="mailmime">). | ||
13506 | </para> | ||
13507 | </sect2> | ||
13508 | |||
13509 | <sect2 id="mailmessage-fetch-section"> | ||
13510 | <title>mailmessage_fetch_section</title> | ||
13511 | |||
13512 | <programlisting role="C"> | ||
13513 | #include <libetpan/libetpan.h> | ||
13514 | |||
13515 | int mailmessage_fetch_section(mailmessage * msg_info, | ||
13516 | struct mailmime * mime, | ||
13517 | char ** result, size_t * result_len); | ||
13518 | </programlisting> | ||
13519 | |||
13520 | <para> | ||
13521 | This function returns the content of a MIME part. | ||
13522 | </para> | ||
13523 | </sect2> | ||
13524 | |||
13525 | <sect2 id="mailmessage-fetch-section-header"> | ||
13526 | <title>mailmessage_fetch_section_header</title> | ||
13527 | |||
13528 | <programlisting role="C"> | ||
13529 | #include <libetpan/libetpan.h> | ||
13530 | |||
13531 | int mailmessage_fetch_section_header(mailmessage * msg_info, | ||
13532 | struct mailmime * mime, | ||
13533 | char ** result, | ||
13534 | size_t * result_len); | ||
13535 | </programlisting> | ||
13536 | |||
13537 | <para> | ||
13538 | This function returns the header of the message contained | ||
13539 | in the given MIME part. | ||
13540 | </para> | ||
13541 | </sect2> | ||
13542 | |||
13543 | <sect2 id="mailmessage-fetch-section-mime"> | ||
13544 | <title>mailmessage_fetch_section_mime</title> | ||
13545 | |||
13546 | <programlisting role="C"> | ||
13547 | #include <libetpan/libetpan.h> | ||
13548 | |||
13549 | int mailmessage_fetch_section_mime(mailmessage * msg_info, | ||
13550 | struct mailmime * mime, | ||
13551 | char ** result, | ||
13552 | size_t * result_len); | ||
13553 | </programlisting> | ||
13554 | |||
13555 | <para> | ||
13556 | This function returns the MIME header of the given MIME | ||
13557 | part. | ||
13558 | </para> | ||
13559 | </sect2> | ||
13560 | |||
13561 | <sect2 id="mailmessage-fetch-section-body"> | ||
13562 | <title>mailmessage_fetch_section_body</title> | ||
13563 | |||
13564 | <programlisting role="C"> | ||
13565 | #include <libetpan/libetpan.h> | ||
13566 | |||
13567 | int mailmessage_fetch_section_body(mailmessage * msg_info, | ||
13568 | struct mailmime * mime, | ||
13569 | char ** result, | ||
13570 | size_t * result_len); | ||
13571 | </programlisting> | ||
13572 | |||
13573 | <para> | ||
13574 | This function returns the text part of the message contained | ||
13575 | in the given MIME part. | ||
13576 | </para> | ||
13577 | </sect2> | ||
13578 | |||
13579 | <sect2 id="mailmessage-fetch-envelope"> | ||
13580 | <title>mailmessage_fetch_envelope</title> | ||
13581 | |||
13582 | <programlisting role="C"> | ||
13583 | #include <libetpan/libetpan.h> | ||
13584 | |||
13585 | int mailmessage_fetch_envelope(mailmessage * msg_info, | ||
13586 | struct mailimf_fields ** result); | ||
13587 | </programlisting> | ||
13588 | </sect2> | ||
13589 | |||
13590 | <sect2 id="mailmessage-get-flags"> | ||
13591 | <title>mailmessage_get_flags</title> | ||
13592 | |||
13593 | <programlisting role="C"> | ||
13594 | #include <libetpan/libetpan.h> | ||
13595 | |||
13596 | int mailmessage_get_flags(mailmessage * msg_info, | ||
13597 | struct mail_flags ** result); | ||
13598 | </programlisting> | ||
13599 | |||
13600 | <para> | ||
13601 | This function returns the flags related to the message. | ||
13602 | The returned information MUST not be freed by hand. It is freed by | ||
13603 | <command>mailmessage_free()</command>. | ||
13604 | </para> | ||
13605 | </sect2> | ||
13606 | |||
13607 | <sect2 id="mailmessage-resolve-single-fields"> | ||
13608 | <title>mailmessage_resolve_single_fields</title> | ||
13609 | |||
13610 | <programlisting role="C"> | ||
13611 | #include <libetpan/libetpan.h> | ||
13612 | |||
13613 | void mailmessage_resolve_single_fields(mailmessage * msg_info); | ||
13614 | </programlisting> | ||
13615 | |||
13616 | <para> | ||
13617 | This function will use the fields information to fill | ||
13618 | the single_fields structure in the mailmessage structure. | ||
13619 | </para> | ||
13620 | </sect2> | ||
13621 | |||
13622 | <sect2 id="mailmessage-list"> | ||
13623 | <title>Message list</title> | ||
13624 | |||
13625 | <programlisting role="C"> | ||
13626 | #include <libetpan/libetpan.h> | ||
13627 | |||
13628 | struct mailmessage_list { | ||
13629 | carray * msg_tab; /* elements are (mailmessage *) */ | ||
13630 | }; | ||
13631 | |||
13632 | struct mailmessage_list * mailmessage_list_new(carray * msg_tab); | ||
13633 | |||
13634 | void mailmessage_list_free(struct mailmessage_list * env_list); | ||
13635 | </programlisting> | ||
13636 | |||
13637 | <para> | ||
13638 | This is a list of messages. | ||
13639 | </para> | ||
13640 | |||
13641 | <para> | ||
13642 | <command>msg_tab</command> is an array containing the | ||
13643 | messages (see linkend="carray"). | ||
13644 | </para> | ||
13645 | |||
13646 | <para> | ||
13647 | <command>mailmessage_list_new()</command> will initialize a | ||
13648 | list of messages, using a given array of messages. | ||
13649 | </para> | ||
13650 | |||
13651 | <para> | ||
13652 | <command>mailmessage_list_free()</command> will free the | ||
13653 | memory used by the list of messages. This will also free the | ||
13654 | messages. | ||
13655 | </para> | ||
13656 | </sect2> | ||
13657 | |||
13658 | <sect2 id="mailmessage-tree"> | ||
13659 | <title>Message tree</title> | ||
13660 | |||
13661 | <programlisting role="C"> | ||
13662 | #include <libetpan/libetpan.h> | ||
13663 | |||
13664 | struct mailmessage_tree { | ||
13665 | struct mailmessage_tree * node_parent; | ||
13666 | char * node_msgid; | ||
13667 | time_t node_date; | ||
13668 | mailmessage * node_msg; | ||
13669 | carray * node_children; /* array of (struct mailmessage_tree *) */ | ||
13670 | |||
13671 | /* private, used for threading */ | ||
13672 | int node_is_reply; | ||
13673 | char * node_base_subject; | ||
13674 | }; | ||
13675 | |||
13676 | |||
13677 | struct mailmessage_tree * | ||
13678 | mailmessage_tree_new(char * node_msgid, time_t node_date, | ||
13679 | mailmessage * node_msg); | ||
13680 | |||
13681 | void mailmessage_tree_free(struct mailmessage_tree * tree); | ||
13682 | |||
13683 | void mailmessage_tree_free_recursive(struct mailmessage_tree * tree); | ||
13684 | </programlisting> | ||
13685 | |||
13686 | <para> | ||
13687 | This is a node of a tree of messages. | ||
13688 | </para> | ||
13689 | |||
13690 | <itemizedlist> | ||
13691 | <listitem> | ||
13692 | <para> | ||
13693 | <command>node_parent</command> is the parent of this | ||
13694 | node. | ||
13695 | </para> | ||
13696 | </listitem> | ||
13697 | |||
13698 | <listitem> | ||
13699 | <para> | ||
13700 | <command>node_msgid</command> is the content of the | ||
13701 | field <command>Message-ID</command> of the message. | ||
13702 | </para> | ||
13703 | </listitem> | ||
13704 | |||
13705 | <listitem> | ||
13706 | <para> | ||
13707 | <command>node_date</command> is the date in UNIX | ||
13708 | format. | ||
13709 | </para> | ||
13710 | </listitem> | ||
13711 | |||
13712 | <listitem> | ||
13713 | <para> | ||
13714 | <command>node_msg</command> is the message of the node. | ||
13715 | The message should have the <command>msg_fields</command> | ||
13716 | field initialized. | ||
13717 | </para> | ||
13718 | </listitem> | ||
13719 | |||
13720 | <listitem> | ||
13721 | <para> | ||
13722 | <command>node_children</command> is the list of | ||
13723 | children of this node. | ||
13724 | </para> | ||
13725 | </listitem> | ||
13726 | |||
13727 | <listitem> | ||
13728 | <para> | ||
13729 | <command>node_is_reply</command> is set to 1 if the | ||
13730 | message is a reply. | ||
13731 | </para> | ||
13732 | </listitem> | ||
13733 | |||
13734 | <listitem> | ||
13735 | <para> | ||
13736 | <command>node_base_subject</command> is the base subject | ||
13737 | of the message (base subject is defined in definition of | ||
13738 | IMAP thread draft). | ||
13739 | </para> | ||
13740 | </listitem> | ||
13741 | </itemizedlist> | ||
13742 | |||
13743 | <para> | ||
13744 | <command>mailmessage_tree_new()</command> will initialize a | ||
13745 | message node. | ||
13746 | </para> | ||
13747 | |||
13748 | <para> | ||
13749 | <command>mailmessage_tree_free()</command> will release | ||
13750 | memory used by the node. This will <emphasis>NOT</emphasis> | ||
13751 | free the message. | ||
13752 | </para> | ||
13753 | </sect2> | ||
13754 | |||
13755 | <sect2 id="mail-flags"> | ||
13756 | <title>Message flags</title> | ||
13757 | |||
13758 | <programlisting role="C"> | ||
13759 | #include <libetpan/libetpan.h> | ||
13760 | |||
13761 | enum { | ||
13762 | MAIL_FLAG_NEW = 1 << 0, | ||
13763 | MAIL_FLAG_SEEN = 1 << 1, | ||
13764 | MAIL_FLAG_FLAGGED = 1 << 2, | ||
13765 | MAIL_FLAG_DELETED = 1 << 3, | ||
13766 | MAIL_FLAG_ANSWERED = 1 << 4, | ||
13767 | MAIL_FLAG_FORWARDED = 1 << 5, | ||
13768 | MAIL_FLAG_CANCELLED = 1 << 6, | ||
13769 | }; | ||
13770 | |||
13771 | struct mail_flags { | ||
13772 | uint32_t fl_flags; | ||
13773 | clist * fl_extension; /* elements are (char *) */ | ||
13774 | }; | ||
13775 | |||
13776 | struct mail_flags * mail_flags_new(uint32_t fl_flags, clist * fl_ext); | ||
13777 | |||
13778 | void mail_flags_free(struct mail_flags * flags); | ||
13779 | |||
13780 | int mail_flags_add_extension(struct mail_flags * flags, | ||
13781 | char * ext_flag); | ||
13782 | |||
13783 | int mail_flags_remove_extension(struct mail_flags * flags, | ||
13784 | char * ext_flag); | ||
13785 | |||
13786 | int mail_flags_has_extension(struct mail_flags * flags, | ||
13787 | char * ext_flag); | ||
13788 | </programlisting> | ||
13789 | |||
13790 | <para> | ||
13791 | This is the structure containing the message flags. | ||
13792 | </para> | ||
13793 | |||
13794 | <itemizedlist> | ||
13795 | <listitem> | ||
13796 | <para> | ||
13797 | <command>fl_flags</command> will contain the standards | ||
13798 | flags. The value will be a combinaison (with or binary | ||
13799 | operation) of <command>MAIL_FLAG_XXX</command> values. | ||
13800 | </para> | ||
13801 | </listitem> | ||
13802 | <listitem> | ||
13803 | <para> | ||
13804 | <command>fl_extension</command> will be a list (see | ||
13805 | <xref linkend="clist">) of strings representing the | ||
13806 | non-standard flags. | ||
13807 | </para> | ||
13808 | </listitem> | ||
13809 | </itemizedlist> | ||
13810 | </sect2> | ||
13811 | |||
13812 | <sect2> | ||
13813 | <title>Example</title> | ||
13814 | |||
13815 | <example> | ||
13816 | <title>use of message</title> | ||
13817 | |||
13818 | <programlisting role="C"> | ||
13819 | #include <libetpan/libetpan.h> | ||
13820 | |||
13821 | #define DEST_CHARSET "iso-8859-1" | ||
13822 | |||
13823 | enum { | ||
13824 | NO_ERROR, | ||
13825 | ERROR_FILE, | ||
13826 | ERROR_MEMORY, | ||
13827 | ERROR_INVAL, | ||
13828 | ERROR_FETCH, | ||
13829 | }; | ||
13830 | |||
13831 | /* returns TRUE is given MIME part is a text part */ | ||
13832 | |||
13833 | int etpan_mime_is_text(struct mailmime * build_info) | ||
13834 | { | ||
13835 | if (build_info->mm_type == MAILMIME_SINGLE) { | ||
13836 | if (build_info->mm_content_type != NULL) { | ||
13837 | if (build_info->mm_content_type->ct_type->tp_type == | ||
13838 | MAILMIME_TYPE_DISCRETE_TYPE) { | ||
13839 | if (build_info->mm_content_type->ct_type->tp_data.tp_discrete_type->dt_type == | ||
13840 | MAILMIME_DISCRETE_TYPE_TEXT) | ||
13841 | return 1; | ||
13842 | } | ||
13843 | } | ||
13844 | else | ||
13845 | return 1; | ||
13846 | } | ||
13847 | |||
13848 | return 0; | ||
13849 | } | ||
13850 | |||
13851 | |||
13852 | /* display content type */ | ||
13853 | |||
13854 | int show_part_info(FILE * f, | ||
13855 | struct mailmime_single_fields * mime_fields, | ||
13856 | struct mailmime_content * content) | ||
13857 | { | ||
13858 | char * description; | ||
13859 | char * filename; | ||
13860 | int col; | ||
13861 | int r; | ||
13862 | |||
13863 | description = mime_fields->fld_description; | ||
13864 | filename = mime_fields->fld_disposition_filename; | ||
13865 | |||
13866 | col = 0; | ||
13867 | |||
13868 | r = fprintf(f, " [ Part "); | ||
13869 | if (r < 0) | ||
13870 | goto err; | ||
13871 | |||
13872 | if (content != NULL) { | ||
13873 | r = mailmime_content_type_write(f, &col, content); | ||
13874 | if (r != MAILIMF_NO_ERROR) | ||
13875 | goto err; | ||
13876 | } | ||
13877 | |||
13878 | if (filename != NULL) { | ||
13879 | r = fprintf(f, " (%s)", filename); | ||
13880 | if (r < 0) | ||
13881 | goto err; | ||
13882 | } | ||
13883 | |||
13884 | if (description != NULL) { | ||
13885 | r = fprintf(f, " : %s", description); | ||
13886 | if (r < 0) | ||
13887 | goto err; | ||
13888 | } | ||
13889 | |||
13890 | r = fprintf(f, " ]\n\n"); | ||
13891 | if (r < 0) | ||
13892 | goto err; | ||
13893 | |||
13894 | return NO_ERROR; | ||
13895 | |||
13896 | err: | ||
13897 | return ERROR_FILE; | ||
13898 | } | ||
13899 | |||
13900 | /* fetch message and decode if it is base64 or quoted-printable */ | ||
13901 | |||
13902 | int etpan_fetch_message(mailmessage * msg_info, | ||
13903 | struct mailmime * mime_part, | ||
13904 | struct mailmime_single_fields * fields, | ||
13905 | char ** result, size_t * result_len) | ||
13906 | { | ||
13907 | char * data; | ||
13908 | size_t len; | ||
13909 | int r; | ||
13910 | int encoding; | ||
13911 | char * decoded; | ||
13912 | size_t decoded_len; | ||
13913 | size_t cur_token; | ||
13914 | int res; | ||
13915 | int encoded; | ||
13916 | |||
13917 | encoded = 0; | ||
13918 | |||
13919 | r = mailmessage_fetch_section(msg_info, | ||
13920 | mime_part, &data, &len); | ||
13921 | if (r != MAIL_NO_ERROR) { | ||
13922 | res = ERROR_FETCH; | ||
13923 | goto err; | ||
13924 | } | ||
13925 | |||
13926 | encoded = 1; | ||
13927 | |||
13928 | /* decode message */ | ||
13929 | |||
13930 | if (encoded) { | ||
13931 | if (fields->fld_encoding != NULL) | ||
13932 | encoding = fields->fld_encoding->enc_type; | ||
13933 | else | ||
13934 | encoding = MAILMIME_MECHANISM_8BIT; | ||
13935 | } | ||
13936 | else { | ||
13937 | encoding = MAILMIME_MECHANISM_8BIT; | ||
13938 | } | ||
13939 | |||
13940 | cur_token = 0; | ||
13941 | r = mailmime_part_parse(data, len, &cur_token, | ||
13942 | encoding, &decoded, &decoded_len); | ||
13943 | if (r != MAILIMF_NO_ERROR) { | ||
13944 | res = ERROR_FETCH; | ||
13945 | goto free; | ||
13946 | } | ||
13947 | |||
13948 | mailmessage_fetch_result_free(msg_info, data); | ||
13949 | |||
13950 | * result = decoded; | ||
13951 | * result_len = decoded_len; | ||
13952 | |||
13953 | return NO_ERROR; | ||
13954 | |||
13955 | free: | ||
13956 | mailmessage_fetch_result_free(msg_info, data); | ||
13957 | err: | ||
13958 | return res; | ||
13959 | } | ||
13960 | |||
13961 | /* fetch fields */ | ||
13962 | |||
13963 | struct mailimf_fields * fetch_fields(mailmessage * msg_info, | ||
13964 | struct mailmime * mime) | ||
13965 | { | ||
13966 | char * data; | ||
13967 | size_t len; | ||
13968 | int r; | ||
13969 | size_t cur_token; | ||
13970 | struct mailimf_fields * fields; | ||
13971 | |||
13972 | r = mailmessage_fetch_section_header(msg_info, mime, | ||
13973 | &data, &len); | ||
13974 | if (r != MAIL_NO_ERROR) | ||
13975 | return NULL; | ||
13976 | |||
13977 | cur_token = 0; | ||
13978 | r = mailimf_envelopes_fields_parse(data, len, | ||
13979 | &cur_token, &fields); | ||
13980 | if (r != MAILIMF_NO_ERROR) { | ||
13981 | mailmessage_fetch_result_free(msg_info, data); | ||
13982 | return NULL; | ||
13983 | } | ||
13984 | |||
13985 | mailmessage_fetch_result_free(msg_info, data); | ||
13986 | |||
13987 | return fields; | ||
13988 | } | ||
13989 | |||
13990 | /* render message */ | ||
13991 | |||
13992 | static int etpan_render_mime(FILE * f, mailmessage * msg_info, | ||
13993 | struct mailmime * mime) | ||
13994 | { | ||
13995 | int r; | ||
13996 | clistiter * cur; | ||
13997 | int col; | ||
13998 | int text; | ||
13999 | int show; | ||
14000 | struct mailmime_single_fields fields; | ||
14001 | int res; | ||
14002 | |||
14003 | mailmime_single_fields_init(&fields, mime->mm_mime_fields, | ||
14004 | mime->mm_content_type); | ||
14005 | |||
14006 | text = etpan_mime_is_text(mime); | ||
14007 | |||
14008 | r = show_part_info(f, &fields, mime->mm_content_type); | ||
14009 | if (r != NO_ERROR) { | ||
14010 | res = r; | ||
14011 | goto err; | ||
14012 | } | ||
14013 | |||
14014 | switch(mime->mm_type) { | ||
14015 | case MAILMIME_SINGLE: | ||
14016 | show = 0; | ||
14017 | if (text) | ||
14018 | show = 1; | ||
14019 | |||
14020 | if (show) { | ||
14021 | char * data; | ||
14022 | size_t len; | ||
14023 | char * converted; | ||
14024 | size_t converted_len; | ||
14025 | char * source_charset; | ||
14026 | size_t write_len; | ||
14027 | |||
14028 | /* viewable part */ | ||
14029 | |||
14030 | r = etpan_fetch_message(msg_info, mime, | ||
14031 | &fields, &data, &len); | ||
14032 | if (r != NO_ERROR) { | ||
14033 | res = r; | ||
14034 | goto err; | ||
14035 | } | ||
14036 | |||
14037 | source_charset = fields.fld_content_charset; | ||
14038 | if (source_charset == NULL) | ||
14039 | source_charset = DEST_CHARSET; | ||
14040 | |||
14041 | r = charconv_buffer(source_charset, DEST_CHARSET, | ||
14042 | data, len, &converted, &converted_len); | ||
14043 | if (r != MAIL_CHARCONV_NO_ERROR) { | ||
14044 | |||
14045 | r = fprintf(f, "[ error converting charset from %s to %s ]\n", | ||
14046 | source_charset, DEST_CHARSET); | ||
14047 | if (r < 0) { | ||
14048 | res = ERROR_FILE; | ||
14049 | goto err; | ||
14050 | } | ||
14051 | |||
14052 | write_len = fwrite(data, 1, len, f); | ||
14053 | if (write_len != len) { | ||
14054 | mailmime_decoded_part_free(data); | ||
14055 | res = r; | ||
14056 | goto err; | ||
14057 | } | ||
14058 | } | ||
14059 | else { | ||
14060 | write_len = fwrite(converted, 1, converted_len, f); | ||
14061 | if (write_len != len) { | ||
14062 | charconv_buffer_free(converted); | ||
14063 | mailmime_decoded_part_free(data); | ||
14064 | res = r; | ||
14065 | goto err; | ||
14066 | } | ||
14067 | |||
14068 | charconv_buffer_free(converted); | ||
14069 | } | ||
14070 | |||
14071 | write_len = fwrite("\r\n\r\n", 1, 4, f); | ||
14072 | if (write_len < 4) { | ||
14073 | mailmime_decoded_part_free(data); | ||
14074 | res = ERROR_FILE; | ||
14075 | goto err; | ||
14076 | } | ||
14077 | |||
14078 | mailmime_decoded_part_free(data); | ||
14079 | } | ||
14080 | else { | ||
14081 | /* not viewable part */ | ||
14082 | |||
14083 | r = fprintf(f, " (not shown)\n\n"); | ||
14084 | if (r < 0) { | ||
14085 | res = ERROR_FILE; | ||
14086 | goto err; | ||
14087 | } | ||
14088 | } | ||
14089 | |||
14090 | break; | ||
14091 | |||
14092 | case MAILMIME_MULTIPLE: | ||
14093 | |||
14094 | if (strcasecmp(mime->mm_content_type->ct_subtype, | ||
14095 | "alternative") == 0) { | ||
14096 | struct mailmime * prefered_body; | ||
14097 | int prefered_score; | ||
14098 | |||
14099 | /* case of multiple/alternative */ | ||
14100 | |||
14101 | /* | ||
14102 | we choose the better part, | ||
14103 | alternative preference : | ||
14104 | |||
14105 | text/plain => score 3 | ||
14106 | text/xxx => score 2 | ||
14107 | other => score 1 | ||
14108 | */ | ||
14109 | |||
14110 | prefered_body = NULL; | ||
14111 | prefered_score = 0; | ||
14112 | |||
14113 | for(cur = clist_begin(mime->mm_data.mm_multipart.mm_mp_list) ; | ||
14114 | cur != NULL ; cur = clist_next(cur)) { | ||
14115 | struct mailmime * submime; | ||
14116 | int score; | ||
14117 | |||
14118 | score = 1; | ||
14119 | submime = clist_content(cur); | ||
14120 | if (etpan_mime_is_text(submime)) | ||
14121 | score = 2; | ||
14122 | |||
14123 | if (submime->mm_content_type != NULL) { | ||
14124 | if (strcasecmp(submime->mm_content_type->ct_subtype, | ||
14125 | "plain") == 0) | ||
14126 | score = 3; | ||
14127 | } | ||
14128 | |||
14129 | if (score > prefered_score) { | ||
14130 | prefered_score = score; | ||
14131 | prefered_body = submime; | ||
14132 | } | ||
14133 | } | ||
14134 | |||
14135 | if (prefered_body != NULL) { | ||
14136 | r = etpan_render_mime(f, msg_info, prefered_body); | ||
14137 | if (r != NO_ERROR) { | ||
14138 | res = r; | ||
14139 | goto err; | ||
14140 | } | ||
14141 | } | ||
14142 | } | ||
14143 | else { | ||
14144 | for(cur = clist_begin(mime->mm_data.mm_multipart.mm_mp_list) ; | ||
14145 | cur != NULL ; cur = clist_next(cur)) { | ||
14146 | |||
14147 | r = etpan_render_mime(f, msg_info, clist_content(cur)); | ||
14148 | if (r != NO_ERROR) { | ||
14149 | res = r; | ||
14150 | goto err; | ||
14151 | } | ||
14152 | } | ||
14153 | } | ||
14154 | |||
14155 | break; | ||
14156 | |||
14157 | case MAILMIME_MESSAGE: | ||
14158 | |||
14159 | if (mime->mm_data.mm_message.mm_fields != NULL) { | ||
14160 | struct mailimf_fields * fields; | ||
14161 | |||
14162 | if (msg_info != NULL) { | ||
14163 | fields = fetch_fields(msg_info, mime); | ||
14164 | if (fields == NULL) { | ||
14165 | res = ERROR_FETCH; | ||
14166 | goto err; | ||
14167 | } | ||
14168 | |||
14169 | col = 0; | ||
14170 | r = mailimf_fields_write(f, &col, fields); | ||
14171 | if (r != NO_ERROR) { | ||
14172 | mailimf_fields_free(fields); | ||
14173 | res = r; | ||
14174 | goto err; | ||
14175 | } | ||
14176 | |||
14177 | mailimf_fields_free(fields); | ||
14178 | } | ||
14179 | else { | ||
14180 | col = 0; | ||
14181 | r = fields_write(f, &col, mime->mm_data.mm_message.mm_fields); | ||
14182 | if (r != NO_ERROR) { | ||
14183 | res = r; | ||
14184 | goto err; | ||
14185 | } | ||
14186 | } | ||
14187 | |||
14188 | r = fprintf(f, "\r\n"); | ||
14189 | if (r < 0) { | ||
14190 | res = ERROR_FILE; | ||
14191 | goto err; | ||
14192 | } | ||
14193 | } | ||
14194 | |||
14195 | if (mime->mm_data.mm_message.mm_msg_mime != NULL) { | ||
14196 | r = etpan_render_mime(f, msg_info, | ||
14197 | mime->mm_data.mm_message.mm_msg_mime); | ||
14198 | if (r != NO_ERROR) { | ||
14199 | res = r; | ||
14200 | goto err; | ||
14201 | } | ||
14202 | } | ||
14203 | |||
14204 | break; | ||
14205 | } | ||
14206 | |||
14207 | return NO_ERROR; | ||
14208 | |||
14209 | err: | ||
14210 | return res; | ||
14211 | } | ||
14212 | |||
14213 | |||
14214 | |||
14215 | int main(void) | ||
14216 | { | ||
14217 | struct mailstorage * storage; | ||
14218 | int r; | ||
14219 | |||
14220 | storage = mailstorage_new(NULL); | ||
14221 | |||
14222 | imap_mailstorage_init(storage, "imap.my-servers.org", 0, | ||
14223 | NULL, CONNECTION_TYPE_TRY_STARTTLS, IMAP_AUTH_TYPE_PLAIN, | ||
14224 | "my-login", "my-password", 1, "/home/login/.libetpan/cache"); | ||
14225 | |||
14226 | r = mailstorage_connect(storage); | ||
14227 | if (r == MAIL_NO_ERROR) { | ||
14228 | struct mailfolder * folder; | ||
14229 | |||
14230 | folder = mailfolder_new(storage, "INBOX", NULL); | ||
14231 | |||
14232 | r = mailfolder_connect(folder); | ||
14233 | if (r == MAIL_NO_ERROR) { | ||
14234 | struct mailmessage_list * msg_list; | ||
14235 | mailmessage * msg; | ||
14236 | |||
14237 | mailfolder_get_messages_list(folder, &msg_list); | ||
14238 | |||
14239 | if (carray_count(msg_list->msg_tab) > 0) { | ||
14240 | struct mailmime * mime; | ||
14241 | |||
14242 | msg = carray_get(msg_list->msg_tab, 0); | ||
14243 | |||
14244 | mailmessage_get_bodystructure(msg, &mime); | ||
14245 | |||
14246 | recursive_fetch(msg, mime); | ||
14247 | |||
14248 | /* do the things */ | ||
14249 | |||
14250 | mailmessage_flush(msg); | ||
14251 | } | ||
14252 | mailmessage_list_free(msg_list); | ||
14253 | |||
14254 | mailfolder_disconnect(folder); | ||
14255 | } | ||
14256 | |||
14257 | mailstorage_disconnect(storage); | ||
14258 | } | ||
14259 | |||
14260 | mailstorage_free(storage); | ||
14261 | } | ||
14262 | </programlisting> | ||
14263 | </example> | ||
14264 | </sect2> | ||
14265 | </sect1> | ||
14266 | |||
14267 | <!-- Session --> | ||
14268 | <sect1> | ||
14269 | <title>Session</title> | ||
14270 | |||
14271 | <sect2 id="mailsession-driver"> | ||
14272 | <title>Session driver</title> | ||
14273 | |||
14274 | <programlisting role="C"> | ||
14275 | #include <libetpan/libetpan.h> | ||
14276 | |||
14277 | struct mailsession_driver { | ||
14278 | char * sess_name; | ||
14279 | |||
14280 | int (* sess_initialize)(mailsession * session); | ||
14281 | void (* sess_uninitialize)(mailsession * session); | ||
14282 | |||
14283 | int (* sess_parameters)(mailsession * session, | ||
14284 | int id, void * value); | ||
14285 | |||
14286 | int (* sess_connect_stream)(mailsession * session, mailstream * s); | ||
14287 | int (* sess_connect_path)(mailsession * session, char * path); | ||
14288 | |||
14289 | int (* sess_starttls)(mailsession * session); | ||
14290 | |||
14291 | int (* sess_login)(mailsession * session, char * userid, char * password); | ||
14292 | int (* sess_logout)(mailsession * session); | ||
14293 | int (* sess_noop)(mailsession * session); | ||
14294 | |||
14295 | /* folders operations */ | ||
14296 | |||
14297 | int (* sess_build_folder_name)(mailsession * session, char * mb, | ||
14298 | char * name, char ** result); | ||
14299 | |||
14300 | int (* sess_create_folder)(mailsession * session, char * mb); | ||
14301 | int (* sess_delete_folder)(mailsession * session, char * mb); | ||
14302 | int (* sess_rename_folder)(mailsession * session, char * mb, | ||
14303 | char * new_name); | ||
14304 | int (* sess_check_folder)(mailsession * session); | ||
14305 | int (* sess_examine_folder)(mailsession * session, char * mb); | ||
14306 | int (* sess_select_folder)(mailsession * session, char * mb); | ||
14307 | int (* sess_expunge_folder)(mailsession * session); | ||
14308 | int (* sess_status_folder)(mailsession * session, char * mb, | ||
14309 | uint32_t * result_num, uint32_t * result_recent, | ||
14310 | uint32_t * result_unseen); | ||
14311 | int (* sess_messages_number)(mailsession * session, char * mb, | ||
14312 | uint32_t * result); | ||
14313 | int (* sess_recent_number)(mailsession * session, char * mb, | ||
14314 | uint32_t * result); | ||
14315 | int (* sess_unseen_number)(mailsession * session, char * mb, | ||
14316 | uint32_t * result); | ||
14317 | |||
14318 | int (* sess_list_folders)(mailsession * session, char * mb, | ||
14319 | struct mail_list ** result); | ||
14320 | int (* sess_lsub_folders)(mailsession * session, char * mb, | ||
14321 | struct mail_list ** result); | ||
14322 | |||
14323 | int (* sess_subscribe_folder)(mailsession * session, char * mb); | ||
14324 | int (* sess_unsubscribe_folder)(mailsession * session, char * mb); | ||
14325 | |||
14326 | /* messages operations */ | ||
14327 | |||
14328 | int (* sess_append_message)(mailsession * session, | ||
14329 | char * message, size_t size); | ||
14330 | int (* sess_copy_message)(mailsession * session, | ||
14331 | uint32_t num, char * mb); | ||
14332 | int (* sess_move_message)(mailsession * session, | ||
14333 | uint32_t num, char * mb); | ||
14334 | |||
14335 | int (* sess_get_message)(mailsession * session, | ||
14336 | uint32_t num, mailmessage ** result); | ||
14337 | |||
14338 | int (* sess_get_message_by_uid)(mailsession * session, | ||
14339 | const char * uid, mailmessage ** result); | ||
14340 | |||
14341 | int (* sess_get_messages_list)(mailsession * session, | ||
14342 | struct mailmessage_list ** result); | ||
14343 | int (* sess_get_envelopes_list)(mailsession * session, | ||
14344 | struct mailmessage_list * env_list); | ||
14345 | int (* sess_remove_message)(mailsession * session, uint32_t num); | ||
14346 | }; | ||
14347 | </programlisting> | ||
14348 | |||
14349 | <para> | ||
14350 | This is a driver for a session. | ||
14351 | </para> | ||
14352 | |||
14353 | <itemizedlist> | ||
14354 | <listitem> | ||
14355 | <para> | ||
14356 | <command>sess_name</command> is the name of the driver. | ||
14357 | </para> | ||
14358 | </listitem> | ||
14359 | |||
14360 | <listitem> | ||
14361 | <para> | ||
14362 | <command>sess_initialize()</command> is the function | ||
14363 | that will initializes a data structure (field | ||
14364 | <command>sess_data</command> in the session) specific to | ||
14365 | the driver. | ||
14366 | The field data (field <command>sess_data</command> in | ||
14367 | the session) is the state of the session, | ||
14368 | the internal data structure used by the driver. | ||
14369 | It is called when creating the | ||
14370 | <command>mailsession</command> structure with | ||
14371 | <command>mailsession_new()</command>. | ||
14372 | </para> | ||
14373 | </listitem> | ||
14374 | |||
14375 | <listitem> | ||
14376 | <para> | ||
14377 | <command>sess_uninitialize()</command> frees the structure | ||
14378 | created with <command>sess_initialize()</command> | ||
14379 | </para> | ||
14380 | </listitem> | ||
14381 | |||
14382 | <listitem> | ||
14383 | <para> | ||
14384 | <command>sess_parameters()</command> implements | ||
14385 | functions specific to the given mail access. | ||
14386 | </para> | ||
14387 | </listitem> | ||
14388 | |||
14389 | <listitem> | ||
14390 | <para> | ||
14391 | <command>sess_connect_stream()</command> connects a | ||
14392 | stream to the session. | ||
14393 | </para> | ||
14394 | </listitem> | ||
14395 | |||
14396 | <listitem> | ||
14397 | <para> | ||
14398 | <command>sess_connect_path()</command> notify a main | ||
14399 | path to the session. | ||
14400 | </para> | ||
14401 | </listitem> | ||
14402 | |||
14403 | <listitem> | ||
14404 | <para> | ||
14405 | <command>sess_starttls()</command> changes the current | ||
14406 | stream to a TLS stream | ||
14407 | (see <xref linkend="mailstream-ssl">). | ||
14408 | </para> | ||
14409 | </listitem> | ||
14410 | |||
14411 | <listitem> | ||
14412 | <para> | ||
14413 | <command>sess_login()</command> notifies the user and | ||
14414 | the password to authenticate to the session. | ||
14415 | </para> | ||
14416 | </listitem> | ||
14417 | |||
14418 | <listitem> | ||
14419 | <para> | ||
14420 | <command>sess_logout()</command> exits the session and | ||
14421 | closes the stream. | ||
14422 | </para> | ||
14423 | </listitem> | ||
14424 | |||
14425 | <listitem> | ||
14426 | <para> | ||
14427 | <command>sess_noop()</command> does no operation on the | ||
14428 | session, but it can be used to poll for the status of | ||
14429 | the connection. | ||
14430 | </para> | ||
14431 | </listitem> | ||
14432 | |||
14433 | <listitem> | ||
14434 | <para> | ||
14435 | <command>sess_build_folder_name()</command> will return an | ||
14436 | allocated string with that contains the complete path of | ||
14437 | the folder to create. | ||
14438 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14439 | </para> | ||
14440 | </listitem> | ||
14441 | |||
14442 | <listitem> | ||
14443 | <para> | ||
14444 | <command>sess_create_folder()</command> creates the | ||
14445 | folder that corresponds to the given name. | ||
14446 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14447 | </para> | ||
14448 | </listitem> | ||
14449 | |||
14450 | <listitem> | ||
14451 | <para> | ||
14452 | <command>sess_delete_folder()</command> deletes the folder | ||
14453 | that corresponds to the given name. | ||
14454 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14455 | </para> | ||
14456 | </listitem> | ||
14457 | |||
14458 | <listitem> | ||
14459 | <para> | ||
14460 | <command>sess_rename_folder()</command> change the name | ||
14461 | of the folder. | ||
14462 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14463 | </para> | ||
14464 | </listitem> | ||
14465 | |||
14466 | <listitem> | ||
14467 | <para> | ||
14468 | <command>sess_check_folder()</command> makes a | ||
14469 | checkpoint of the session. | ||
14470 | </para> | ||
14471 | </listitem> | ||
14472 | |||
14473 | <listitem> | ||
14474 | <para> | ||
14475 | <command>sess_examine_folder()</command> selects a mailbox as | ||
14476 | readonly. | ||
14477 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14478 | </para> | ||
14479 | </listitem> | ||
14480 | |||
14481 | <listitem> | ||
14482 | <para> | ||
14483 | <command>sess_select_folder()</command> selects a mailbox. | ||
14484 | </para> | ||
14485 | </listitem> | ||
14486 | |||
14487 | <listitem> | ||
14488 | <para> | ||
14489 | <command>sess_expunge_folder()</command> deletes all | ||
14490 | messages marked \Deleted. | ||
14491 | </para> | ||
14492 | </listitem> | ||
14493 | |||
14494 | <listitem> | ||
14495 | <para> | ||
14496 | <command>sess_status_folder()</command> queries the | ||
14497 | status of the folder (number of messages, number of | ||
14498 | recent messages, number of unseen messages). | ||
14499 | </para> | ||
14500 | </listitem> | ||
14501 | |||
14502 | <listitem> | ||
14503 | <para> | ||
14504 | <command>sess_messages_number()</command> queries the | ||
14505 | number of messages in the folder. | ||
14506 | </para> | ||
14507 | </listitem> | ||
14508 | |||
14509 | <listitem> | ||
14510 | <para> | ||
14511 | <command>sess_recent_number()</command> queries the | ||
14512 | number of recent messages in the folder. | ||
14513 | </para> | ||
14514 | </listitem> | ||
14515 | |||
14516 | <listitem> | ||
14517 | <para> | ||
14518 | <command>sess_unseen_number()</command> queries the number of | ||
14519 | unseen messages in the folder. | ||
14520 | </para> | ||
14521 | </listitem> | ||
14522 | |||
14523 | <listitem> | ||
14524 | <para> | ||
14525 | <command>sess_list_folders()</command> returns the list of | ||
14526 | all sub-mailboxes of the given mailbox. | ||
14527 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14528 | </para> | ||
14529 | </listitem> | ||
14530 | |||
14531 | <listitem> | ||
14532 | <para> | ||
14533 | <command>sess_lsub_folders()</command> returns the list of | ||
14534 | subscribed sub-mailboxes of the given mailbox. | ||
14535 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14536 | </para> | ||
14537 | </listitem> | ||
14538 | |||
14539 | <listitem> | ||
14540 | <para> | ||
14541 | <command>sess_subscribe_folder()</command> subscribes to | ||
14542 | the given mailbox. | ||
14543 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14544 | </para> | ||
14545 | </listitem> | ||
14546 | |||
14547 | <listitem> | ||
14548 | <para> | ||
14549 | <command>sess_unsubscribe_folder()</command> unsubscribes to | ||
14550 | the given mailbox. | ||
14551 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14552 | </para> | ||
14553 | </listitem> | ||
14554 | |||
14555 | <listitem> | ||
14556 | <para> | ||
14557 | <command>sess_append_message()</command> adds a RFC 2822 | ||
14558 | message to the current given mailbox. | ||
14559 | </para> | ||
14560 | </listitem> | ||
14561 | |||
14562 | <listitem> | ||
14563 | <para> | ||
14564 | <command>sess_copy_message()</command> copies a message | ||
14565 | whose number is given to a given mailbox. The mailbox | ||
14566 | must be accessible from the same session. | ||
14567 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14568 | </listitem> | ||
14569 | |||
14570 | <listitem> | ||
14571 | <para> | ||
14572 | <command>sess_move_message()</command> moves a message whose | ||
14573 | number is given to | ||
14574 | a given mailbox. The mailbox must be accessible from the | ||
14575 | same session. | ||
14576 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14577 | </para> | ||
14578 | </listitem> | ||
14579 | |||
14580 | <listitem> | ||
14581 | <para> | ||
14582 | <command>sess_get_messages_list()</command> returns the list | ||
14583 | of message numbers | ||
14584 | of the current mailbox | ||
14585 | (see <xref linkend="mailmessage-list">). | ||
14586 | </para> | ||
14587 | </listitem> | ||
14588 | |||
14589 | <listitem> | ||
14590 | <para> | ||
14591 | <command>sess_get_envelopes_list()</command> fills the parsed | ||
14592 | fields in the <command>mailmessage</command> structures | ||
14593 | (see <xref linkend="mailmessage">) | ||
14594 | of the <command>mailmessage_list</command> | ||
14595 | (see <xref linkend="mailmessage-list">). | ||
14596 | </para> | ||
14597 | </listitem> | ||
14598 | |||
14599 | <listitem> | ||
14600 | <para> | ||
14601 | <command>sess_remove_message()</command> removes the given | ||
14602 | message from the mailbox. | ||
14603 | The message is permanently deleted. | ||
14604 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14605 | </para> | ||
14606 | </listitem> | ||
14607 | |||
14608 | <listitem> | ||
14609 | <para> | ||
14610 | <command>sess_get_message()</command> returns a | ||
14611 | mailmessage structure | ||
14612 | (see <xref linkend="mailmessage">) | ||
14613 | that corresponds | ||
14614 | to the given message number. | ||
14615 | <emphasis>Use of this method is deprecated</emphasis>. | ||
14616 | </para> | ||
14617 | </listitem> | ||
14618 | |||
14619 | <listitem> | ||
14620 | <para> | ||
14621 | <command>sess_get_message_by_uid()</command> returns a | ||
14622 | mailmessage structure | ||
14623 | (see <xref linkend="mailmessage">) | ||
14624 | that corresponds | ||
14625 | to the given message unique identifier. | ||
14626 | </para> | ||
14627 | </listitem> | ||
14628 | </itemizedlist> | ||
14629 | |||
14630 | <para> | ||
14631 | mandatory functions are the following : | ||
14632 | </para> | ||
14633 | |||
14634 | <itemizedlist> | ||
14635 | <listitem> | ||
14636 | <para> | ||
14637 | <command>sess_connect_stream()</command> or | ||
14638 | <command>connect_path()</command> | ||
14639 | </para> | ||
14640 | </listitem> | ||
14641 | |||
14642 | <listitem> | ||
14643 | <para> | ||
14644 | <command>sess_logout()</command> | ||
14645 | </para> | ||
14646 | </listitem> | ||
14647 | |||
14648 | <listitem> | ||
14649 | <para> | ||
14650 | <command>sess_get_messages_list()</command> | ||
14651 | </para> | ||
14652 | </listitem> | ||
14653 | |||
14654 | <listitem> | ||
14655 | <para> | ||
14656 | <command>sess_get_envelopes_list()</command> | ||
14657 | </para> | ||
14658 | </listitem> | ||
14659 | </itemizedlist> | ||
14660 | |||
14661 | <para> | ||
14662 | we advise you to implement these functions : | ||
14663 | </para> | ||
14664 | |||
14665 | <itemizedlist> | ||
14666 | <listitem> | ||
14667 | <para> | ||
14668 | <command>sess_select_folder()</command> (in case a session | ||
14669 | can access several folders). | ||
14670 | </para> | ||
14671 | </listitem> | ||
14672 | |||
14673 | <listitem> | ||
14674 | <para> | ||
14675 | <command>sess_noop()</command> (to check if the server is | ||
14676 | responding) | ||
14677 | </para> | ||
14678 | </listitem> | ||
14679 | |||
14680 | <listitem> | ||
14681 | <para> | ||
14682 | <command>sess_check_folder()</command> (to make a checkpoint | ||
14683 | of the session) | ||
14684 | </para> | ||
14685 | </listitem> | ||
14686 | |||
14687 | <listitem> | ||
14688 | <para> | ||
14689 | <command>sess_status_folder()</command>, | ||
14690 | <command>sess_messages_number()</command>, | ||
14691 | <command>sess_recent_number()</command>, | ||
14692 | <command>sess_unseen_number()</command> | ||
14693 | (to get stat of the folder) | ||
14694 | </para> | ||
14695 | </listitem> | ||
14696 | |||
14697 | <listitem> | ||
14698 | <para> | ||
14699 | <command>sess_append_message()</command> (but can't be done | ||
14700 | in the case of POP3 at least). | ||
14701 | </para> | ||
14702 | </listitem> | ||
14703 | |||
14704 | <listitem> | ||
14705 | <para> | ||
14706 | <command>sess_login()</command> in a case of an | ||
14707 | authenticated driver. | ||
14708 | </para> | ||
14709 | </listitem> | ||
14710 | |||
14711 | <listitem> | ||
14712 | <para> | ||
14713 | <command>sess_starttls()</command> in a case of a stream | ||
14714 | driver, if the procotol supports STARTTLS. | ||
14715 | </para> | ||
14716 | </listitem> | ||
14717 | |||
14718 | <listitem> | ||
14719 | <para> | ||
14720 | <command>sess_get_message_by_uid()</command> so that the | ||
14721 | application can remember the messages | ||
14722 | by UID and build its own list of messages. | ||
14723 | </para> | ||
14724 | </listitem> | ||
14725 | |||
14726 | <listitem> | ||
14727 | <para> | ||
14728 | Everything that is specific to the driver will be | ||
14729 | implemented in <command>sess_parameters()</command>. | ||
14730 | </para> | ||
14731 | </listitem> | ||
14732 | </itemizedlist> | ||
14733 | </sect2> | ||
14734 | |||
14735 | <sect2 id="mailsession"> | ||
14736 | <title>Session</title> | ||
14737 | |||
14738 | <programlisting role="C"> | ||
14739 | #include <libetpan/libetpan.h> | ||
14740 | |||
14741 | struct mailsession { | ||
14742 | void * sess_data; | ||
14743 | mailsession_driver * sess_driver; | ||
14744 | }; | ||
14745 | |||
14746 | mailsession * mailsession_new(mailsession_driver * sess_driver); | ||
14747 | |||
14748 | void mailsession_free(mailsession * session); | ||
14749 | </programlisting> | ||
14750 | |||
14751 | <para> | ||
14752 | This is a session. This is an abstraction used to access the | ||
14753 | storage, using the network or the filesystem. | ||
14754 | </para> | ||
14755 | |||
14756 | <itemizedlist> | ||
14757 | <listitem> | ||
14758 | <para> | ||
14759 | <command>sess_data</command> is the state of the | ||
14760 | session. This is specific to the driver. | ||
14761 | </para> | ||
14762 | </listitem> | ||
14763 | <listitem> | ||
14764 | <para> | ||
14765 | <command>sess_driver</command> is the driver of the | ||
14766 | session. | ||
14767 | </para> | ||
14768 | </listitem> | ||
14769 | </itemizedlist> | ||
14770 | |||
14771 | <para> | ||
14772 | <command>mailsession_new()</command> will create a new session | ||
14773 | using the given driver (<command>sess_driver</command>). | ||
14774 | </para> | ||
14775 | |||
14776 | <para> | ||
14777 | <command>mailsession_free()</command> will release the memory | ||
14778 | used by the session. | ||
14779 | </para> | ||
14780 | </sect2> | ||
14781 | |||
14782 | <sect2> | ||
14783 | <title>mailsession_parameters</title> | ||
14784 | |||
14785 | <programlisting> | ||
14786 | #include <libetpan/libetpan.h> | ||
14787 | |||
14788 | int mailsession_parameters(mailsession * session, | ||
14789 | int id, void * value); | ||
14790 | </programlisting> | ||
14791 | |||
14792 | <para> | ||
14793 | This function make calls specific to the driver | ||
14794 | </para> | ||
14795 | </sect2> | ||
14796 | |||
14797 | <sect2> | ||
14798 | <title>mailsession_connect_stream</title> | ||
14799 | |||
14800 | <programlisting> | ||
14801 | #include <libetpan/libetpan.h> | ||
14802 | |||
14803 | int mailsession_connect_stream(mailsession * session, mailstream * s); | ||
14804 | </programlisting> | ||
14805 | |||
14806 | <para> | ||
14807 | There are drivers of two kinds : stream drivers (driver that | ||
14808 | connects to servers through TCP or other means of connection) | ||
14809 | and file drivers (driver that are based on filesystem) | ||
14810 | |||
14811 | This function can only be used by stream drivers and | ||
14812 | this connects a stream to the session | ||
14813 | </para> | ||
14814 | </sect2> | ||
14815 | |||
14816 | <sect2> | ||
14817 | <title>mailsession_connect_path</title> | ||
14818 | |||
14819 | <programlisting> | ||
14820 | #include <libetpan/libetpan.h> | ||
14821 | |||
14822 | int mailsession_connect_path(mailsession * session, char * path); | ||
14823 | </programlisting> | ||
14824 | |||
14825 | <para> | ||
14826 | This function can only be used by file drivers and | ||
14827 | selects the main path of the session. | ||
14828 | </para> | ||
14829 | </sect2> | ||
14830 | |||
14831 | <sect2> | ||
14832 | <title>mailsession_starttls</title> | ||
14833 | |||
14834 | <programlisting> | ||
14835 | #include <libetpan/libetpan.h> | ||
14836 | |||
14837 | int mailsession_starttls(mailsession * session); | ||
14838 | </programlisting> | ||
14839 | |||
14840 | <para> | ||
14841 | This switches the current connection to TLS (secure layer). | ||
14842 | This will only work with stream drivers. | ||
14843 | </para> | ||
14844 | </sect2> | ||
14845 | |||
14846 | <sect2> | ||
14847 | <title>mailsession_login</title> | ||
14848 | |||
14849 | <programlisting> | ||
14850 | #include <libetpan/libetpan.h> | ||
14851 | |||
14852 | int mailsession_login(mailsession * session, | ||
14853 | char * userid, char * password); | ||
14854 | </programlisting> | ||
14855 | |||
14856 | <para> | ||
14857 | This notifies the login and the password to authenticate | ||
14858 | to the session. | ||
14859 | </para> | ||
14860 | </sect2> | ||
14861 | |||
14862 | <sect2> | ||
14863 | <title>mailsession_logout</title> | ||
14864 | |||
14865 | <programlisting> | ||
14866 | #include <libetpan/libetpan.h> | ||
14867 | |||
14868 | int mailsession_logout(mailsession * session); | ||
14869 | </programlisting> | ||
14870 | |||
14871 | <para> | ||
14872 | This function disconnects the session and closes the stream. | ||
14873 | </para> | ||
14874 | </sect2> | ||
14875 | |||
14876 | <sect2> | ||
14877 | <title>mailsession_noop</title> | ||
14878 | |||
14879 | <programlisting> | ||
14880 | #include <libetpan/libetpan.h> | ||
14881 | |||
14882 | int mailsession_noop(mailsession * session); | ||
14883 | </programlisting> | ||
14884 | |||
14885 | <para> | ||
14886 | This function does no operation on the session, but it can be | ||
14887 | used to poll for the status of the connection. | ||
14888 | </para> | ||
14889 | </sect2> | ||
14890 | |||
14891 | <sect2> | ||
14892 | <title>mailsession_check_folder</title> | ||
14893 | |||
14894 | <programlisting> | ||
14895 | #include <libetpan/libetpan.h> | ||
14896 | |||
14897 | int mailsession_check_folder(mailsession * session); | ||
14898 | </programlisting> | ||
14899 | |||
14900 | <para> | ||
14901 | This function makes a checkpoint of the session. | ||
14902 | </para> | ||
14903 | </sect2> | ||
14904 | |||
14905 | <sect2> | ||
14906 | <title>mailsession_select_folder</title> | ||
14907 | |||
14908 | <programlisting> | ||
14909 | #include <libetpan/libetpan.h> | ||
14910 | |||
14911 | int mailsession_select_folder(mailsession * session, char * mb); | ||
14912 | </programlisting> | ||
14913 | |||
14914 | <para> | ||
14915 | This function selects a mailbox. | ||
14916 | </para> | ||
14917 | </sect2> | ||
14918 | |||
14919 | <sect2> | ||
14920 | <title>mailsession_expunge_folder</title> | ||
14921 | |||
14922 | <programlisting> | ||
14923 | #include <libetpan/libetpan.h> | ||
14924 | |||
14925 | int mailsession_expunge_folder(mailsession * session); | ||
14926 | </programlisting> | ||
14927 | |||
14928 | <para> | ||
14929 | This function deletes all messages marked for deletion. | ||
14930 | </para> | ||
14931 | </sect2> | ||
14932 | |||
14933 | <sect2> | ||
14934 | <title>mailsession_status_folder</title> | ||
14935 | |||
14936 | <programlisting> | ||
14937 | #include <libetpan/libetpan.h> | ||
14938 | |||
14939 | int mailsession_status_folder(mailsession * session, char * mb, | ||
14940 | uint32_t * result_messages, uint32_t * result_recent, | ||
14941 | uint32_t * result_unseen); | ||
14942 | </programlisting> | ||
14943 | |||
14944 | <para> | ||
14945 | This function queries the status of the folder | ||
14946 | (number of messages, number of recent messages, number of | ||
14947 | unseen messages). | ||
14948 | </para> | ||
14949 | </sect2> | ||
14950 | |||
14951 | <sect2> | ||
14952 | <title>mailsession_messages_number</title> | ||
14953 | |||
14954 | <programlisting> | ||
14955 | #include <libetpan/libetpan.h> | ||
14956 | |||
14957 | int mailsession_messages_number(mailsession * session, char * mb, | ||
14958 | uint32_t * result); | ||
14959 | </programlisting> | ||
14960 | |||
14961 | <para> | ||
14962 | This function queries the number of messages in the folder. | ||
14963 | </para> | ||
14964 | </sect2> | ||
14965 | |||
14966 | <sect2> | ||
14967 | <title>mailsession_recent_number</title> | ||
14968 | |||
14969 | <programlisting> | ||
14970 | #include <libetpan/libetpan.h> | ||
14971 | |||
14972 | int mailsession_recent_number(mailsession * session, | ||
14973 | char * mb, uint32_t * result); | ||
14974 | </programlisting> | ||
14975 | |||
14976 | <para> | ||
14977 | This function queries the number of recent messages in the | ||
14978 | folder. | ||
14979 | </para> | ||
14980 | </sect2> | ||
14981 | |||
14982 | <sect2> | ||
14983 | <title>mailsession_unseen_number</title> | ||
14984 | |||
14985 | <programlisting> | ||
14986 | #include <libetpan/libetpan.h> | ||
14987 | |||
14988 | int mailsession_unseen_number(mailsession * session, char * mb, | ||
14989 | uint32_t * result); | ||
14990 | </programlisting> | ||
14991 | |||
14992 | <para> | ||
14993 | This function queries the number of unseen messages in the | ||
14994 | folder. | ||
14995 | </para> | ||
14996 | </sect2> | ||
14997 | |||
14998 | <sect2> | ||
14999 | <title>mailsession_append_message</title> | ||
15000 | |||
15001 | <programlisting> | ||
15002 | #include <libetpan/libetpan.h> | ||
15003 | |||
15004 | int mailsession_append_message(mailsession * session, | ||
15005 | char * message, size_t size); | ||
15006 | </programlisting> | ||
15007 | |||
15008 | <para> | ||
15009 | This adds a RFC 2822 message to the current mailbox. | ||
15010 | </para> | ||
15011 | </sect2> | ||
15012 | |||
15013 | <sect2> | ||
15014 | <title>mailsession_get_messages_list</title> | ||
15015 | |||
15016 | <programlisting> | ||
15017 | #include <libetpan/libetpan.h> | ||
15018 | |||
15019 | int mailsession_get_messages_list(mailsession * session, | ||
15020 | struct mailmessage_list ** result); | ||
15021 | </programlisting> | ||
15022 | |||
15023 | <para> | ||
15024 | This function returns the list of messages | ||
15025 | of the current mailbox. | ||
15026 | </para> | ||
15027 | </sect2> | ||
15028 | |||
15029 | <sect2> | ||
15030 | <title>mailsession_get_envelopes_list</title> | ||
15031 | |||
15032 | <programlisting> | ||
15033 | #include <libetpan/libetpan.h> | ||
15034 | |||
15035 | int mailsession_get_envelopes_list(mailsession * session, | ||
15036 | struct mailmessage_list * result); | ||
15037 | </programlisting> | ||
15038 | |||
15039 | <para> | ||
15040 | This function fills the parsed fields in the | ||
15041 | <command>mailmessage</command> structures | ||
15042 | (see <xref linkend="mailmessage">) | ||
15043 | of the mailmessage_list | ||
15044 | (see <xref linkend="mailmessage-list">). | ||
15045 | </para> | ||
15046 | </sect2> | ||
15047 | |||
15048 | <sect2> | ||
15049 | <title>mailsession_get_message</title> | ||
15050 | |||
15051 | <programlisting> | ||
15052 | #include <libetpan/libetpan.h> | ||
15053 | |||
15054 | int mailsession_get_message(mailsession * session, | ||
15055 | uint32_t num, mailmessage ** result); | ||
15056 | </programlisting> | ||
15057 | |||
15058 | <para> | ||
15059 | This function returns a <command>mailmessage</command> | ||
15060 | (see <xref linkend="mailmessage">) structure that | ||
15061 | corresponds to the given message number. | ||
15062 | </para> | ||
15063 | |||
15064 | <warning> | ||
15065 | <para> | ||
15066 | <command>mailsession_get_message_by_uid()</command> should | ||
15067 | be used instead. | ||
15068 | </para> | ||
15069 | </warning> | ||
15070 | </sect2> | ||
15071 | |||
15072 | <sect2> | ||
15073 | <title>mailsession_get_message_by_uid</title> | ||
15074 | |||
15075 | <programlisting> | ||
15076 | #include <libetpan/libetpan.h> | ||
15077 | |||
15078 | int mailsession_get_message_by_uid(mailsession * session, | ||
15079 | const char * uid, mailmessage ** result); | ||
15080 | </programlisting> | ||
15081 | |||
15082 | <para> | ||
15083 | This function returns a mailmessage structure | ||
15084 | that corresponds to the given message unique identifier. | ||
15085 | This is currently implemented only for cached drivers. | ||
15086 | </para> | ||
15087 | <warning> | ||
15088 | <para> | ||
15089 | That deprecates the use of | ||
15090 | <command>mailsession_get_message()</command>. | ||
15091 | </para> | ||
15092 | </warning> | ||
15093 | </sect2> | ||
15094 | </sect1> | ||
15095 | </chapter> | ||
15096 | |||
15097 | </book> | ||