Go to the first, previous, next, last section, table of contents.


Framework

Wherever the mail is and whatever format it is stored in, the same operations to manipulate emails are common. To unified the C API, GNU mailutils offers a heteroclite set of objects that work in aggregation to do operations on emails. Each object do a specific task and delegates non related tasks to others. The object comes alive by specifying a URL parameter when created, it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..).

                          folder_t                  url_t
  -/var/mail-    +- .. ->+-----------------+   +-->+------------+
 (  alain *-)-+  |       |   url_t       *-|---+   |   port     |
  ----------- |  |       |-----------------|       |   hostname |
 (  jakob *-)-+--+       |   auth_t      *-|---+   |   file     |
  ----------- |          |-----------------|   |   |   ...      |
 (  jeff  *-)-+          |   stream_t      |   |   +------------+
  ----------- |          |-----------------|   |
 (  shaleh*-)-+          |   .....         |   |    auth_t
  ----------             |-----------------|   +-->+------------+
                     +---|-* mailbox_t[]   |       |   ticket_t |
  mailbox_t          |   +-----------------+       +------------+
 +----------------+<-+
 |   locker_t  *--|-------------+
 |----------------|             |
 |   url_t        |             |          locker_t
 |----------------|             +-------->+---------+
 |   stream_t     |                       | lock    |
 |----------------|                       | unlock  |
 |  message_t[] *-|-------+               +---------+
 +----------------+       |                     envelope_t
                          |          +-------->+-----------+
  message_t               |          |         | date      |
 +----------------+<------+          |         | from      |
 |   envelope_t *-|------------------+         | to        |
 |----------------|              header_t      +-----------+
 |   header_t   *-|------------>+--------------+
 |----------------|             |   stream_t   |
 |   body_t     *-|----+        +--------------+
 +----------------+    |    body_t
                       +-->+--------------+
                           |   stream_t   |
                           +--------------+

For example writing a simple from command that will list the From and Subject headers of every mail in a mailbox.

/* sfrom, Simple From */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <mailutils/registrar.h>
#include <mailutils/list.h>
#include <mailutils/mailbox.h>

#define BUFFER_SIZE 64
int
main (int argc, const char **argv)
{
   char from[BUFFER_SIZE];
   char subject[BUFFER_SIZE];
   char *mail;
   mailbox_t mbox;
   int status
   size_t msgno, total = 0;

   mail = (argc == 2) ? argv[1] : getenv ("MAIL");

   /* Register the type of mailbox. IMAP4, POP3 and local format  */
   {
       list_t registrar;
       registrar_get_list (&registrar);
       list_append (registrar, imap_record);
       list_append (registrar, path_record);
       list_append (registrar, pop_record);
   }

   status = mailbox_create (&mbox, mail);
   if (status != 0)
     {
        fprintf (stderr, "mailbox_create: %s\n", strerror (status));
        exit (EXIT_FAILURE);
     }

   status = mailbox_open (mbox, MU_STREAM_READ);
   if (status != 0)
     {
        fprintf (stderr, "mailbox_open: %s\n", strerror (status));
        exit (EXIT_FAILURE);
     }

   mailbox_messages_count (mbox, &total);

   for (msgno = 1; msgno <= total; msgno++)
      {
         message_t msg;
         header_t hdr;

         if ((status = mailbox_get_message (mbox, msgno, &msg)) != 0
             || (status = message_get_header (msg, &hdr)) != 0)
           {
               fprintf (stderr, "Error message:%s\n",
                        strerror (status));
               exit (EXIT_FAILURE);
           }

         status = header_get_value (hdr, MU_HEADER_FROM, from,
                                    sizeof (from), NULL);
         if (status != 0)
            strcpy (from, "(NO FROM)");

         status = header_get_value (hdr, MU_HEADER_SUBJECT, subject,
                                    sizeof (subject), NULL);
         if (status != 0)
            strcpy (subject, "(NO SUBJECT)");

         printf ("%s\t%s\n", from, subject);
      }

    mailbox_close (mbox);
    mailbox_destroy (&mbox);
    return 0;
}
% MAIL=pop://[email protected] ./sfrom
Passwd: xxxx
Jim Meyering <[email protected]>      fetish(shellutils) beta
[email protected],{c}ois Pinard <[email protected]> recode new alpha
...

Folder

/* Prefix folder_ is reserve */
#include <mailutils/folder.h>

                             folder_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain *-)-+  |          |  url_t        *-|----+   |  port     |
  ----------- |  |          |-----------------+        |  hostname |
 (  jakob *-)-+--+          |  observer_t   *-|        |  file     |
  ----------- |             |-----------------+        |  ...      |
 (  jeff  *-)-+             |  stream_t       |        \-----------/
  ----------- |             |-----------------|
 (  sean  *-)-+             |  auth_t         |
  ----------                |-----------------|
                            |  mailbox_t(1)   |
                            |-----------------|
                            |  mailbox_t(2)   |
                            |  ......         |
                            |  mailbox_t(n)   |
                            \-----------------/

