mailcap.texi
4.46 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@smallexample
@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}:
@smallexample
application/pgp; gpg < %s | metamail; needsterminal; \
test=test %@{encapsulation@}=entity ; copiousoutput
@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:
@smallexample
Mailcap-File = *Mailcap-Line
Mailcap-Line = Comment | Mailcap-Entry
Comment = NEWLINE | "#" * CHAR NEWLINE
NEWLINE = <newline as defined by OS convention>
@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.
@smallexample
Mailcap-Entry = typefield ";" view-command ";" *[ ";" 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
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] |
\--------------------/
@end group
@end smallexample
@subheading An example of parsing a mailcap file:
@smallexample
@include mailcap.inc
@end smallexample
@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