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 @@ ...@@ -19,7 +19,7 @@
19 19
20 info_TEXINFOS = mailutils.texi 20 info_TEXINFOS = mailutils.texi
21 21
22 INCFILES=addr.inc http.inc numaddr.inc sfrom.inc url-parse.inc 22 INCFILES=addr.inc http.inc numaddr.inc sfrom.inc url-parse.inc mailcap.inc
23 23
24 mailutils_TEXINFOS = \ 24 mailutils_TEXINFOS = \
25 address.texi \ 25 address.texi \
...@@ -40,6 +40,7 @@ mailutils_TEXINFOS = \ ...@@ -40,6 +40,7 @@ mailutils_TEXINFOS = \
40 libsieve.texi \ 40 libsieve.texi \
41 locker.texi \ 41 locker.texi \
42 mailbox.texi \ 42 mailbox.texi \
43 mailcap.texi \
43 mailer.texi \ 44 mailer.texi \
44 maildir.texi \ 45 maildir.texi \
45 mbox.texi \ 46 mbox.texi \
......
...@@ -17,7 +17,8 @@ ...@@ -17,7 +17,8 @@
17 * Address:: Address. 17 * Address:: Address.
18 * Locker:: Locker. 18 * Locker:: Locker.
19 * URL:: Uniform Resource Locators. 19 * URL:: Uniform Resource Locators.
20 * Parse822:: Parsing RFC 822 headers 20 * Parse822:: Parsing RFC 822 headers.
21 * Mailcap:: Parsing RFC 1524 file.
21 @end menu 22 @end menu
22 23
23 Wherever the mail is and whatever format it is stored in, it is operated 24 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 ...@@ -188,3 +189,8 @@ Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
188 @node Parse822 189 @node Parse822
189 @section Parse822 --- Functions for Parsing RFC 822 Headers 190 @section Parse822 --- Functions for Parsing RFC 822 Headers
190 @include parse822.texi 191 @include parse822.texi
192
193 @node Mailcap
194 @section Mailcap --- Functions for Parsing RFC 1524 Files
195 @include mailcap.texi
196
......
1 @comment GNU Mailutils -- a suite of utilities for electronic mail
2 @comment Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc.
3 @comment
4 @comment GNU Mailutils is free software; you can redistribute it and/or modify
5 @comment it under the terms of the GNU General Public License as published by
6 @comment the Free Software Foundation; either version 2, or (at your option)
7 @comment any later version.
8 @comment
9 @comment GNU Mailutils is distributed in the hope that it will be useful,
10 @comment but WITHOUT ANY WARRANTY; without even the implied warranty of
11 @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 @comment GNU General Public License for more details.
13 @comment
14 @comment You should have received a copy of the GNU General Public License
15 @comment along with GNU Mailutils; if not, write to the Free Software
16 @comment Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
18 #include <stdio.h>
19 #include <mailutils/mailcap.h>
20
21 int main(int argc, char **argv)
22 @{
23 stream_t stream = NULL;
24 int status = 0;
25
26 status = file_stream_create (&stream, "/etc/mailcap", MU_STREAM_READ);
27 if (status == 0)
28 @{
29 status = stream_open (stream);
30 if (status == 0)
31 @{
32 mu_mailcap_t mailcap = NULL;
33 status = mu_mailcap_create (&mailcap, stream);
34 if (status == 0)
35 @{
36 int i;
37 size_t count = 0;
38 char buffer[256];
39
40 mu_mailcap_entries_count (mailcap, &count);
41 for (i = 1; i <= count; i++)
42 @{
43 int j;
44 mu_mailcap_entry_t entry = NULL;
45 int fields_count = 0;
46
47 printf ("entry[%d]\n", i);
48
49 mu_mailcap_get_entry (mailcap, i, &entry);
50
51 /* typefield. */
52 mu_mailcap_entry_get_typefield (entry, buffer, sizeof (buffer), NULL);
53 printf ("\ttypefield: %s\n", buffer);
54
55 /* view-command. */
56 mu_mailcap_entry_get_viewcommand (entry, buffer, sizeof (buffer), NULL);
57 printf ("\tview-command: %s\n", buffer);
58
59 /* fields. */
60 mu_mailcap_entry_fields_count (entry, &fields_count);
61 for (j = 1; j <= fields_count; j++)
62 @{
63 mu_mailcap_entry_get_field (entry, j, buffer, sizeof (buffer), NULL);
64 printf ("\tfields[%d]: %s\n", j, buffer);
65 @}
66 printf ("\n");
67 @}
68 mu_mailcap_destroy (&mailcap);
69 @}
70 @}
71 @}
72 return 0;
73 @}
1 @c This is part of the GNU Mailutils manual.
2 @c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
3 @c See file mailutils.texi for copying conditions.
4 @comment *******************************************************************
5 @example
6 @code{/* Prefix @emph{mu_mailcap_} is reserved */}
7 @code{#include <mailutils/mailcap.h>}
8
9 @end example
10
11 The standard rfc1524(A User Agent Configuration Mechanism) suggests a file format
12 to be used to inform a mail user agent about facilities for handling mail in various
13 format. The configuration file is known also as mailcap and it is tipically found
14 in UNIX platforms, a example of @file{/etc/mailcap}:
15 @example
16 application/pgp; gpg < %s | metamail; needsterminal; \
17 test=test %@{encapsulation@}=entity ; copiousoutput
18 @end example
19
20 A mailcap file consits of a set of mailcap entries per line, lines beginning with @emph{#} are
21 considered comments and ignored. Long mailcap entry may be continued on multiple lines if
22 each line ends with a backslash character @emph{\}, the multiline will be considered a single
23 mailcap entry. The overall format in BNF:
24 @example
25 Mailcap-File = *Mailcap-Line
26 Mailcap-Line = Comment | Mailcap-Entry
27 Comment = NEWLINE | "#" * CHAR NEWLINE
28 NEWLINE = <newline as defined by OS convention>
29 @end example
30
31 Each mailcap entry consists of a number of fields, separated by semi-colons.
32 The first two filds are required and must occur in the secified order, the remaining
33 fields are optional.
34 @example
35 Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ]
36 @end example
37
38 @deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t
39 The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects are used to hold information
40 and it is an opaque data structure to the user. Functions are provided to retrieve information
41 from the data structure.
42 @end deftp
43 @example
44 @group
45 mu_mailcap_t mu_mailcap_entry_t
46 -/etc/mailcap- +----->/------------------------\ +-->/--------------------\
47 ( alain ) | mu_mailcap_entry[0]*--|----+ | typefield |
48 | mu_mailcap_entry[1] | | view-command |
49 | ..... | | field[0] |
50 | mu_mailcap_entry[n] | | ..... |
51 \------------------------/ | field[n] |
52 \--------------------/
53 @end group
54 @end example
55
56 An example of parsing a mailcap file.
57 @example
58 @include mailcap.inc
59 @end example
60
61 @deftypefun int mu_mailcap_create (mu_mailcap_t *@var{mailcap}, stream_t @var{stream})
62 The function allocates, parses the buffer from the @var{stream} and initializes @var{mailcap}.
63 The return value is @code{0} on success and a code number on error conditions:
64 @table @code
65 @item MU_ERROR_INVALID_PARAMETER
66 @var{mailcap} is null or @var{stream} is invalid.
67 @end table
68 @end deftypefun
69
70 @deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap})
71 Release any resources from the mailcap object.
72
73 @end deftypefun
74
75 @deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count})
76 The function returns the number of entries found in the mailcap.
77 The return value is @code{0} on success and a code number on error conditions:
78 @table @code
79
80 @item EINVAL
81 @var{mailcap} or @var{count} is null.
82 @end table
83 @end deftypefun
84
85 @deftypefun int mu_mailcap_get_entry (mu_mailcap_t @var{mailcap}, size_t no, mu_mailcap_entry_t*@var{entry})
86 Returns in @var{entry} the mailcap entry of @var{no}
87 @end deftypefun
88
89 @deftypefun int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
90 @end deftypefun
91
92 @deftypefun int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t @var{entry}, char * @var{buffer}, size_t @var{buflen}, size_t *@var{pn})
93 @end deftypefun
94
95 @deftypefun int mu_mailcap_entry_fields_count (mu_mailcap_entry_t @var{entry}, size_t *@var{count})
96 The function returns the number of fields found in the entry.
97 The return value is @code{0} on success and a code number on error conditions:
98 @table @code
99
100 @item EINVAL
101 @var{entry} or @var{count} is null.
102 @end table
103 @end deftypefun
104
105 @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})
106 @end deftypefun
107