diff --git a/doc/texinfo/address.texi b/doc/texinfo/address.texi index 899fb84..8276968 100644 --- a/doc/texinfo/address.texi +++ b/doc/texinfo/address.texi @@ -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,7 +77,11 @@ data structure to the user. Functions are provided to retrieve information about an address in the address list. @end deftp -@deftypefun int address_create (address_t *@var{addr}, const char *@var{string}) +@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}. @@ -89,10 +93,10 @@ The return value is @code{0} on success and a code number on error conditions: @end table @end deftypefun -@deftypefun int address_createv (address_t *@var{addr}, const char *@var{sv}, size_t @var{len}) +@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: @@ -103,12 +107,18 @@ The return value is @code{0} on success and a code number on error conditions: @end table @end deftypefun -@deftypefun void address_destroy (address_t *@var{addr}) +@deftypefun void address_destroy (address_t *@var{addr}) 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 diff --git a/doc/texinfo/attribute.texi b/doc/texinfo/attribute.texi index 53c68d0..004a8bc 100644 --- a/doc/texinfo/attribute.texi +++ b/doc/texinfo/attribute.texi @@ -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}) +@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 diff --git a/doc/texinfo/auth.texi b/doc/texinfo/auth.texi index 22ef41e..e0f1bcc 100644 --- a/doc/texinfo/auth.texi +++ b/doc/texinfo/auth.texi @@ -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: diff --git a/doc/texinfo/body.texi b/doc/texinfo/body.texi index b1096d1..c79f13d 100644 --- a/doc/texinfo/body.texi +++ b/doc/texinfo/body.texi @@ -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}. +@deftypefun int body_create (body_t *@var{body}, void *@var{owner}) +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_set_stream (body_t @var{body}, stream_t @var{stream}, void *@var{owner}) +@deftypefun int body_is_modified (body_t @var{body}) @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_clear_modified (body_t @var{body}) @end deftypefun -@deftypefun int body_set_filename (body_t @var{body}, const char*@var{buffer}) +@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 (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_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 diff --git a/doc/texinfo/envelope.texi b/doc/texinfo/envelope.texi index 9373542..09a3e80 100644 --- a/doc/texinfo/envelope.texi +++ b/doc/texinfo/envelope.texi @@ -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 diff --git a/doc/texinfo/folder.texi b/doc/texinfo/folder.texi index 8ccb4dc..0a01187 100644 --- a/doc/texinfo/folder.texi +++ b/doc/texinfo/folder.texi @@ -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,77 +12,126 @@ @smallexample @group folder_t url_t - -/var/mail- +---//---->/-----------------\ +-->/-----------\ - ( alain *-)-+ | | url_t *-|----+ | port | - ----------- | | |-----------------+ | hostname | - ( jakob *-)-+--+ | observer_t *-| | file | - ----------- | |-----------------+ | ... | - ( jeff *-)-+ | stream_t | \-----------/ - ----------- | |-----------------| - ( sean *-)-+ | auth_t | - ---------- |-----------------| - | mailbox_t(1) | - |-----------------| - | mailbox_t(2) | - | ...... | - | mailbox_t(n) | - \-----------------/ + -/var/mail- +---//--->/-----------------\ +-->/-----------\ + ( alain *-)-+ | | url_t *-|---+ | port | + ---------- | | |-----------------+ | hostname | + ( jakob *-)-+--+ | observer_t *-| | file | + ---------- | |-----------------+ | ... | + ( jeff *-)-+ | stream_t | \-----------/ + ---------- | |-----------------| + ( sean *-)-+ | auth_t | + ---------- |-----------------| + | mailbox_t(1) | + |-----------------| + | mailbox_t(2) | + | ...... | + | mailbox_t(n) | + \-----------------/ @end group @end smallexample -@deftypefun int folder_create (folder_t *, const char *@var{url}) +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 @deftypefun void folder_destroy (folder_t *) @end deftypefun -@deftypefun int folder_open (folder_t, int @var{flag}) +@deftypefun int folder_open (folder_t, int @var{flag}) +@end deftypefun + +@deftypefun int folder_close (folder_t) +@end deftypefun + +@deftypefun int folder_delete (folder_t, const char *@var{mailbox}) @end deftypefun -@deftypefun int folder_close (folder_t) +@deftypefun int folder_rename (folder_t, const char *, const char *@var{mailbox}) @end deftypefun -@deftypefun int folder_delete (folder_t, const char *@var{mailbox}) +@deftypefun int folder_subscribe (folder_t, const char *@var{mailbox}) @end deftypefun -@deftypefun int folder_rename (folder_t, const char *, const char *@var{mailbox}) +@deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox}) @end deftypefun -@deftypefun int folder_subscribe (folder_t, const char *@var{mailbox}) +@deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *) @end deftypefun -@deftypefun int folder_unsubscribe (folder_t, const char *@var{mailbox}) +@deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcard}, struct folder_list *) @end deftypefun -@deftypefun int folder_list (folder_t, const char *@var{ref}, const char *@var{wcard}, iterator_t *) +@deftypefun int folder_list_destroy (struct folder_list *) @end deftypefun -@deftypefun int folder_lsub (folder_t, const char *@var{ref}, const char *@var{wcar}, iterator_t *) +@c +@c Stream Settings. +@c + +@deftypefun int folder_get_stream (folder_t, stream_t *) @end deftypefun -@deftypefun int folder_get_stream (folder_t, stream_t *) +@deftypefun int folder_set_stream (folder_t, stream_t) @end deftypefun -@deftypefun int folder_set_stream (folder_t, stream_t) +@c +@c Notifications. +@c + +@deftypefun int folder_get_observable (folder_t, observable_t *) @end deftypefun -@deftypefun int folder_get_observable (folder_t, observable_t *) +@c +@c Debug. +@c + +@deftypefun int folder_has_debug (folder_t) @end deftypefun -@deftypefun int folder_get_debug (folder_t, debug_t *) +@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 -@deftypefun int folder_get_authority (folder_t, authority_t *) +@c +@c Authentication. +@c + +@deftypefun int folder_get_authority (folder_t, authority_t *) @end deftypefun -@deftypefun int folder_set_authority (folder_t, authority_t) +@deftypefun int folder_set_authority (folder_t, authority_t) @end deftypefun -@deftypefun int folder_get_url (folder_t, url_t *) +@c +@c URL. +@c + +@deftypefun int folder_get_url (folder_t, url_t *) @end deftypefun -@deftypefun int folder_set_url (folder_t, url_t) +@deftypefun int folder_set_url (folder_t, url_t) @end deftypefun diff --git a/doc/texinfo/framework.texi b/doc/texinfo/framework.texi index f8d4e06..118cec2 100644 --- a/doc/texinfo/framework.texi +++ b/doc/texinfo/framework.texi @@ -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 - diff --git a/doc/texinfo/headers.texi b/doc/texinfo/headers.texi index 4a0c20d..5458781 100644 --- a/doc/texinfo/headers.texi +++ b/doc/texinfo/headers.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. +@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 @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,27 +93,118 @@ 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 -@deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n}) +@deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n}) Value of field-name @var{fn} is returned in buffer @var{fv} of size @var{len}. The number of bytes written is put in @var{n}. @end deftypefun -@deftypefun int header_aget_value (header_t @var{hdr}, const char *@var{fn}, char **@var{fv}) +@deftypefun int header_aget_value (header_t @var{hdr}, const char *@var{fn}, char **@var{fv}) 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 diff --git a/doc/texinfo/iterator.texi b/doc/texinfo/iterator.texi index 9908f63..523656d 100644 --- a/doc/texinfo/iterator.texi +++ b/doc/texinfo/iterator.texi @@ -4,24 +4,30 @@ @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 *) @end deftypefun -@deftypefun int iterator_first (iterator_t) +@deftypefun int iterator_first (iterator_t) +@end deftypefun + +@deftypefun int iterator_next (iterator_t) @end deftypefun -@deftypefun int iterator_next (iterator_t) +@deftypefun int iterator_current (iterator_t, void **@var{item}) @end deftypefun -@deftypefun int iterator_current (iterator_t, void **pitem) +@deftypefun int iterator_is_done (iterator_t) @end deftypefun -@deftypefun int iterator_is_done (iterator_t) +@deftypefun int iterator_get_list (iterator_t @var{iterator}, list_t *@var{list}) @end deftypefun diff --git a/doc/texinfo/libmuauth.texi b/doc/texinfo/libmuauth.texi index 7c82bb1..d072a1a 100644 --- a/doc/texinfo/libmuauth.texi +++ b/doc/texinfo/libmuauth.texi @@ -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}) @@ -181,8 +175,7 @@ Search the information about given user by its uid. Similar to system's @code{getpwuid} call). @end deftypefun -@deftypefun int mu_authenticate (struct mu_auth_data *@var{auth_data}, char *@var{pass}) - +@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} diff --git a/doc/texinfo/libsieve.texi b/doc/texinfo/libsieve.texi index 6f8e6e8..2962408 100644 --- a/doc/texinfo/libsieve.texi +++ b/doc/texinfo/libsieve.texi @@ -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 diff --git a/doc/texinfo/locker.texi b/doc/texinfo/locker.texi index 06bf5dd..92997c1 100644 --- a/doc/texinfo/locker.texi +++ b/doc/texinfo/locker.texi @@ -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 diff --git a/doc/texinfo/mailbox.texi b/doc/texinfo/mailbox.texi index f9f6dba..09e47fd 100644 --- a/doc/texinfo/mailbox.texi +++ b/doc/texinfo/mailbox.texi @@ -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,53 +17,37 @@ from the data structure. @smallexample @group mailbox_t url_t - -/var/mail- +---//---->/-----------------\ +-->/-----------\ - ( alain ) | | url_t *-|----+ | port | - ----------- | |-----------------+ | hostname | - ( jakob *-)----+ | observer_t *-| | file | - ----------- |-----------------+ | ... | - ( jeff ) | stream_t | \-----------/ - ----------- |-----------------| - ( sean ) | locker_t | - ---------- |-----------------| - | message_t(1) | - |-----------------| - | message_t(2) | - | ...... | - | message_t(n) | - \-----------------/ + -/var/mail- +---//--->/-----------------\ +-->/-----------\ + ( alain ) | | url_t *-|---+ | port | + ---------- | |-----------------+ | hostname | + ( jakob *-)----+ | observer_t *-| | file | + ---------- |-----------------+ | ... | + ( jeff ) | stream_t | \-----------/ + ---------- |-----------------| + ( sean ) | locker_t | + ---------- |-----------------| + | message_t(1) | + |-----------------| + | message_t(2) | + | ...... | + | message_t(n) | + \-----------------/ @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 +@c +@c Constructor/destructor and possible types. +@c -@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. -@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 diff --git a/doc/texinfo/mailcap.texi b/doc/texinfo/mailcap.texi index acd4ad5..8dce883 100644 --- a/doc/texinfo/mailcap.texi +++ b/doc/texinfo/mailcap.texi @@ -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 | - | mu_mailcap_entry[1] | | view-command | - | ..... | | field[0] | - | mu_mailcap_entry[n] | | ..... | - \------------------------/ | field[n] | - \--------------------/ + mu_mailcap_t mu_mailcap_entry_t +-/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,32 +75,26 @@ 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 -@deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap}) +@deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap}) Release any resources from the mailcap object. @end deftypefun -@deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count}) +@deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count}) The function returns the number of entries found in the mailcap. 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 diff --git a/doc/texinfo/mailer.texi b/doc/texinfo/mailer.texi index 7b7e099..9a6cb8d 100644 --- a/doc/texinfo/mailer.texi +++ b/doc/texinfo/mailer.texi @@ -4,64 +4,69 @@ @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) +@deftypefun int mailer_close (mailer_t) @end deftypefun -@deftypefun int mailer_send_message (mailer_t @var{mailer}, message_t @var{msg}, address_t @var{from}, address_t @var{to}); +@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. +and "Bcc:" fields, this is equivalent to Sendmail's @option{-t} flag. +@end deftypefun + +@deftypefun int mailer_get_property (mailer_t, property_t *) +@end deftypefun -Note: the previous implementation of mailer_send_message() was equivalent -to having both @var{from} and @var{to} be @var{NULL}. +@deftypefun int mailer_get_stream (mailer_t, stream_t *) @end deftypefun -@deftypefun int mailer_get_property (mailer_t, property_t *) +@deftypefun int mailer_set_stream (mailer_t, stream_t) @end deftypefun -@deftypefun int mailer_get_stream (mailer_t, stream_t *) +@deftypefun int mailer_get_debug (mailer_t, mu_debug_t *) @end deftypefun -@deftypefun int mailer_set_stream (mailer_t, stream_t) +@deftypefun int mailer_set_debug (mailer_t, mu_debug_t) @end deftypefun -@deftypefun int mailer_get_debug (mailer_t, debug_t *) +@deftypefun int mailer_get_observable (mailer_t, observable_t *) @end deftypefun -@deftypefun int mailer_set_debug (mailer_t, debug_t) +@deftypefun int mailer_get_url (mailer_t, url_t *) @end deftypefun -@deftypefun int mailer_get_observable (mailer_t, observable_t *) +@deftypefun int mailer_check_from (address_t @var{from}) @end deftypefun -@deftypefun int mailer_get_url (mailer_t, url_t *) +@deftypefun int mailer_check_to (address_t @var{to}) @end deftypefun @sp 1 @@ -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. diff --git a/doc/texinfo/message.texi b/doc/texinfo/message.texi index ad55cc9..3e778de 100644 --- a/doc/texinfo/message.texi +++ b/doc/texinfo/message.texi @@ -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]) +------>+-----------------------+ - ---------- | | envelope_t | - (message[2]) | |-----------------------| - ---------- | | header_t | - (message[3])--------+ |-----------------------| - ---------- | body_t | - (message[n]) |-----------------------| - ---------- | attribute_t | - |-----------------------| - | stream_t | - +-----------------------+ + ---------- message_t + (message[1]) +------>+--------------------+ + ---------- | | envelope_t | + (message[2]) | |--------------------| + ---------- | | header_t | + (message[3])--------+ |--------------------| + ---------- | body_t | + (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,67 +41,129 @@ 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}) +@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{body}) +@end deftypefun + +@deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, void *@var{owner}) +@end deftypefun + +@deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{stream}) +@end deftypefun + +@deftypefun int message_set_stream (message_t @var{msg}, stream_t @var{stream}, void *@var{owner}) +@end deftypefun + +@deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{attribute}) +@end deftypefun + +@deftypefun int message_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *@var{owner}) +@end deftypefun + +@deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable}) +@end deftypefun + +@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_is_multipart (message_t @var{msg}, int (*@var{_is_multipart}) (message_t, int *), void *); @end deftypefun -@deftypefun int message_get_body (message_t @var{msg}, body_t *@var{pbody}) +@deftypefun int message_size (message_t @var{msg}, size_t *@var{size}) @end deftypefun -@deftypefun int message_set_body (message_t @var{msg}, body_t @var{body}, 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_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_lines (message_t @var{msg}, size_t *@var{size}) @end deftypefun -@deftypefun int message_get_num_parts (message_t @var{msg}, size_t *nparts) +@deftypefun int message_set_lines (message_t @var{msg}, int (*@var{_lines}) (message_t, size_t *), void *@var{owner}) @end deftypefun -@deftypefun int message_get_part (message_t @var{msg}, size_t part, message_t *msg) +@deftypefun int message_get_num_parts (message_t @var{msg}, size_t *@var{nparts}) @end deftypefun -@deftypefun int message_get_stream (message_t @var{msg}, stream_t *@var{pstream}) +@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_set_stream (message_t @var{msg}, stream_t @var{stream},void *@var{owner} ) +@deftypefun int message_get_part (message_t @var{msg}, size_t @var{part}, message_t *@var{msg}) @end deftypefun -@deftypefun int message_get_attribute (message_t @var{msg}, attribute_t *@var{pattribute}) +@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_set_attribute (message_t @var{msg}, attribute_t @var{attribute}, void *owner) +@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_get_envelope (message_t @var{msg}, envelope_t *penvelope) +@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_set_envelope (message_t @var{msg}, envelope_t envelope, void *@var{owner}) +@deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid}) @end deftypefun -@deftypefun int message_get_uid (message_t @var{msg}, size_t *@var{uid}) +@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_get_uidl (message_t @var{msg}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{pwriten}) +@deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg}) @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_save_attachment (message_t @var{msg}, const char *@var{filename}, void **@var{data}) @end deftypefun -@deftypefun int message_get_observable (message_t @var{msg}, observable_t *@var{observable}) +@deftypefun int message_encapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}) @end deftypefun -@deftypefun int message_create_attachment (const char *@var{content_type}, const char *@var{encoding}, const char *@var{filename}, message_t *@var{newmsg}) +@deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}); @end deftypefun -@deftypefun int message_save_attachment (message_t @var{msg}, const char *@var{filename}, void **@var{data}) +@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_encapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}) +@deftypefun int message_aget_attachment_name (message_t @var{msg}, char **@var{name}); @end deftypefun -@deftypefun int message_unencapsulate (message_t @var{msg}, message_t *@var{newmsg}, void **@var{data}); +@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 diff --git a/doc/texinfo/parse822.texi b/doc/texinfo/parse822.texi index ee3eb06..e83995a 100644 --- a/doc/texinfo/parse822.texi +++ b/doc/texinfo/parse822.texi @@ -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 diff --git a/doc/texinfo/stream.texi b/doc/texinfo/stream.texi index 026673c..2da86ac 100644 --- a/doc/texinfo/stream.texi +++ b/doc/texinfo/stream.texi @@ -33,80 +33,116 @@ 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 stream_open (stream_t @var{stream}) +@deftypefun int filter_prog_stream_create (stream_t *@var{stream}, char *@var{progname}, stream_t @var{input}) @end deftypefun -@deftypefun int stream_close (stream_t @var{stream}) +@deftypefun void stream_destroy (stream_t *@var{stream}, void *@var{owner}) @end deftypefun -@deftypefun int stream_is_seekable (stream_t @var{stream}) +@c +@c --------- +@c + +@deftypefun int stream_open (stream_t @var{stream}) @end deftypefun -@deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd}) +@deftypefun int stream_close (stream_t @var{stream}) @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_is_seekable (stream_t @var{stream}) @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_get_fd (stream_t @var{stream}, int *@var{fd}) @end deftypefun -@deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize}) +@deftypefun int stream_get_fd2 (stream_t @var{stream}, int *@var{fd1}, int *@var{fd2}) @end deftypefun -@deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size}) +@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_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten}) +@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_setbufsiz (stream_t @var{stream}, size_t @var{size}) +@deftypefun int stream_size (stream_t @var{stream}, off_t *@var{size}) @end deftypefun -@deftypefun int stream_flush (stream_t @var{stream}) +@deftypefun n int stream_truncate (stream_t @var{stream}, off_t @var{size}) @end deftypefun -These functions will typically only be useful to implementors of streams. +@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_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner}) +@deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size}) +@end deftypefun + +@deftypefun int stream_flush (stream_t @var{stream}) +@end deftypefun + +@c +@c These functions will typically only be useful to implementors of streams. +@c + +@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 diff --git a/doc/texinfo/url.texi b/doc/texinfo/url.texi index f495d5c..39abc24 100644 --- a/doc/texinfo/url.texi +++ b/doc/texinfo/url.texi @@ -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. @@ -35,16 +37,18 @@ For more complete information see @cite{RFC 2368}. @subheading IMAP The IMAP URL scheme contains an IMAP server, optional port number -and the authentication mechanism. The general form is +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. +@deftypefun int url_create (url_t *@var{url}, const char *@var{name}) +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