4.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 <stdio.h>
#include <mailutils/mailcap.h>
#include <mailutils/stream.h>
#include <mailutils/error.h>

int
main (int argc, char **argv)
{
  stream_t stream = NULL;
  int status = 0;
  char *file = argc == 1 ? "/etc/mailcap" : argv[1];
  mu_mailcap_t mailcap = NULL;

  status = 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 = 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, 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.