Function: int folder_create (folder_t *, const char *url)

Function: void folder_destroy (folder_t *)

Function: int folder_open (folder_t, int flag)

Function: int folder_close (folder_t)

Function: int folder_delete (folder_t, const char *mailbox)

Function: int folder_rename (folder_t, const char *, const char *mailbox)

Function: int folder_subscribe (folder_t, const char *mailbox)

Function: int folder_unsubscribe (folder_t, const char *mailbox)

Function: int folder_list (folder_t, const char *ref, const char *wcard, iterator_t *)

Function: int folder_lsub (folder_t, const char *ref, const char *wcar, iterator_t *)

Function: int folder_get_stream (folder_t, stream_t *)

Function: int folder_set_stream (folder_t, stream_t)

Function: int folder_get_observable (folder_t, observable_t *)

Function: int folder_get_debug (folder_t, debug_t *)

Function: int folder_set_debug (folder_t, debug_t)

Function: int folder_get_authority (folder_t, authority_t *)

Function: int folder_set_authority (folder_t, authority_t)

Function: int folder_get_url (folder_t, url_t *)

Function: int folder_set_url (folder_t, url_t)

Mailbox

/* Prefix mailbox_ is reserved */
#include <mailutils/mailbox.h>

Data Type: mailbox_t
The mailbox_t object is used to hold information and it is an opaque data structure to the user. Functions are provided to retrieve information from the data structure.
                             mailbox_t                  url_t
  -/var/mail-    +---//---->/-----------------\    +-->/-----------\
 (  alain   )    |          |  url_t        *-|----+   |  port     |
  -----------    |          |-----------------+        |  hostname |
 (  jakob *-)----+          |  observer_t   *-|        |  file     |
  -----------               |-----------------+        |  ...      |
 (  jeff    )               |  stream_t       |        \-----------/
  -----------               |-----------------|
 (  sean    )               |  locker_t       |
  ----------                |-----------------|
                            |  message_t(1)   |
                            |-----------------|
                            |  message_t(2)   |
                            |  ......         |
                            |  message_t(n)   |
                            \-----------------/

Function: int mailbox_append_message (mailbox_t mbox, message_t message)
The message is appended to the mailbox mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null or message is invalid.

Function: int mailbox_close (mailbox_t mbox)
The stream attach to mbox is closed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_create (mailbox_t *pmbox, const char *name)
The function mailbox_create allocates and initializes pmbox. The concrete mailbox type instantiate is based on the scheme of the url name.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
The url name supplied is invalid or not supported. pmbox is NULL.
ENOMEM
Not enough memory to allocate resources.

Function: int mailbox_create_default (mailbox_t *pmbox, const char *name)
Create a mailbox with mailbox_create () based on the environment variable $MAIL or the string formed by _PATH_MAILDIR/user" or $LOGNAME if user is null,

Function: void mailbox_destroy (mailbox_t *pmbox)
Destroys and releases resources held by pmbox.

Function: int mailbox_expunge (mailbox_t mbox)
All messages marked for deletion are removed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_folder (mailbox_t mbox, folder_t *folder)
Get the folder.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_debug (mailbox_t mbox, debug_t *debug)
Get a debug object. The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM

Function: int mailbox_get_locker (mailbox_t mbox, locker_t *plocker)
Return the locker object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_message (mailbox_t mbox, size_t msgno, message_t *pmessage)
Retrieve message number msgno, pmessage is allocated and initialized.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null or msgno is invalid.
ENOMEM
Not enough memory.

Function: int mailbox_get_observable (mailbox_t mbox mbox, observable_t*observable)
Get the observable object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM
Not enough memory.

Function: int mailbox_get_property (mailbox_t mbox, property_t *property)
Get the property object. The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM

Function: int mailbox_get_size (mailbox_t mbox, off_t *psize)
Gives the mbox size.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_stream (mailbox_t mbox, stream_t *pstream)
The mailbox stream is put in pstream.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is invalid or pstream is NULL.

Function: int mailbox_get_ticket (mailbox_t mbox, ticket_t ticket)
The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_get_url (mailbox_t mbox, url_t *purl)
Gives the constructed url.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_is_modified (mailbox_t mbox)
Check if the mailbox been modified by an external source.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_message_unseen (mailbox_t mbox, size_t *pnumber);
Give the number of first unseen message in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_messages_count (mailbox_t mbox, size_t *pnumber);
Give the number of messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_messages_recent (mailbox_t mbox, size_t *pnumber);
Give the number of recent messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_open (mailbox_t mbox, int flag)
A connection is open, if no stream was provided, a stream is created based on the mbox type. The flag can be OR'ed. See stream_create for flag's description.

