mailutils, Programming Manual

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

POP3

/* Prefix pop3_ is reserved */
#include <mailutils/pop3.h>

The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client to download a maildrop from a remote server. It does not provide complex or extensive operation on the maildrop. When the client successfully authenticates, the server acquires an exclusive access lock on the mailbox and holds it the entire duration of the session. After the authentication, the session enters transaction state and the client may issues commands to access messages in the mailbox.

Authorization state @itemize @bullet @item User @item Pass @item Quit @item Capa (extension) @item Auth (extension) @end itemize
Transaction state @itemize @bullet @item Stat @item List @item Retr @item Dele @item Noop @item Rset @item Top @item Uidl (extension) @item Quit @item Capa (extension) @end itemize

When the command Quit is issue the session enters the update state. The servers removes all messages marked deleted, releases the exclusive lock and closes the TCP connection.

Commands

An opaque structure pop3_t is use as a handle for the session, it is allocated and initialized by calling pop3_create (). All Functions will wait for a reply from the POP3 server before returning. The duration of the wait can be set by calling pop3_set_timeout (), the default is 10 minutes(1). Once a successful connection is established with pop3_connect (), two builtins authentications are provided pop3_apop () or pop3_user ()/pop3_pass (). The pop3_stat () and pop3_list () functions can be use to get the number and size of messages. Downloading of messages is done via a stream provided by pop3_retr () or pop3_top ()(2). The stream_t should be destroyed to indicate to the library that the action is finished. POP3 only provide a single channel for operation, it means only one operation can be done at a time, all the functions will return MU_ERROR_OPERATION_IN_PROGRESS if call during another operation. The functions pop3_list_all (), pop3_uidl_all () and pop3_capa () return iterators pop3_list_current (), pop3_uidl_current () are provided as cover function to format the string return by iterator_current (), iterator_destroy () must be call to release any resources.

In a multithreaded application, only one thread should access pop3_t handles.

Initialization

Function: int pop3_create (pop3_t * pop3)

Allocate and initialize a pop3 handle.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER

Function: void pop3_destroy (pop3_t *pop3)

When a POP3 session is finished, the structure must be free ()'ed to reclaim memory.

Function: int pop3_connect (pop3_t, const char *host, unsigned port, int flags)

A connection is established by calling pop3d_open (), the previous connection is close first. If non-blocking the function should be recalled until the return value is not MU_ERROR_TRY_AGAIN or MU_ERROR_IN_PROGRESS.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_IN_PROGRESS
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
MU_ERROR_TIMEOUT
MU_ERROR_NO_LOCK

Carrier

Function: int pop3_set_carrier (pop3_t, stream_t carrier);

The type of stream use to contact as server will be set to carrier in the pop3_t handle. Any previous carrier stream in the handle, will be close and release.

MU_ERROR_INVALID_PARAMETER

Function: int pop3_get_carrier (pop3_t, stream_t *carrier);

Return the pop3_t carrier. If none was set, a new tcp stream will be created.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Apop

Function: int pop3_apop (pop3_t, const char *user, const char *secret)

Apop offers an alternative to User/Pass authentication. For intermittent use of POP3, like checking for new mail, it is the preferred the authentication. It reduces the risk of password capture. The user and the shared secret are pass to pop3_apop (), the MD5 digest is calculated by applying the times tamp given by the server in the greeting followed by the secret.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Capa

Function: int pop3_capa (pop3_t, pop3_capa_iterator_t *iterator)

The Capa command is send to the sever and the list of capabilities is return in an iterator. iterator_current () gives an allocated string that should be free ()'ed. Caution: The iterator must be destroy after use, it will discard any remaining responses from CAPA and clear the way for new operations.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_capabilities (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_capa (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              char *capa;
              if (iterator_current (iterator, &capa) == 0)
               {;
                   printf ("CAPA: %s\n", capa);
                   free (capa);
               }
          }
        pop3_capa_destroy (&iterator);
    }
   else
     printf ("NONE\n");
}

Dele

Function: int pop3_dele (pop3_t, unsigned msgno)

Sends a Dele to the servers who will mark the msgno for deletion. The msgno may not refer to a message already marked deleted. If successful any future reference to msgno in other operations will be an error, unless unmarked by RSET.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

List

Function: int pop3_list (pop3_t, unsigned msgno, size_t *size)

Sends a List for a specific msgno and returns the size.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_list_all (pop3_t, iterator_t *iterator)

Sends A List with no argument to the server. The iterator must be destroy after use, it will discard any remaining response from LIST and clear the way for new operations. A cover function pop3_list_current () around to scan properly the string return by the iterator_current ().

