Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 77fdebe6 77fdebe69045f6fdc4e61918ef9226aeb331cf2a by Wojciech Polak
Options

Updated to the current API.

1 parent aa33e6e1
Expand all
Inline Side-by-side
Showing 19 changed files with 1049 additions and 361 deletions
...@@ -4,87 +4,146 @@ ...@@ -4,87 +4,146 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{attribute_} is reserved */} 7 @code{/* Prefix @emph{attribute_} is reserved. */}
8 @code{#include <mailutils/attribute.h>} 8 @code{#include <mailutils/attribute.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int attribute_create (attribute_t *@var{pattribute}) 11 @deftypefun int attribute_create (attribute_t *@var{attr}, void *)
12 @end deftypefun 12 @end deftypefun
13 13
14 @deftypefun void attribute_destroy (attribute_t *@var{pattribute}) 14 @deftypefun void attribute_destroy (attribute_t *@var{attr}, void *)
15 @end deftypefun 15 @end deftypefun
16 16
17 @deftypefun int attribute_is_seen (attribute_t @var{attribute}) 17 @deftypefun void* attribute_get_owner (attribute_t @var{attr})
18 @end deftypefun 18 @end deftypefun
19 19
20 @deftypefun int attribute_is_answered (attribute_t @var{attribute}) 20 @deftypefun int attribute_is_modified (attribute_t @var{attr})
21 @end deftypefun 21 @end deftypefun
22 22
23 @deftypefun int attribute_is_flagged (attribute_t @var{attribute}) 23 @deftypefun int attribute_clear_modified (attribute_t @var{attr})
24 @end deftypefun 24 @end deftypefun
25 25
26 @deftypefun int attribute_is_deleted (attribute_t @var{attribute}) 26 @deftypefun int attribute_set_modified (attribute_t @var{attr})
27 @end deftypefun 27 @end deftypefun
28 28
29 @deftypefun int attribute_is_draft (attribute_t @var{attribute}) 29 @c
30 @c _is_
31 @c
32
33 @deftypefun int attribute_is_userflag (attribute_t @var{attr})
34 @end deftypefun
35
36 @deftypefun int attribute_is_seen (attribute_t @var{attr})
37 @end deftypefun
38
39 @deftypefun int attribute_is_answered (attribute_t @var{attr})
40 @end deftypefun
41
42 @deftypefun int attribute_is_flagged (attribute_t @var{attr})
43 @end deftypefun
44
45 @deftypefun int attribute_is_deleted (attribute_t @var{attr})
46 @end deftypefun
47
48 @deftypefun int attribute_is_draft (attribute_t @var{attr})
49 @end deftypefun
50
51 @deftypefun int attribute_is_recent (attribute_t @var{attr})
30 @end deftypefun 52 @end deftypefun
31 53
32 @deftypefun int attribute_is_recent (attribute_t @var{attribute}) 54 @deftypefun int attribute_is_read (attribute_t @var{attr})
33 @end deftypefun 55 @end deftypefun
34 56
35 @deftypefun int attribute_is_read (attribute_t @var{attribute}) 57 @c
58 @c _set_
59 @c
60
61 @deftypefun int attribute_set_userflag (attribute_t @var{attr}, int)
36 @end deftypefun 62 @end deftypefun
37 63
38 @deftypefun int attribute_set_seen (attribute_t @var{attribute}) 64 @deftypefun int attribute_set_seen (attribute_t @var{attr})
39 @end deftypefun 65 @end deftypefun
40 66
41 @deftypefun int attribute_set_answered (attribute_t @var{attribute}) 67 @deftypefun int attribute_set_answered (attribute_t @var{attr})
42 @end deftypefun 68 @end deftypefun
43 69
44 @deftypefun int attribute_set_flagged (attribute_t @var{attribute}) 70 @deftypefun int attribute_set_flagged (attribute_t @var{attr})
45 @end deftypefun 71 @end deftypefun
46 72
47 @deftypefun int attribute_set_deleted (attribute_t @var{attribute}) 73 @deftypefun int attribute_set_deleted (attribute_t @var{attr})
48 @end deftypefun 74 @end deftypefun
49 75
50 @deftypefun int attribute_set_draft (attribute_t @var{attribute}) 76 @deftypefun int attribute_set_draft (attribute_t @var{attr})
51 @end deftypefun 77 @end deftypefun
52 78
53 @deftypefun int attribute_set_recent (attribute_t @var{attribute}) 79 @deftypefun int attribute_set_recent (attribute_t @var{attr})
54 @end deftypefun 80 @end deftypefun
55 81
56 @deftypefun int attribute_set_read (attribute_t @var{attribute}) 82 @deftypefun int attribute_set_read (attribute_t @var{attr})
57 @end deftypefun 83 @end deftypefun
58 84
59 @deftypefun int attribute_unset_seen (attribute_t @var{attribute}) 85 @c
86 @c _unset_
87 @c
88
89 @deftypefun int attribute_unset_userflag (attribute_t @var{attr}, int)
60 @end deftypefun 90 @end deftypefun
61 91
62 @deftypefun int attribute_unset_answered (attribute_t @var{attribute}) 92 @deftypefun int attribute_unset_seen (attribute_t @var{attr})
63 @end deftypefun 93 @end deftypefun
64 94
65 @deftypefun int attribute_unset_flagged (attribute_t @var{attribute}) 95 @deftypefun int attribute_unset_answered (attribute_t @var{attr})
66 @end deftypefun 96 @end deftypefun
67 97
68 @deftypefun int attribute_unset_deleted (attribute_t @var{attribute}) 98 @deftypefun int attribute_unset_flagged (attribute_t @var{attr})
69 @end deftypefun 99 @end deftypefun
70 100
71 @deftypefun int attribute_unset_draft (attribute_t @var{attribute}) 101 @deftypefun int attribute_unset_deleted (attribute_t @var{attr})
72 @end deftypefun 102 @end deftypefun
73 103
74 @deftypefun int attribute_unset_recent (attribute_t @var{attribute}) 104 @deftypefun int attribute_unset_draft (attribute_t @var{attr})
75 @end deftypefun 105 @end deftypefun
76 106
77 @deftypefun int attribute_unset_read (attribute_t @var{attribute}) 107 @deftypefun int attribute_unset_recent (attribute_t @var{attr})
78 @end deftypefun 108 @end deftypefun
79 109
80 @deftypefun int attribute_is_equal (attribute_t @var{att1}, attribute_t @var{att2}) 110 @deftypefun int attribute_unset_read (attribute_t @var{attr})
111 @end deftypefun
112
113 @c
114 @c ----------
115 @c
116
117 @deftypefun int attribute_get_flags (attribute_t @var{attr}, int *)
118 @end deftypefun
119
120 @deftypefun int attribute_set_flags (attribute_t @var{attr}, int)
121 @end deftypefun
122
123 @deftypefun int attribute_unset_flags (attribute_t @var{attr}, int)
124 @end deftypefun
125
126 @deftypefun int attribute_set_set_flags (attribute_t @var{attr}, int (*@var{_set_flags}) (attribute_t, int), void *)
127 @end deftypefun
128
129 @deftypefun int attribute_set_unset_flags (attribute_t @var{attr}, int (*@var{_unset_flags}) (attribute_t, int), void *)
130 @end deftypefun
131
132 @deftypefun int attribute_set_get_flags (attribute_t @var{attr}, int (*@var{_get_flags}) (attribute_t, int *), void *)
133 @end deftypefun
134
135 @c
136 @c ----------
137 @c
138
139 @deftypefun int attribute_is_equal (attribute_t @var{attr1}, attribute_t @var{attr2})
81 @end deftypefun 140 @end deftypefun
82 141
83 @deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src}) 142 @deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src})
84 @end deftypefun 143 @end deftypefun
85 144
86 @deftypefun int string_to_attribute (const char *@var{buf}, attribute_t *@var{pattr}) 145 @deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{writen})
87 @end deftypefun 146 @end deftypefun
88 147
89 @deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{pwriten}) 148 @deftypefun int string_to_flags (const char *@var{buf}, int *)
90 @end deftypefun 149 @end deftypefun
......
...@@ -4,37 +4,108 @@ ...@@ -4,37 +4,108 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{auth_} is reserved */} 7 @code{/* Prefixes @emph{authority_}, @emph{ticket_}, and @emph{wicket_t} are reserved */}
8 @code{#include <mailutils/auth.h>} 8 @code{#include <mailutils/auth.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 There are many ways to authenticate to a server. To be flexible the 12 There are many ways to authenticate to a server. To be flexible the
13 authentication process is provided by two objects @code{auth_t} and 13 authentication process is provided by three objects @code{authority_t},
14 @code{ticket_t}. The @code{auth_t} can implement different protocol like 14 @code{ticket_t}, and @code{wicket_t}. The @code{authority_t} can implement
15 APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox 15 different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
16 does not understand or know how to authenticate it falls back to 16 if a mailbox does not understand or know how to authenticate it falls back
17 user/passwd authentication. The @code{ticket_t} is a way for 17 to user/passwd authentication. The @code{ticket_t} is a way for
18 Mailboxes and Mailers provide a way to authenticate when the URL does not 18 Mailboxes and Mailers provide a way to authenticate when the URL does not
19 contain enough information. The default action is to call the function 19 contain enough information. The default action is to call the function
20 @code{auth_authenticate} which will get the @emph{user} and @emph{passwd} 20 @code{authority_authenticate()} which will get the @emph{user} and @emph{passwd}
21 if not set, this function can be overridden by a custom method. 21 if not set, this function can be overridden by a custom method.
22 22
23 @deftypefun int auth_create (auth_t *@var{pauth}, void *@var{owner}) 23 @c
24 @c Ticket
25 @c
26
27 @deftypefun int ticket_create (ticket_t *, void *@var{owner})
28 @end deftypefun
29
30 @deftypefun void ticket_destroy (ticket_t *, void *@var{owner})
31 @end deftypefun
32
33 @deftypefun int ticket_set_destroy (ticket_t, void (*) (ticket_t), void *@var{owner})
34 @end deftypefun
35
36 @deftypefun void* ticket_get_owner (ticket_t)
37 @end deftypefun
38
39 @deftypefun int ticket_set_pop (ticket_t, int (*@var{_pop}) (ticket_t, url_t, const char *, char **), void *)
40 @end deftypefun
41
42 @deftypefun int ticket_pop (ticket_t, url_t, const char *, char **)
43 @end deftypefun
44
45 @deftypefun int ticket_set_data (ticket_t, void *, void *@var{owner})
46 @end deftypefun
47
48 @deftypefun int ticket_get_data (ticket_t, void **)
49 @end deftypefun
50
51 @c
52 @c Authority
53 @c
54
55 @sp 1
56
57 @deftypefun int authority_create (authority_t *, ticket_t, void *)
58 @end deftypefun
59
60 @deftypefun void authority_destroy (authority_t *, void *)
61 @end deftypefun
62
63 @deftypefun void* authority_get_owner (authority_t)
24 @end deftypefun 64 @end deftypefun
25 65
26 @deftypefun void auth_destroy (auth_t *@var{pauth}, void *@var{owner}) 66 @deftypefun int authority_set_ticket (authority_t, ticket_t)
27 @end deftypefun 67 @end deftypefun
28 68
29 @deftypefun int auth_prologue (auth_t @var{auth}) 69 @deftypefun int authority_get_ticket (authority_t, ticket_t *)
30 @end deftypefun 70 @end deftypefun
31 71
32 @deftypefun int auth_authenticate (auth_t @var{auth}, char **@var{user}, char **@var{passwd}) 72 @deftypefun int authority_authenticate (authority_t)
33 @end deftypefun 73 @end deftypefun
34 74
35 @deftypefun int auth_epilogue (auth_t @var{auth}) 75 @deftypefun int authority_set_authenticate (authority_t, int (*@var{_authenticate}) (authority_t), void *)
36 @end deftypefun 76 @end deftypefun
37 77
78 @deftypefun int authority_create_null (authority_t *@var{authority}, void *@var{owner})
79 @end deftypefun
80
81 @c
82 @c Wicket
83 @c
84
85 @sp 1
86
87 @deftypefun int wicket_create (wicket_t *, const char *)
88 @end deftypefun
89
90 @deftypefun void wicket_destroy (wicket_t *)
91 @end deftypefun
92
93 @deftypefun int wicket_set_filename (wicket_t, const char *)
94 @end deftypefun
95
96 @deftypefun int wicket_get_filename (wicket_t, char *, size_t, size_t *)
97 @end deftypefun
98
99 @deftypefun int wicket_set_ticket (wicket_t, int (*) (wicket_t, const char *, const char *, ticket_t *))
100 @end deftypefun
101
102 @deftypefun int wicket_get_ticket (wicket_t, ticket_t *, const char *, const char *)
103 @end deftypefun
104
105 @c
106 @c An example.
107 @c
108
38 @sp 1 109 @sp 1
39 A simple example of an authenticate function: 110 A simple example of an authenticate function:
40 111
......
...@@ -4,32 +4,48 @@ ...@@ -4,32 +4,48 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{body_} is reserved */} 7 @code{/* Prefix @emph{body_} is reserved. */}
8 @code{#include <mailutils/body.h>} 8 @code{#include <mailutils/body.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int body_create (body_t *@var{body}, void *@var{owner}) 11 @deftypefun int body_create (body_t *@var{body}, void *@var{owner})
12 Initialize an object @var{bdy}. 12 Initialize an object @var{body}.
13 @end deftypefun 13 @end deftypefun
14 14
15 @deftypefun void body_destroy (body_t *@var{pbody}) 15 @deftypefun void body_destroy (body_t *@var{body})
16 The resources allocate are release. 16 The resources allocated are release.
17 @end deftypefun 17 @end deftypefun
18 18
19 @deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{pstream}) 19 @deftypefun void* body_get_owner (body_t @var{body})
20 @end deftypefun 20 @end deftypefun
21 21
22 @deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner}) 22 @deftypefun int body_is_modified (body_t @var{body})
23 @end deftypefun 23 @end deftypefun
24 24
25 @deftypefun int body_get_filename __P ((body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten})) 25 @deftypefun int body_clear_modified (body_t @var{body})
26 @end deftypefun 26 @end deftypefun
27 27
28 @deftypefun int body_set_filename (body_t @var{body}, const char*@var{buffer}) 28 @c
29 @c -----------
30 @c
31
32 @deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{stream})
33 @end deftypefun
34
35 @deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner})
36 @end deftypefun
37
38 @deftypefun int body_get_filename (body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
39 @end deftypefun
40
41 @deftypefun int body_size (body_t @var{body}, size_t *@var{size})
42 @end deftypefun
43
44 @deftypefun int body_set_size (body_t @var{body}, int (*@var{_size}) (body_t, size_t *), void *@var{owner})
29 @end deftypefun 45 @end deftypefun
30 46
31 @deftypefun int body_size (body_t @var{body}, size_t*@var{psize}) 47 @deftypefun int body_lines (body_t @var{body}, size_t *@var{lines})
32 @end deftypefun 48 @end deftypefun
33 49
34 @deftypefun int body_lines (body_t @var{body}, size_t *@var{plines}) 50 @deftypefun int body_set_lines (body_t @var{body}, int (*@var{_lines}) (body_t, size_t *), void *@var{owner})
35 @end deftypefun 51 @end deftypefun
......
...@@ -4,40 +4,44 @@ ...@@ -4,40 +4,44 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{envelope_} is reserved */} 7 @code{/* Prefix @emph{envelope_} is reserved. */}
8 @code{#include <mailutils/envelope.h>} 8 @code{#include <mailutils/envelope.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *); 11 @deftypefun int envelope_create (envelope_t *, void *)
12 Get the date that the message was delivered to the mailbox, in 12 Primarily for internal use.
13 something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
14 @end deftypefun 13 @end deftypefun
15 14
16 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *); 15 @deftypefun void envelope_destroy (envelope_t *, void *)
17 Get the address that this message was reportedly received from. This 16 Primarily for internal use.
18 would be the "mail from" argument if the message was delivered
19 or received via SMTP, for example.
20 @end deftypefun 17 @end deftypefun
21 18
22 @deftypefun int envelope_get_message (envelope_t, message_t *); 19 @deftypefun void* envelope_get_owner (envelope_t)
23 @end deftypefun 20 @end deftypefun
24 21
25 @deftypefun int envelope_create (envelope_t *, void *); 22 @c
26 Primarily for internal use. 23 @c ----------
27 @end deftypefun 24 @c
28 25
29 @deftypefun void envelope_destroy (envelope_t *, void *); 26 @deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *)
30 Primarily for internal use. 27 Get the address that this message was reportedly received from. This
28 would be the "mail from" argument if the message was delivered
29 or received via SMTP, for example.
31 @end deftypefun 30 @end deftypefun
32 31
33 @deftypefun int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *); 32 @deftypefun int envelope_set_sender (envelope_t, int (*@var{_sender}) (envelope_t, char *, size_t, size_t *), void *)
34 Primarily for internal use. The implementation of envelope_t depends 33 Primarily for internal use. The implementation of @code{envelope_t} depends
35 on the mailbox type, this allows the function which actually gets 34 on the mailbox type, this allows the function which actually gets
36 the sender to be set by the creator of an @code{envelope_t}. 35 the sender to be set by the creator of an @code{envelope_t}.
37 @end deftypefun 36 @end deftypefun
38 37
39 @deftypefun int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *); 38 @deftypefun int envelope_date (envelope_t, char *, size_t, size_t *)
40 Primarily for internal use. The implementation of envelope_t depends 39 Get the date that the message was delivered to the mailbox, in
40 something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
41 @end deftypefun
42
43 @deftypefun int envelope_set_date (envelope_t, int (*@var{_date}) (envelope_t, char *, size_t, size_t *), void *)
44 Primarily for internal use. The implementation of @code{envelope_t} depends
41 on the mailbox type, this allows the function which actually gets 45 on the mailbox type, this allows the function which actually gets
42 the date to be set by the creator of an @code{envelope_t}. 46 the date to be set by the creator of an @code{envelope_t}.
43 @end deftypefun 47 @end deftypefun
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{folder_} is reserve */} 7 @code{/* Prefix @emph{folder_} is reserved. */}
8 @code{#include <mailutils/folder.h>} 8 @code{#include <mailutils/folder.h>}
9 9
10 @end smallexample 10 @end smallexample
...@@ -12,77 +12,126 @@ ...@@ -12,77 +12,126 @@
12 @smallexample 12 @smallexample
13 @group 13 @group
14 folder_t url_t 14 folder_t url_t
15 -/var/mail- +---//---->/-----------------\ +-->/-----------\ 15 -/var/mail- +---//--->/-----------------\ +-->/-----------\
16 ( alain *-)-+ | | url_t *-|----+ | port | 16 ( alain *-)-+ | | url_t *-|---+ | port |
17 ----------- | | |-----------------+ | hostname | 17 ---------- | | |-----------------+ | hostname |
18 ( jakob *-)-+--+ | observer_t *-| | file | 18 ( jakob *-)-+--+ | observer_t *-| | file |
19 ----------- | |-----------------+ | ... | 19 ---------- | |-----------------+ | ... |
20 ( jeff *-)-+ | stream_t | \-----------/ 20 ( jeff *-)-+ | stream_t | \-----------/
21 ----------- | |-----------------| 21 ---------- | |-----------------|
22 ( sean *-)-+ | auth_t | 22 ( sean *-)-+ | auth_t |
23 ---------- |-----------------| 23 ---------- |-----------------|
24 | mailbox_t(1) | 24 | mailbox_t(1) |
25 |-----------------| 25 |-----------------|
26 | mailbox_t(2) | 26 | mailbox_t(2) |
27 | ...... | 27 | ...... |
28 | mailbox_t(n) | 28 | mailbox_t(n) |
29 \-----------------/ 29 \-----------------/
30 @end group 30 @end group
31 @end smallexample 31 @end smallexample
32 32
33 @deftypefun int folder_create (folder_t *, const char *@var{url}) 33 Data structures:
34
35 @smallexample
36 @group
37 struct list_response
38 @{
39 int type;
40 int separator;
41 char *name;
42 @};
43
44 struct folder_list
45 @{
46 struct list_response **element;
47 size_t num;
48 @};
49 @end group
50 @end smallexample
51
52 @c
53 @c Constructor/Destructor and possible types.
54 @c
55
56 @deftypefun int folder_create (folder_t *, const char *@var{url})
34 @end deftypefun 57 @end deftypefun
35 58
36 @deftypefun void folder_destroy (folder_t *) 59 @deftypefun void folder_destroy (folder_t *)
37 @end deftypefun 60 @end deftypefun
38 61
39 @deftypefun int folder_open (folder_t, int @var{flag}) 62 @deftypefun int folder_open (folder_t, int @var{flag})
63 @end deftypefun
64
65 @deftypefun int folder_close (folder_t)
66 @end deftypefun
67
68 @deftypefun int folder_delete (folder_t, const char *@var{mailbox})
40 @end deftypefun 69 @end deftypefun
41 70
42 @deftypefun int folder_close (folder_t) 71 @deftypefun int folder_rename (folder_t, const char *, const char *@var{mailbox})
43 @end deftypefun 72 @end deftypefun
44 73
45 @deftypefun int folder_delete (folder_t, const char *@var{mailbox}) 74 @deftypefun int folder_subscribe (folder_t, const char *@var{mailbox})
46 @end deftypefun 75 @end deftypefun
47 76
48 @deftypefun int folder_rename (folder_t, const char *, const char *@var{mailbox}) 77 @deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox})
49 @end deftypefun 78 @end deftypefun
50 79
51 @deftypefun int folder_subscribe (folder_t, const char *@var{mailbox}) 80 @deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
52 @end deftypefun 81 @end deftypefun
53 82
54 @deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox}) 83 @deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
55 @end deftypefun 84 @end deftypefun
56 85
57 @deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, iterator_t *) 86 @deftypefun int folder_list_destroy (struct folder_list *)
58 @end deftypefun 87 @end deftypefun
59 88
60 @deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcar}, iterator_t *) 89 @c
90 @c Stream Settings.
91 @c
92
93 @deftypefun int folder_get_stream (folder_t, stream_t *)
61 @end deftypefun 94 @end deftypefun
62 95
63 @deftypefun int folder_get_stream (folder_t, stream_t *) 96 @deftypefun int folder_set_stream (folder_t, stream_t)
64 @end deftypefun 97 @end deftypefun
65 98
66 @deftypefun int folder_set_stream (folder_t, stream_t) 99 @c
100 @c Notifications.
101 @c
102
103 @deftypefun int folder_get_observable (folder_t, observable_t *)
67 @end deftypefun 104 @end deftypefun
68 105
69 @deftypefun int folder_get_observable (folder_t, observable_t *) 106 @c
107 @c Debug.
108 @c
109
110 @deftypefun int folder_has_debug (folder_t)
70 @end deftypefun 111 @end deftypefun
71 112
72 @deftypefun int folder_get_debug (folder_t, debug_t *) 113 @deftypefun int folder_get_debug (folder_t, mu_debug_t *)
73 @end deftypefun 114 @end deftypefun
74 115
75 @deftypefun int folder_set_debug (folder_t, debug_t) 116 @deftypefun int folder_set_debug (folder_t, mu_debug_t)
76 @end deftypefun 117 @end deftypefun
77 118
78 @deftypefun int folder_get_authority (folder_t, authority_t *) 119 @c
120 @c Authentication.
121 @c
122
123 @deftypefun int folder_get_authority (folder_t, authority_t *)
79 @end deftypefun 124 @end deftypefun
80 125
81 @deftypefun int folder_set_authority (folder_t, authority_t) 126 @deftypefun int folder_set_authority (folder_t, authority_t)
82 @end deftypefun 127 @end deftypefun
83 128
84 @deftypefun int folder_get_url (folder_t, url_t *) 129 @c
130 @c URL.
131 @c
132
133 @deftypefun int folder_get_url (folder_t, url_t *)
85 @end deftypefun 134 @end deftypefun
86 135
87 @deftypefun int folder_set_url (folder_t, url_t) 136 @deftypefun int folder_set_url (folder_t, url_t)
88 @end deftypefun 137 @end deftypefun
......
...@@ -36,11 +36,11 @@ etc ..). ...@@ -36,11 +36,11 @@ etc ..).
36 folder_t url_t 36 folder_t url_t
37 -/var/mail- +- .. ->+-----------------+ +-->+------------+ 37 -/var/mail- +- .. ->+-----------------+ +-->+------------+
38 ( alain *-)-+ | | url_t *-|---+ | port | 38 ( alain *-)-+ | | url_t *-|---+ | port |
39 ----------- | | |-----------------| | hostname | 39 ---------- | | |-----------------| | hostname |
40 ( jakob *-)-+--+ | auth_t *-|---+ | file | 40 ( jakob *-)-+--+ | auth_t *-|---+ | file |
41 ----------- | |-----------------| | | ... | 41 ---------- | |-----------------| | | ... |
42 ( jeff *-)-+ | stream_t | | +------------+ 42 ( jeff *-)-+ | stream_t | | +------------+
43 ----------- | |-----------------| | 43 ---------- | |-----------------| |
44 ( shaleh*-)-+ | ..... | | auth_t 44 ( shaleh*-)-+ | ..... | | auth_t
45 ---------- |-----------------| +-->+------------+ 45 ---------- |-----------------| +-->+------------+
46 +---|-* mailbox_t[] | | ticket_t | 46 +---|-* mailbox_t[] | | ticket_t |
...@@ -165,4 +165,3 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha ...@@ -165,4 +165,3 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
165 @node Mailcap 165 @node Mailcap
166 @subsection Mailcap 166 @subsection Mailcap
167 @include mailcap.texi 167 @include mailcap.texi
168
......
...@@ -4,31 +4,43 @@ ...@@ -4,31 +4,43 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{header_} is reserved */} 7 @code{/* Prefix @emph{header_} is reserved. */}
8 @code{#include <mailutils/header.h>} 8 @code{#include <mailutils/header.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII 12 So far we plan support for RFC822 and plan for RFC1522. With RFC1522 non-ASCII
13 characters will be encoded. 13 characters will be encoded.
14 14
15 @deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner}) 15 @deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner})
16 Initialize a @var{hdr} to a supported type. If @var{blurb} is not NULL, it is 16 Initialize a @var{hdr} to a supported type. If @var{blurb} is not @code{NULL},
17 parsed. 17 it is parsed.
18 @end deftypefun 18 @end deftypefun
19 19
20 @deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner}) 20 @deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner})
21 The resources allocated for @var{hdr} are freed. 21 The resources allocated for @var{hdr} are freed.
22 @end deftypefun 22 @end deftypefun
23 23
24 @deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, size_t n, int @var{replace}) 24 @deftypefun void* header_get_owner (header_t *@var{hdr})
25 Set the field-name @var{fn} to field-value @var{fv} of size @var{n} in 25 @end deftypefun
26 @var{hdr}. If @var{replace} is non-zero the initial value is replaced, if zero 26
27 it is appended. 27 @deftypefun int header_is_modified (header_t @var{hdr})
28 @end deftypefun
29
30 @deftypefun int header_clear_modified (header_t @var{hdr})
31 @end deftypefun
32
33 @c
34 @c Set and get field values by field name.
35 @c
28 36
29 Some basic macros are already provided for rfc822. 37 @deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, int @var{n})
38
39 Some basic macros are already provided for RFC822.
30 40
31 @table @code 41 @table @code
42 @item MU_HEADER_UNIX_FROM
43 From
32 @item MU_HEADER_RETURN_PATH 44 @item MU_HEADER_RETURN_PATH
33 Return-Path 45 Return-Path
34 @item MU_HEADER_RECEIVED 46 @item MU_HEADER_RECEIVED
...@@ -37,6 +49,8 @@ Received ...@@ -37,6 +49,8 @@ Received
37 Date 49 Date
38 @item MU_HEADER_FROM 50 @item MU_HEADER_FROM
39 From 51 From
52 @item MU_HEADER_SENDER
53 Sender
40 @item MU_HEADER_RESENT_FROM 54 @item MU_HEADER_RESENT_FROM
41 Resent-From 55 Resent-From
42 @item MU_HEADER_SUBJECT 56 @item MU_HEADER_SUBJECT
...@@ -67,6 +81,10 @@ Message-ID ...@@ -67,6 +81,10 @@ Message-ID
67 Resent-Message-ID 81 Resent-Message-ID
68 @item MU_HEADER_IN_REPLY_TO 82 @item MU_HEADER_IN_REPLY_TO
69 In-Reply-To 83 In-Reply-To
84 @item MU_HEADER_REFERENCE
85 Reference
86 @item MU_HEADER_REFERENCES
87 References
70 @item MU_HEADER_ENCRYPTED 88 @item MU_HEADER_ENCRYPTED
71 Encrypted 89 Encrypted
72 @item MU_HEADER_PRECEDENCE 90 @item MU_HEADER_PRECEDENCE
...@@ -75,27 +93,118 @@ Precedence ...@@ -75,27 +93,118 @@ Precedence
75 Status 93 Status
76 @item MU_HEADER_CONTENT_LENGTH 94 @item MU_HEADER_CONTENT_LENGTH
77 Content-Length 95 Content-Length
96 @item MU_HEADER_CONTENT_LANGUAGE
97 Content-Language
98 @item MU_HEADER_CONTENT_TRANSFER_ENCODING
99 Content-transfer-encoding
100 @item MU_HEADER_CONTENT_ID
101 Content-ID
78 @item MU_HEADER_CONTENT_TYPE 102 @item MU_HEADER_CONTENT_TYPE
79 Content-Type 103 Content-Type
104 @item MU_HEADER_CONTENT_DESCRIPTION
105 Content-Description
106 @item MU_HEADER_CONTENT_DISPOSITION
107 Content-Disposition
108 @item MU_HEADER_CONTENT_MD5
109 Content-MD5
80 @item MU_HEADER_MIME_VERSION 110 @item MU_HEADER_MIME_VERSION
81 MIME-Version 111 MIME-Version
112 @item MU_HEADER_X_UIDL
113 X-UIDL
114 @item MU_HEADER_X_UID
115 X-UID
116 @item MU_HEADER_X_IMAPBASE
117 X-IMAPbase
118 @item MU_HEADER_ENV_SENDER
119 X-Envelope-Sender
120 @item MU_HEADER_ENV_DATE
121 X-Envelope-Date
122 @item MU_HEADER_FCC
123 Fcc
124 @item MU_HEADER_DELIVERY_DATE
125 Delivery-date
126 @item MU_HEADER_ENVELOPE_TO
127 Envelope-to
82 @end table 128 @end table
83 @end deftypefun 129 @end deftypefun
84 130
85 @deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n}) 131 @deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n})
86 Value of field-name @var{fn} is returned in buffer @var{fv} of size @var{len}. 132 Value of field-name @var{fn} is returned in buffer @var{fv} of size @var{len}.
87 The number of bytes written is put in @var{n}. 133 The number of bytes written is put in @var{n}.
88 @end deftypefun 134 @end deftypefun
89 135
90 @deftypefun int header_aget_value (header_t @var{hdr}, const char *@var{fn}, char **@var{fv}) 136 @deftypefun int header_aget_value (header_t @var{hdr}, const char *@var{fn}, char **@var{fv})
91 The value is allocated. 137 The value is allocated.
92 @end deftypefun 138 @end deftypefun
93 139
94 @deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{pstream}) 140 @c
141 @c Get field values as an address_t.
142 @c
143
144 @deftypefun int header_get_address (header_t @var{hdr}, const char *@var{buf}, address_t *@var{addr})
145 @end deftypefun
146
147 @c
148 @c Stream
149 @c
150
151 @deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{stream})
152 @end deftypefun
153
154 @deftypefun int header_set_stream (header_t @var{hdr}, stream_t @var{stream}, void *)
155 @end deftypefun
156
157 @c
158 @c
159 @c
160
161 @deftypefun int header_get_field_count (header_t @var{hdr}, size_t *@var{count})
162 @end deftypefun
163
164 @deftypefun int header_get_field_value (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
165 @end deftypefun
166
167 @deftypefun int header_get_field_name (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
168 @end deftypefun
169
170 @deftypefun int header_aget_field_value (header_t @var{hdr}, size_t @var{index}, char **)
171 @end deftypefun
172
173 @deftypefun int header_aget_field_name (header_t @var{hdr}, size_t @var{index}, char **)
174 @end deftypefun
175
176 @deftypefun int header_get_value_unfold (header_t @var{hdr}, const char *@var{name}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
177 @end deftypefun
178
179 @deftypefun int header_aget_value_unfold (header_t @var{hdr}, const char *@var{name}, char **@var{value})
180 @end deftypefun
181
182 @deftypefun int header_get_field_value_unfold (header_t @var{hdr}, size_t @var{num}, char *@var{buf}, size_t @var{buflen}, size_t *@var{nwritten})
183 @end deftypefun
184
185 @deftypefun int header_aget_field_value_unfold (header_t @var{hdr}, size_t @var{num}, char **@var{value});
186 @end deftypefun
187
188 @deftypefun int header_size (header_t @var{hdr}, size_t *);
189 @end deftypefun
190
191 @deftypefun int header_lines (header_t @var{hdr}, size_t *);
192 @end deftypefun
193
194 @deftypefun int header_set_set_value (header_t @var{hdr}, int (*@var{_set_value}) (header_t, const char *, const char *, int), void *);
195 @end deftypefun
196
197 @deftypefun int header_set_get_value (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
198 @end deftypefun
199
200 @deftypefun int header_set_get_fvalue (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
201 @end deftypefun
202
203 @deftypefun int header_set_size (header_t @var{hdr}, int (*@var{_size}) (header_t, size_t *), void *);
95 @end deftypefun 204 @end deftypefun
96 205
97 @deftypefun int header_set_size (header_t @var{hdr}, size_t *@var{size}) 206 @deftypefun int header_set_lines (header_t @var{hdr}, int (*@var{_lines}) (header_t, size_t *), void *);
98 @end deftypefun 207 @end deftypefun
99 208
100 @deftypefun int header_set_lines (header_t @var{hdr}, size_t *@var{lpines}) 209 @deftypefun int header_set_fill (header_t @var{hdr}, int (*@var{_fill}) (header_t, char *, size_t, off_t, size_t *), void *@var{owner});
101 @end deftypefun 210 @end deftypefun
......
...@@ -4,24 +4,30 @@ ...@@ -4,24 +4,30 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{iterator_} is reserved */} 7 @code{/* Prefix @emph{iterator_} is reserved. */}
8 @code{#include <mailutils/iterator.h>} 8 @code{#include <mailutils/iterator.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int iterator_create (iterator_t *) 11 @deftypefun int iterator_create (iterator_t *@var{iterator}, list_t)
12 @end deftypefun
13
14 @deftypefun int iterator_dup (iterator_t *@var{iterator}, iterator_t @var{orig})
12 @end deftypefun 15 @end deftypefun
13 16
14 @deftypefun void iterator_destroy (iterator_t *) 17 @deftypefun void iterator_destroy (iterator_t *)
15 @end deftypefun 18 @end deftypefun
16 19
17 @deftypefun int iterator_first (iterator_t) 20 @deftypefun int iterator_first (iterator_t)
21 @end deftypefun
22
23 @deftypefun int iterator_next (iterator_t)
18 @end deftypefun 24 @end deftypefun
19 25
20 @deftypefun int iterator_next (iterator_t) 26 @deftypefun int iterator_current (iterator_t, void **@var{item})
21 @end deftypefun 27 @end deftypefun
22 28
23 @deftypefun int iterator_current (iterator_t, void **pitem) 29 @deftypefun int iterator_is_done (iterator_t)
24 @end deftypefun 30 @end deftypefun
25 31
26 @deftypefun int iterator_is_done (iterator_t) 32 @deftypefun int iterator_get_list (iterator_t @var{iterator}, list_t *@var{list})
27 @end deftypefun 33 @end deftypefun
......
...@@ -30,18 +30,19 @@ This is a pointer to authentication or authorization data. It ...@@ -30,18 +30,19 @@ This is a pointer to authentication or authorization data. It
30 is defined as follows: 30 is defined as follows:
31 31
32 @smallexample 32 @smallexample
33 typedef int (*mu_auth_fp) (void *@var{return_data}, 33 @group
34 typedef int (*mu_auth_fp) (struct mu_auth_data **@var{return_data},
34 void *@var{key}, 35 void *@var{key},
35 void *@var{func_data}, 36 void *@var{func_data},
36 void *@var{call_data}); 37 void *@var{call_data});
38 @end group
37 @end smallexample 39 @end smallexample
40
38 @noindent 41 @noindent
39 Its arguments are: 42 Its arguments are:
40 43
41 @table @var 44 @table @var
42 @item return_data 45 @item return_data
43 @footnote{Actually it shoud have been @code{struct mu_auth_data** return_data}.
44 This will be fixed in the next release}.
45 Upon successful return authorization handler leaves in this memory 46 Upon successful return authorization handler leaves in this memory
46 location a pointer to the filled @code{mu_auth_data} structure 47 location a pointer to the filled @code{mu_auth_data} structure
47 with the user's information. 48 with the user's information.
...@@ -118,7 +119,6 @@ struct mu_auth_module @{ ...@@ -118,7 +119,6 @@ struct mu_auth_module @{
118 @subsection Initializing @file{libmuauth} 119 @subsection Initializing @file{libmuauth}
119 120
120 @deftypefun void mu_auth_init (void) 121 @deftypefun void mu_auth_init (void)
121
122 This function registers the command line capability ``auth''. It must be 122 This function registers the command line capability ``auth''. It must be
123 called after registering @file{libmuauth} modules and before calling 123 called after registering @file{libmuauth} modules and before calling
124 @code{mu_agrp_parse()}. If an error occurs, this function prints 124 @code{mu_agrp_parse()}. If an error occurs, this function prints
...@@ -126,27 +126,24 @@ diagnostic message and aborts the program. ...@@ -126,27 +126,24 @@ diagnostic message and aborts the program.
126 @end deftypefun 126 @end deftypefun
127 127
128 @deftypefun void MU_AUTH_REGISTER_ALL_MODULES (void) 128 @deftypefun void MU_AUTH_REGISTER_ALL_MODULES (void)
129
130 This macro registers all default modules and calls @code{mu_auth_init()}. 129 This macro registers all default modules and calls @code{mu_auth_init()}.
131 @end deftypefun 130 @end deftypefun
132 131
133 @node Module Creation and Destruction 132 @node Module Creation and Destruction
134 @subsection Module Creation and Destruction 133 @subsection Module Creation and Destruction
135 134
136 @deftypefun int mu_auth_data_alloc (struct mu_auth_data **ptr, const char *name, const char *passwd, uid_t uid, gid_t gid, const char *gecos, const char *dir, const char *shell, const char *mailbox, int change_uid) 135 @deftypefun int mu_auth_data_alloc (struct mu_auth_data **@var{ptr}, const char *@var{name}, const char *@var{passwd}, uid_t @var{uid}, gid_t @var{gid}, const char *@var{gecos}, const char *@var{dir}, const char *@var{shell}, const char *@var{mailbox}, int @var{change_uid})
137 136
138 Create a @code{mu_auth_data} structure and initialize it with the given 137 Create a @code{mu_auth_data} structure and initialize it with the given
139 values. Returns 0 on success and 1 otherwise. 138 values. Returns 0 on success and 1 otherwise.
140 @end deftypefun 139 @end deftypefun
141 140
142 @deftypefun void mu_auth_data_free (struct mu_auth_data *@var{ptr}) 141 @deftypefun void mu_auth_data_free (struct mu_auth_data *@var{ptr})
143
144 Free the @code{mu_auth_data} structure allocated by a call to 142 Free the @code{mu_auth_data} structure allocated by a call to
145 @code{mu_auth_data_alloc()}. 143 @code{mu_auth_data_alloc()}.
146 @end deftypefun 144 @end deftypefun
147 145
148 @deftypefun void mu_auth_register_module (struct mu_auth_module *@var{mod}) 146 @deftypefun void mu_auth_register_module (struct mu_auth_module *@var{mod})
149
150 Register the module defined by the @var{mod} argument. 147 Register the module defined by the @var{mod} argument.
151 @end deftypefun 148 @end deftypefun
152 149
...@@ -154,8 +151,7 @@ Register the module defined by the @var{mod} argument. ...@@ -154,8 +151,7 @@ Register the module defined by the @var{mod} argument.
154 @subsection Obtaining Authorization Information 151 @subsection Obtaining Authorization Information
155 @cindex libmuauth, obtaining authorization information 152 @cindex libmuauth, obtaining authorization information
156 153
157 @deftypefun int mu_auth_runlist (list_t @var{flist}, void *@var{return_data}, void *@var{key}, void *@var{call_data}); 154 @deftypefun int mu_auth_runlist (list_t @var{flist}, struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{call_data});
158
159 The list is expected to contain @code{mu_auth_fp} pointers. Each of them 155 The list is expected to contain @code{mu_auth_fp} pointers. Each of them
160 is dereferenced and executed until either the list is exhausted or any 156 is dereferenced and executed until either the list is exhausted or any
161 of the functions returns non-zero, whichever occurs first. The 157 of the functions returns non-zero, whichever occurs first. The
...@@ -170,10 +166,8 @@ return code from the succeeded function. ...@@ -170,10 +166,8 @@ return code from the succeeded function.
170 @end deftypefun 166 @end deftypefun
171 167
172 @deftypefun {struct mu_auth_data *} mu_get_auth_by_name (const char *@var{username}) 168 @deftypefun {struct mu_auth_data *} mu_get_auth_by_name (const char *@var{username})
173
174 Search the information about given user by its username. Similar to 169 Search the information about given user by its username. Similar to
175 system's @code{getpwnam} call). 170 system's @code{getpwnam} call).
176
177 @end deftypefun 171 @end deftypefun
178 172
179 @deftypefun {struct mu_auth_data *} mu_get_auth_by_uid (uid_t @var{uid}) 173 @deftypefun {struct mu_auth_data *} mu_get_auth_by_uid (uid_t @var{uid})
...@@ -181,8 +175,7 @@ Search the information about given user by its uid. Similar to ...@@ -181,8 +175,7 @@ Search the information about given user by its uid. Similar to
181 system's @code{getpwuid} call). 175 system's @code{getpwuid} call).
182 @end deftypefun 176 @end deftypefun
183 177
184 @deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass}) 178 @deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass})
185
186 Authenticate the user whose data are in @var{auth_data} using password 179 Authenticate the user whose data are in @var{auth_data} using password
187 @var{pass}. Return 0 if the user is authenticated. 180 @var{pass}. Return 0 if the user is authenticated.
188 @end deftypefun 181 @end deftypefun
...@@ -191,20 +184,17 @@ Authenticate the user whose data are in @var{auth_data} using password ...@@ -191,20 +184,17 @@ Authenticate the user whose data are in @var{auth_data} using password
191 @subsection Existing Modules 184 @subsection Existing Modules
192 @cindex libmuauth modules 185 @cindex libmuauth modules
193 186
194 @deftypefun int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data); 187 @deftypefun int mu_auth_nosupport (struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{func_data}, void *@var{call_data});
195
196 The ``not-supported'' module. Always returns @code{ENOSYS}. 188 The ``not-supported'' module. Always returns @code{ENOSYS}.
197 @end deftypefun 189 @end deftypefun
198 190
199 @defvar mu_auth_system_module 191 @defvar mu_auth_system_module
200
201 This module is always registered even if @file{libmuauth} is not linked. 192 This module is always registered even if @file{libmuauth} is not linked.
202 It performs usual authentication using system user database 193 It performs usual authentication using system user database
203 (@file{/etc/password} et al.) 194 (@file{/etc/password} et al.)
204 @end defvar 195 @end defvar
205 196
206 @defvar mu_auth_generic_module 197 @defvar mu_auth_generic_module
207
208 This module is always registered even if @file{libmuauth} is not linked. 198 This module is always registered even if @file{libmuauth} is not linked.
209 Both its authorization handlers are @code{mu_auth_nosupport}. Its 199 Both its authorization handlers are @code{mu_auth_nosupport}. Its
210 authentication handler computes the MD5 or DES hash over the supplied 200 authentication handler computes the MD5 or DES hash over the supplied
...@@ -214,13 +204,11 @@ member itself and returns 1 if both strings match. ...@@ -214,13 +204,11 @@ member itself and returns 1 if both strings match.
214 @end defvar 204 @end defvar
215 205
216 @defvar mu_auth_pam_module 206 @defvar mu_auth_pam_module
217
218 Implements PAM authentication. Both authorization handlers are 207 Implements PAM authentication. Both authorization handlers are
219 @code{mu_auth_nosupport()}. 208 @code{mu_auth_nosupport()}.
220 @end defvar 209 @end defvar
221 210
222 @defvar mu_auth_sql_module 211 @defvar mu_auth_sql_module
223
224 Implements authentication and authorization via MySQL database. The 212 Implements authentication and authorization via MySQL database. The
225 credentials for accessing the database are taken from global variables 213 credentials for accessing the database are taken from global variables
226 @code{sql_host}, @code{sql_port}, @code{sql_user}, @code{sql_passwd} 214 @code{sql_host}, @code{sql_port}, @code{sql_user}, @code{sql_passwd}
...@@ -232,7 +220,6 @@ information on command line options used to set these variables. ...@@ -232,7 +220,6 @@ information on command line options used to set these variables.
232 @end defvar 220 @end defvar
233 221
234 @defvar mu_auth_virtual_module 222 @defvar mu_auth_virtual_module
235
236 Implements @code{mu_get_auth_by_name} method using virtual mail domains. 223 Implements @code{mu_get_auth_by_name} method using virtual mail domains.
237 Neither @code{mu_get_auth_by_uid} nor @code{mu_authenticate} is 224 Neither @code{mu_get_auth_by_uid} nor @code{mu_authenticate} is
238 implemented. This module must be used together with @code{generic} 225 implemented. This module must be used together with @code{generic}
......
...@@ -389,7 +389,7 @@ match_part_checker (const char *name, list_t tags, list_t args) ...@@ -389,7 +389,7 @@ match_part_checker (const char *name, list_t tags, list_t args)
389 @end smallexample 389 @end smallexample
390 @end deftypefun 390 @end deftypefun
391 391
392 @deftypefun void *sieve_get_data (sieve_machine_t @var{mach}) 392 @deftypefun void* sieve_get_data (sieve_machine_t @var{mach})
393 This function returns the application-specific data associated with 393 This function returns the application-specific data associated with
394 the instance of sieve machine. See @code{sieve_machine_init()}. 394 the instance of sieve machine. See @code{sieve_machine_init()}.
395 @end deftypefun 395 @end deftypefun
......
...@@ -4,28 +4,73 @@ ...@@ -4,28 +4,73 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{locker_} is reserved */} 7 @code{/* Prefix @emph{locker_} is reserved. */}
8 @code{#include <mailutils/locker.h>} 8 @code{#include <mailutils/locker.h>}
9 @end smallexample 9 @end smallexample
10 10
11 @deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags}) 11 @deftypefun int locker_set_default_flags (int @var{flags}, enum mu_locker_set_mode @var{mode})
12 @end deftypefun 12 @end deftypefun
13 13
14 @deftypefun void locker_destroy (locker_t * @var{plocker}) 14 @deftypefun void locker_set_default_retry_timeout (time_t @var{to})
15 @end deftypefun 15 @end deftypefun
16 16
17 @deftypefun int locker_lock (locker_t @var{locker}, int @var{flag}) 17 @deftypefun void locker_set_default_retry_count (size_t @var{n})
18 @table @code
19 @item MU_LOCKER_RDLOCK
20 @item MU_LOCKER_WRLOCK
21 @item MU_LOCKER_PID
22 @item MU_LOCKER_FCNTL
23 @item MU_LOCKER_TIME
24 @end table
25 @end deftypefun 18 @end deftypefun
26 19
27 @deftypefun int locker_touchlock (locker_t @var{locker}) 20 @deftypefun void locker_set_default_expire_timeout (time_t @var{t})
28 @end deftypefun 21 @end deftypefun
29 22
30 @deftypefun int locker_unlock (locker_t @var{locker}) 23 @deftypefun void locker_set_default_external_program (char *@var{path})
24 @end deftypefun
25
26 A flags of 0 means that the default will be used.
27
28 @deftypefun int locker_create (locker_t *, const char *@var{filename}, int @var{flags})
29 @end deftypefun
30
31 @deftypefun void locker_destroy (locker_t *)
32 @end deftypefun
33
34 Time is measured in seconds.
35
36 @deftypefun int locker_set_flags (locker_t, int)
37 @end deftypefun
38
39 @deftypefun int locker_set_expire_time (locker_t, int)
40 @end deftypefun
41
42 @deftypefun int locker_set_retries (locker_t, int)
43 @end deftypefun
44
45 @deftypefun int locker_set_retry_sleep (locker_t, int)
46 @end deftypefun
47
48 @deftypefun int locker_set_external (locker_t, const char *@var{program})
49 @end deftypefun
50
51 @deftypefun int locker_get_flags (locker_t, int *)
52 @end deftypefun
53
54 @deftypefun int locker_get_expire_time (locker_t, int*)
55 @end deftypefun
56
57 @deftypefun int locker_get_retries (locker_t, int *)
58 @end deftypefun
59
60 @deftypefun int locker_get_retry_sleep (locker_t, int *)
61 @end deftypefun
62
63 @deftypefun int locker_get_external (locker_t, char **)
64 @end deftypefun
65
66 @deftypefun int locker_lock (locker_t)
67 @end deftypefun
68
69 @deftypefun int locker_touchlock (locker_t)
70 @end deftypefun
71
72 @deftypefun int locker_unlock (locker_t)
73 @end deftypefun
74
75 @deftypefun int locker_remove_lock (locker_t)
31 @end deftypefun 76 @end deftypefun
......
...@@ -4,61 +4,68 @@ ...@@ -4,61 +4,68 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{mu_mailcap_} is reserved */} 7 @code{/* Prefix @emph{mu_mailcap_} is reserved. */}
8 @code{#include <mailutils/mailcap.h>} 8 @code{#include <mailutils/mailcap.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 The standard @cite{RFC 1524} (A User Agent Configuration Mechanism) suggests a file format 12 The standard @cite{RFC 1524} (A User Agent Configuration Mechanism)
13 to be used to inform a mail user agent about facilities for handling mail in various 13 suggests a file format to be used to inform a mail user agent about
14 format. The configuration file is known also as mailcap and it is tipically found 14 facilities for handling mail in various format. The configuration
15 in UNIX platforms, a example of @file{/etc/mailcap}: 15 file is known also as mailcap and it is tipically found in UNIX
16 platforms, a example of @file{/etc/mailcap}:
16 17
17 @smallexample 18 @smallexample
19 @group
18 application/pgp; gpg < %s | metamail; needsterminal; \ 20 application/pgp; gpg < %s | metamail; needsterminal; \
19 test=test %@{encapsulation@}=entity ; copiousoutput 21 test=test %@{encapsulation@}=entity ; copiousoutput
22 @end group
20 @end smallexample 23 @end smallexample
21 24
22 A mailcap file consits of a set of mailcap entries per line, lines beginning with @samp{#} are 25 A mailcap file consits of a set of mailcap entries per line, lines
23 considered comments and ignored. Long mailcap entry may be continued on multiple lines if 26 beginning with @samp{#} are considered comments and ignored. Long
24 each line ends with a backslash character @samp{\}, the multiline will be considered a single 27 mailcap entry may be continued on multiple lines if each line ends
25 mailcap entry. The overall format in BNF: 28 with a backslash character @samp{\}, the multiline will be considered
29 a single mailcap entry. The overall format in @acronym{BNF}:
26 30
27 @smallexample 31 @smallexample
28 Mailcap-File = *Mailcap-Line 32 @group
29 Mailcap-Line = Comment | Mailcap-Entry 33 Mailcap-File = *@var{mailcap-line}
30 Comment = NEWLINE | "#" * CHAR NEWLINE 34 Mailcap-Line = @var{comment} | @var{mailcap-entry}
31 NEWLINE = <newline as defined by OS convention> 35 Comment = @var{newline} | "#" * @var{char} @var{newline}
36 Newline = <newline as defined by OS convention>
37 @end group
32 @end smallexample 38 @end smallexample
33 39
34 Each mailcap entry consists of a number of fields, separated by semi-colons. 40 Each mailcap entry consists of a number of fields, separated
35 The first two filds are required and must occur in the secified order, the remaining 41 by semi-colons. The first two filds are required and must occur
36 fields are optional. 42 in the secified order, the remaining fields are optional.
37 43
38 @smallexample 44 @smallexample
39 Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ] 45 Mailcap-Entry = @var{typefield} ";" @var{view-command} ";" *[ ";" @var{field} ]
40 @end smallexample 46 @end smallexample
41 47
42 @deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t 48 @deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t
43 The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects are used to hold information 49 The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects
44 and it is an opaque data structure to the user. Functions are provided to retrieve information 50 are used to hold information and it is an opaque data structure
51 to the user. Functions are provided to retrieve information
45 from the data structure. 52 from the data structure.
46 @end deftp 53 @end deftp
47 54
48 @smallexample 55 @smallexample
49 @group 56 @group
50 mu_mailcap_t mu_mailcap_entry_t 57 mu_mailcap_t mu_mailcap_entry_t
51 -/etc/mailcap- +----->/------------------------\ +-->/--------------------\ 58 -/etc/mailcap- +--->/------------------------\ +-->/------------------\
52 ( alain ) | mu_mailcap_entry[0]*--|----+ | typefield | 59 ( alain ) | mu_mailcap_entry[0]*--|--+ | typefield |
53 | mu_mailcap_entry[1] | | view-command | 60 | mu_mailcap_entry[1] | | view-command |
54 | ..... | | field[0] | 61 | ..... | | field[0] |
55 | mu_mailcap_entry[n] | | ..... | 62 | mu_mailcap_entry[n] | | ..... |
56 \------------------------/ | field[n] | 63 \------------------------/ | field[n] |
57 \--------------------/ 64 \------------------/
58 @end group 65 @end group
59 @end smallexample 66 @end smallexample
60 67
61 @subheading An example of parsing a mailcap file: 68 @subheading An Example of Parsing a Mailcap File:
62 @smallexample 69 @smallexample
63 @include mailcap.inc 70 @include mailcap.inc
64 @end smallexample 71 @end smallexample
...@@ -68,32 +75,26 @@ The function allocates, parses the buffer from the @var{stream} and initializes ...@@ -68,32 +75,26 @@ The function allocates, parses the buffer from the @var{stream} and initializes
68 The return value is @code{0} on success and a code number on error conditions: 75 The return value is @code{0} on success and a code number on error conditions:
69 @table @code 76 @table @code
70 @item MU_ERROR_INVALID_PARAMETER 77 @item MU_ERROR_INVALID_PARAMETER
71 @var{mailcap} is null or @var{stream} is invalid. 78 @var{mailcap} is @code{NULL} or @var{stream} is invalid.
72 @end table 79 @end table
73 @end deftypefun 80 @end deftypefun
74 81
75 @deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap}) 82 @deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap})
76 Release any resources from the mailcap object. 83 Release any resources from the mailcap object.
77 @end deftypefun 84 @end deftypefun
78 85
79 @deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count}) 86 @deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count})
80 The function returns the number of entries found in the mailcap. 87 The function returns the number of entries found in the mailcap.
81 The return value is @code{0} on success and a code number on error conditions: 88 The return value is @code{0} on success and a code number on error conditions:
82 @table @code 89 @table @code
83 90
84 @item EINVAL 91 @item EINVAL
85 @var{mailcap} or @var{count} is null. 92 @var{mailcap} or @var{count} is @code{NULL}.
86 @end table 93 @end table
87 @end deftypefun 94 @end deftypefun
88 95
89 @deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t no, mu_mailcap_entry_t*@var{entry}) 96 @deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t @var{no}, mu_mailcap_entry_t *@var{entry})
90 Returns in @var{entry} the mailcap entry of @var{no} 97 Returns in @var{entry} the mailcap entry of @var{no}.
91 @end deftypefun
92
93 @deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
94 @end deftypefun
95
96 @deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
97 @end deftypefun 98 @end deftypefun
98 99
99 @deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count}) 100 @deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count})
...@@ -102,9 +103,62 @@ The return value is @code{0} on success and a code number on error conditions: ...@@ -102,9 +103,62 @@ The return value is @code{0} on success and a code number on error conditions:
102 @table @code 103 @table @code
103 104
104 @item EINVAL 105 @item EINVAL
105 @var{entry} or @var{count} is null. 106 @var{entry} or @var{count} is @code{NULL}.
106 @end table 107 @end table
107 @end deftypefun 108 @end deftypefun
108 109
109 @deftypefun int mu_mailcap_entry_get_field (mu_mailcap_entry_t @var{entry}, size_t @var{no}, char * @var{buffer}, size_t @var{buflen}, size_t * @var{pn}) 110 @deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
111 @end deftypefun
112
113 @deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
114 @end deftypefun
115
116 @deftypefun int mu_mailcap_entry_get_field (mu_mailcap_entry_t @var{entry}, size_t @var{no}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
117 @end deftypefun
118
119 @deftypefun int mu_mailcap_entry_get_value (mu_mailcap_entry_t @var{entry}, const char *@var{key}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
120 @end deftypefun
121
122 @deftypefun int mu_mailcap_entry_get_compose (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
123 Helper function saving in buffer, the argument of "compose" field.
124 @end deftypefun
125
126 @deftypefun int mu_mailcap_entry_get_composetyped (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
127 Helper function saving in buffer, the argument of "composetyped" field.
128 @end deftypefun
129
130 @deftypefun int mu_mailcap_entry_get_edit (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
131 Helper function saving in buffer, the argument of "edit" field.
132 @end deftypefun
133
134 @deftypefun int mu_mailcap_entry_get_textualnewlines (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
135 Helper function saving in buffer, the argument of "textualnewlines" field.
136 @end deftypefun
137
138 @deftypefun int mu_mailcap_entry_get_test (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
139 Helper function saving in buffer, the argument of "test" field.
140 @end deftypefun
141
142 @deftypefun int mu_mailcap_entry_get_x11bitmap (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
143 Helper function saving in buffer, the argument of "x11-bitmap" field.
144 @end deftypefun
145
146 @deftypefun int mu_mailcap_entry_get_description (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
147 Helper function saving in buffer, the argument of "description" field.
148 @end deftypefun
149
150 @deftypefun int mu_mailcap_entry_get_nametemplate (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
151 Helper function saving in buffer, the argument of "nametemplate" field.
152 @end deftypefun
153
154 @deftypefun int mu_mailcap_entry_get_notes (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
155 Helper function saving in buffer, the argument of "notes" field.
156 @end deftypefun
157
158 @deftypefun int mu_mailcap_entry_needsterminal (mu_mailcap_entry_t @var{entry}, int *@var{on})
159 Helper function. Returns *@var{on} != 0 if the flag "needsterminal" is in the record.
160 @end deftypefun
161
162 @deftypefun int mu_mailcap_entry_copiousoutput (mu_mailcap_entry_t @var{entry}, int *@var{on})
163 Helper function. Returns *@var{on} != 0 if the flag "copiousoutput" is in the record.
110 @end deftypefun 164 @end deftypefun
......
...@@ -4,64 +4,69 @@ ...@@ -4,64 +4,69 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{mailer_} is reserved */} 7 @code{/* Prefix @emph{mailer_} is reserved. */}
8 @code{#include <mailutils/mailer.h>} 8 @code{#include <mailutils/mailer.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 The API is still changing. 12 @c
13 @c Constructor/Destructor.
14 @c
13 15
14 @deftypefun int mailer_create (mailer_t *, const char *) 16 @deftypefun int mailer_create (mailer_t *, const char *@var{url})
15 @end deftypefun 17 @end deftypefun
16 18
17 @deftypefun void mailer_destroy (mailer_t *) 19 @deftypefun void mailer_destroy (mailer_t *)
18 @end deftypefun 20 @end deftypefun
19 21
20 @deftypefun int mailer_open (mailer_t, int flags) 22 @deftypefun int mailer_open (mailer_t, int @var{flags})
21 @end deftypefun 23 @end deftypefun
22 24
23 @deftypefun int mailer_close (mailer_t) 25 @deftypefun int mailer_close (mailer_t)
24 @end deftypefun 26 @end deftypefun
25 27
26 @deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to}); 28 @deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to});
27 29
28 If from is not @var{NULL}, it must contain a single fully qualified 30 If @var{from} is not @code{NULL}, it must contain a single fully qualified
29 RFC2822 email address which will be used as the envelope from 31 RFC2822 email address which will be used as the envelope from
30 address. This is the address to which delivery status notifications 32 address. This is the address to which delivery status notifications
31 are sent, so it never matters what it is set to until it REALLY matters. 33 are sent, so it never matters what it is set to until it @strong{really}
32 This is equivalent to sendmail's @var{-f} flag. 34 matters. This is equivalent to Sendmail's @option{-f} flag.
33 35
34 The default for @var{from} is provided by the specific mailer. 36 The default for @var{from} is provided by the specific mailer.
35 37
36 If to is not @var{NULL}, then the message will be sent to the list of 38 If to is not @code{NULL}, then the message will be sent to the list of
37 addresses that it specifies. 39 addresses that it specifies.
38 40
39 The default for @var{to} is to use the contents of the standard "To:", "Cc:", 41 The default for @var{to} is to use the contents of the standard "To:", "Cc:",
40 and "Bcc:" fields, this is equivalent to sendmail's @var{-t} flag. 42 and "Bcc:" fields, this is equivalent to Sendmail's @option{-t} flag.
43 @end deftypefun
44
45 @deftypefun int mailer_get_property (mailer_t, property_t *)
46 @end deftypefun
41 47
42 Note: the previous implementation of mailer_send_message() was equivalent 48 @deftypefun int mailer_get_stream (mailer_t, stream_t *)
43 to having both @var{from} and @var{to} be @var{NULL}.
44 @end deftypefun 49 @end deftypefun
45 50
46 @deftypefun int mailer_get_property (mailer_t, property_t *) 51 @deftypefun int mailer_set_stream (mailer_t, stream_t)
47 @end deftypefun 52 @end deftypefun
48 53
49 @deftypefun int mailer_get_stream (mailer_t, stream_t *) 54 @deftypefun int mailer_get_debug (mailer_t, mu_debug_t *)
50 @end deftypefun 55 @end deftypefun
51 56
52 @deftypefun int mailer_set_stream (mailer_t, stream_t) 57 @deftypefun int mailer_set_debug (mailer_t, mu_debug_t)
53 @end deftypefun 58 @end deftypefun
54 59
55 @deftypefun int mailer_get_debug (mailer_t, debug_t *) 60 @deftypefun int mailer_get_observable (mailer_t, observable_t *)
56 @end deftypefun 61 @end deftypefun
57 62
58 @deftypefun int mailer_set_debug (mailer_t, debug_t) 63 @deftypefun int mailer_get_url (mailer_t, url_t *)
59 @end deftypefun 64 @end deftypefun
60 65
61 @deftypefun int mailer_get_observable (mailer_t, observable_t *) 66 @deftypefun int mailer_check_from (address_t @var{from})
62 @end deftypefun 67 @end deftypefun
63 68
64 @deftypefun int mailer_get_url (mailer_t, url_t *) 69 @deftypefun int mailer_check_to (address_t @var{to})
65 @end deftypefun 70 @end deftypefun
66 71
67 @sp 1 72 @sp 1
...@@ -73,71 +78,74 @@ Some possible use cases the API must support are: ...@@ -73,71 +78,74 @@ Some possible use cases the API must support are:
73 78
74 1 - fill in header addresses 79 1 - fill in header addresses
75 80
76 2 - mailer_send_message(mailer, msg, NULL, NULL); 81 2 - @code{mailer_send_message(mailer, msg, NULL, NULL)}
77 82
78 - from will be filled in if missing, 83 - from will be filled in if missing,
79 84
80 - bcc's will be deleted before delivery to a non-bcc address, 85 - Bcc's will be deleted before delivery to a non-bcc address,
81 86
82 - message-id and date will be added, if missing, 87 - message-id and date will be added, if missing,
83 88
84 - a to: or apparently-to: will be added if non is present (for RFC 89 - a To: or Apparently-To: will be added if non is present (for RFC
85 compliance) 90 compliance)
86 91
87 - MTA-style .forward ( and sieve-style redirect ) 92 - MTA-style @file{.forward} (and Sieve-style redirect)
88 93
89 1 - get the envelope from of the message to be forwarded 94 1 - get the envelope from of the message to be forwarded
90 95
91 2 - mailer_send_message(mailer, msg, from, to) 96 2 - @code{mailer_send_message(mailer, msg, from, to)}
92 97
93 - MUA-style bounce 98 - MUA-style bounce
94 99
95 1 - add Resent-[to,from,....] 100 1 - add Resent-[To,From,...]
96 101
97 2 - mailer_send_message(mailer, msg, NULL, to) 102 2 - @code{mailer_send_message(mailer, msg, NULL, to)}
98 103
99 - DSN "bounce" 104 - DSN "bounce"
100 105
101 1 - compose DSN 106 1 - compose DSN
102 107
103 2 - mailer_deliver(mailer, msg, address_t( "<>" ), to) 108 2 - @code{mailer_deliver(mailer, msg, address_t("<>"), to)}
104 109
105 Don't want mail loops, so the null but valid SMTP address of <> is 110 Don't want mail loops, so the null but valid SMTP address of @samp{<>}
106 the envelope from. 111 is the envelope From.
107 112
108 @subheading The Sendmail Mailer 113 @subheading The Sendmail Mailer
109 114
110 @file{/sbin/sendmail} isn't always sendmail... sometimes its a 115 @file{/sbin/sendmail} isn't always Sendmail... Sometimes it's a
111 sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands 116 Sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands
112 only a recipient list, @option{-f} and @option{-oi}, these seem 117 only a recipient list, @option{-f} and @option{-oi}, these seem
113 to be pretty basic. Cross fingers. 118 to be pretty basic. Cross fingers.
114 119
115 Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying @option{-f} 120 Pipe to "/sbin/sendmail -oi [-f @var{from}] [@var{to}...]", supplying
116 if there was a from, and supplying the recipient list from the to 121 @option{-f} if there was a from, and supplying the recipient list from
117 (if there is no recipient list, assume it will read the message 122 the to (if there is no recipient list, assume it will read the message
118 contents for the recipients). 123 contents for the recipients).
119 124
120 Note: since the stdout and stderr of sendmail is closed, we have no 125 @strong{Caution:} since the @code{stdout} and @code{stderr} of Sendmail
121 way of ever giving feedback on failure. Also, what should the return 126 is closed, we have no way of ever giving feedback on failure. Also, what
122 code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM, 127 should the return code be from @code{mailer_send_message()} when Sendmail
123 which is less than descriptive! 128 returns @samp{1}? @samp{1} maps to @code{EPERM}, which is less than
129 descriptive!
124 130
125 @subheading The SMTP Mailer 131 @subheading The SMTP Mailer
126 132
127 This mailer does NOT canonicalize the message. This must be done before 133 This mailer does @strong{not} canonicalize the message. This must be
128 sending the message, or it may be assumed that the MTA will do so. 134 done before sending the message, or it may be assumed that the MTA
135 will do so.
129 136
130 It does blind out the Bcc: header before sending, though. 137 It does blind out the Bcc: header before sending, though.
131 138
132 Note: mutt always puts the recipient addresses on the command line, even 139 @strong{Caution:} Mutt always puts the recipient addresses on the
133 bcc ones, do we strip the bcc before forwarding with SMTP? 140 command line, even Bcc: ones, do we strip the Bcc: before forwarding
141 with SMTP?
134 142
135 @subheading Non-RFC822 Addresses 143 @subheading Non-RFC822 Addresses
136 144
137 An address that has no domain is not and RFC822 email address. What 145 An address that has no domain is not and RFC822 email address. What
138 do I do with them? Should the user of the API be responsible for 146 do I do with them? Should the user of the API be responsible for
139 determining what is mean by email to "john" means? Or should the 147 determining what is mean by email to "John" means? Or should the
140 be able to configure sendmail to decide globally what this means. 148 be able to configure Sendmail to decide globally what this means.
141 If so, we can pass the address to sendmail, but we have to decide 149 If so, we can pass the address to Sendmail, but we have to decide
142 for SMTP! So, right now these addresses are rejected. 150 for SMTP! So, right now these addresses are rejected.
143 This could be changed. 151 This could be changed.
......
...@@ -4,7 +4,7 @@ ...@@ -4,7 +4,7 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{message_} is reserve */} 7 @code{/* Prefix @emph{message_} is reserved. */}
8 @code{#include <mailutils/message.h>} 8 @code{#include <mailutils/message.h>}
9 9
10 @end smallexample 10 @end smallexample
...@@ -15,21 +15,25 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}. ...@@ -15,21 +15,25 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
15 @smallexample 15 @smallexample
16 @group 16 @group
17 mailbox_t 17 mailbox_t
18 __________ message_t 18 ---------- message_t
19 (message[1]) +------>+-----------------------+ 19 (message[1]) +------>+--------------------+
20 ---------- | | envelope_t | 20 ---------- | | envelope_t |
21 (message[2]) | |-----------------------| 21 (message[2]) | |--------------------|
22 ---------- | | header_t | 22 ---------- | | header_t |
23 (message[3])--------+ |-----------------------| 23 (message[3])--------+ |--------------------|
24 ---------- | body_t | 24 ---------- | body_t |
25 (message[n]) |-----------------------| 25 (message[n]) |--------------------|
26 ---------- | attribute_t | 26 ---------- | attribute_t |
27 |-----------------------| 27 |--------------------|
28 | stream_t | 28 | stream_t |
29 +-----------------------+ 29 +--------------------+
30 @end group 30 @end group
31 @end smallexample 31 @end smallexample
32 32
33 @c
34 @c Basic.
35 @c
36
33 @deftypefun void message_create (message_t *@var{msg}, void *@var{owner}) 37 @deftypefun void message_create (message_t *@var{msg}, void *@var{owner})
34 @end deftypefun 38 @end deftypefun
35 39
...@@ -37,67 +41,129 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}. ...@@ -37,67 +41,129 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
37 The resources allocate for @var{msg} are freed. 41 The resources allocate for @var{msg} are freed.
38 @end deftypefun 42 @end deftypefun
39 43
40 @deftypefun int message_get_header (message_t @var{msg}, header_t *@var{pheader}) 44 @deftypefun int message_create_copy (message_t *@var{to}, message_t *@var{from})
45 @end deftypefun
46
47 @deftypefun void* message_get_owner (message_t @var{msg})
48 @end deftypefun
49
50 @deftypefun int message_is_modified (message_t @var{msg})
51 @end deftypefun
52
53 @deftypefun int message_clear_modified (message_t @var{msg})
54 @end deftypefun
55
56 @deftypefun int message_get_mailbox (message_t @var{msg}, mailbox_t *@var{mbox})
57 @end deftypefun
58
59 @deftypefun int message_set_mailbox (message_t @var{msg}, mailbox_t @var{mbox}, void *@var{owner})
60 @end deftypefun
61
62 @c
63 @c ------------
64 @c
65
66 @deftypefun int message_ref (message_t @var{msg})
67 @end deftypefun
68
69 @deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *@var{envelope})
70 @end deftypefun
71
72 @deftypefun int message_set_envelope (message_t @var{msg}, envelope_t @var{envelope}, void *@var{owner})
73 @end deftypefun
74
75 @deftypefun int message_get_header (message_t @var{msg}, header_t *@var{header})
41 Retrieve @var{msg} header. 76 Retrieve @var{msg} header.
42 @end deftypefun 77 @end deftypefun
43 78
44 @deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner}) 79 @deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner})
80 @end deftypefun
81
82 @deftypefun int message_get_body (message_t @var{msg}, body_t *@var{body})
83 @end deftypefun
84
85 @deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner})
86 @end deftypefun
87
88 @deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{stream})
89 @end deftypefun
90
91 @deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream}, void *@var{owner})
92 @end deftypefun
93
94 @deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{attribute})
95 @end deftypefun
96
97 @deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *@var{owner})
98 @end deftypefun
99
100 @deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable})
101 @end deftypefun
102
103 @c
104 @c ------------
105 @c
106
107 @deftypefun int message_is_multipart (message_t @var{msg}, int *@var{multi})
108 Set *@var{multi} to non-zero value if @var{msg} is multi-part.
109 @end deftypefun
110
111 @deftypefun int message_set_is_multipart (message_t @var{msg}, int (*@var{_is_multipart}) (message_t, int *), void *);
45 @end deftypefun 112 @end deftypefun
46 113
47 @deftypefun int message_get_body (message_t @var{msg}, body_t *@var{pbody}) 114 @deftypefun int message_size (message_t @var{msg}, size_t *@var{size})
48 @end deftypefun 115 @end deftypefun
49 116
50 @deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner}) 117 @deftypefun int message_set_size (message_t @var{msg}, int (*@var{_size}) (message_t, size_t *), void *@var{owner})
51 @end deftypefun 118 @end deftypefun
52 119
53 @deftypefun int message_is_multipart (message_t @var{msg}, int *@var{pmulti}) 120 @deftypefun int message_lines (message_t @var{msg}, size_t *@var{size})
54 Set *@var{pmulti} to non-zero value if @var{msg} is multi-part.
55 @end deftypefun 121 @end deftypefun
56 122
57 @deftypefun int message_get_num_parts (message_t @var{msg}, size_t *nparts) 123 @deftypefun int message_set_lines (message_t @var{msg}, int (*@var{_lines}) (message_t, size_t *), void *@var{owner})
58 @end deftypefun 124 @end deftypefun
59 125
60 @deftypefun int message_get_part (message_t @var{msg}, size_t part, message_t *msg) 126 @deftypefun int message_get_num_parts (message_t @var{msg}, size_t *@var{nparts})
61 @end deftypefun 127 @end deftypefun
62 128
63 @deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{pstream}) 129 @deftypefun int message_set_get_num_parts (message_t @var{msg}, int (*@var{_get_num_parts}) (message_t, size_t *), void *@var{owner})
64 @end deftypefun 130 @end deftypefun
65 131
66 @deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream},void *@var{owner} ) 132 @deftypefun int message_get_part (message_t @var{msg}, size_t @var{part}, message_t *@var{msg})
67 @end deftypefun 133 @end deftypefun
68 134
69 @deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{pattribute}) 135 @deftypefun int message_set_get_part (message_t @var{msg}, int (*@var{_get_part}) (message_t, size_t, message_t *), void *@var{owner})
70 @end deftypefun 136 @end deftypefun
71 137
72 @deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *owner) 138 @deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
73 @end deftypefun 139 @end deftypefun
74 140
75 @deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *penvelope) 141 @deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl}) (message_t, char *, size_t, size_t *), void *@var{owner})
76 @end deftypefun 142 @end deftypefun
77 143
78 @deftypefun int message_set_envelope (message_t @var{msg}, envelope_t envelope, void *@var{owner}) 144 @deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid})
79 @end deftypefun 145 @end deftypefun
80 146
81 @deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid}) 147 @deftypefun int message_set_uid (message_t @var{msg}, int (*@var{_get_uid}) (message_t, size_t *), void *@var{owner})
82 @end deftypefun 148 @end deftypefun
83 149
84 @deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten}) 150 @deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg})
85 @end deftypefun 151 @end deftypefun
86 152
87 @deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl})(message_t, char *, size_t, size_t *), void *@var{owner}) 153 @deftypefun int message_save_attachment (message_t @var{msg}, const char *@var{filename}, void **@var{data})
88 @end deftypefun 154 @end deftypefun
89 155
90 @deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable}) 156 @deftypefun int message_encapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data})
91 @end deftypefun 157 @end deftypefun
92 158
93 @deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg}) 159 @deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data});
94 @end deftypefun 160 @end deftypefun
95 161
96 @deftypefun int message_save_attachment (message_t @var{msg}, const char *@var{filename}, void **@var{data}) 162 @deftypefun int message_get_attachment_name (message_t @var{msg}, char *@var{name}, size_t @var{bufsize}, size_t *@var{size});
97 @end deftypefun 163 @end deftypefun
98 164
99 @deftypefun int message_encapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}) 165 @deftypefun int message_aget_attachment_name (message_t @var{msg}, char **@var{name});
100 @end deftypefun 166 @end deftypefun
101 167
102 @deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}); 168 @deftypefun int message_save_to_mailbox (message_t @var{msg}, ticket_t @var{ticket}, mu_debug_t @var{debug}, const char *@var{toname});
103 @end deftypefun 169 @end deftypefun
......
...@@ -4,60 +4,157 @@ ...@@ -4,60 +4,157 @@
4 @comment ******************************************************************* 4 @comment *******************************************************************
5 5
6 @smallexample 6 @smallexample
7 @code{/* Prefix @emph{parse822_} is reserved */} 7 @code{/* Prefix @emph{parse822_} is reserved. */}
8 @code{#include <mailutils/parse822.h>} 8 @code{#include <mailutils/parse822.h>}
9 9
10 @end smallexample 10 @end smallexample
11 11
12 Internet Message Format, see Address node for the discussion. 12 @deftypefun int parse822_is_char (char @var{c})
13 @end deftypefun
14
15 @deftypefun int parse822_is_digit (char @var{c})
16 @end deftypefun
17
18 @deftypefun int parse822_is_ctl (char @var{c})
19 @end deftypefun
20
21 @deftypefun int parse822_is_space (char @var{c})
22 @end deftypefun
23
24 @deftypefun int parse822_is_htab (char @var{c})
25 @end deftypefun
26
27 @deftypefun int parse822_is_lwsp_char (char @var{c})
28 @end deftypefun
29
30 @deftypefun int parse822_is_special (char @var{c})
31 @end deftypefun
32
33 @deftypefun int parse822_is_atom_char (char @var{c})
34 @end deftypefun
35
36 @deftypefun int parse822_is_q_text (char @var{c})
37 @end deftypefun
38
39 @deftypefun int parse822_is_d_text (char @var{c})
40 @end deftypefun
41
42 @deftypefun int parse822_is_smtp_q (char @var{c})
43 @end deftypefun
44
45 @deftypefun int parse822_skip_crlf (const char **@var{p}, const char *@var{e})
46 @end deftypefun
47
48 @deftypefun int parse822_skip_lwsp_char (const char **@var{p}, const char *@var{e})
49 @end deftypefun
50
51 @deftypefun int parse822_skip_lwsp (const char **@var{p}, const char *@var{e})
52 @end deftypefun
53
54 @deftypefun int parse822_skip_comments (const char **@var{p}, const char *@var{e})
55 @end deftypefun
56
57 @deftypefun int parse822_skip_nl (const char **@var{p}, const char *@var{e})
58 @end deftypefun
59
60 @deftypefun int parse822_digits (const char **@var{p}, const char *@var{e}, int @var{min}, int @var{max}, int *@var{digits})
61 @end deftypefun
62
63 @deftypefun int parse822_special (const char **@var{p}, const char *@var{e}, char @var{c})
64 @end deftypefun
65
66 @deftypefun int parse822_comment (const char **@var{p}, const char *@var{e}, char **@var{comment})
67 @end deftypefun
68
69 @deftypefun int parse822_atom (const char **@var{p}, const char *@var{e}, char **@var{atom})
70 @end deftypefun
71
72 @deftypefun int parse822_quoted_pair (const char **@var{p}, const char *@var{e}, char **@var{qpair})
73 @end deftypefun
74
75 @deftypefun int parse822_quoted_string (const char **@var{p}, const char *@var{e}, char **@var{qstr})
76 @end deftypefun
77
78 @deftypefun int parse822_word (const char **@var{p}, const char *@var{e}, char **@var{word})
79 @end deftypefun
13 80
14 @deftypefun int parse822_address_list (address_t* a, const char* s) 81 @deftypefun int parse822_phrase (const char **@var{p}, const char *@var{e}, char **@var{phrase})
15 @end deftypefun 82 @end deftypefun
16 83
17 @deftypefun int parse822_mail_box (const char** p, const char* e, address_t* a) 84 @deftypefun int parse822_d_text (const char **@var{p}, const char *@var{e}, char **@var{dtext})
18 @end deftypefun 85 @end deftypefun
19 86
20 @deftypefun int parse822_group (const char** p, const char* e, address_t* a) 87 @c
88 @c From RFC 822, 6.1 Address Specification Syntax
89 @c
90
91 @deftypefun int parse822_address_list (address_t *@var{a}, const char *@var{s})
92 @end deftypefun
93
94 @deftypefun int parse822_mail_box (const char **@var{p}, const char *@var{e}, address_t *@var{a})
95 @end deftypefun
96
97 @deftypefun int parse822_group (const char **@var{p}, const char *@var{e}, address_t *@var{a})
98 @end deftypefun
99
100 @deftypefun int parse822_address (const char **@var{p}, const char *@var{e}, address_t *@var{a})
21 @end deftypefun 101 @end deftypefun
22 102
23 @deftypefun int parse822_address (const char** p, const char* e, address_t* a) 103 @deftypefun int parse822_route_addr (const char **@var{p}, const char *@var{e}, address_t *@var{a})
24 @end deftypefun 104 @end deftypefun
25 105
26 @deftypefun int parse822_route_addr (const char** p, const char* e, address_t* a) 106 @deftypefun int parse822_route (const char **@var{p}, const char *@var{e}, char **@var{route})
27 @end deftypefun 107 @end deftypefun
28 108
29 @deftypefun int parse822_route (const char** p, const char* e, char** route) 109 @deftypefun int parse822_addr_spec (const char **@var{p}, const char *@var{e}, address_t *@var{a})
30 @end deftypefun 110 @end deftypefun
31 111
32 @deftypefun int parse822_addr_spec (const char** p, const char* e, address_t* a) 112 @deftypefun int parse822_unix_mbox (const char **@var{p}, const char *@var{e}, address_t *@var{a})
33 @end deftypefun 113 @end deftypefun
34 114
35 @deftypefun int parse822_unix_mbox (const char** p, const char* e, address_t* a) 115 @deftypefun int parse822_local_part (const char **@var{p}, const char *@var{e}, char **@var{local_part})
36 @end deftypefun 116 @end deftypefun
37 117
38 @deftypefun int parse822_local_part (const char** p, const char* e, char** local_part) 118 @deftypefun int parse822_domain (const char **@var{p}, const char *@var{e}, char **@var{domain})
39 @end deftypefun 119 @end deftypefun
40 120
41 @deftypefun int parse822_domain (const char** p, const char* e, char** domain) 121 @deftypefun int parse822_sub_domain (const char **@var{p}, const char *@var{e}, char **@var{sub_domain})
42 @end deftypefun 122 @end deftypefun
43 123
44 @deftypefun int parse822_sub_domain (const char** p, const char* e, char** sub_domain) 124 @deftypefun int parse822_domain_ref (const char **@var{p}, const char *@var{e}, char **@var{domain_ref})
45 @end deftypefun 125 @end deftypefun
46 126
47 @deftypefun int parse822_domain_ref (const char** p, const char* e, char** domain_ref) 127 @deftypefun int parse822_domain_literal (const char **@var{p}, const char *@var{e}, char **@var{domain_literal})
48 @end deftypefun 128 @end deftypefun
49 129
50 @deftypefun int parse822_domain_literal (const char** p, const char* e, char** domain_literal) 130 @c
131 @c RFC 822 Quoting Functions
132 @c
133
134 @deftypefun int parse822_quote_string (char **@var{quoted}, const char *@var{raw})
51 @end deftypefun 135 @end deftypefun
52 136
53 @deftypefun int parse822_quote_string (char** quoted, const char* raw) 137 @deftypefun int parse822_quote_local_part (char **@var{quoted}, const char *@var{raw})
138 @end deftypefun
139
140 @deftypefun int parse822_field_body (const char **@var{p}, const char *@var{e}, char **@var{fieldbody})
141 @end deftypefun
142
143 @deftypefun int parse822_field_name (const char **@var{p}, const char *@var{e}, char **@var{fieldname})
144 @end deftypefun
145
146 @c
147 @c From RFC 822, 5.1 Date and Time Specification Syntax
148 @c
149
150 @deftypefun int parse822_day (const char **@var{p}, const char *@var{e}, int *@var{day})
54 @end deftypefun 151 @end deftypefun
55 152
56 @deftypefun int parse822_quote_local_part (char** quoted, const char* raw) 153 @deftypefun int parse822_date (const char **@var{p}, const char *@var{e}, int *@var{day}, int *@var{mon}, int *@var{year})
57 @end deftypefun 154 @end deftypefun
58 155
59 @deftypefun int parse822_field_body (const char** p, const char *e, char** fieldbody) 156 @deftypefun int parse822_time (const char **@var{p}, const char *@var{e}, int *@var{h}, int *@var{m}, int *@var{s}, int *@var{tz}, const char **@var{tz_name})
60 @end deftypefun 157 @end deftypefun
61 158
62 @deftypefun int parse822_field_name (const char** p, const char *e, char** fieldname) 159 @deftypefun int parse822_date_time (const char **@var{p}, const char *@var{e}, struct tm *@var{tm}, mu_timezone *@var{tz})
63 @end deftypefun 160 @end deftypefun
......
...@@ -33,80 +33,116 @@ The stream is set non blocking. ...@@ -33,80 +33,116 @@ The stream is set non blocking.
33 @item MU_STREAM_NO_CHECK 33 @item MU_STREAM_NO_CHECK
34 @findex MU_STREAM_NO_CHECK 34 @findex MU_STREAM_NO_CHECK
35 Stream is destroyed without checking for the owner. 35 Stream is destroyed without checking for the owner.
36 @item MU_STREAM_SEEKABLE
37 @findex MU_STREAM_SEEKABLE
38
36 @item MU_STREAM_NO_CLOSE 39 @item MU_STREAM_NO_CLOSE
37 @findex MU_STREAM_NO_CLOSE 40 @findex MU_STREAM_NO_CLOSE
38 Stream doesn't close it's underlying resource when it is closed or destroyed. 41 Stream doesn't close it's underlying resource when it is closed or destroyed.
42 @item MU_STREAM_ALLOW_LINKS
43 @findex MU_STREAM_ALLOW_LINKS
44
39 @end table 45 @end table
40 46
41 @deftypefun int file_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 47 @deftypefun int file_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
42 @end deftypefun 48 @end deftypefun
43 49
44 @deftypefun int tcp_stream_create (stream_t *@var{pstream}, const char *@var{host}, int @var{port}, int @var{flags}) 50 @deftypefun int tcp_stream_create (stream_t *@var{stream}, const char *@var{host}, int @var{port}, int @var{flags})
45 @end deftypefun 51 @end deftypefun
46 52
47 @deftypefun int mapfile_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 53 @deftypefun int mapfile_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
48 @end deftypefun 54 @end deftypefun
49 55
50 @deftypefun int memory_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags}) 56 @deftypefun int memory_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
51 @end deftypefun 57 @end deftypefun
52 58
53 @deftypefun int encoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding}) 59 @deftypefun int encoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
54 @end deftypefun 60 @end deftypefun
55 61
56 @deftypefun int decoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding}) 62 @deftypefun int decoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
57 @end deftypefun 63 @end deftypefun
58 64
59 @deftypefun int stdio_stream_create (stream_t *@var{pstream}, FILE* @var{stdio}, int @var{flags}) 65 @deftypefun int stdio_stream_create (stream_t *@var{stream}, FILE *@var{stdio}, int @var{flags})
60 If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on 66 If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
61 @var{stdio} when the stream is closed. 67 @var{stdio} when the stream is closed.
62 @end deftypefun 68 @end deftypefun
63 69
64 @deftypefun void stream_destroy (stream_t *@var{pstream}, void *@var{owner}) 70 @deftypefun int prog_stream_create (stream_t *@var{stream}, char *@var{progname}, int @var{flags})
65 @end deftypefun 71 @end deftypefun
66 72
67 @deftypefun int stream_open (stream_t @var{stream}) 73 @deftypefun int filter_prog_stream_create (stream_t *@var{stream}, char *@var{progname}, stream_t @var{input})
68 @end deftypefun 74 @end deftypefun
69 75
70 @deftypefun int stream_close (stream_t @var{stream}) 76 @deftypefun void stream_destroy (stream_t *@var{stream}, void *@var{owner})
71 @end deftypefun 77 @end deftypefun
72 78
73 @deftypefun int stream_is_seekable (stream_t @var{stream}) 79 @c
80 @c ---------
81 @c
82
83 @deftypefun int stream_open (stream_t @var{stream})
74 @end deftypefun 84 @end deftypefun
75 85
76 @deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd}) 86 @deftypefun int stream_close (stream_t @var{stream})
77 @end deftypefun 87 @end deftypefun
78 88
79 @deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 89 @deftypefun int stream_is_seekable (stream_t @var{stream})
80 @end deftypefun 90 @end deftypefun
81 91
82 @deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 92 @deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{fd})
83 @end deftypefun 93 @end deftypefun
84 94
85 @deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize}) 95 @deftypefun int stream_get_fd2 (stream_t @var{stream}, int *@var{fd1}, int *@var{fd2})
86 @end deftypefun 96 @end deftypefun
87 97
88 @deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size}) 98 @deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
89 @end deftypefun 99 @end deftypefun
90 100
91 @deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) 101 @deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
92 @end deftypefun 102 @end deftypefun
93 103
94 @deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size}) 104 @deftypefun int stream_size (stream_t @var{stream}, off_t *@var{size})
95 @end deftypefun 105 @end deftypefun
96 106
97 @deftypefun int stream_flush (stream_t @var{stream}) 107 @deftypefun n int stream_truncate (stream_t @var{stream}, off_t @var{size})
98 @end deftypefun 108 @end deftypefun
99 109
100 These functions will typically only be useful to implementors of streams. 110 @deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
111 @end deftypefun
101 112
102 @deftypefun int stream_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner}) 113 @deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size})
114 @end deftypefun
115
116 @deftypefun int stream_flush (stream_t @var{stream})
117 @end deftypefun
118
119 @c
120 @c These functions will typically only be useful to implementors of streams.
121 @c
122
123 @deftypefun int stream_create (stream_t *@var{stream}, int @var{flags}, void *@var{owner})
103 Used to implement a new kind of stream. 124 Used to implement a new kind of stream.
104 @end deftypefun 125 @end deftypefun
105 126
106 @deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{pflags}) 127 @deftypefun void* stream_get_owner (stream_t @var{stream})
128 @end deftypefun
129
130 @deftypefun void stream_set_owner (stream_t @var{stream}, void *@var{owner})
131 @end deftypefun
132
133 @deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{flags})
107 @end deftypefun 134 @end deftypefun
108 135
109 @deftypefun int stream_get_state (stream_t @var{stream}, int *@var{pstate}) 136 @deftypefun int stream_set_flags (stream_t @var{stream}, int @var{flags})
137 @end deftypefun
138
139 @deftypefun int stream_get_property (stream_t @var{stream}, property_t *)
140 @end deftypefun
141
142 @deftypefun int stream_set_property (stream_t @var{stream}, property_t, void *)
143 @end deftypefun
144
145 @deftypefun int stream_get_state (stream_t @var{stream}, int *@var{state})
110 @table @code 146 @table @code
111 @item MU_STREAM_STATE_OPEN 147 @item MU_STREAM_STATE_OPEN
112 Last action was @code{stream_open}. 148 Last action was @code{stream_open}.
...@@ -119,7 +155,52 @@ Last action was @code{stream_close}. ...@@ -119,7 +155,52 @@ Last action was @code{stream_close}.
119 @end table 155 @end table
120 @end deftypefun 156 @end deftypefun
121 157
122 An example using @code{tcp_stream_create} to make a simple web client: 158 @deftypefun int stream_set_destroy (stream_t @var{stream}, void (*@var{_destroy}) (stream_t), void *@var{owner})
159 @end deftypefun
160
161 @deftypefun int stream_set_open (stream_t @var{stream}, int (*@var{_open}) (stream_t), void *@var{owner})
162 @end deftypefun
163
164 @deftypefun int stream_set_close (stream_t @var{stream}, int (*@var{_close}) (stream_t), void *@var{owner})
165 @end deftypefun
166
167 @deftypefun int stream_set_fd (stream_t @var{stream}, int (*@var{_get_fd}) (stream_t, int *, int *), void *@var{owner})
168 @end deftypefun
169
170 @deftypefun int stream_set_read (stream_t @var{stream}, int (*@var{_read}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
171 @end deftypefun
172
173 @deftypefun int stream_set_readline (stream_t @var{stream}, int (*@var{_readline}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
174 @end deftypefun
175
176 @deftypefun int stream_set_size (stream_t @var{stream}, int (*@var{_size}) (stream_t, off_t *), void *@var{owner})
177 @end deftypefun
178
179 @deftypefun int stream_set_truncate (stream_t @var{stream}, int (*@var{_truncate}) (stream_t, off_t), void *@var{owner})
180 @end deftypefun
181
182 @deftypefun int stream_set_write (stream_t @var{stream}, int (*@var{_write}) (stream_t, const char *, size_t, off_t, size_t *), void *@var{owner})
183 @end deftypefun
184
185 @deftypefun int stream_set_flush (stream_t @var{stream}, int (*@var{_flush}) (stream_t), void *@var{owner})
186 @end deftypefun
187
188 @deftypefun int stream_set_strerror (stream_t @var{stream}, int (*@var{_fp}) (stream_t, char **), void *@var{owner})
189 @end deftypefun
190
191 @deftypefun int stream_sequential_readline (stream_ts @var{stream}, char *@var{buf}, size_t @var{size}, size_t *@var{nbytes})
192 @end deftypefun
193
194 @deftypefun int stream_sequential_write (stream_t @var{stream}, char *@var{buf}, size_t @var{size})
195 @end deftypefun
196
197 @deftypefun int stream_seek (stream_t @var{stream}, off_t @var{off}, int @var{whence})
198 @end deftypefun
199
200 @deftypefun int stream_strerror (stream_t @var{stream}, char **@var{p})
201 @end deftypefun
202
203 An example using @code{tcp_stream_create()} to make a simple web client:
123 204
124 @smallexample 205 @smallexample
125 @include http.inc 206 @include http.inc
......
...@@ -13,13 +13,15 @@ The POP URL scheme contains a POP server, optional port number ...@@ -13,13 +13,15 @@ The POP URL scheme contains a POP server, optional port number
13 and the authentication mechanism. The general form is 13 and the authentication mechanism. The general form is
14 14
15 @smallexample 15 @smallexample
16 @url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]} 16 @group
17 @url{pop://[<@var{user}>[;AUTH=<@var{auth}>]@@]<@var{host}>[:<@var{port}>]}
17 or 18 or
18 @url{pop://[<user>[:<passwd>]@@]<host>[:<port>]} 19 @url{pop://[<@var{user}>[:<@var{passwd}>]@@]<@var{host}>[:<@var{port}>]}
20 @end group
19 @end smallexample 21 @end smallexample
20 22
21 If @emph{:port} is omitted the default value is 110. Different forms of 23 If @emph{:port} is omitted the default value is 110. Different forms of
22 authentication can be specified with @emph{;AUTH=type}. 24 authentication can be specified with @emph{;AUTH=@var{type}}.
23 The special string @emph{;AUTH=*} indicates that the client will use 25 The special string @emph{;AUTH=*} indicates that the client will use
24 a default scheme base on the capability of the server. 26 a default scheme base on the capability of the server.
25 27
...@@ -35,16 +37,18 @@ For more complete information see @cite{RFC 2368}. ...@@ -35,16 +37,18 @@ For more complete information see @cite{RFC 2368}.
35 37
36 @subheading IMAP 38 @subheading IMAP
37 The IMAP URL scheme contains an IMAP server, optional port number 39 The IMAP URL scheme contains an IMAP server, optional port number
38 and the authentication mechanism. The general form is 40 and the authentication mechanism. The general form is
39 41
40 @smallexample 42 @smallexample
41 @url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]} 43 @group
44 @url{imap://[<@var{user}>[;AUTH=<@var{type}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
42 or 45 or
43 @url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]} 46 @url{imap://[<@var{user}>[:<@var{passwd}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
47 @end group
44 @end smallexample 48 @end smallexample
45 49
46 If @emph{:port} is omitted the default value is 220. Different forms of 50 If @emph{:port} is omitted the default value is 143. Different forms of
47 authentication can be specified with @emph{;AUTH=type}. 51 authentication can be specified with @emph{;AUTH=@var{type}}.
48 The special string @emph{;AUTH=*} indicates that the client will use 52 The special string @emph{;AUTH=*} indicates that the client will use
49 a default scheme base on the capability of the server. 53 a default scheme base on the capability of the server.
50 54
...@@ -63,17 +67,21 @@ the mailbox recognize the type of mailbox and take the appropriate ...@@ -63,17 +67,21 @@ the mailbox recognize the type of mailbox and take the appropriate
63 action. 67 action.
64 68
65 @smallexample 69 @smallexample
66 @url{file://path} 70 @group
71 @url{file://@var{path}}
67 @url{file://var/mail/user} 72 @url{file://var/mail/user}
68 @url{file://home/obelix/Mail} 73 @url{file://home/obelix/Mail}
74 @end group
69 @end smallexample 75 @end smallexample
70 76
71 For MMDF, MH local mailboxes URLs are provided, but it is preferable to 77 For MMDF, MH local mailboxes URLs are provided, but it is preferable to
72 use @url{file://path} and let the library figure out which one. 78 use @url{file://@var{path}} and let the library figure out which one.
73 79
74 @smallexample 80 @smallexample
75 @url{mmdf://path} 81 @group
76 @url{mh://path} 82 @url{mmdf://@var{path}}
83 @url{mh://@var{path}}
84 @end group
77 @end smallexample 85 @end smallexample
78 86
79 @subheading Mailto 87 @subheading Mailto
...@@ -82,7 +90,7 @@ After setting a mailer, @url{mailto:} is used to tell the mailer where ...@@ -82,7 +90,7 @@ After setting a mailer, @url{mailto:} is used to tell the mailer where
82 and to whom the message is for. 90 and to whom the message is for.
83 91
84 @smallexample 92 @smallexample
85 @url{mailto://hostname} 93 @url{mailto://@var{hostname}}
86 @end smallexample 94 @end smallexample
87 95
88 Mailto can be used to generate short messages, for example to subscribe 96 Mailto can be used to generate short messages, for example to subscribe
...@@ -95,70 +103,99 @@ to mailing lists. ...@@ -95,70 +103,99 @@ to mailing lists.
95 103
96 For more complete information see @cite{RFC 2368}. 104 For more complete information see @cite{RFC 2368}.
97 105
98 @subheading URL functions 106 @c
107 @c URL Functions
108 @c
109
110 @subheading URL Functions
99 111
100 Helper functions are provided to retrieve and set the @emph{URL} fields. 112 Helper functions are provided to retrieve and set the @emph{URL} fields.
101 113
102 @deftypefun int url_create (url_t *@var{url}, const char *@var{name}) 114 @deftypefun int url_create (url_t *@var{url}, const char *@var{name})
103 Create and the @var{url} data structure, but do not parse it. 115 Create the url data structure, but do not parse it.
104 @end deftypefun 116 @end deftypefun
105 117
106 @deftypefun void url_destroy (url_t *) 118 @deftypefun void url_destroy (url_t *@var{url})
107 Destroy the url and free it's resources. 119 Destroy the url and free its resources.
108 @end deftypefun 120 @end deftypefun
109 121
110 @deftypefun int url_parse (url_t @var{url}) 122 @deftypefun int url_parse (url_t)
111 Parses the url, after calling this the get functions can be called. 123 Parses the url, after calling this the get functions can be called.
112 124
113 The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth= 125 The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth=
114 of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is: 126 of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is:
115 127
116 @smallexample 128 @smallexample
129 @group
117 url = 130 url =
118 scheme ":" [ "//" 131 scheme ":" [ "//"
119 132
120 [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ] 133 [ @var{user} [ ( ":" @var{password} ) | ( ";auth=" @var{auth} ) ] "@@" ]
121 134
122 host [ ":" port ] 135 @var{host} [ ":" @var{port} ]
123 136
124 [ ( "/" urlpath ) | ( "?" query ) ] ] 137 [ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
138 @end group
125 @end smallexample 139 @end smallexample
126 140
127 This is a generalized URL syntax, and may not be exactly appropriate 141 This is a generalized URL syntax, and may not be exactly appropriate
128 for any particular scheme. 142 for any particular scheme.
143 @end deftypefun
144
145 @deftypefun int url_get_scheme (const url_t, char *, size_t, size_t *)
146 @end deftypefun
147
148 @deftypefun int url_get_user (const url_t, char *, size_t, size_t *)
149 @end deftypefun
150
151 @deftypefun int url_get_passwd (const url_t, char *, size_t, size_t *)
152 @end deftypefun
129 153
154 @deftypefun int url_get_auth (const url_t, char *, size_t, size_t *)
130 @end deftypefun 155 @end deftypefun
131 156
132 @deftypefun const char* url_to_string (const url_t @var{url}) 157 @deftypefun int url_get_host (const url_t, char *, size_t, size_t *)
133 @end deftypefun 158 @end deftypefun
134 159
135 @deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n}) 160 @deftypefun int url_get_port (const url_t, long *)
136 @end deftypefun 161 @end deftypefun
137 162
138 @deftypefun int url_get_user (const url_t @var{url}, char *@var{usr}, size_t @var{len}, size_t *@var{n}) 163 @deftypefun int url_get_path (const url_t, char *, size_t, size_t *)
139 @end deftypefun 164 @end deftypefun
140 165
141 @deftypefun int url_get_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, size_t *@var{n}) 166 @deftypefun int url_get_query (const url_t, char *, size_t, size_t *)
142 @end deftypefun 167 @end deftypefun
143 168
144 @deftypefun int url_get_host (const url_t @var{url}, char *@var{host}, size_t @var{len}, size_t *@var{n}) 169 @deftypefun {const char*} url_to_string (const url_t)
145 @end deftypefun 170 @end deftypefun
146 171
147 @deftypefun int url_get_port (const url_t @var{url}, long *@var{port}) 172 @deftypefun int url_is_scheme (url_t, const char *@var{scheme})
148 @end deftypefun 173 @end deftypefun
149 174
150 @deftypefun int url_get_path (const url_t @var{url}, char *@var{path}, size_t @var{len}, size_t *@var{n}) 175 @deftypefun int url_is_same_scheme (url_t, url_t)
151 @end deftypefun 176 @end deftypefun
152 177
153 @deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n}) 178 @deftypefun int url_is_same_user (url_t, url_t)
154 @end deftypefun 179 @end deftypefun
155 180
156 @deftypefun char* url_decode (const char* @var{string}) 181 @deftypefun int url_is_same_path (url_t, url_t)
157 Decodes an @cite{RFC 1738} % encoded string, returning the decoded string 182 @end deftypefun
183
184 @deftypefun int url_is_same_host (url_t, url_t)
185 @end deftypefun
186
187 @deftypefun int url_is_same_port (url_t, url_t)
188 @end deftypefun
189
190 @deftypefun char* url_decode (const char *@var{string})
191 Decodes an @cite{RFC 1738} encoded string, returning the decoded string
158 in allocated memory. If the string is not encoded, this degenerates to 192 in allocated memory. If the string is not encoded, this degenerates to
159 a @code{strdup()}. 193 a @code{strdup()}.
160 @end deftypefun 194 @end deftypefun
161 195
196 @deftypefun int url_is_ticket (url_t @var{ticket}, url_t @var{url})
197 @end deftypefun
198
162 @subheading Example 199 @subheading Example
163 @smallexample 200 @smallexample
164 @include url-parse.inc 201 @include url-parse.inc
......