The return value is 0 on success and a code number on error conditions:

EAGAIN
EINPROGRESS
Operation in progress.
EBUSY
Resource busy.
MU_ERROR_INVALID_PARAMETER
mbox is null or flag is invalid.
ENOMEM
Not enough memory.

Function: int mailbox_scan (mailbox_t mbox, size_t msgno, size_t *pcount);
Scan the mailbox for new messages starting at message msgno.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.
ENOMEM
Not enough memory.

Function: int mailbox_set_locker (mailbox_t mbox, locker_t locker)
Set the type of locking done by the mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_set_stream (mailbox_t mbox, stream_t stream)
Set the stream connection to use for the mailbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox or stream is NULL.

Function: int mailbox_set_ticket (mailbox_t mbox, ticket_t ticket)
The ticket will be set on the auth_t object on creation.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_uidnext (mailbox_t mbox, size_t *pnumber);
Give the next predicted uid for mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Function: int mailbox_uidvalidity (mailbox_t mbox, size_t *pnumber);
Give the uid validity of mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is null.

Mailer

/* Prefix mailer_ is reserved */
#include <mailutils/mailer.h>

The API is still shaky and undefined.

Function: int mailer_create (mailer_t *, const char *)

Function: void mailer_destroy (mailer_t *)

Function: int mailer_open (mailer_t, int flags)

Function: int mailer_close (mailer_t)

Function: int mailer_send_message (mailer_t, message_t)

Function: int mailer_get_property (mailer_t, property_t *)

Function: int mailer_get_stream (mailer_t, stream_t *)

Function: int mailer_set_stream (mailer_t, stream_t)

Function: int mailer_get_debug (mailer_t, debug_t *)

Function: int mailer_set_debug (mailer_t, debug_t)

Function: int mailer_get_observable (mailer_t, observable_t *)

Function: int mailer_get_url (mailer_t, url_t *)

Message

#include <mailutils/message.h>
/* Prefix message_ is reserve */

The message_t object is a convenient way to manipulate messages. It encapsulates the envelope_t, the header_t and the body_t.

    mailbox_t
    __________                   message_t
   (message[1])        +------>+-----------------------+
    ----------         |       |  envelope_t           |
   (message[2])        |       |-----------------------|
    ----------         |       |  header_t             |
   (message[3])--------+       |-----------------------|
    ----------                 |  body_t               |
   (message[n])                |-----------------------|
    ----------                 |  attribute_t          |
                               |-----------------------|
                               |  stream_t             |
                               +-----------------------+

Function: void message_create (message_t *msg, void *owner)

Function: void message_destroy (message_t *msg, void *owner)
The resources allocate for msg are freed.

Function: int message_get_header (message_t msg, header_t *pheader)
Retrieve msg header.

Function: int message_set_header (message_t msg, header_t header, void *owner)

Function: int message_get_body (message_t msg, body_t *pbody)

Function: int message_set_body (message_t msg, body_t body, void *owner)

Function: int message_is_multipart (message_t msg)
Return non-zero value if message is multi-part.

Function: int message_get_num_parts (message_t msg, size_t *nparts)

Function: int message_get_part (message_t msg, size_t part, message_t *msg)

Function: int message_get_stream (message_t msg, stream_t *pstream)

Function: int message_set_stream (message_t msg, stream_t stream,void *owner )

Function: int message_get_attribute (message_t msg, attribute_t *pattribute)

Function: int message_set_attribute (message_t msg, attribute_t attribute, void *owner)

Function: int message_get_envelope (message_t msg, envelope_t *penvelope)

Function: int message_set_envelope (message_t msg, envelope_t envelope, void *owner)

Function: int message_get_uid (message_t msg, size_t *uid)

Function: int message_get_uidl (message_t msg, char *buffer, size_t buflen, size_t *pwriten)

Function: int message_set_uidl (message_t msg, int (*_get_uidl)(message_t, char *, size_t, size_t *), void *owner)

Function: int message_get_observable (message_t msg, observable_t *observable)

Function: int message_create_attachment (const char *content_type, const char *encoding, const char *filename, message_t *newmsg)

Function: int message_save_attachment (message_t msg, const char *filename, void **data)

Function: int message_encapsulate (message_t msg, message_t *newmsg, void **data)

Function: int message_unencapsulate (message_t msg, message_t *newmsg, void **data);

Envelope

/* Prefix envelope_ is reserved */
#include <mailutils/envelope.h>

Function: int envelope_date (envelope_t, char *, size_t, size_t *);

Get the date that the message was delivered to the mailbox, in something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999.

Function: int envelope_sender (envelope_t, char *, size_t, size_t *);

