diff options
author | Alain Magloire <alainm@gnu.org> | 2003-02-23 23:32:02 +0000 |
---|---|---|
committer | Alain Magloire <alainm@gnu.org> | 2003-02-23 23:32:02 +0000 |
commit | 767025a1a8d1d207903eec1951829eb20a06488d (patch) | |
tree | f16507e0fd764616b70eeaee6c3e73f4ced5cc74 | |
parent | ab4c775e5208a5db76de23524d2b2d8b4e59eb92 (diff) | |
download | mailutils-767025a1a8d1d207903eec1951829eb20a06488d.tar.gz mailutils-767025a1a8d1d207903eec1951829eb20a06488d.tar.bz2 |
Makefile.am framework.texi
Include mailcap.texi
mailcap.inc mailcap.texi
Document the mailcap functions.
-rw-r--r-- | doc/texinfo/Makefile.am | 3 | ||||
-rw-r--r-- | doc/texinfo/framework.texi | 8 | ||||
-rw-r--r-- | doc/texinfo/mailcap.inc | 73 | ||||
-rw-r--r-- | doc/texinfo/mailcap.texi | 107 |
4 files changed, 189 insertions, 2 deletions
diff --git a/doc/texinfo/Makefile.am b/doc/texinfo/Makefile.am index 35fe038d1..36ec00c85 100644 --- a/doc/texinfo/Makefile.am +++ b/doc/texinfo/Makefile.am @@ -19,7 +19,7 @@ info_TEXINFOS = mailutils.texi -INCFILES=addr.inc http.inc numaddr.inc sfrom.inc url-parse.inc +INCFILES=addr.inc http.inc numaddr.inc sfrom.inc url-parse.inc mailcap.inc mailutils_TEXINFOS = \ address.texi \ @@ -40,6 +40,7 @@ mailutils_TEXINFOS = \ libsieve.texi \ locker.texi \ mailbox.texi \ + mailcap.texi \ mailer.texi \ maildir.texi \ mbox.texi \ diff --git a/doc/texinfo/framework.texi b/doc/texinfo/framework.texi index bc772c90a..73b2e7bd1 100644 --- a/doc/texinfo/framework.texi +++ b/doc/texinfo/framework.texi @@ -17,7 +17,8 @@ * Address:: Address. * Locker:: Locker. * URL:: Uniform Resource Locators. -* Parse822:: Parsing RFC 822 headers +* Parse822:: Parsing RFC 822 headers. +* Mailcap:: Parsing RFC 1524 file. @end menu Wherever the mail is and whatever format it is stored in, it is operated @@ -188,3 +189,8 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha @node Parse822 @section Parse822 --- Functions for Parsing RFC 822 Headers @include parse822.texi + +@node Mailcap +@section Mailcap --- Functions for Parsing RFC 1524 Files +@include mailcap.texi + diff --git a/doc/texinfo/mailcap.inc b/doc/texinfo/mailcap.inc new file mode 100644 index 000000000..117d14e30 --- /dev/null +++ b/doc/texinfo/mailcap.inc @@ -0,0 +1,73 @@ +@comment GNU Mailutils -- a suite of utilities for electronic mail +@comment Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc. +@comment +@comment GNU Mailutils is free software; you can redistribute it and/or modify +@comment it under the terms of the GNU General Public License as published by +@comment the Free Software Foundation; either version 2, or (at your option) +@comment any later version. +@comment +@comment GNU Mailutils is distributed in the hope that it will be useful, +@comment but WITHOUT ANY WARRANTY; without even the implied warranty of +@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +@comment GNU General Public License for more details. +@comment +@comment You should have received a copy of the GNU General Public License +@comment along with GNU Mailutils; if not, write to the Free Software +@comment Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +#include <stdio.h> +#include <mailutils/mailcap.h> + +int main(int argc, char **argv) +@{ + stream_t stream = NULL; + int status = 0; + + status = file_stream_create (&stream, "/etc/mailcap", MU_STREAM_READ); + if (status == 0) + @{ + status = stream_open (stream); + if (status == 0) + @{ + mu_mailcap_t mailcap = NULL; + status = mu_mailcap_create (&mailcap, stream); + if (status == 0) + @{ + int i; + size_t count = 0; + char buffer[256]; + + mu_mailcap_entries_count (mailcap, &count); + for (i = 1; i <= count; i++) + @{ + int j; + mu_mailcap_entry_t entry = NULL; + int fields_count = 0; + + printf ("entry[%d]\n", i); + + mu_mailcap_get_entry (mailcap, i, &entry); + + /* typefield. */ + mu_mailcap_entry_get_typefield (entry, buffer, sizeof (buffer), NULL); + printf ("\ttypefield: %s\n", buffer); + + /* view-command. */ + mu_mailcap_entry_get_viewcommand (entry, buffer, sizeof (buffer), NULL); + printf ("\tview-command: %s\n", buffer); + + /* fields. */ + mu_mailcap_entry_fields_count (entry, &fields_count); + for (j = 1; j <= fields_count; j++) + @{ + mu_mailcap_entry_get_field (entry, j, buffer, sizeof (buffer), NULL); + printf ("\tfields[%d]: %s\n", j, buffer); + @} + printf ("\n"); + @} + mu_mailcap_destroy (&mailcap); + @} + @} + @} + return 0; +@} diff --git a/doc/texinfo/mailcap.texi b/doc/texinfo/mailcap.texi new file mode 100644 index 000000000..467428481 --- /dev/null +++ b/doc/texinfo/mailcap.texi @@ -0,0 +1,107 @@ +@c This is part of the GNU Mailutils manual. +@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc. +@c See file mailutils.texi for copying conditions. +@comment ******************************************************************* +@example +@code{/* Prefix @emph{mu_mailcap_} is reserved */} +@code{#include <mailutils/mailcap.h>} + +@end example + + The standard rfc1524(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}: +@example +application/pgp; gpg < %s | metamail; needsterminal; \ + test=test %@{encapsulation@}=entity ; copiousoutput +@end example + +A mailcap file consits of a set of mailcap entries per line, lines beginning with @emph{#} are +considered comments and ignored. Long mailcap entry may be continued on multiple lines if +each line ends with a backslash character @emph{\}, the multiline will be considered a single +mailcap entry. The overall format in BNF: +@example +Mailcap-File = *Mailcap-Line +Mailcap-Line = Comment | Mailcap-Entry +Comment = NEWLINE | "#" * CHAR NEWLINE +NEWLINE = <newline as defined by OS convention> +@end example + +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. +@example +Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ] +@end example + +@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 +from the data structure. +@end deftp +@example +@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] | + \--------------------/ +@end group +@end example + +An example of parsing a mailcap file. +@example +@include mailcap.inc +@end example + +@deftypefun int mu_mailcap_create (mu_mailcap_t *@var{mailcap}, stream_t @var{stream}) +The function allocates, parses the buffer from the @var{stream} and initializes @var{mailcap}. +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. +@end table +@end deftypefun + +@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}) +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. +@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}) +@end deftypefun + +@deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count}) +The function returns the number of fields found in the entry. +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. +@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}) +@end deftypefun + |