#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_list (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_list_all (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              unsigned int msgno, size;
              if (pop3_list_current (iterator, &msgno, &size) == 0)
               {
                   printf ("LIST: %d %d\n", msgno, size);
               }
          }
        iterator (&iterator);
    }
   else
     printf ("NONE\n");
}

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_list_current (pop3_t, unsigned int *msgno, size_t *size)

Cover functions around iterator_current () from an iterator created by pop3_list_all () to format the result.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Noop

Function: int pop3_noop (pop3_t)

Sends a NOOP, useful to reset the timeout on the server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Pass

Function: int pop3_pass (pop3_t, const char *passwd)

Sends the PASS, to authenticate after the USER command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Quit

Function: int pop3_quit (pop3_t)

Enter the UPDATE state. The server will delete all messages marked deleted before closing the connection.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Retr

Function: int pop3_retr (pop3_t, unsigned msgno, stream_t *)

If successful a stream_t is created to allow downloading of the message, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will fail until the stream is destroyed by the caller.

#include <stdio.h>
#include <mailutils/pop3.h>

int
print_message (pop3_t pop3, unsigned int msgno)
{
   stream_t stream;
   int status = pop3_retr (pop3, msgno, &stream);
   if (status == 0)
    {
       size_t n = 0;
       char buf[128];
       while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
              && n)
         printf ("%s", buf);
       stream_release (stream);
    }
   return status;
}

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Rset

Function: int pop3_rset (pop3_t)

Sends a RSET to unmark the messages marked as deleted.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Stat

Function: int pop3_stat (pop3_t, unsigned msgno, unsigned *msg_count, size_t *size)

The number of messages in the mailbox and the size of the mailbox in octets. Caution: The size is in RFC822 where line termination is CRLF, messages marked as deleted are not counted in either total.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Top

Function: int pop3_top (pop3_t, unsigned int msgno, unsigned int lines, stream_t *stream)

If successful a stream is created to allow downloading of the header, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will failed until the stream is destroyed by the caller.

#include <stdio.h>
#include <mailutils/pop3.h>

int
print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
{
    stream_t stream;
    int status = pop3_top (pop3, msgno, lines, &stream);
    if (status == 0)
     {
        size_t n = 0;
        char buf[128];
        while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
               && n)
          printf ("%s", buf);
        stream_release (stream);
     }
  return status;
}

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Uidl

Function: int pop3_uidl (pop3_t, unsigned int msgno, char **uidl)

The Uniq Identifier is return in uidl, the string must be free ()'ed, by the caller.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_uidl_all (pop3_t, iterator_t * iterator)

An iterator object is return to iterate through the response and must be destroyed by the caller.

#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>

void print_uidl (pop3_t pop3)
{
   iterator_t iterator;
   status = pop3_uidl_all (pop3, &iterator);
   if (status == 0)
    {
        for (iterator_first (iterator);
             !iterator_is_done (iterator);
             iterator_next (iterator))
          {
              unsigned int msgno;
              char *uidl;
              if (pop3_uidl_current (iterator, &msgno, &uidl) == 0)
               {
                   printf ("LIST: %d %s\n", msgno, uidl);
                   free (uidl);
               }
          }
        iterator (&iterator);
    }
   else
     printf ("NONE\n");
}

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_uidl_current (iterator_t iterator, unsigned int *msgno, char **uidl)

Cover functions around iterator_current () from an iterator created by pop3_uidl_all () to format the result. The variable uidl should be free ()'ed.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

User

Function: int pop3_user (pop3_t, const char *user)

Sends the User command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Help functions

Function: int pop3_writeline (pop3_t, const char *format, ...);

Copy in the internal buffer of pop3_t the string, pop3_send () should be called later to flush the string to the POP3 server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_sendline (pop3_t, const char *cmd);

Cover function for pop3_writeline () and pop3_send ().

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_send (pop3_t, const char *cmd);

Flushes out the strings written by pop3_writeline () in the internal buffer to the channel.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function: int pop3_response (pop3_t, char *buffer, size_t len, size_t *plen)

The last response from the last command is save and can be examine after a failure or success.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Timeout

Function: int pop3_set_timeout (pop3_t, int timeout)

Set the timeout time for I/O on the carrier. The default is 10 minutes. The timeout is given in milliseconds.

Function: int pop3_get_timeout (pop3_t, int *timeout)

Get the timeout time for I/O on the carrier. The timeout is given in milliseconds.

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