Get the address that this message was reportedly received from. This would be the "mail from" argument if the message was delivered or received via SMTP, for example.

Function: int envelope_get_message (envelope_t, message_t *);

Function: int envelope_create (envelope_t *, void *);
Primarily for internal use.

Function: void envelope_destroy (envelope_t *, void *);
Primarily for internal use.

Function: int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *);

Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the sender to be set by the creator of an envelope_t.

Function: int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *);

Primarily for internal use. The implementation of envelope_t depends on the mailbox type, this allows the function which actually gets the date to be set by the creator of an envelope_t.

Headers

/* Prefix header_ is reserved */
#include <mailutils/header.h>

So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII characters will be encoded.

Function: int header_create (header_t *hdr, const char *blurb, size_t len, void *owner)
Initialize a hdr to a supported type. If blurb is not NULL, it is parsed.

Function: void header_destroy (header_t *hdr, void *owner)
The resources allocated for hdr are freed.

Function: int header_set_value (header_t hdr, const char *fn, const char *fv, size_t n, int replace)
Set the field-name fn to field-value fv of size n in hdr. If replace is non-zero the initial value is replaced, if zero it is appended.

Some basic macros are already provided for rfc822.

MU_HDR_RETURN_PATH
Return-Path
MU_HDR_RECEIVED
Received
MU_HDR_DATE
Date
MU_HDR_FROM
From
MU_HDR_RESENT_FROM
Resent-From
MU_HDR_SUBJECT
Subject
MU_HDR_SENDER
Sender
MU_HDR_RESENT_SENDER
Resent-SENDER
MU_HDR_TO
To
MU_HDR_RESENT_TO
Resent-To
MU_HDR_CC
Cc
MU_HDR_RESENT_CC
Resent-Cc
MU_HDR_BCC
Bcc
MU_HDR_RESENT_BCC
Resent-Bcc
MU_HDR_REPLY_TO
Reply-To
MU_HDR_RESENT_REPLY_TO
Resent-Reply-To
MU_HDR_MESSAGE_ID
Message-ID
MU_HDR_RESENT_MESSAGE_ID
Resent-Message-ID
MU_HDR_IN_REPLY_TO
In-Reply-To
MU_HDR_ENCRYPTED
Encrypted
MU_HDR_PRECEDENCE
Precedence
MU_HDR_STATUS
Status
MU_HDR_CONTENT_LENGTH
Content-Length
MU_HDR_CONTENT_TYPE
Content-Type
MU_HDR_MIME_VERSION
MIME-Version

Function: int header_get_value (header_t hdr, const char *fn, char *fv, size_t len, size_t *n)
Value of field-name fn is returned in buffer fv of size len. The number of bytes written is put in n.

Function: int header_aget_value (header_t hdr, const char *fn, char **fv)
The value is allocated.

Function: int header_get_stream (header_t hdr, stream_t *pstream)

Function: int header_set_size (header_t hdr, size_t *size)

Function: int header_set_lines (header_t hdr, size_t *lpines)

Body

/* Prefix body_ is reserved */
#include <mailutils/body.h>

Function: int body_create (body_t *body, void *owner)
Initialize an object bdy.

Function: void body_destroy (body_t *pbody)
The resources allocate are release.

Function: int body_get_stream (body_t body, stream_t *pstream)

Function: int body_set_stream (body_t body, stream_t stream, void *owner)

