Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 767025a1 767025a1a8d1d207903eec1951829eb20a06488d by Alain Magloire
Options

Makefile.am framework.texi 

Include mailcap.texi
	mailcap.inc mailcap.texi
Document the mailcap functions.
1 parent ab4c775e
Inline Side-by-side
Showing 4 changed files with 189 additions and 2 deletions
......@@ -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 \
......
......@@ -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
......
@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;
@}
@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