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
Inline Side-by-side
Showing 19 changed files with 1222 additions and 478 deletions
......@@ -4,7 +4,7 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{address_} is reserved */}
@code{/* Prefix @emph{address_} is reserved. */}
@code{#include <mailutils/address.h>}
@end smallexample
......@@ -19,19 +19,19 @@ RFC 822 for the details. @samp{[]} pairs mean "optional", @samp{/} means
"one or the other", and double-quoted characters are literals.
@smallexample
addr-spec = local-part "@" domain
mailbox = addr-spec ["(" display-name ")"] /
[display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group = display-name ":" [mailbox-list] ";"
address = mailbox / group / unix-mbox
address-list = address ["," address-list]
addr-spec = @var{local-part} "@@" @var{domain}
mailbox = @var{addr-spec} ["(" @var{display-name} ")"] /
[@var{display-name}] "<" [@var{route}] @var{addr-spec} ">"
mailbox-list = @var{mailbox} ["," @var{mailbox-list}]
group = @var{display-name} ":" [@var{mailbox-list}] ";"
address = @var{mailbox} / @var{group} / @var{unix-mbox}
address-list = @var{address} ["," @var{address-list}]
@end smallexample
unix-mbox is a non-standard extension meant to deal with the common
Unix-mbox is a non-standard extension meant to deal with the common
practice of using user names as addresses in mail utilities. It allows
addresses such as "root" to be parsed correctly. These are NOT valid
internet email addresses, they must be qualified before use.
addresses such as "root" to be parsed correctly. These are @strong{not}
valid internet email addresses, they must be qualified before use.
Several address functions have a set of common arguments with consistent
semantics, these are described here to avoid repetition.
......@@ -43,7 +43,7 @@ counts to access messages and attributes of messages.
If @var{len} is greater than @code{0} it is the length of the buffer
@var{buf}, and as much of the component as possible will be copied
into the buffer. The buffer will be null terminated.
into the buffer. The buffer will be @code{NULL} terminated.
The size of a particular component may be queried by providing @code{0}
for the @var{len} of the buffer, in which case the buffer is optional.
......@@ -67,7 +67,7 @@ The index @var{no} is outside of the range of available addresses.
@macro ADDRESSEINVAL
@item EINVAL
Invalid usage, usually a required argument was @code{null}.
Invalid usage, usually a required argument was @code{NULL}.
@end macro
@deftp {Data Type} address_t
......@@ -77,6 +77,10 @@ data structure to the user. Functions are provided to retrieve information
about an address in the address list.
@end deftp
@c
@c Functions.
@c
@deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
This function allocates and initializes @var{addr} by parsing the
RFC822 address-list @var{string}.
......@@ -92,7 +96,7 @@ The return value is @code{0} on success and a code number on error conditions:
@deftypefun int address_createv (address_t *@var{addr}, const char *@var{sv}, size_t @var{len})
This function allocates and initializes @var{addr} by parsing the
array of pointers to RFC822 address-lists in @var{sv}. If @var{len} is
@code{-1}, then @var{sv} must be null-terminated in the fashion of @var{argv},
@code{-1}, then @var{sv} must be @code{NULL} terminated in the fashion of @var{argv},
otherwise @var{len} is the length of the array.
The return value is @code{0} on success and a code number on error conditions:
......@@ -107,8 +111,14 @@ The return value is @code{0} on success and a code number on error conditions:
The @var{addr} is destroyed.
@end deftypefun
@deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
@c
@c address_get_
@c
@deftypefun int address_get_nth (address_t @var{addr}, size_t @var{no}, address_t *@var{ret})
@end deftypefun
@deftypefun int address_get_email (address_t @var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the @var{no}th email address component of the address list. This
address is the plain email address, correctly quoted, suitable for
using in an smtp dialog, for example, or as the address part of
......@@ -124,12 +134,21 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_aget_email (address_t *@var{addr}, size_t @var{no}, char** @var{bufp})
@deftypefun int address_get_local_part (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the local-part of an email addr-spec extracted while
parsing the @var{no}th email address.
As above, but mallocs the email address, if present,
The return value is @code{0} on success and a code number on error conditions:
@table @code
@ADDRESSEINVAL
@ADDRESSENOENT
@end table
@end deftypefun
and write a pointer to it into @var{bufp}. @var{bufp} will be @code{NULL}
if there is no email address to return.
@deftypefun int address_get_domain (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the domain of an email addr-spec extracted while
parsing the @var{no}th email address. This will be @code{0}
length for a unix-mbox.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -138,8 +157,7 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_personal (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
@deftypefun int address_get_personal (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the display-name describing the @var{no}th email address. This
display-name is optional, so may not be present. If it is not present, but
there is an RFC822 comment after the address, that comment will be
......@@ -159,8 +177,7 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_comments (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
@deftypefun int address_get_comments (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the comments extracted while parsing the @var{no}th email address.
These comments have no defined meaning, and are not currently collected.
......@@ -171,11 +188,11 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Accesses the email addr-spec extracted while
parsing the @var{no}th email address. This will be @code{0}
length for a unix-mbox.
@deftypefun int address_get_route (address_t @var{addr}, size_t @var{no}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Accesses the route of an email addr-spec extracted while
parsing the @var{no}th email address. This is a rarely used RFC822 address
syntax, but is legal in SMTP as well. The entire route is returned as
a string, those wishing to parse it should look at @file{mailutils/parse822.h}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -184,10 +201,14 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_local_part (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
@c
@c address_aget_
@c
Accesses the local-part of an email addr-spec extracted while
parsing the @var{no}th email address.
@deftypefun int address_aget_email (address_t @var{addr}, size_t @var{no}, char **@var{bufp})
As above, but mallocs the email address, if present,
and write a pointer to it into @var{bufp}. @var{bufp} will be @code{NULL}
if there is no email address to return.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -196,40 +217,25 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_domain (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Accesses the domain of an email addr-spec extracted while
parsing the @var{no}th email address. This will be @code{0}
length for a unix-mbox.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@ADDRESSEINVAL
@ADDRESSENOENT
@end table
@deftypefun int address_aget_local_part (address_t @var{addr}, size_t @var{no}, char **@var{buf})
@end deftypefun
@deftypefun int address_get_route (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Accesses the route of an email addr-spec extracted while
parsing the @var{no}th email address. This is a rarely used RFC822 address
syntax, but is legal in SMTP as well. The entire route is returned as
a string, those wishing to parse it should look at @file{mailutils/parse822.h}.
@deftypefun int address_aget_domain (address_t @var{addr}, size_t @var{no}, char **@var{buf})
@end deftypefun
The return value is @code{0} on success and a code number on error conditions:
@table @code
@ADDRESSEINVAL
@ADDRESSENOENT
@end table
@deftypefun int address_aget_personal (address_t @var{addr}, size_t @var{no}, char **@var{buf})
@end deftypefun
@deftypefun int address_is_group (address_t *@var{addr}, size_t @var{no}, size_t @var{len}, int* @var{yes})
@c
@c -----------
@c
@deftypefun int address_is_group (address_t @var{addr}, size_t @var{no}, int *@var{yes})
Sets *@var{yes} to @code{1} if this address is just the name of a group,
@code{0} otherwise. This is faster than checking if the address has
a non-zero length personal, and a zero-length local_part and domain.
@var{yes} can be @code{null}, though that doesn't serve much purpose other
@var{yes} can be @code{NULL}, though that doesn't serve much purpose other
than determining that @var{no} refers to an address.
Currently, there is no way to determine the end of the group.
......@@ -241,10 +247,8 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_to_string (address_t *@var{addr}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Returns the entire address list as a single RFC822 formatted address
list.
@deftypefun int address_to_string (address_t *@var{addr}, char *@var{buf}, size_t @var{len}, size_t *@var{n})
Returns the entire address list as a single RFC822 formatted address list.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -253,16 +257,33 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_count (address_t @var{addr}, size_t* @var{count})
@deftypefun int address_get_count (address_t @var{addr}, size_t *@var{count})
Returns a count of the addresses in the address list.
If @var{addr} is @code{null}, the count is @code{0}. If @var{count} is
not @code{null}, the count will be written to *@var{count}.
If @var{addr} is @code{NULL}, the count is @code{0}. If @var{count} is
not @code{NULL}, the count will be written to *@var{count}.
The return value is @code{0}.
@end deftypefun
@deftypefun int address_get_group_count (address_t @var{addr}, size_t *)
@end deftypefun
@deftypefun int address_get_email_count (address_t @var{addr}, size_t *)
@end deftypefun
@deftypefun int address_get_unix_mailbox_count (address_t @var{addr}, size_t *)
@end deftypefun
@deftypefun int address_contains_email (address_t @var{addr}, const char *@var{email})
@end deftypefun
@deftypefun int address_union (address_t *@var{a}, address_t @var{b})
@end deftypefun
@deftypefun size_t address_format_string (address_t @var{addr}, char *@var{buf}, size_t @var{buflen})
@end deftypefun
@subheading Example
@smallexample
@include addr.inc
......
......@@ -4,87 +4,146 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{attribute_} is reserved */}
@code{/* Prefix @emph{attribute_} is reserved. */}
@code{#include <mailutils/attribute.h>}
@end smallexample
@deftypefun int attribute_create (attribute_t *@var{pattribute})
@deftypefun int attribute_create (attribute_t *@var{attr}, void *)
@end deftypefun
@deftypefun void attribute_destroy (attribute_t *@var{pattribute})
@deftypefun void attribute_destroy (attribute_t *@var{attr}, void *)
@end deftypefun
@deftypefun int attribute_is_seen (attribute_t @var{attribute})
@deftypefun void* attribute_get_owner (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_answered (attribute_t @var{attribute})
@deftypefun int attribute_is_modified (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_flagged (attribute_t @var{attribute})
@deftypefun int attribute_clear_modified (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_deleted (attribute_t @var{attribute})
@deftypefun int attribute_set_modified (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_draft (attribute_t @var{attribute})
@c
@c _is_
@c
@deftypefun int attribute_is_userflag (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_seen (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_answered (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_flagged (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_deleted (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_draft (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_recent (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_recent (attribute_t @var{attribute})
@deftypefun int attribute_is_read (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_read (attribute_t @var{attribute})
@c
@c _set_
@c
@deftypefun int attribute_set_userflag (attribute_t @var{attr}, int)
@end deftypefun
@deftypefun int attribute_set_seen (attribute_t @var{attribute})
@deftypefun int attribute_set_seen (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_answered (attribute_t @var{attribute})
@deftypefun int attribute_set_answered (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_flagged (attribute_t @var{attribute})
@deftypefun int attribute_set_flagged (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_deleted (attribute_t @var{attribute})
@deftypefun int attribute_set_deleted (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_draft (attribute_t @var{attribute})
@deftypefun int attribute_set_draft (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_recent (attribute_t @var{attribute})
@deftypefun int attribute_set_recent (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_set_read (attribute_t @var{attribute})
@deftypefun int attribute_set_read (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_seen (attribute_t @var{attribute})
@c
@c _unset_
@c
@deftypefun int attribute_unset_userflag (attribute_t @var{attr}, int)
@end deftypefun
@deftypefun int attribute_unset_answered (attribute_t @var{attribute})
@deftypefun int attribute_unset_seen (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_flagged (attribute_t @var{attribute})
@deftypefun int attribute_unset_answered (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_deleted (attribute_t @var{attribute})
@deftypefun int attribute_unset_flagged (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_draft (attribute_t @var{attribute})
@deftypefun int attribute_unset_deleted (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_recent (attribute_t @var{attribute})
@deftypefun int attribute_unset_draft (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_unset_read (attribute_t @var{attribute})
@deftypefun int attribute_unset_recent (attribute_t @var{attr})
@end deftypefun
@deftypefun int attribute_is_equal (attribute_t @var{att1}, attribute_t @var{att2})
@deftypefun int attribute_unset_read (attribute_t @var{attr})
@end deftypefun
@c
@c ----------
@c
@deftypefun int attribute_get_flags (attribute_t @var{attr}, int *)
@end deftypefun
@deftypefun int attribute_set_flags (attribute_t @var{attr}, int)
@end deftypefun
@deftypefun int attribute_unset_flags (attribute_t @var{attr}, int)
@end deftypefun
@deftypefun int attribute_set_set_flags (attribute_t @var{attr}, int (*@var{_set_flags}) (attribute_t, int), void *)
@end deftypefun
@deftypefun int attribute_set_unset_flags (attribute_t @var{attr}, int (*@var{_unset_flags}) (attribute_t, int), void *)
@end deftypefun
@deftypefun int attribute_set_get_flags (attribute_t @var{attr}, int (*@var{_get_flags}) (attribute_t, int *), void *)
@end deftypefun
@c
@c ----------
@c
@deftypefun int attribute_is_equal (attribute_t @var{attr1}, attribute_t @var{attr2})
@end deftypefun
@deftypefun int attribute_copy (attribute_t @var{dst}, attribute_t @var{src})
@end deftypefun
@deftypefun int string_to_attribute (const char *@var{buf}, attribute_t *@var{pattr})
@deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{writen})
@end deftypefun
@deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{pwriten})
@deftypefun int string_to_flags (const char *@var{buf}, int *)
@end deftypefun
......
......@@ -4,37 +4,108 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{auth_} is reserved */}
@code{/* Prefixes @emph{authority_}, @emph{ticket_}, and @emph{wicket_t} are reserved */}
@code{#include <mailutils/auth.h>}
@end smallexample
There are many ways to authenticate to a server. To be flexible the
authentication process is provided by two objects @code{auth_t} and
@code{ticket_t}. The @code{auth_t} can implement different protocol like
APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox
does not understand or know how to authenticate it falls back to
user/passwd authentication. The @code{ticket_t} is a way for
authentication process is provided by three objects @code{authority_t},
@code{ticket_t}, and @code{wicket_t}. The @code{authority_t} can implement
different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
if a mailbox does not understand or know how to authenticate it falls back
to user/passwd authentication. The @code{ticket_t} is a way for
Mailboxes and Mailers provide a way to authenticate when the URL does not
contain enough information. The default action is to call the function
@code{auth_authenticate} which will get the @emph{user} and @emph{passwd}
@code{authority_authenticate()} which will get the @emph{user} and @emph{passwd}
if not set, this function can be overridden by a custom method.
@deftypefun int auth_create (auth_t *@var{pauth}, void *@var{owner})
@c
@c Ticket
@c
@deftypefun int ticket_create (ticket_t *, void *@var{owner})
@end deftypefun
@deftypefun void ticket_destroy (ticket_t *, void *@var{owner})
@end deftypefun
@deftypefun int ticket_set_destroy (ticket_t, void (*) (ticket_t), void *@var{owner})
@end deftypefun
@deftypefun void* ticket_get_owner (ticket_t)
@end deftypefun
@deftypefun int ticket_set_pop (ticket_t, int (*@var{_pop}) (ticket_t, url_t, const char *, char **), void *)
@end deftypefun
@deftypefun int ticket_pop (ticket_t, url_t, const char *, char **)
@end deftypefun
@deftypefun int ticket_set_data (ticket_t, void *, void *@var{owner})
@end deftypefun
@deftypefun int ticket_get_data (ticket_t, void **)
@end deftypefun
@c
@c Authority
@c
@sp 1
@deftypefun int authority_create (authority_t *, ticket_t, void *)
@end deftypefun
@deftypefun void authority_destroy (authority_t *, void *)
@end deftypefun
@deftypefun void* authority_get_owner (authority_t)
@end deftypefun
@deftypefun void auth_destroy (auth_t *@var{pauth}, void *@var{owner})
@deftypefun int authority_set_ticket (authority_t, ticket_t)
@end deftypefun
@deftypefun int auth_prologue (auth_t @var{auth})
@deftypefun int authority_get_ticket (authority_t, ticket_t *)
@end deftypefun
@deftypefun int auth_authenticate (auth_t @var{auth}, char **@var{user}, char **@var{passwd})
@deftypefun int authority_authenticate (authority_t)
@end deftypefun
@deftypefun int auth_epilogue (auth_t @var{auth})
@deftypefun int authority_set_authenticate (authority_t, int (*@var{_authenticate}) (authority_t), void *)
@end deftypefun
@deftypefun int authority_create_null (authority_t *@var{authority}, void *@var{owner})
@end deftypefun
@c
@c Wicket
@c
@sp 1
@deftypefun int wicket_create (wicket_t *, const char *)
@end deftypefun
@deftypefun void wicket_destroy (wicket_t *)
@end deftypefun
@deftypefun int wicket_set_filename (wicket_t, const char *)
@end deftypefun
@deftypefun int wicket_get_filename (wicket_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int wicket_set_ticket (wicket_t, int (*) (wicket_t, const char *, const char *, ticket_t *))
@end deftypefun
@deftypefun int wicket_get_ticket (wicket_t, ticket_t *, const char *, const char *)
@end deftypefun
@c
@c An example.
@c
@sp 1
A simple example of an authenticate function:
......
......@@ -4,32 +4,48 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{body_} is reserved */}
@code{/* Prefix @emph{body_} is reserved. */}
@code{#include <mailutils/body.h>}
@end smallexample
@deftypefun int body_create (body_t *@var{body}, void *@var{owner})
Initialize an object @var{bdy}.
Initialize an object @var{body}.
@end deftypefun
@deftypefun void body_destroy (body_t *@var{pbody})
The resources allocate are release.
@deftypefun void body_destroy (body_t *@var{body})
The resources allocated are release.
@end deftypefun
@deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{pstream})
@deftypefun void* body_get_owner (body_t @var{body})
@end deftypefun
@deftypefun int body_is_modified (body_t @var{body})
@end deftypefun
@deftypefun int body_clear_modified (body_t @var{body})
@end deftypefun
@c
@c -----------
@c
@deftypefun int body_get_stream (body_t @var{body}, stream_t *@var{stream})
@end deftypefun
@deftypefun int body_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner})
@end deftypefun
@deftypefun int body_get_filename __P ((body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten}))
@deftypefun int body_get_filename (body_t @var{body}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
@end deftypefun
@deftypefun int body_size (body_t @var{body}, size_t *@var{size})
@end deftypefun
@deftypefun int body_set_filename (body_t @var{body}, const char*@var{buffer})
@deftypefun int body_set_size (body_t @var{body}, int (*@var{_size}) (body_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int body_size (body_t @var{body}, size_t*@var{psize})
@deftypefun int body_lines (body_t @var{body}, size_t *@var{lines})
@end deftypefun
@deftypefun int body_lines (body_t @var{body}, size_t *@var{plines})
@deftypefun int body_set_lines (body_t @var{body}, int (*@var{_lines}) (body_t, size_t *), void *@var{owner})
@end deftypefun
......
......@@ -4,40 +4,44 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{envelope_} is reserved */}
@code{/* Prefix @emph{envelope_} is reserved. */}
@code{#include <mailutils/envelope.h>}
@end smallexample
@deftypefun int envelope_date (envelope_t, char *, size_t, size_t *);
Get the date that the message was delivered to the mailbox, in
something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
@deftypefun int envelope_create (envelope_t *, void *)
Primarily for internal use.
@end deftypefun
@deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *);
Get the address that this message was reportedly received from. This
would be the "mail from" argument if the message was delivered
or received via SMTP, for example.
@deftypefun void envelope_destroy (envelope_t *, void *)
Primarily for internal use.
@end deftypefun
@deftypefun int envelope_get_message (envelope_t, message_t *);
@deftypefun void* envelope_get_owner (envelope_t)
@end deftypefun
@deftypefun int envelope_create (envelope_t *, void *);
Primarily for internal use.
@end deftypefun
@c
@c ----------
@c
@deftypefun void envelope_destroy (envelope_t *, void *);
Primarily for internal use.
@deftypefun int envelope_sender (envelope_t, char *, size_t, size_t *)
Get the address that this message was reportedly received from. This
would be the "mail from" argument if the message was delivered
or received via SMTP, for example.
@end deftypefun
@deftypefun int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *);
Primarily for internal use. The implementation of envelope_t depends
@deftypefun int envelope_set_sender (envelope_t, int (*@var{_sender}) (envelope_t, char *, size_t, size_t *), void *)
Primarily for internal use. The implementation of @code{envelope_t} depends
on the mailbox type, this allows the function which actually gets
the sender to be set by the creator of an @code{envelope_t}.
@end deftypefun
@deftypefun int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *);
Primarily for internal use. The implementation of envelope_t depends
@deftypefun int envelope_date (envelope_t, char *, size_t, size_t *)
Get the date that the message was delivered to the mailbox, in
something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
@end deftypefun
@deftypefun int envelope_set_date (envelope_t, int (*@var{_date}) (envelope_t, char *, size_t, size_t *), void *)
Primarily for internal use. The implementation of @code{envelope_t} depends
on the mailbox type, this allows the function which actually gets
the date to be set by the creator of an @code{envelope_t}.
@end deftypefun
......
......@@ -4,7 +4,7 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{folder_} is reserve */}
@code{/* Prefix @emph{folder_} is reserved. */}
@code{#include <mailutils/folder.h>}
@end smallexample
......@@ -12,13 +12,13 @@
@smallexample
@group
folder_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
( alain *-)-+ | | url_t *-|----+ | port |
----------- | | |-----------------+ | hostname |
-/var/mail- +---//--->/-----------------\ +-->/-----------\
( alain *-)-+ | | url_t *-|---+ | port |
---------- | | |-----------------+ | hostname |
( jakob *-)-+--+ | observer_t *-| | file |
----------- | |-----------------+ | ... |
---------- | |-----------------+ | ... |
( jeff *-)-+ | stream_t | \-----------/
----------- | |-----------------|
---------- | |-----------------|
( sean *-)-+ | auth_t |
---------- |-----------------|
| mailbox_t(1) |
......@@ -30,6 +30,29 @@
@end group
@end smallexample
Data structures:
@smallexample
@group
struct list_response
@{
int type;
int separator;
char *name;
@};
struct folder_list
@{
struct list_response **element;
size_t num;
@};
@end group
@end smallexample
@c
@c Constructor/Destructor and possible types.
@c
@deftypefun int folder_create (folder_t *, const char *@var{url})
@end deftypefun
......@@ -54,33 +77,59 @@
@deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox})
@end deftypefun
@deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, iterator_t *)
@deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
@end deftypefun
@deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *)
@end deftypefun
@deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcar}, iterator_t *)
@deftypefun int folder_list_destroy (struct folder_list *)
@end deftypefun
@c
@c Stream Settings.
@c
@deftypefun int folder_get_stream (folder_t, stream_t *)
@end deftypefun
@deftypefun int folder_set_stream (folder_t, stream_t)
@end deftypefun
@c
@c Notifications.
@c
@deftypefun int folder_get_observable (folder_t, observable_t *)
@end deftypefun
@deftypefun int folder_get_debug (folder_t, debug_t *)
@c
@c Debug.
@c
@deftypefun int folder_has_debug (folder_t)
@end deftypefun
@deftypefun int folder_get_debug (folder_t, mu_debug_t *)
@end deftypefun
@deftypefun int folder_set_debug (folder_t, debug_t)
@deftypefun int folder_set_debug (folder_t, mu_debug_t)
@end deftypefun
@c
@c Authentication.
@c
@deftypefun int folder_get_authority (folder_t, authority_t *)
@end deftypefun
@deftypefun int folder_set_authority (folder_t, authority_t)
@end deftypefun
@c
@c URL.
@c
@deftypefun int folder_get_url (folder_t, url_t *)
@end deftypefun
......
......@@ -36,11 +36,11 @@ etc ..).
folder_t url_t
-/var/mail- +- .. ->+-----------------+ +-->+------------+
( alain *-)-+ | | url_t *-|---+ | port |
----------- | | |-----------------| | hostname |
---------- | | |-----------------| | hostname |
( jakob *-)-+--+ | auth_t *-|---+ | file |
----------- | |-----------------| | | ... |
---------- | |-----------------| | | ... |
( jeff *-)-+ | stream_t | | +------------+
----------- | |-----------------| |
---------- | |-----------------| |
( shaleh*-)-+ | ..... | | auth_t
---------- |-----------------| +-->+------------+
+---|-* mailbox_t[] | | ticket_t |
......@@ -165,4 +165,3 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
@node Mailcap
@subsection Mailcap
@include mailcap.texi
......
......@@ -4,31 +4,43 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{header_} is reserved */}
@code{/* Prefix @emph{header_} is reserved. */}
@code{#include <mailutils/header.h>}
@end smallexample
So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII
So far we plan support for RFC822 and plan for RFC1522. With RFC1522 non-ASCII
characters will be encoded.
@deftypefun int header_create (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, void *@var{owner})
Initialize a @var{hdr} to a supported type. If @var{blurb} is not NULL, it is
parsed.
Initialize a @var{hdr} to a supported type. If @var{blurb} is not @code{NULL},
it is parsed.
@end deftypefun
@deftypefun void header_destroy (header_t *@var{hdr}, void *@var{owner})
The resources allocated for @var{hdr} are freed.
@end deftypefun
@deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, size_t n, int @var{replace})
Set the field-name @var{fn} to field-value @var{fv} of size @var{n} in
@var{hdr}. If @var{replace} is non-zero the initial value is replaced, if zero
it is appended.
@deftypefun void* header_get_owner (header_t *@var{hdr})
@end deftypefun
@deftypefun int header_is_modified (header_t @var{hdr})
@end deftypefun
@deftypefun int header_clear_modified (header_t @var{hdr})
@end deftypefun
@c
@c Set and get field values by field name.
@c
Some basic macros are already provided for rfc822.
@deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, int @var{n})
Some basic macros are already provided for RFC822.
@table @code
@item MU_HEADER_UNIX_FROM
From
@item MU_HEADER_RETURN_PATH
Return-Path
@item MU_HEADER_RECEIVED
......@@ -37,6 +49,8 @@ Received
Date
@item MU_HEADER_FROM
From
@item MU_HEADER_SENDER
Sender
@item MU_HEADER_RESENT_FROM
Resent-From
@item MU_HEADER_SUBJECT
......@@ -67,6 +81,10 @@ Message-ID
Resent-Message-ID
@item MU_HEADER_IN_REPLY_TO
In-Reply-To
@item MU_HEADER_REFERENCE
Reference
@item MU_HEADER_REFERENCES
References
@item MU_HEADER_ENCRYPTED
Encrypted
@item MU_HEADER_PRECEDENCE
......@@ -75,10 +93,38 @@ Precedence
Status
@item MU_HEADER_CONTENT_LENGTH
Content-Length
@item MU_HEADER_CONTENT_LANGUAGE
Content-Language
@item MU_HEADER_CONTENT_TRANSFER_ENCODING
Content-transfer-encoding
@item MU_HEADER_CONTENT_ID
Content-ID
@item MU_HEADER_CONTENT_TYPE
Content-Type
@item MU_HEADER_CONTENT_DESCRIPTION
Content-Description
@item MU_HEADER_CONTENT_DISPOSITION
Content-Disposition
@item MU_HEADER_CONTENT_MD5
Content-MD5
@item MU_HEADER_MIME_VERSION
MIME-Version
@item MU_HEADER_X_UIDL
X-UIDL
@item MU_HEADER_X_UID
X-UID
@item MU_HEADER_X_IMAPBASE
X-IMAPbase
@item MU_HEADER_ENV_SENDER
X-Envelope-Sender
@item MU_HEADER_ENV_DATE
X-Envelope-Date
@item MU_HEADER_FCC
Fcc
@item MU_HEADER_DELIVERY_DATE
Delivery-date
@item MU_HEADER_ENVELOPE_TO
Envelope-to
@end table
@end deftypefun
......@@ -91,11 +137,74 @@ The number of bytes written is put in @var{n}.
The value is allocated.
@end deftypefun
@deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{pstream})
@c
@c Get field values as an address_t.
@c
@deftypefun int header_get_address (header_t @var{hdr}, const char *@var{buf}, address_t *@var{addr})
@end deftypefun
@c
@c Stream
@c
@deftypefun int header_get_stream (header_t @var{hdr}, stream_t *@var{stream})
@end deftypefun
@deftypefun int header_set_stream (header_t @var{hdr}, stream_t @var{stream}, void *)
@end deftypefun
@c
@c
@c
@deftypefun int header_get_field_count (header_t @var{hdr}, size_t *@var{count})
@end deftypefun
@deftypefun int header_get_field_value (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
@end deftypefun
@deftypefun int header_get_field_name (header_t @var{hdr}, size_t @var{index}, char *, size_t, size_t *)
@end deftypefun
@deftypefun int header_aget_field_value (header_t @var{hdr}, size_t @var{index}, char **)
@end deftypefun
@deftypefun int header_aget_field_name (header_t @var{hdr}, size_t @var{index}, char **)
@end deftypefun
@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})
@end deftypefun
@deftypefun int header_aget_value_unfold (header_t @var{hdr}, const char *@var{name}, char **@var{value})
@end deftypefun
@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})
@end deftypefun
@deftypefun int header_aget_field_value_unfold (header_t @var{hdr}, size_t @var{num}, char **@var{value});
@end deftypefun
@deftypefun int header_size (header_t @var{hdr}, size_t *);
@end deftypefun
@deftypefun int header_lines (header_t @var{hdr}, size_t *);
@end deftypefun
@deftypefun int header_set_set_value (header_t @var{hdr}, int (*@var{_set_value}) (header_t, const char *, const char *, int), void *);
@end deftypefun
@deftypefun int header_set_get_value (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
@end deftypefun
@deftypefun int header_set_get_fvalue (header_t @var{hdr}, int (*@var{_get_value}) (header_t, const char *, char *, size_t, size_t *), void *);
@end deftypefun
@deftypefun int header_set_size (header_t @var{hdr}, int (*@var{_size}) (header_t, size_t *), void *);
@end deftypefun
@deftypefun int header_set_size (header_t @var{hdr}, size_t *@var{size})
@deftypefun int header_set_lines (header_t @var{hdr}, int (*@var{_lines}) (header_t, size_t *), void *);
@end deftypefun
@deftypefun int header_set_lines (header_t @var{hdr}, size_t *@var{lpines})
@deftypefun int header_set_fill (header_t @var{hdr}, int (*@var{_fill}) (header_t, char *, size_t, off_t, size_t *), void *@var{owner});
@end deftypefun
......
......@@ -4,11 +4,14 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{iterator_} is reserved */}
@code{/* Prefix @emph{iterator_} is reserved. */}
@code{#include <mailutils/iterator.h>}
@end smallexample
@deftypefun int iterator_create (iterator_t *)
@deftypefun int iterator_create (iterator_t *@var{iterator}, list_t)
@end deftypefun
@deftypefun int iterator_dup (iterator_t *@var{iterator}, iterator_t @var{orig})
@end deftypefun
@deftypefun void iterator_destroy (iterator_t *)
......@@ -20,8 +23,11 @@
@deftypefun int iterator_next (iterator_t)
@end deftypefun
@deftypefun int iterator_current (iterator_t, void **pitem)
@deftypefun int iterator_current (iterator_t, void **@var{item})
@end deftypefun
@deftypefun int iterator_is_done (iterator_t)
@end deftypefun
@deftypefun int iterator_get_list (iterator_t @var{iterator}, list_t *@var{list})
@end deftypefun
......
......@@ -30,18 +30,19 @@ This is a pointer to authentication or authorization data. It
is defined as follows:
@smallexample
typedef int (*mu_auth_fp) (void *@var{return_data},
@group
typedef int (*mu_auth_fp) (struct mu_auth_data **@var{return_data},
void *@var{key},
void *@var{func_data},
void *@var{call_data});
@end group
@end smallexample
@noindent
Its arguments are:
@table @var
@item return_data
@footnote{Actually it shoud have been @code{struct mu_auth_data** return_data}.
This will be fixed in the next release}.
Upon successful return authorization handler leaves in this memory
location a pointer to the filled @code{mu_auth_data} structure
with the user's information.
......@@ -118,7 +119,6 @@ struct mu_auth_module @{
@subsection Initializing @file{libmuauth}
@deftypefun void mu_auth_init (void)
This function registers the command line capability ``auth''. It must be
called after registering @file{libmuauth} modules and before calling
@code{mu_agrp_parse()}. If an error occurs, this function prints
......@@ -126,27 +126,24 @@ diagnostic message and aborts the program.
@end deftypefun
@deftypefun void MU_AUTH_REGISTER_ALL_MODULES (void)
This macro registers all default modules and calls @code{mu_auth_init()}.
@end deftypefun
@node Module Creation and Destruction
@subsection Module Creation and Destruction
@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)
@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})
Create a @code{mu_auth_data} structure and initialize it with the given
values. Returns 0 on success and 1 otherwise.
@end deftypefun
@deftypefun void mu_auth_data_free (struct mu_auth_data *@var{ptr})
Free the @code{mu_auth_data} structure allocated by a call to
@code{mu_auth_data_alloc()}.
@end deftypefun
@deftypefun void mu_auth_register_module (struct mu_auth_module *@var{mod})
Register the module defined by the @var{mod} argument.
@end deftypefun
......@@ -154,8 +151,7 @@ Register the module defined by the @var{mod} argument.
@subsection Obtaining Authorization Information
@cindex libmuauth, obtaining authorization information
@deftypefun int mu_auth_runlist (list_t @var{flist}, void *@var{return_data}, void *@var{key}, void *@var{call_data});
@deftypefun int mu_auth_runlist (list_t @var{flist}, struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{call_data});
The list is expected to contain @code{mu_auth_fp} pointers. Each of them
is dereferenced and executed until either the list is exhausted or any
of the functions returns non-zero, whichever occurs first. The
......@@ -170,10 +166,8 @@ return code from the succeeded function.
@end deftypefun
@deftypefun {struct mu_auth_data *} mu_get_auth_by_name (const char *@var{username})
Search the information about given user by its username. Similar to
system's @code{getpwnam} call).
@end deftypefun
@deftypefun {struct mu_auth_data *} mu_get_auth_by_uid (uid_t @var{uid})
......@@ -182,7 +176,6 @@ system's @code{getpwuid} call).
@end deftypefun
@deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass})
Authenticate the user whose data are in @var{auth_data} using password
@var{pass}. Return 0 if the user is authenticated.
@end deftypefun
......@@ -191,20 +184,17 @@ Authenticate the user whose data are in @var{auth_data} using password
@subsection Existing Modules
@cindex libmuauth modules
@deftypefun int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data);
@deftypefun int mu_auth_nosupport (struct mu_auth_data **@var{return_data}, void *@var{key}, void *@var{func_data}, void *@var{call_data});
The ``not-supported'' module. Always returns @code{ENOSYS}.
@end deftypefun
@defvar mu_auth_system_module
This module is always registered even if @file{libmuauth} is not linked.
It performs usual authentication using system user database
(@file{/etc/password} et al.)
@end defvar
@defvar mu_auth_generic_module
This module is always registered even if @file{libmuauth} is not linked.
Both its authorization handlers are @code{mu_auth_nosupport}. Its
authentication handler computes the MD5 or DES hash over the supplied
......@@ -214,13 +204,11 @@ member itself and returns 1 if both strings match.
@end defvar
@defvar mu_auth_pam_module
Implements PAM authentication. Both authorization handlers are
@code{mu_auth_nosupport()}.
@end defvar
@defvar mu_auth_sql_module
Implements authentication and authorization via MySQL database. The
credentials for accessing the database are taken from global variables
@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.
@end defvar
@defvar mu_auth_virtual_module
Implements @code{mu_get_auth_by_name} method using virtual mail domains.
Neither @code{mu_get_auth_by_uid} nor @code{mu_authenticate} is
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)
@end smallexample
@end deftypefun
@deftypefun void *sieve_get_data (sieve_machine_t @var{mach})
@deftypefun void* sieve_get_data (sieve_machine_t @var{mach})
This function returns the application-specific data associated with
the instance of sieve machine. See @code{sieve_machine_init()}.
@end deftypefun
......
......@@ -4,28 +4,73 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{locker_} is reserved */}
@code{/* Prefix @emph{locker_} is reserved. */}
@code{#include <mailutils/locker.h>}
@end smallexample
@deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags})
@deftypefun int locker_set_default_flags (int @var{flags}, enum mu_locker_set_mode @var{mode})
@end deftypefun
@deftypefun void locker_destroy (locker_t * @var{plocker})
@deftypefun void locker_set_default_retry_timeout (time_t @var{to})
@end deftypefun
@deftypefun int locker_lock (locker_t @var{locker}, int @var{flag})
@table @code
@item MU_LOCKER_RDLOCK
@item MU_LOCKER_WRLOCK
@item MU_LOCKER_PID
@item MU_LOCKER_FCNTL
@item MU_LOCKER_TIME
@end table
@deftypefun void locker_set_default_retry_count (size_t @var{n})
@end deftypefun
@deftypefun int locker_touchlock (locker_t @var{locker})
@deftypefun void locker_set_default_expire_timeout (time_t @var{t})
@end deftypefun
@deftypefun int locker_unlock (locker_t @var{locker})
@deftypefun void locker_set_default_external_program (char *@var{path})
@end deftypefun
A flags of 0 means that the default will be used.
@deftypefun int locker_create (locker_t *, const char *@var{filename}, int @var{flags})
@end deftypefun
@deftypefun void locker_destroy (locker_t *)
@end deftypefun
Time is measured in seconds.
@deftypefun int locker_set_flags (locker_t, int)
@end deftypefun
@deftypefun int locker_set_expire_time (locker_t, int)
@end deftypefun
@deftypefun int locker_set_retries (locker_t, int)
@end deftypefun
@deftypefun int locker_set_retry_sleep (locker_t, int)
@end deftypefun
@deftypefun int locker_set_external (locker_t, const char *@var{program})
@end deftypefun
@deftypefun int locker_get_flags (locker_t, int *)
@end deftypefun
@deftypefun int locker_get_expire_time (locker_t, int*)
@end deftypefun
@deftypefun int locker_get_retries (locker_t, int *)
@end deftypefun
@deftypefun int locker_get_retry_sleep (locker_t, int *)
@end deftypefun
@deftypefun int locker_get_external (locker_t, char **)
@end deftypefun
@deftypefun int locker_lock (locker_t)
@end deftypefun
@deftypefun int locker_touchlock (locker_t)
@end deftypefun
@deftypefun int locker_unlock (locker_t)
@end deftypefun
@deftypefun int locker_remove_lock (locker_t)
@end deftypefun
......
......@@ -4,7 +4,7 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{mailbox_} is reserved */}
@code{/* Prefix @emph{mailbox_} is reserved. */}
@code{#include <mailutils/mailbox.h>}
@end smallexample
......@@ -17,13 +17,13 @@ from the data structure.
@smallexample
@group
mailbox_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
( alain ) | | url_t *-|----+ | port |
----------- | |-----------------+ | hostname |
-/var/mail- +---//--->/-----------------\ +-->/-----------\
( alain ) | | url_t *-|---+ | port |
---------- | |-----------------+ | hostname |
( jakob *-)----+ | observer_t *-| | file |
----------- |-----------------+ | ... |
---------- |-----------------+ | ... |
( jeff ) | stream_t | \-----------/
----------- |-----------------|
---------- |-----------------|
( sean ) | locker_t |
---------- |-----------------|
| message_t(1) |
......@@ -35,35 +35,19 @@ from the data structure.
@end group
@end smallexample
@deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
The @var{message} is appended to the mailbox @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null or @var{message} is invalid.
@end table
@end deftypefun
@deftypefun int mailbox_close (mailbox_t @var{mbox})
The stream attach to @var{mbox} is closed.
@c
@c Constructor/destructor and possible types.
@c
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@end table
@end deftypefun
@deftypefun int mailbox_create (mailbox_t *@var{pmbox}, const char *@var{name})
The function @code{mailbox_create} allocates and initializes @var{pmbox}.
@deftypefun int mailbox_create (mailbox_t *@var{mbox}, const char *@var{name})
The function @code{mailbox_create} allocates and initializes @var{mbox}.
The concrete mailbox type instantiate is based on the scheme of the url @var{name}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERR_OUT_PTR_NULL
The pointer @var{pmbox} supplied is NULL.
The pointer @var{mbox} supplied is @code{NULL}.
@item MU_ERR_NO_HANDLER
The url @var{name} supplied is invalid or not supported.
@item EINVAL
......@@ -72,198 +56,215 @@ Not enough memory to allocate resources.
@end table
@end deftypefun
@deftypefun int mailbox_create_default (mailbox_t *@var{pmbox}, const char *@var{name})
Create a mailbox with @code{mailbox_create ()} based on the environment
variable @emph{$MAIL} or the string formed by
@emph{_PATH_MAILDIR}/@var{user}" or @emph{$LOGNAME} if @var{user} is null,
@deftypefun int mailbox_create_default (mailbox_t *@var{mbox}, const char *@var{name})
Create a mailbox with @code{mailbox_create()} based on the environment
variable @env{MAIL} or the string formed by
@emph{_PATH_MAILDIR}/@var{user}" or @env{LOGNAME} if @var{user} is null,
@end deftypefun
@deftypefun void mailbox_destroy (mailbox_t *@var{pmbox})
Destroys and releases resources held by @var{pmbox}.
@deftypefun void mailbox_destroy (mailbox_t *@var{mbox})
Destroys and releases resources held by @var{mbox}.
@end deftypefun
@deftypefun int mailbox_expunge (mailbox_t @var{mbox})
All messages marked for deletion are removed.
@deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag})
A connection is open, if no stream was provided, a stream
is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
See @code{stream_create()} for @var{flag}'s description.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EAGAIN
@itemx EINPROGRESS
Operation in progress.
@item EBUSY
Resource busy.
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL} or flag is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun
@deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
Get the @var{folder}.
@deftypefun int mailbox_close (mailbox_t @var{mbox})
The stream attach to @var{mbox} is closed.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_debug (mailbox_t @var{mbox}, debug_t *@var{debug})
Get a debug object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@item ENOMEM
@end table
@deftypefun int mailbox_flush (mailbox_t @var{mbox}, int @var{expunge})
@end deftypefun
@deftypefun int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{plocker})
Return the @var{locker} object.
@deftypefun int mailbox_get_folder (mailbox_t @var{mbox}, folder_t *@var{folder})
Get the @var{folder}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{pmessage})
Retrieve message number @var{msgno}, @var{pmessage} is allocated and
initialized.
@deftypefun int mailbox_set_folder (mailbox_t @var{mbox}, folder_t @var{folder})
@end deftypefun
@deftypefun int mailbox_uidvalidity (mailbox_t @var{mbox}, unsigned long *@var{number});
Give the uid validity of @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null or @var{msgno} is invalid.
@item ENOMEM
Not enough memory.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t*@var{observable})
Get the observable object.
@deftypefun int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{number});
Give the next predicted uid for @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@item ENOMEM
Not enough memory.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property})
Get the property object.
@c
@c Messages.
@c
@deftypefun int mailbox_get_message (mailbox_t @var{mbox}, size_t @var{msgno}, message_t *@var{message})
Retrieve message number @var{msgno}, @var{message} is allocated and
initialized.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL} or @var{msgno} is invalid.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun
@deftypefun int mailbox_get_size (mailbox_t @var{mbox}, off_t *@var{psize})
Gives the @var{mbox} size.
@deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
The @var{message} is appended to the mailbox @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL} or @var{message} is invalid.
@end table
@end deftypefun
@deftypefun int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{pstream})
The mailbox stream is put in @var{pstream}.
@deftypefun int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{number});
Give the number of messages in @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is invalid or @var{pstream} is NULL.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
The return value is @code{0} on success and a code number on error conditions:
@deftypefun int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{number});
Give the number of recent messages in @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{purl})
Gives the constructed @var{url}.
@deftypefun int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{number});
Give the number of first unseen message in @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_is_modified (mailbox_t @var{mbox})
Check if the mailbox been modified by an external source.
@deftypefun int mailbox_expunge (mailbox_t @var{mbox})
All messages marked for deletion are removed.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_message_unseen (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of first unseen message in @var{mbox}.
@deftypefun int mailbox_save_attributes (mailbox_t @var{mbox})
@end deftypefun
@c
@c Update and Scanning.
@c
@deftypefun int mailbox_get_size (mailbox_t @var{mbox}, off_t *@var{size})
Gives the @var{mbox} size.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_messages_count (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of messages in @var{mbox}.
@deftypefun int mailbox_is_updated (mailbox_t @var{mbox})
@end deftypefun
@deftypefun int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{count});
Scan the mailbox for new messages starting at message @var{msgno}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun
@deftypefun int mailbox_messages_recent (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the number of recent messages in @var{mbox}.
@c
@c Mailbox Stream.
@c
@deftypefun int mailbox_get_stream (mailbox_t @var{mbox}, stream_t *@var{stream})
The mailbox stream is put in @var{stream}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is invalid or @var{stream} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_open (mailbox_t @var{mbox}, int @var{flag})
A connection is open, if no stream was provided, a stream
is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
See @code{stream_create} for @var{flag}'s description.
@deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream})
Set the @var{stream} connection to use for the mailbox.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EAGAIN
@itemx EINPROGRESS
Operation in progress.
@item EBUSY
Resource busy.
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null or flag is invalid.
@item ENOMEM
Not enough memory.
@var{mbox} or @var{stream} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_scan (mailbox_t @var{mbox}, size_t @var{msgno}, size_t *@var{pcount});
Scan the mailbox for new messages starting at message @var{msgno}.
@c
@c Lock Settings.
@c
@deftypefun int mailbox_get_locker (mailbox_t @var{mbox}, locker_t *@var{locker})
Get the @var{locker_t} object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@item ENOMEM
Not enough memory.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
......@@ -273,46 +274,80 @@ Set the type of locking done by the @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_set_stream (mailbox_t @var{mbox}, stream_t @var{stream})
Set the @var{stream} connection to use for the mailbox.
@c
@c Property.
@c
@deftypefun int mailbox_get_property (mailbox_t @var{mbox}, property_t *@var{property})
Get the property object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} or @var{stream} is NULL.
@var{mbox} is @code{NULL}.
@item ENOMEM
@end table
@end deftypefun
@deftypefun int mailbox_set_ticket (mailbox_t @var{mbox}, ticket_t @var{ticket})
The @var{ticket} will be set on the @code{auth_t} object on creation.
@c
@c URL.
@c
@deftypefun int mailbox_get_url (mailbox_t @var{mbox}, url_t *@var{url})
Gives the constructed @var{url}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mailbox_uidnext (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the next predicted uid for @var{mbox}.
@c
@c Debug.
@c
@deftypefun int mailbox_has_debug (mailbox_t @var{mbox})
@end deftypefun
@deftypefun int mailbox_get_debug (mailbox_t @var{mbox}, mu_debug_t *@var{debug})
Get a debug object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@item ENOMEM
@end table
@end deftypefun
@deftypefun int mailbox_uidvalidity (mailbox_t @var{mbox}, size_t *@var{pnumber});
Give the uid validity of @var{mbox}.
@deftypefun int mailbox_set_debug (mailbox_t @var{mbox}, mu_debug_t @var{debug})
@end deftypefun
@c
@c Events.
@c
@deftypefun int mailbox_get_observable (mailbox_t mbox @var{mbox}, observable_t *@var{observable})
Get the observable object.
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mbox} is null.
@var{mbox} is @code{NULL}.
@item ENOMEM
Not enough memory.
@end table
@end deftypefun
@c
@c Locking
@c
@deftypefun int mailbox_lock (mailbox_t @var{mbox})
@end deftypefun
@deftypefun int mailbox_unlock (mailbox_t @var{mbox})
@end deftypefun
......
......@@ -4,61 +4,68 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{mu_mailcap_} is reserved */}
@code{/* Prefix @emph{mu_mailcap_} is reserved. */}
@code{#include <mailutils/mailcap.h>}
@end smallexample
The standard @cite{RFC 1524} (A User Agent Configuration Mechanism) suggests a file format
to be used to inform a mail user agent about facilities for handling mail in various
format. The configuration file is known also as mailcap and it is tipically found
in UNIX platforms, a example of @file{/etc/mailcap}:
The standard @cite{RFC 1524} (A User Agent Configuration Mechanism)
suggests a file format to be used to inform a mail user agent about
facilities for handling mail in various format. The configuration
file is known also as mailcap and it is tipically found in UNIX
platforms, a example of @file{/etc/mailcap}:
@smallexample
@group
application/pgp; gpg < %s | metamail; needsterminal; \
test=test %@{encapsulation@}=entity ; copiousoutput
@end group
@end smallexample
A mailcap file consits of a set of mailcap entries per line, lines beginning with @samp{#} are
considered comments and ignored. Long mailcap entry may be continued on multiple lines if
each line ends with a backslash character @samp{\}, the multiline will be considered a single
mailcap entry. The overall format in BNF:
A mailcap file consits of a set of mailcap entries per line, lines
beginning with @samp{#} are considered comments and ignored. Long
mailcap entry may be continued on multiple lines if each line ends
with a backslash character @samp{\}, the multiline will be considered
a single mailcap entry. The overall format in @acronym{BNF}:
@smallexample
Mailcap-File = *Mailcap-Line
Mailcap-Line = Comment | Mailcap-Entry
Comment = NEWLINE | "#" * CHAR NEWLINE
NEWLINE = <newline as defined by OS convention>
@group
Mailcap-File = *@var{mailcap-line}
Mailcap-Line = @var{comment} | @var{mailcap-entry}
Comment = @var{newline} | "#" * @var{char} @var{newline}
Newline = <newline as defined by OS convention>
@end group
@end smallexample
Each mailcap entry consists of a number of fields, separated by semi-colons.
The first two filds are required and must occur in the secified order, the remaining
fields are optional.
Each mailcap entry consists of a number of fields, separated
by semi-colons. The first two filds are required and must occur
in the secified order, the remaining fields are optional.
@smallexample
Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ]
Mailcap-Entry = @var{typefield} ";" @var{view-command} ";" *[ ";" @var{field} ]
@end smallexample
@deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t
The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects are used to hold information
and it is an opaque data structure to the user. Functions are provided to retrieve information
The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects
are used to hold information and it is an opaque data structure
to the user. Functions are provided to retrieve information
from the data structure.
@end deftp
@smallexample
@group
mu_mailcap_t mu_mailcap_entry_t
-/etc/mailcap- +----->/------------------------\ +-->/--------------------\
( alain ) | mu_mailcap_entry[0]*--|----+ | typefield |
-/etc/mailcap- +--->/------------------------\ +-->/------------------\
( alain ) | mu_mailcap_entry[0]*--|--+ | typefield |
| mu_mailcap_entry[1] | | view-command |
| ..... | | field[0] |
| mu_mailcap_entry[n] | | ..... |
\------------------------/ | field[n] |
\--------------------/
\------------------/
@end group
@end smallexample
@subheading An example of parsing a mailcap file:
@subheading An Example of Parsing a Mailcap File:
@smallexample
@include mailcap.inc
@end smallexample
......@@ -68,7 +75,7 @@ The function allocates, parses the buffer from the @var{stream} and initializes
The return value is @code{0} on success and a code number on error conditions:
@table @code
@item MU_ERROR_INVALID_PARAMETER
@var{mailcap} is null or @var{stream} is invalid.
@var{mailcap} is @code{NULL} or @var{stream} is invalid.
@end table
@end deftypefun
......@@ -82,18 +89,12 @@ The return value is @code{0} on success and a code number on error conditions:
@table @code
@item EINVAL
@var{mailcap} or @var{count} is null.
@var{mailcap} or @var{count} is @code{NULL}.
@end table
@end deftypefun
@deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t no, mu_mailcap_entry_t*@var{entry})
Returns in @var{entry} the mailcap entry of @var{no}
@end deftypefun
@deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
@end deftypefun
@deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
@deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t @var{no}, mu_mailcap_entry_t *@var{entry})
Returns in @var{entry} the mailcap entry of @var{no}.
@end deftypefun
@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:
@table @code
@item EINVAL
@var{entry} or @var{count} is null.
@var{entry} or @var{count} is @code{NULL}.
@end table
@end deftypefun
@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})
@deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
@end deftypefun
@deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
@end deftypefun
@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})
@end deftypefun
@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})
@end deftypefun
@deftypefun int mu_mailcap_entry_get_compose (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "compose" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_composetyped (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "composetyped" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_edit (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "edit" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_textualnewlines (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "textualnewlines" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_test (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "test" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_x11bitmap (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "x11-bitmap" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_description (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "description" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_nametemplate (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "nametemplate" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_get_notes (mu_mailcap_entry_t @var{entry}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{n})
Helper function saving in buffer, the argument of "notes" field.
@end deftypefun
@deftypefun int mu_mailcap_entry_needsterminal (mu_mailcap_entry_t @var{entry}, int *@var{on})
Helper function. Returns *@var{on} != 0 if the flag "needsterminal" is in the record.
@end deftypefun
@deftypefun int mu_mailcap_entry_copiousoutput (mu_mailcap_entry_t @var{entry}, int *@var{on})
Helper function. Returns *@var{on} != 0 if the flag "copiousoutput" is in the record.
@end deftypefun
......
......@@ -4,20 +4,22 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{mailer_} is reserved */}
@code{/* Prefix @emph{mailer_} is reserved. */}
@code{#include <mailutils/mailer.h>}
@end smallexample
The API is still changing.
@c
@c Constructor/Destructor.
@c
@deftypefun int mailer_create (mailer_t *, const char *)
@deftypefun int mailer_create (mailer_t *, const char *@var{url})
@end deftypefun
@deftypefun void mailer_destroy (mailer_t *)
@end deftypefun
@deftypefun int mailer_open (mailer_t, int flags)
@deftypefun int mailer_open (mailer_t, int @var{flags})
@end deftypefun
@deftypefun int mailer_close (mailer_t)
......@@ -25,22 +27,19 @@ The API is still changing.
@deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to});
If from is not @var{NULL}, it must contain a single fully qualified
If @var{from} is not @code{NULL}, it must contain a single fully qualified
RFC2822 email address which will be used as the envelope from
address. This is the address to which delivery status notifications
are sent, so it never matters what it is set to until it REALLY matters.
This is equivalent to sendmail's @var{-f} flag.
are sent, so it never matters what it is set to until it @strong{really}
matters. This is equivalent to Sendmail's @option{-f} flag.
The default for @var{from} is provided by the specific mailer.
If to is not @var{NULL}, then the message will be sent to the list of
If to is not @code{NULL}, then the message will be sent to the list of
addresses that it specifies.
The default for @var{to} is to use the contents of the standard "To:", "Cc:",
and "Bcc:" fields, this is equivalent to sendmail's @var{-t} flag.
Note: the previous implementation of mailer_send_message() was equivalent
to having both @var{from} and @var{to} be @var{NULL}.
and "Bcc:" fields, this is equivalent to Sendmail's @option{-t} flag.
@end deftypefun
@deftypefun int mailer_get_property (mailer_t, property_t *)
......@@ -52,10 +51,10 @@ to having both @var{from} and @var{to} be @var{NULL}.
@deftypefun int mailer_set_stream (mailer_t, stream_t)
@end deftypefun
@deftypefun int mailer_get_debug (mailer_t, debug_t *)
@deftypefun int mailer_get_debug (mailer_t, mu_debug_t *)
@end deftypefun
@deftypefun int mailer_set_debug (mailer_t, debug_t)
@deftypefun int mailer_set_debug (mailer_t, mu_debug_t)
@end deftypefun
@deftypefun int mailer_get_observable (mailer_t, observable_t *)
......@@ -64,6 +63,12 @@ to having both @var{from} and @var{to} be @var{NULL}.
@deftypefun int mailer_get_url (mailer_t, url_t *)
@end deftypefun
@deftypefun int mailer_check_from (address_t @var{from})
@end deftypefun
@deftypefun int mailer_check_to (address_t @var{to})
@end deftypefun
@sp 1
@subheading Some Usage Notes
......@@ -73,71 +78,74 @@ Some possible use cases the API must support are:
1 - fill in header addresses
2 - mailer_send_message(mailer, msg, NULL, NULL);
2 - @code{mailer_send_message(mailer, msg, NULL, NULL)}
- from will be filled in if missing,
- bcc's will be deleted before delivery to a non-bcc address,
- Bcc's will be deleted before delivery to a non-bcc address,
- message-id and date will be added, if missing,
- a to: or apparently-to: will be added if non is present (for RFC
- a To: or Apparently-To: will be added if non is present (for RFC
compliance)
- MTA-style .forward ( and sieve-style redirect )
- MTA-style @file{.forward} (and Sieve-style redirect)
1 - get the envelope from of the message to be forwarded
2 - mailer_send_message(mailer, msg, from, to)
2 - @code{mailer_send_message(mailer, msg, from, to)}
- MUA-style bounce
1 - add Resent-[to,from,....]
1 - add Resent-[To,From,...]
2 - mailer_send_message(mailer, msg, NULL, to)
2 - @code{mailer_send_message(mailer, msg, NULL, to)}
- DSN "bounce"
1 - compose DSN
2 - mailer_deliver(mailer, msg, address_t( "<>" ), to)
2 - @code{mailer_deliver(mailer, msg, address_t("<>"), to)}
Don't want mail loops, so the null but valid SMTP address of <> is
the envelope from.
Don't want mail loops, so the null but valid SMTP address of @samp{<>}
is the envelope From.
@subheading The Sendmail Mailer
@file{/sbin/sendmail} isn't always sendmail... sometimes its a
sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands
@file{/sbin/sendmail} isn't always Sendmail... Sometimes it's a
Sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands
only a recipient list, @option{-f} and @option{-oi}, these seem
to be pretty basic. Cross fingers.
Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying @option{-f}
if there was a from, and supplying the recipient list from the to
(if there is no recipient list, assume it will read the message
Pipe to "/sbin/sendmail -oi [-f @var{from}] [@var{to}...]", supplying
@option{-f} if there was a from, and supplying the recipient list from
the to (if there is no recipient list, assume it will read the message
contents for the recipients).
Note: since the stdout and stderr of sendmail is closed, we have no
way of ever giving feedback on failure. Also, what should the return
code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM,
which is less than descriptive!
@strong{Caution:} since the @code{stdout} and @code{stderr} of Sendmail
is closed, we have no way of ever giving feedback on failure. Also, what
should the return code be from @code{mailer_send_message()} when Sendmail
returns @samp{1}? @samp{1} maps to @code{EPERM}, which is less than
descriptive!
@subheading The SMTP Mailer
This mailer does NOT canonicalize the message. This must be done before
sending the message, or it may be assumed that the MTA will do so.
This mailer does @strong{not} canonicalize the message. This must be
done before sending the message, or it may be assumed that the MTA
will do so.
It does blind out the Bcc: header before sending, though.
Note: mutt always puts the recipient addresses on the command line, even
bcc ones, do we strip the bcc before forwarding with SMTP?
@strong{Caution:} Mutt always puts the recipient addresses on the
command line, even Bcc: ones, do we strip the Bcc: before forwarding
with SMTP?
@subheading Non-RFC822 Addresses
An address that has no domain is not and RFC822 email address. What
do I do with them? Should the user of the API be responsible for
determining what is mean by email to "john" means? Or should the
be able to configure sendmail to decide globally what this means.
If so, we can pass the address to sendmail, but we have to decide
determining what is mean by email to "John" means? Or should the
be able to configure Sendmail to decide globally what this means.
If so, we can pass the address to Sendmail, but we have to decide
for SMTP! So, right now these addresses are rejected.
This could be changed.
......
......@@ -4,7 +4,7 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{message_} is reserve */}
@code{/* Prefix @emph{message_} is reserved. */}
@code{#include <mailutils/message.h>}
@end smallexample
......@@ -15,21 +15,25 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
@smallexample
@group
mailbox_t
__________ message_t
(message[1]) +------>+-----------------------+
---------- message_t
(message[1]) +------>+--------------------+
---------- | | envelope_t |
(message[2]) | |-----------------------|
(message[2]) | |--------------------|
---------- | | header_t |
(message[3])--------+ |-----------------------|
(message[3])--------+ |--------------------|
---------- | body_t |
(message[n]) |-----------------------|
(message[n]) |--------------------|
---------- | attribute_t |
|-----------------------|
|--------------------|
| stream_t |
+-----------------------+
+--------------------+
@end group
@end smallexample
@c
@c Basic.
@c
@deftypefun void message_create (message_t *@var{msg}, void *@var{owner})
@end deftypefun
......@@ -37,57 +41,110 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
The resources allocate for @var{msg} are freed.
@end deftypefun
@deftypefun int message_get_header (message_t @var{msg}, header_t *@var{pheader})
@deftypefun int message_create_copy (message_t *@var{to}, message_t *@var{from})
@end deftypefun
@deftypefun void* message_get_owner (message_t @var{msg})
@end deftypefun
@deftypefun int message_is_modified (message_t @var{msg})
@end deftypefun
@deftypefun int message_clear_modified (message_t @var{msg})
@end deftypefun
@deftypefun int message_get_mailbox (message_t @var{msg}, mailbox_t *@var{mbox})
@end deftypefun
@deftypefun int message_set_mailbox (message_t @var{msg}, mailbox_t @var{mbox}, void *@var{owner})
@end deftypefun
@c
@c ------------
@c
@deftypefun int message_ref (message_t @var{msg})
@end deftypefun
@deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *@var{envelope})
@end deftypefun
@deftypefun int message_set_envelope (message_t @var{msg}, envelope_t @var{envelope}, void *@var{owner})
@end deftypefun
@deftypefun int message_get_header (message_t @var{msg}, header_t *@var{header})
Retrieve @var{msg} header.
@end deftypefun
@deftypefun int message_set_header (message_t @var{msg}, header_t @var{header}, void *@var{owner})
@end deftypefun
@deftypefun int message_get_body (message_t @var{msg}, body_t *@var{pbody})
@deftypefun int message_get_body (message_t @var{msg}, body_t *@var{body})
@end deftypefun
@deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner})
@end deftypefun
@deftypefun int message_is_multipart (message_t @var{msg}, int *@var{pmulti})
Set *@var{pmulti} to non-zero value if @var{msg} is multi-part.
@deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{stream})
@end deftypefun
@deftypefun int message_get_num_parts (message_t @var{msg}, size_t *nparts)
@deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream}, void *@var{owner})
@end deftypefun
@deftypefun int message_get_part (message_t @var{msg}, size_t part, message_t *msg)
@deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{attribute})
@end deftypefun
@deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{pstream})
@deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *@var{owner})
@end deftypefun
@deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream},void *@var{owner} )
@deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable})
@end deftypefun
@deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{pattribute})
@c
@c ------------
@c
@deftypefun int message_is_multipart (message_t @var{msg}, int *@var{multi})
Set *@var{multi} to non-zero value if @var{msg} is multi-part.
@end deftypefun
@deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *owner)
@deftypefun int message_set_is_multipart (message_t @var{msg}, int (*@var{_is_multipart}) (message_t, int *), void *);
@end deftypefun
@deftypefun int message_get_envelope (message_t @var{msg}, envelope_t *penvelope)
@deftypefun int message_size (message_t @var{msg}, size_t *@var{size})
@end deftypefun
@deftypefun int message_set_envelope (message_t @var{msg}, envelope_t envelope, void *@var{owner})
@deftypefun int message_set_size (message_t @var{msg}, int (*@var{_size}) (message_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid})
@deftypefun int message_lines (message_t @var{msg}, size_t *@var{size})
@end deftypefun
@deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten})
@deftypefun int message_set_lines (message_t @var{msg}, int (*@var{_lines}) (message_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl})(message_t, char *, size_t, size_t *), void *@var{owner})
@deftypefun int message_get_num_parts (message_t @var{msg}, size_t *@var{nparts})
@end deftypefun
@deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable})
@deftypefun int message_set_get_num_parts (message_t @var{msg}, int (*@var{_get_num_parts}) (message_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_get_part (message_t @var{msg}, size_t @var{part}, message_t *@var{msg})
@end deftypefun
@deftypefun int message_set_get_part (message_t @var{msg}, int (*@var{_get_part}) (message_t, size_t, message_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
@end deftypefun
@deftypefun int message_set_uidl (message_t @var{msg}, int (*@var{_get_uidl}) (message_t, char *, size_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid})
@end deftypefun
@deftypefun int message_set_uid (message_t @var{msg}, int (*@var{_get_uid}) (message_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg})
......@@ -101,3 +158,12 @@ Set *@var{pmulti} to non-zero value if @var{msg} is multi-part.
@deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data});
@end deftypefun
@deftypefun int message_get_attachment_name (message_t @var{msg}, char *@var{name}, size_t @var{bufsize}, size_t *@var{size});
@end deftypefun
@deftypefun int message_aget_attachment_name (message_t @var{msg}, char **@var{name});
@end deftypefun
@deftypefun int message_save_to_mailbox (message_t @var{msg}, ticket_t @var{ticket}, mu_debug_t @var{debug}, const char *@var{toname});
@end deftypefun
......
......@@ -4,60 +4,157 @@
@comment *******************************************************************
@smallexample
@code{/* Prefix @emph{parse822_} is reserved */}
@code{/* Prefix @emph{parse822_} is reserved. */}
@code{#include <mailutils/parse822.h>}
@end smallexample
Internet Message Format, see Address node for the discussion.
@deftypefun int parse822_is_char (char @var{c})
@end deftypefun
@deftypefun int parse822_is_digit (char @var{c})
@end deftypefun
@deftypefun int parse822_is_ctl (char @var{c})
@end deftypefun
@deftypefun int parse822_is_space (char @var{c})
@end deftypefun
@deftypefun int parse822_is_htab (char @var{c})
@end deftypefun
@deftypefun int parse822_is_lwsp_char (char @var{c})
@end deftypefun
@deftypefun int parse822_is_special (char @var{c})
@end deftypefun
@deftypefun int parse822_is_atom_char (char @var{c})
@end deftypefun
@deftypefun int parse822_is_q_text (char @var{c})
@end deftypefun
@deftypefun int parse822_is_d_text (char @var{c})
@end deftypefun
@deftypefun int parse822_is_smtp_q (char @var{c})
@end deftypefun
@deftypefun int parse822_skip_crlf (const char **@var{p}, const char *@var{e})
@end deftypefun
@deftypefun int parse822_skip_lwsp_char (const char **@var{p}, const char *@var{e})
@end deftypefun
@deftypefun int parse822_skip_lwsp (const char **@var{p}, const char *@var{e})
@end deftypefun
@deftypefun int parse822_skip_comments (const char **@var{p}, const char *@var{e})
@end deftypefun
@deftypefun int parse822_skip_nl (const char **@var{p}, const char *@var{e})
@end deftypefun
@deftypefun int parse822_digits (const char **@var{p}, const char *@var{e}, int @var{min}, int @var{max}, int *@var{digits})
@end deftypefun
@deftypefun int parse822_special (const char **@var{p}, const char *@var{e}, char @var{c})
@end deftypefun
@deftypefun int parse822_comment (const char **@var{p}, const char *@var{e}, char **@var{comment})
@end deftypefun
@deftypefun int parse822_atom (const char **@var{p}, const char *@var{e}, char **@var{atom})
@end deftypefun
@deftypefun int parse822_quoted_pair (const char **@var{p}, const char *@var{e}, char **@var{qpair})
@end deftypefun
@deftypefun int parse822_quoted_string (const char **@var{p}, const char *@var{e}, char **@var{qstr})
@end deftypefun
@deftypefun int parse822_word (const char **@var{p}, const char *@var{e}, char **@var{word})
@end deftypefun
@deftypefun int parse822_address_list (address_t* a, const char* s)
@deftypefun int parse822_phrase (const char **@var{p}, const char *@var{e}, char **@var{phrase})
@end deftypefun
@deftypefun int parse822_mail_box (const char** p, const char* e, address_t* a)
@deftypefun int parse822_d_text (const char **@var{p}, const char *@var{e}, char **@var{dtext})
@end deftypefun
@deftypefun int parse822_group (const char** p, const char* e, address_t* a)
@c
@c From RFC 822, 6.1 Address Specification Syntax
@c
@deftypefun int parse822_address_list (address_t *@var{a}, const char *@var{s})
@end deftypefun
@deftypefun int parse822_mail_box (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_group (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_address (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_address (const char** p, const char* e, address_t* a)
@deftypefun int parse822_route_addr (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_route_addr (const char** p, const char* e, address_t* a)
@deftypefun int parse822_route (const char **@var{p}, const char *@var{e}, char **@var{route})
@end deftypefun
@deftypefun int parse822_route (const char** p, const char* e, char** route)
@deftypefun int parse822_addr_spec (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_addr_spec (const char** p, const char* e, address_t* a)
@deftypefun int parse822_unix_mbox (const char **@var{p}, const char *@var{e}, address_t *@var{a})
@end deftypefun
@deftypefun int parse822_unix_mbox (const char** p, const char* e, address_t* a)
@deftypefun int parse822_local_part (const char **@var{p}, const char *@var{e}, char **@var{local_part})
@end deftypefun
@deftypefun int parse822_local_part (const char** p, const char* e, char** local_part)
@deftypefun int parse822_domain (const char **@var{p}, const char *@var{e}, char **@var{domain})
@end deftypefun
@deftypefun int parse822_domain (const char** p, const char* e, char** domain)
@deftypefun int parse822_sub_domain (const char **@var{p}, const char *@var{e}, char **@var{sub_domain})
@end deftypefun
@deftypefun int parse822_sub_domain (const char** p, const char* e, char** sub_domain)
@deftypefun int parse822_domain_ref (const char **@var{p}, const char *@var{e}, char **@var{domain_ref})
@end deftypefun
@deftypefun int parse822_domain_ref (const char** p, const char* e, char** domain_ref)
@deftypefun int parse822_domain_literal (const char **@var{p}, const char *@var{e}, char **@var{domain_literal})
@end deftypefun
@deftypefun int parse822_domain_literal (const char** p, const char* e, char** domain_literal)
@c
@c RFC 822 Quoting Functions
@c
@deftypefun int parse822_quote_string (char **@var{quoted}, const char *@var{raw})
@end deftypefun
@deftypefun int parse822_quote_string (char** quoted, const char* raw)
@deftypefun int parse822_quote_local_part (char **@var{quoted}, const char *@var{raw})
@end deftypefun
@deftypefun int parse822_field_body (const char **@var{p}, const char *@var{e}, char **@var{fieldbody})
@end deftypefun
@deftypefun int parse822_field_name (const char **@var{p}, const char *@var{e}, char **@var{fieldname})
@end deftypefun
@c
@c From RFC 822, 5.1 Date and Time Specification Syntax
@c
@deftypefun int parse822_day (const char **@var{p}, const char *@var{e}, int *@var{day})
@end deftypefun
@deftypefun int parse822_quote_local_part (char** quoted, const char* raw)
@deftypefun int parse822_date (const char **@var{p}, const char *@var{e}, int *@var{day}, int *@var{mon}, int *@var{year})
@end deftypefun
@deftypefun int parse822_field_body (const char** p, const char *e, char** fieldbody)
@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})
@end deftypefun
@deftypefun int parse822_field_name (const char** p, const char *e, char** fieldname)
@deftypefun int parse822_date_time (const char **@var{p}, const char *@var{e}, struct tm *@var{tm}, mu_timezone *@var{tz})
@end deftypefun
......
......@@ -33,37 +33,53 @@ The stream is set non blocking.
@item MU_STREAM_NO_CHECK
@findex MU_STREAM_NO_CHECK
Stream is destroyed without checking for the owner.
@item MU_STREAM_SEEKABLE
@findex MU_STREAM_SEEKABLE
@item MU_STREAM_NO_CLOSE
@findex MU_STREAM_NO_CLOSE
Stream doesn't close it's underlying resource when it is closed or destroyed.
@item MU_STREAM_ALLOW_LINKS
@findex MU_STREAM_ALLOW_LINKS
@end table
@deftypefun int file_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@deftypefun int file_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
@end deftypefun
@deftypefun int tcp_stream_create (stream_t *@var{pstream}, const char *@var{host}, int @var{port}, int @var{flags})
@deftypefun int tcp_stream_create (stream_t *@var{stream}, const char *@var{host}, int @var{port}, int @var{flags})
@end deftypefun
@deftypefun int mapfile_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@deftypefun int mapfile_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
@end deftypefun
@deftypefun int memory_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@deftypefun int memory_stream_create (stream_t *@var{stream}, const char *@var{filename}, int @var{flags})
@end deftypefun
@deftypefun int encoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
@deftypefun int encoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
@end deftypefun
@deftypefun int decoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
@deftypefun int decoder_stream_create (stream_t *@var{stream}, stream_t @var{iostream}, const char *@var{encoding})
@end deftypefun
@deftypefun int stdio_stream_create (stream_t *@var{pstream}, FILE* @var{stdio}, int @var{flags})
@deftypefun int stdio_stream_create (stream_t *@var{stream}, FILE *@var{stdio}, int @var{flags})
If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
@var{stdio} when the stream is closed.
@end deftypefun
@deftypefun void stream_destroy (stream_t *@var{pstream}, void *@var{owner})
@deftypefun int prog_stream_create (stream_t *@var{stream}, char *@var{progname}, int @var{flags})
@end deftypefun
@deftypefun int filter_prog_stream_create (stream_t *@var{stream}, char *@var{progname}, stream_t @var{input})
@end deftypefun
@deftypefun void stream_destroy (stream_t *@var{stream}, void *@var{owner})
@end deftypefun
@c
@c ---------
@c
@deftypefun int stream_open (stream_t @var{stream})
@end deftypefun
......@@ -73,22 +89,25 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
@deftypefun int stream_is_seekable (stream_t @var{stream})
@end deftypefun
@deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd})
@deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{fd})
@end deftypefun
@deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@deftypefun int stream_get_fd2 (stream_t @var{stream}, int *@var{fd1}, int *@var{fd2})
@end deftypefun
@deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
@end deftypefun
@deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize})
@deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
@end deftypefun
@deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size})
@deftypefun int stream_size (stream_t @var{stream}, off_t *@var{size})
@end deftypefun
@deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@deftypefun n int stream_truncate (stream_t @var{stream}, off_t @var{size})
@end deftypefun
@deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{writen})
@end deftypefun
@deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size})
......@@ -97,16 +116,33 @@ If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
@deftypefun int stream_flush (stream_t @var{stream})
@end deftypefun
These functions will typically only be useful to implementors of streams.
@c
@c These functions will typically only be useful to implementors of streams.
@c
@deftypefun int stream_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner})
@deftypefun int stream_create (stream_t *@var{stream}, int @var{flags}, void *@var{owner})
Used to implement a new kind of stream.
@end deftypefun
@deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{pflags})
@deftypefun void* stream_get_owner (stream_t @var{stream})
@end deftypefun
@deftypefun void stream_set_owner (stream_t @var{stream}, void *@var{owner})
@end deftypefun
@deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{flags})
@end deftypefun
@deftypefun int stream_get_state (stream_t @var{stream}, int *@var{pstate})
@deftypefun int stream_set_flags (stream_t @var{stream}, int @var{flags})
@end deftypefun
@deftypefun int stream_get_property (stream_t @var{stream}, property_t *)
@end deftypefun
@deftypefun int stream_set_property (stream_t @var{stream}, property_t, void *)
@end deftypefun
@deftypefun int stream_get_state (stream_t @var{stream}, int *@var{state})
@table @code
@item MU_STREAM_STATE_OPEN
Last action was @code{stream_open}.
......@@ -119,7 +155,52 @@ Last action was @code{stream_close}.
@end table
@end deftypefun
An example using @code{tcp_stream_create} to make a simple web client:
@deftypefun int stream_set_destroy (stream_t @var{stream}, void (*@var{_destroy}) (stream_t), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_open (stream_t @var{stream}, int (*@var{_open}) (stream_t), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_close (stream_t @var{stream}, int (*@var{_close}) (stream_t), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_fd (stream_t @var{stream}, int (*@var{_get_fd}) (stream_t, int *, int *), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_read (stream_t @var{stream}, int (*@var{_read}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_readline (stream_t @var{stream}, int (*@var{_readline}) (stream_t, char *, size_t, off_t, size_t *), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_size (stream_t @var{stream}, int (*@var{_size}) (stream_t, off_t *), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_truncate (stream_t @var{stream}, int (*@var{_truncate}) (stream_t, off_t), void *@var{owner})
@end deftypefun
@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})
@end deftypefun
@deftypefun int stream_set_flush (stream_t @var{stream}, int (*@var{_flush}) (stream_t), void *@var{owner})
@end deftypefun
@deftypefun int stream_set_strerror (stream_t @var{stream}, int (*@var{_fp}) (stream_t, char **), void *@var{owner})
@end deftypefun
@deftypefun int stream_sequential_readline (stream_ts @var{stream}, char *@var{buf}, size_t @var{size}, size_t *@var{nbytes})
@end deftypefun
@deftypefun int stream_sequential_write (stream_t @var{stream}, char *@var{buf}, size_t @var{size})
@end deftypefun
@deftypefun int stream_seek (stream_t @var{stream}, off_t @var{off}, int @var{whence})
@end deftypefun
@deftypefun int stream_strerror (stream_t @var{stream}, char **@var{p})
@end deftypefun
An example using @code{tcp_stream_create()} to make a simple web client:
@smallexample
@include http.inc
......
......@@ -13,13 +13,15 @@ The POP URL scheme contains a POP server, optional port number
and the authentication mechanism. The general form is
@smallexample
@url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]}
@group
@url{pop://[<@var{user}>[;AUTH=<@var{auth}>]@@]<@var{host}>[:<@var{port}>]}
or
@url{pop://[<user>[:<passwd>]@@]<host>[:<port>]}
@url{pop://[<@var{user}>[:<@var{passwd}>]@@]<@var{host}>[:<@var{port}>]}
@end group
@end smallexample
If @emph{:port} is omitted the default value is 110. Different forms of
authentication can be specified with @emph{;AUTH=type}.
authentication can be specified with @emph{;AUTH=@var{type}}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.
......@@ -38,13 +40,15 @@ The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism. The general form is
@smallexample
@url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]}
@group
@url{imap://[<@var{user}>[;AUTH=<@var{type}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
or
@url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]}
@url{imap://[<@var{user}>[:<@var{passwd}>]]@@<@var{host}>[:@var{port}][/<@var{mailbox}>]}
@end group
@end smallexample
If @emph{:port} is omitted the default value is 220. Different forms of
authentication can be specified with @emph{;AUTH=type}.
If @emph{:port} is omitted the default value is 143. Different forms of
authentication can be specified with @emph{;AUTH=@var{type}}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.
......@@ -63,17 +67,21 @@ the mailbox recognize the type of mailbox and take the appropriate
action.
@smallexample
@url{file://path}
@group
@url{file://@var{path}}
@url{file://var/mail/user}
@url{file://home/obelix/Mail}
@end group
@end smallexample
For MMDF, MH local mailboxes URLs are provided, but it is preferable to
use @url{file://path} and let the library figure out which one.
use @url{file://@var{path}} and let the library figure out which one.
@smallexample
@url{mmdf://path}
@url{mh://path}
@group
@url{mmdf://@var{path}}
@url{mh://@var{path}}
@end group
@end smallexample
@subheading Mailto
......@@ -82,7 +90,7 @@ After setting a mailer, @url{mailto:} is used to tell the mailer where
and to whom the message is for.
@smallexample
@url{mailto://hostname}
@url{mailto://@var{hostname}}
@end smallexample
Mailto can be used to generate short messages, for example to subscribe
......@@ -95,70 +103,99 @@ to mailing lists.
For more complete information see @cite{RFC 2368}.
@subheading URL functions
@c
@c URL Functions
@c
@subheading URL Functions
Helper functions are provided to retrieve and set the @emph{URL} fields.
@deftypefun int url_create (url_t *@var{url}, const char *@var{name})
Create and the @var{url} data structure, but do not parse it.
Create the url data structure, but do not parse it.
@end deftypefun
@deftypefun void url_destroy (url_t *)
Destroy the url and free it's resources.
@deftypefun void url_destroy (url_t *@var{url})
Destroy the url and free its resources.
@end deftypefun
@deftypefun int url_parse (url_t @var{url})
@deftypefun int url_parse (url_t)
Parses the url, after calling this the get functions can be called.
The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth=
of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is:
@smallexample
@group
url =
scheme ":" [ "//"
[ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]
[ @var{user} [ ( ":" @var{password} ) | ( ";auth=" @var{auth} ) ] "@@" ]
host [ ":" port ]
@var{host} [ ":" @var{port} ]
[ ( "/" urlpath ) | ( "?" query ) ] ]
[ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
@end group
@end smallexample
This is a generalized URL syntax, and may not be exactly appropriate
for any particular scheme.
@end deftypefun
@deftypefun int url_get_scheme (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_user (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_passwd (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_auth (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun const char* url_to_string (const url_t @var{url})
@deftypefun int url_get_host (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n})
@deftypefun int url_get_port (const url_t, long *)
@end deftypefun
@deftypefun int url_get_user (const url_t @var{url}, char *@var{usr}, size_t @var{len}, size_t *@var{n})
@deftypefun int url_get_path (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, size_t *@var{n})
@deftypefun int url_get_query (const url_t, char *, size_t, size_t *)
@end deftypefun
@deftypefun int url_get_host (const url_t @var{url}, char *@var{host}, size_t @var{len}, size_t *@var{n})
@deftypefun {const char*} url_to_string (const url_t)
@end deftypefun
@deftypefun int url_get_port (const url_t @var{url}, long *@var{port})
@deftypefun int url_is_scheme (url_t, const char *@var{scheme})
@end deftypefun
@deftypefun int url_get_path (const url_t @var{url}, char *@var{path}, size_t @var{len}, size_t *@var{n})
@deftypefun int url_is_same_scheme (url_t, url_t)
@end deftypefun
@deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n})
@deftypefun int url_is_same_user (url_t, url_t)
@end deftypefun
@deftypefun char* url_decode (const char* @var{string})
Decodes an @cite{RFC 1738} % encoded string, returning the decoded string
@deftypefun int url_is_same_path (url_t, url_t)
@end deftypefun
@deftypefun int url_is_same_host (url_t, url_t)
@end deftypefun
@deftypefun int url_is_same_port (url_t, url_t)
@end deftypefun
@deftypefun char* url_decode (const char *@var{string})
Decodes an @cite{RFC 1738} encoded string, returning the decoded string
in allocated memory. If the string is not encoded, this degenerates to
a @code{strdup()}.
@end deftypefun
@deftypefun int url_is_ticket (url_t @var{ticket}, url_t @var{url})
@end deftypefun
@subheading Example
@smallexample
@include url-parse.inc
......