Function: int body_get_filename __P ((body_t body, char *buffer, size_tbuflen, size_t *pwriten)

Function: int body_set_filename (body_t body, const char*buffer)

Function: int body_size (body_t body, size_t*psize)

Function: int body_lines (body_t body, size_t *plines)

Attribute

/* Prefix attribute_ is reserved */
#include <mailutils/attribute.h>

Function: int attribute_create (attribute_t *pattribute)

Function: void attribute_destroy (attribute_t *pattribute)

Function: int attribute_is_seen (attribute_t attribute)

Function: int attribute_is_answered (attribute_t attribute)

Function: int attribute_is_flagged (attribute_t attribute)

Function: int attribute_is_deleted (attribute_t attribute)

Function: int attribute_is_draft (attribute_t attribute)

Function: int attribute_is_recent (attribute_t attribute)

Function: int attribute_is_read (attribute_t attribute)

Function: int attribute_set_seen (attribute_t attribute)

Function: int attribute_set_answered (attribute_t attribute)

Function: int attribute_set_flagged (attribute_t attribute)

Function: int attribute_set_deleted (attribute_t attribute)

Function: int attribute_set_draft (attribute_t attribute)

Function: int attribute_set_recent (attribute_t attribute)

Function: int attribute_set_read (attribute_t attribute)

Function: int attribute_unset_seen (attribute_t attribute)

Function: int attribute_unset_answered (attribute_t attribute)

Function: int attribute_unset_flagged (attribute_t attribute)

Function: int attribute_unset_deleted (attribute_t attribute)

Function: int attribute_unset_draft (attribute_t attribute)

Function: int attribute_unset_recent (attribute_t attribute)

Function: int attribute_unset_read (attribute_t attribute)

Function: int attribute_is_equal (attribute_t att1, attribute_t att2)

Function: int attribute_copy (attribute_t dst, attribute_t src)

Function: int string_to_attribute (const char *buf, attribute_t *pattr)

Function: int attribute_to_string (attribute_t attr, char *buf, size_t len, size_t *pwriten)

Stream

#include <mailutils/stream.h>

Function: int stream_create (stream_t *pstream, int flags, void *owner)
MU_STREAM_READ
The stream is open read only.
MU_STREAM_WRITE
The stream is open write only.
MU_STREAM_RDWR
The stream is open read and write.
MU_STREAM_APPEND
The stream is open in append mode for writing.
MU_STREAM_CREAT
The stream is created.
MU_STREAM_NONBLOCK
The stream is set non blocking.
MU_STREAM_NO_CHECK
Stream is destroyed without checking for the owner.

Function: void stream_destroy (stream_t *pstream, void *owner)

Function: int stream_open (stream_t stream, const char *name, intport, int flag)

Function: int stream_close (stream_t stream)

Function: int stream_get_fd (stream_t stream, int *pfd)

Function: int stream_read (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_readline (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_size (stream_t stream, off_t *psize)

Function: int stream_truncate (stream_t stream, off_t size)

Function: int stream_write (stream_t stream, const char *buffer, size_t buflen, off_t offset, size_t *pwriten)

Function: int stream_flush (stream_t stream)

Function: int stream_get_flags (stream_t stream, int *pflags)

Function: int stream_get_state (stream_t stream, int *pstate)
MU_STREAM_STATE_OPEN
Last action was stream_open.
MU_STREAM_STATE_READ
Last action was stream_read or stream_readline.
MU_STREAM_STATE_WRITE
Last action was stream_write.
MU_STREAM_STATE_CLOSE
Last action was stream_close.

Function: int file_stream_create (stream_t *pstream)

Function: int mapfile_stream_create (stream_t *pstream)

Function: int encoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding)

Function: int decoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding)

Function: int tcp_stream_create (stream_t *pstream)

An example using tcp_stream_create to make a simple web client:

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <sys/select.h>

#include <mailutils/io.h>

const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];

int
main(int argc, char **argv)
{
  int ret, off = 0, fd;
  stream_t stream;
  size_t nb;
  fd_set fds;

  argc = argc, argv = argv;

  ret = tcp_stream_create (&stream);
  if (ret != 0)
    {
       fprintf (stderr, "tcp_stream_create: %s\n",
                mailutils_error(ret));
       exit (EXIT_FAILURE);
    }

connect_again:
  ret = stream_open (stream, "www.netscape.com", 80,
                     MU_STREAM_NONBLOCK);
  if (ret != 0)
    {
       if (ret == MU_ERROR_EAGAIN)
         {
             ret = stream_get_fd(stream, &fd);
             if (ret != 0)
               {
                   fprintf (stderr, "stream_get_fd: %s\n",
                            mailutils_error(ret));
                   exit (EXIT_FAILURE);
               }
               FD_ZERO (&fds);
               FD_SET (fd, &fds);
               select (fd+1, NULL, &fds, NULL, NULL);
               goto connect_again;
          }
          fprintf (stderr, "stream_open: %s\n", mailutils_error (ret));
          exit (EXIT_FAILURE);
    }

    ret = stream_get_fd (stream, &fd);
    if (ret != 0)
      {
         fprintf(stderr, "stream_get_fd: %s\n", strerror(ret));
         exit (EXIT_FAILURE);
      }

write_again:
    ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
    if (ret != 0 )
      {
         if (ret == EAGAIN)
           {
              FD_ZERO (&fds);
              FD_SET (fd, &fds);
              select (fd + 1, NULL, &fds, NULL, NULL);
              off += nb;
              goto write_again;
           }
         fprintf (stderr, "stream_write: %s\n", strerror(ret));
         exit (EXIT_FAILURE)
      }

      if (nb != strlen (wbuf))
        {
           fprintf(stderr, "stream_write: %s\n", "nb != wbuf length");
           exit (EXIT_FAILURE);
        }

      do
        {
read_again:
           ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
           if (ret != 0)
             {
                if (ret == EAGAIN)
                  {
                     FD_ZERO (&fds);
                     FD_SET (fd, &fds);
                     select (fd + 1, &fds, NULL, NULL, NULL);
                     goto read_again;
                   }
                 fprintf (stderr, "stream_read: %s\n", strerror(ret));
                 exit(EXIT_FAILURE);
              }
              write (2, rbuf, nb);
         } while (nb);

         ret = stream_close (stream);
         if (ret!= 0)
           {
              fprintf (stderr, "stream_close: %s\n", strerror(ret));
              exit (EXIT_FAILURE);
           }

         stream_destroy (&stream, NULL);
         exit (EXIT_SUCCESS);
}

