summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlain Magloire <alainm@gnu.org>2003-02-23 23:32:02 +0000
committerAlain Magloire <alainm@gnu.org>2003-02-23 23:32:02 +0000
commit767025a1a8d1d207903eec1951829eb20a06488d (patch)
treef16507e0fd764616b70eeaee6c3e73f4ced5cc74
parentab4c775e5208a5db76de23524d2b2d8b4e59eb92 (diff)
downloadmailutils-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.am3
-rw-r--r--doc/texinfo/framework.texi8
-rw-r--r--doc/texinfo/mailcap.inc73
-rw-r--r--doc/texinfo/mailcap.texi107
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
+

Return to:

Send suggestions and report system problems to the System administrator.