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://alain@localhost ./sfrom
Passwd: xxxx
Jim Meyering <meyering@foo.org>      fetish(shellutils) beta
Fran@,{c}ois Pinard <pinard@bar.org> 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

#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;
}

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

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

pop://obelix@gaulois.org
pop://asterix;AUTH=*@france.com
pop://falbala;AUTH=+APOP@france.com
pop://obelix;AUTH=+APOP@village.gaulois.org:2000
pop://obelix:menhir@village.gaulois.org:2000

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

imap://obelix@imap.gaulois.org
imap://asterix;AUTH=*@imap.france.com
imap://asterix:potion@imap.france.com

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

mmdf://path
mh://path

mailto://hostname

mailto://bug-mailutils@gnu.org?body=subscribe
mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe

#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;
}