Iterator

/* Prefix iterator_ is reserved */
#include <mailutils/iterator.h>

Function: int iterator_create (iterator_t *)

Function: void iterator_destroy (iterator_t *)

Function: int iterator_first (iterator_t)

Function: int iterator_next (iterator_t)

Function: int iterator_current (iterator_t, void **pitem)

Function: int iterator_is_done (iterator_t)

Authenticator

/* Prefix auth_ is reserved */
#include <mailutils/auth.h>

There are many ways to authenticate to a server. To be flexible the authentication process is provided by two objects auth_t and ticket_t. The auth_t can implement different protocol like APOP, MD5-AUTH, One Time Passwd etc .. By default if a mailbox does not understand or know how to authenticate it falls back to user/passwd authentication. The ticket_t is a way for Mailboxes and Mailers provide a way to authenticate when the URL does not contain enough information. The default action is to call the function auth_authenticate which will get the user and passwd if not set, this function can be overridden by a custom method.

Function: int auth_create (auth_t *pauth, void *owner)

Function: void auth_destroy (auth_t *pauth, void *owner)

Function: int auth_prologue (auth_t auth)

Function: int auth_authenticate (auth_t auth, char **user, char **passwd)

Function: int auth_epilogue (auth_t auth)

A simple example of an authenticate function:

#include <mailutils/auth.h>
#include <stdio.h>
#include <string.h>

int
my_authenticate (auth_t auth, char **user, char **passwd)
{
  char u[128] = "";
  char p[128] = "";

  /* prompt the user name */
  printf ("User: ");
  fflush (stdout);
  fgets (u, sizeof (u), stdin);
  u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */

  /* prompt the passwd */
  printf ("Passwd: "); fflush (stdout);
  echo_off ();
  fgets (p, sizeof(p), stdin);
  echo_on ();
  p[strlen (p) - 1] = '\0';

  /* duplicate */
  *user = strdup (u);
  *passwd = strdup (p);
  return 0;
}

Address

/* Prefix address_ is reserved */
#include <mailutils/address.h>

The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822.

The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or the other", and double-quoted characters are literals.

