@example
@code{/* Prefix @emph{pop3_} is reserved */}
@code{#include <mailutils/pop3.h>}

@end example

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.
@itemize @bullet
@item
Authorization state
  @itemize @bullet
  @item
  User
  @item
  Pass
  @item
  Quit
  @item
  Capa (extension)
  @item
  Auth (extension)
  @end itemize
@item
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
@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.

@subsection Commands
@cindex pop3_t

An opaque structure @var{pop3_t} is use as a handle for the session, it is
allocated and initialized by calling @code{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 @code{pop3_set_timeout ()}, the default
is 10 minutes@footnote{@strong{Caution:} Although the @cite{RFC 1939}
specifies that the minimum default timeout is ten minutes many servers has
shorter idle period, care should be taken to at least send a
@code{pop3_noop ()} between lengthy period of times.}.  Once a successful
connection is established with @code{pop3_connect ()}, two builtins
authentications are provided @code{pop3_apop ()} or
@code{pop3_user ()}/@code{pop3_pass ()}.  The @code{pop3_stat ()} and
@code{pop3_list ()} functions can be use to get the number and size of
messages. Downloading of messages is done via a stream provided by
@code{pop3_retr ()} or @code{pop3_top ()}@footnote{@strong{Caution:} Some
Internet Service Providers do not permit to leave mail
on server and the message will be deleted once downloaded.}.
The @code{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 @code{pop3_list_all ()}, @code{pop3_uidl_all ()} and
@code{pop3_capa ()} return iterators @code{pop3_list_current ()},
@code{pop3_uidl_current ()} are provided as cover function to format the
string return by @code{iterator_current ()}, @code{iterator_destroy ()} must
be call to release any resources.

In a multithreaded application, only one thread should access @var{pop3_t}
handles.

@subsubsection Initialization
@cindex POP3 Initialization

@deftypefun int pop3_create (pop3_t * @var{pop3})

Allocate and initialize a @var{pop3} handle.

@table @code
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun void pop3_destroy (pop3_t *@var{pop3})

When a POP3 session is finished, the structure must be @code{free ()}'ed to
reclaim memory.
@end deftypefun

@deftypefun int pop3_connect (pop3_t, const char *@var{host}, unsigned @var{port}, int @var{flags})

A connection is established by calling @code{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.

@table @code
@item MU_ERROR_NO_MEMORY
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_IN_PROGRESS
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@item MU_ERROR_TIMEOUT
@item MU_ERROR_NO_LOCK
@end table
@end deftypefun

@subsubsection Carrier
@cindex POP3 channel

@deftypefun int pop3_set_carrier (pop3_t, stream_t @var{carrier});

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@end table
@end deftypefun

@deftypefun int pop3_get_carrier (pop3_t, stream_t *@var{carrier});

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_NO_MEMORY
@end table
@end deftypefun

@subsubsection Apop
@cindex POP3 Apop

@deftypefun int pop3_apop (pop3_t, const char *@var{user}, const char *@var{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 @var{user}
and the shared @var{secret} are pass to @code{pop3_apop ()}, the MD5 digest
is calculated by applying the times tamp given by the server in the greeting
followed by the @var{secret}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Capa
@cindex POP3 Capa

@deftypefun int pop3_capa (pop3_t, pop3_capa_iterator_t *@var{iterator})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@example
#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");
@}
@end example

@end deftypefun

@subsubsection Dele
@cindex POP3 Dele

@deftypefun int pop3_dele (pop3_t, unsigned @var{msgno})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@end deftypefun

@subsubsection List
@cindex POP3 List
@cindex struct pop3_list

@deftypefun int pop3_list (pop3_t, unsigned @var{msgno}, size_t *@var{size})

Sends a List for a specific @var{msgno} and returns the @var{size}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@deftypefun int pop3_list_all (pop3_t, iterator_t *@var{iterator})

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

@example
#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");
@}
@end example

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@end deftypefun

@deftypefun int pop3_list_current (pop3_t, unsigned int *@var{msgno}, size_t *@var{size})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@end deftypefun

@subsubsection Noop
@cindex POP3 Noop

@deftypefun int pop3_noop (pop3_t)

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Pass
@cindex POP3 Pass

@deftypefun int pop3_pass (pop3_t, const char *@var{passwd})

Sends the PASS, to authenticate after the USER command.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Quit
@cindex POP3 Quit

@deftypefun int pop3_quit (pop3_t)

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Retr
@cindex POP3 Retr

@deftypefun int pop3_retr (pop3_t, unsigned @var{msgno}, stream_t *)

If successful a @code{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.

@example
#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;
@}
@end example

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Rset
@cindex POP3 Rset

@deftypefun int pop3_rset (pop3_t)

Sends a RSET to unmark the messages marked as deleted.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Stat
@cindex POP3 Stat

@deftypefun int pop3_stat (pop3_t, unsigned @var{msgno}, unsigned *@var{msg_count}, size_t *@var{size})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Top
@cindex POP3 Top

@deftypefun int pop3_top  (pop3_t, unsigned int @var{msgno}, unsigned int @var{lines}, stream_t *@var{stream})

If successful a @code{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.

@example
#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;
@}
@end example

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Uidl
@cindex POP3 Uidl

@deftypefun int pop3_uidl (pop3_t, unsigned int @var{msgno}, char **@var{uidl})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@deftypefun int pop3_uidl_all (pop3_t, iterator_t * @var{iterator})

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

@example
#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");
@}
@end example

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@deftypefun int pop3_uidl_current (iterator_t @var{iterator}, unsigned int *@var{msgno}, char **@var{uidl})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection User
@cindex POP3 User

@deftypefun int pop3_user (pop3_t, const char *@var{user})

Sends the User command.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@subsubsection Help functions

@deftypefun int pop3_writeline (pop3_t, const char *@var{format}, ...);

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@deftypefun int pop3_sendline (pop3_t, const char *@var{cmd});

Cover function for @code{pop3_writeline ()} and @code{pop3_send ()}.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@end deftypefun

@deftypefun int pop3_send (pop3_t, const char *@var{cmd});

Flushes out the strings written by @code{pop3_writeline ()} in the internal
buffer to the channel.

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table
@end deftypefun

@deftypefun int pop3_response (pop3_t, char *@var{buffer}, size_t @var{len}, size_t *@var{plen})

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

@table @code
@item MU_ERROR_INVALID_PARAMETER
@item MU_ERROR_IO
@item MU_ERROR_TIMEOUT
@item MU_ERROR_TRY_AGAIN
@item MU_ERROR_OPERATION_DENIED
@end table

@end deftypefun

@subsubsection Timeout
@cindex Pop3 Timeout

@deftypefun int pop3_set_timeout (pop3_t, int @var{timeout})

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

@end deftypefun

@deftypefun int pop3_get_timeout (pop3_t, int *@var{timeout})

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

@end deftypefun