Previous: Parse822, Up: libmailbox

3.1.16 Mailcap

     /* Prefix mu_mailcap_ is reserved. */
     #include <mailutils/mailcap.h>

The standard 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 /etc/mailcap: 

     application/pgp; gpg < %s | metamail; needsterminal; \
            test=test %{encapsulation}=entity ; copiousoutput

A mailcap file consits of a set of mailcap entries per line, lines beginning with ‘#’ are considered comments and ignored. Long mailcap entry may be continued on multiple lines if each line ends with a backslash character ‘\’, the multiline will be considered a single mailcap entry. The overall format in BNF: 

     Mailcap-File = *mailcap-line
     Mailcap-Line = comment | mailcap-entry
     Comment = newline | "#" * char newline
     Newline = <newline as defined by OS convention>

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. 

     Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ]
— Data Type: mu_mailcap_t, mu_mailcap_entry_t

The mu_mailcap_t and 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. 

                             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]        |
                                                          \------------------/

An Example of Parsing a Mailcap File:

     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     #include <stdlib.h>
     #include <stdio.h>
     #include <mailutils/mailcap.h>
     #include <mailutils/stream.h>
     #include <mailutils/error.h>
     
     int
     main (int argc, char **argv)
     {
       mu_stream_t stream = NULL;
       int status = 0;
       char *file = argc == 1 ? "/etc/mailcap" : argv[1];
       mu_mailcap_t mailcap = NULL;
     
       status = mu_file_stream_create (&stream, file, MU_STREAM_READ);
       if (status)
         {
           mu_error ("cannot create file stream %s: %s",
     		file, mu_strerror (status));
           exit (1);
         }
     
       status = mu_stream_open (stream);
       if (status)
         {
           mu_error ("cannot open file stream %s: %s",
     		file, mu_strerror (status));
           exit (1);
         }
     
       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++)
     	{
     	  size_t j;
     	  mu_mailcap_entry_t entry = NULL;
     	  size_t 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++)
     	    {
     	      int status = mu_mailcap_entry_get_field (entry, j, buffer,
     						       sizeof (buffer), NULL);
     	      if (status)
     		{
     		  mu_error ("cannot retrieve field %lu: %s",
     			    (unsigned long) j,
     			    mu_strerror (status));
     		  break;
     		}
     	      printf ("\tfields[%d]: %s\n", j, buffer);
     	    }
     	  printf ("\n");
     	}
           mu_mailcap_destroy (&mailcap);
         }
     
       return 0;
     }
— Function: int mu_mailcap_create (mu_mailcap_t *mailcap, mu_stream_t stream)

The function allocates, parses the buffer from the stream and initializes mailcap. The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mailcap is NULL or stream is invalid.

— Function: void mu_mailcap_destroy (mu_mailcap_t *mailcap)

Release any resources from the mailcap object.

— Function: int mu_mailcap_entries_count (mu_mailcap_t mailcap, size_t *count)

The function returns the number of entries found in the mailcap. The return value is 0 on success and a code number on error conditions:

EINVAL
mailcap or count is NULL.

— Function: int mu_mailcap_get_entry (mu_mailcap_t mailcap, size_t no, mu_mailcap_entry_t *entry)

Returns in entry the mailcap entry of no.

— Function: int mu_mailcap_entry_fields_count (mu_mailcap_entry_t entry, size_t *count)

The function returns the number of fields found in the entry. The return value is 0 on success and a code number on error conditions:

EINVAL
entry or count is NULL.

— Function: int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)
— Function: int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)
— Function: int mu_mailcap_entry_get_field (mu_mailcap_entry_t entry, size_t no, char *buffer, size_t buflen, size_t *n)
— Function: int mu_mailcap_entry_get_value (mu_mailcap_entry_t entry, const char *key, char *buffer, size_t buflen, size_t *n)
— Function: int mu_mailcap_entry_get_compose (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "compose" field.

— Function: int mu_mailcap_entry_get_composetyped (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "composetyped" field.

— Function: int mu_mailcap_entry_get_edit (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "edit" field.

— Function: int mu_mailcap_entry_get_textualnewlines (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "textualnewlines" field.

— Function: int mu_mailcap_entry_get_test (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "test" field.

— Function: int mu_mailcap_entry_get_x11bitmap (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "x11-bitmap" field.

— Function: int mu_mailcap_entry_get_description (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "description" field.

— Function: int mu_mailcap_entry_get_nametemplate (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "nametemplate" field.

— Function: int mu_mailcap_entry_get_notes (mu_mailcap_entry_t entry, char *buffer, size_t buflen, size_t *n)

Helper function saving in buffer, the argument of "notes" field.

— Function: int mu_mailcap_entry_needsterminal (mu_mailcap_entry_t entry, int *on)

Helper function. Returns *on != 0 if the flag needsterminal is in the record.

— Function: int mu_mailcap_entry_copiousoutput (mu_mailcap_entry_t entry, int *on)

Helper function. Returns *on != 0 if the flag copiousoutput is in the record.