addr-spec    = local-part "@" domain
mailbox      = addr-spec ["(" display-name ")"] /
               [display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group        = display-name ":" [mailbox-list] ";"
address      = mailbox / group / unix-mbox
address-list = address ["," address-list]

unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are NOT valid internet email addresses, they must be qualified before use.

Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition.

Since an address-list may contain multiple addresses, they are accessed by a one-based index number, no. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages.

If len is greater than 0 it is the length of the buffer buf, and as much of the component as possible will be copied into the buffer. The buffer will be null terminated.

The size of a particular component may be queried by providing 0 for the len of the buffer, in which case the buffer is optional. In this case, if n is provided *n is assigned the length of the component string.

@macro ADDRESSENOMEM

  • ENOMEM Not enough memory to allocate resources. @macro ADDRESSEPARSE
  • ENOENT Invalid RFC822 syntax, parsing failed. @macro ADDRESSENOENT
  • ENOENT The index no is outside of the range of available addresses. @macro ADDRESSEINVAL
  • EINVAL Invalid usage, usually a required argument was null.
    Data Type: address_t
    The address_t object is used to hold information about a parsed RFC822 address list, and is an opaque data structure to the user. Functions are provided to retrieve information about an address in the address list.
    Function: int address_create (address_t *addr, const char *string)
    This function allocates and initializes addr by parsing the RFC822 address-list string. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOMEM @ADDRESSEPARSE
    Function: void address_destroy (address_t *addr)
    The addr is destroyed.
    Function: int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the noth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_personal (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the display-name describing the noth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard. A group is a kind of a special case. It has a display-name, followed by an optional mailbox-list. The display-name will be allocated an address all it's own, but all the other elements (local-part, domain, etc.) will be zero-length. So "a group: ;" is valid, will have a count of 1, but address_get_email(), and all the rest, will return zero-length output. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_comments (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the comments extracted while parsing the noth email address. These comments have no defined meaning, and are not currently collected. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the email addr-spec extracted while parsing the noth email address. This will be 0 length for a unix-mbox. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_local_part (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the local-part of an email addr-spec extracted while parsing the noth email address. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_domain (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the domain of an email addr-spec extracted while parsing the noth email address. This will be 0 length for a unix-mbox. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_get_route (address_t *addr, size_t no, char* buf, size_t len, size_t* n)
    Accesses the route of an email addr-spec extracted while parsing the noth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at <mailutils/parse822.h>. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_is_group (address_t *addr, size_t no, size_t len, int* yes)
    Sets *yes to 1 if this address is just the name of a group, 0 otherwise. This is faster than checking if the address has a non-zero length personal, and a zero-length local_part and domain. yes can be null, though that doesn't serve much purpose other than determining that no refers to an address. Currently, there is no way to determine the end of the group. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOENT
    Function: int address_to_string (address_t *addr, char* buf, size_t len, size_t* n)
    Returns the entire address list as a single RFC822 formatted address list. The return value is 0 on success and a code number on error conditions:
    @ADDRESSEINVAL @ADDRESSENOMEM
    Function: int address_get_count (address_t addr, size_t* count)
    Returns a count of the addresses in the address list. If addr is null, the count is 0. If count is not null, the count will be written to *count. The return value is 0.

    Example

    #include <stdio.h>
    #include <errno.h>
    #include <mailutils/address.h>
    
    #define EPARSE ENOENT
    
    static const char* err_name(int e)
    {
        struct {
    	int e;
    	const char* s;
        } map[] = {
    #define E(e) { e, #e },
    	E(ENOENT)
    	E(EINVAL)
    	E(ENOMEM)
    #undef E
    	{ 0, NULL }
        };
        static char s[sizeof(int) * 8 + 3];
        int i;
    
        for(i = 0; map[i].s; i++) {
    	if(map[i].e == e)
    	    return map[i].s;
        }
        sprintf(s, "[%d]", e);
    
        return s;
    }
    
    static int parse(const char* str)
    {
        size_t no = 0;
        size_t pcount = 0;
        int status;
    
        char buf[BUFSIZ];
    
        address_t  address = NULL;
    
        status = address_create(&address, str);
    
        address_get_count(address, &pcount);
    
        if(status) {
    	printf("%s=> error %s\n\n", str, err_name(status));
    	return 0;
        } else {
    	printf("%s=> pcount %d\n", str, pcount);
        }
    
        for(no = 1; no <= pcount; no++) {
    	size_t got = 0;
    	int isgroup;
    
    	address_is_group(address, no, &isgroup);
    
    	printf("%d ", no);
    
    	if(isgroup) {
    	  address_get_personal(address, no, buf, sizeof(buf), &got);
    
    	  printf("group <%s>\n", buf);
    	} else {
    	  address_get_email(address, no, buf, sizeof(buf), 0);
    
    	  printf("email <%s>\n", buf);
    	}
    
    	address_get_personal(address, no, buf, sizeof(buf), &got);
    
    	if(got && !isgroup) printf("   personal <%s>\n", buf);
    
    	address_get_comments(address, no, buf, sizeof(buf), &got);
    
    	if(got) printf("   comments <%s>\n", buf);
    
    	address_get_local_part(address, no, buf, sizeof(buf), &got);
    
    	if(got) {
    	    printf("   local-part <%s>", buf);
    
    	    address_get_domain(address, no, buf, sizeof(buf), &got);
    
    	    if(got) printf(" domain <%s>", buf);
    
    	    printf("\n");
    	}
    
    	address_get_route(address, no, buf, sizeof(buf), &got);
    
    	if(got) printf("   route <%s>\n", buf);
        }
        address_destroy(&address);
    
        printf("\n");
    
        return 0;
    }
    
    static int parseinput(void)
    {
        char buf[BUFSIZ];
    
        while(fgets(buf, sizeof(buf), stdin) != 0) {
    	buf[strlen(buf) - 1] = 0;
    	parse(buf);
        }
    
        return 0;
    }
    
    int main(int argc, const char *argv[])
    {
        argc = 1;
    
        if(!argv[argc]) {
    	return parseinput();
        }
        for(; argv[argc]; argc++) {
    	if(strcmp(argv[argc], "-") == 0) {
    	    parseinput();
    	} else {
    	    parse(argv[argc]);
    	}
        }
    
        return 0;
    }
    

    Locker

    /* Prefix locker_ is reserved */
    #include <mailutils/locker.h>
    
    

    Function: int locker_create (locker_t * plocker, char *filename, size_t len, int flags)

    Function: void locker_destroy (locker_t * plocker)

    Function: int locker_lock (locker_t locker, int flag)
    MU_LOCKER_RDLOCK
    MU_LOCKER_WRLOCK
    MU_LOCKER_PID
    MU_LOCKER_FCNTL
    MU_LOCKER_TIME

    Function: int locker_touchlock (locker_t locker)

    Function: int locker_unlock (locker_t locker)

    URL

    A mailbox or a mailer can be described in a URL, the string will contain the necessary information to initialize mailbox_t, or mailer_t properly.

    POP3

    The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is

    pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]
     or
    pop://[<user>[:<passwd>]@]<host>[:<port>]
    

    If :port is omitted the default value is 110. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.

    pop://[email protected]
    pop://asterix;AUTH=*@france.com
    pop://falbala;[email protected]
    pop://obelix;[email protected]:2000
    pop://obelix:[email protected]:2000
    

    For more complete information see rfc2368.

    IMAP

    The IMAP URL scheme contains an IMAP server, optional port number and the authentication mechanism. The general form is

    imap://[<user>[;AUTH=<type>]]@<host>[:port][/<mailbox>]
     or
    imap://[<user>[:<passwd>]]@<host>[:port][/<mailbox>]
    

    If :port is omitted the default value is 220. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.

    imap://[email protected]
    imap://asterix;AUTH=*@imap.france.com
    imap://asterix:[email protected]
    

    For more complete information see rfc2192.

    File

    Local folder should be handle by this URL. It is preferable to let the mailbox recognize the type of mailbox and take the appropriate action.

    file://path
    file://var/mail/user
    file://home/obelix/Mail
    

    For MMDF, MH local mailboxes URLs are provided, but it is preferable to use file://path and let the library figure out which one.

    mmdf://path
    mh://path
    

    Mailto

    After setting a mailer, mailto: is used to tell the mailer where and to whom the message is for.

    mailto://hostname
    

    Mailto can be used to generate short messages, for example to subscribe to mailing lists.

    mailto://[email protected]?body=subscribe
    mailto://[email protected]?Subject=hello&body=subscribe
    

    For more complete information see rfc2368.

    URL functions

    Helper functions are provided to retrieve and set the URL fields.

    Function: int url_create (url_t *url, const char *name)
    Create and the url data structure, but do not parse it.

    Function: void url_destroy (url_t *)
    Destroy the url and free it's resources.

    Function: int url_parse (url_t url)
    Parses the url, after calling this the get functions can be called.

    The syntax, condensed from RFC 1738, and extended with the ;auth= of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:

    url =
        scheme ":" = "//"
    
        [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]
    
        host [ ":" port ]
    
        [ ( "/" urlpath ) | ( "?" query ) ]
    

    This is a generalized URL syntax, and may not be exactly appropriate for any particular scheme.

    Function: const char* url_to_string (const url_t url)

    Function: int url_get_scheme (const url_t url, char *schem, size_t len, size_t *n)

    Function: int url_get_user (const url_t url, char *usr, size_t len, size_t *n)

    Function: int url_get_passwd (const url_t url, char *passwd, size_t len, size_t *n)

    Function: int url_get_host (const url_t url, char *host, size_t len, size_t *n)

    Function: int url_get_port (const url_t url, long *port)

    Function: int url_get_path (const url_t url, char *path, size_t len, size_t *n)

    Function: int url_get_query (const url_t url, char *query, size_t{len}, size_t *n)

    Function: char* url_decode (const char* s)
    Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup().

    Example

    #include <mailutils/url.h>
    #include <stdio.h>
    #include <string.h>
    
    int
    main ()
    {
      char str[1024];
      char buffer[1024];
      long port = 0;
      int len = sizeof (buffer);
      url_t u = NULL;
    
      while (fgets (str, sizeof (str), stdin) != NULL)
        {
          int rc;
    
          str[strlen (str) - 1] = '\0'; /* chop newline */
          if(strspn(str, " \t") == strlen(str))
            continue; /* skip empty lines */
          if ((rc = url_create(&u, str)) != 0)
          {
            printf(stderr, "url_create %s ERROR: [%d] %s",
              str, rc, strerror(rc));
            exit (1);
          }
          if ((rc = url_parse (u)) != 0)
            {
              printf ("%s --> FAILED: [%d] %s\n",
                str, rc, strerror(rc));
              continue;
            }
          printf ("%s --> SUCCESS\n", str);
    
          url_get_scheme (u, buffer, len, NULL);
          printf (" scheme <%s>\n", buffer);
    
          url_get_user (u, buffer, len, NULL);
          printf (" user <%s>\n", buffer);
    
          url_get_passwd (u, buffer, len, NULL);
          printf (" passwd <%s>\n", buffer);
    
          url_get_auth (u, buffer, len, NULL);
          printf (" auth <%s>\n", buffer);
    
          url_get_host (u, buffer, len, NULL);
          printf (" host <%s>\n", buffer);
    
          url_get_port (u, &port);
          printf (" port %ld\n", port);
    
          url_get_path (u, buffer, len, NULL);
          printf (" path <%s>\n", buffer);
    
          url_get_query (u, buffer, len, NULL);
          printf (" query <%s>\n", buffer);
    
          url_destroy (&u);
    
        }
      return 0;
    }
    
    


    Go to the first, previous, next, last section, table of contents.