Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit ad855c91 ad855c91be194b6ecbd4dfd44a7a322969727d32 by Alain Magloire
Options

updated.

1 parent 3f0aa410
Inline Side-by-side
Showing 2 changed files with 201 additions and 315 deletions
2003-10-05 Alain Magloire
Implementation of the lower level functions for POP3 in a separate library.
This the first draft, the code is not yet enable in the Makefile.am
* mailbox/pop/pop3_apop.c: APOP
* mailbox/pop/pop3_capa.c: CAPA
* mailbox/pop/pop3_carrier.c: TCP stream.
* mailbox/pop/pop3_connect.c:
* mailbox/pop/pop3_create.c:
* mailbox/pop/pop3_debug.c:
* mailbox/pop/pop3_dele.c: DELE
* mailbox/pop/pop3_destroy.c:
* mailbox/pop/pop3_disconnect.c:
* mailbox/pop/pop3_lista.c: LIST
* mailbox/pop/pop3_list.c: LIST
* mailbox/pop/pop3_noop.c: NOOP
* mailbox/pop/pop3_pass.c: PASS
* mailbox/pop/pop3_quit.c: QUIT
* mailbox/pop/pop3_readline.c:
* mailbox/pop/pop3_response.c:
* mailbox/pop/pop3_retr.c: RETR
* mailbox/pop/pop3_rset.c: RSET
* mailbox/pop/pop3_sendline.c:
* mailbox/pop/pop3_stat.c: STAT
* mailbox/pop/pop3_stream.c:
* mailbox/pop/pop3_timeout.c:
* mailbox/pop/pop3_top.c: TOP
* mailbox/pop/pop3_uidl.c: UIDL
* mailbox/pop/pop3_uidla.c: UIDL
* mailbox/pop/pop3_user.c: USER
* include/mailutils/pop3.h: Declaration of the public functions.
* include/mailutils/sys/pop3.h: Declaration of the internal functions and structures.
* doc/texinfo/pop3.texi: updated.
2003-10-05 Alain Magloire
When list_destroy() is called, we need to provide also
a way to free the item is necessary. To do this we added a new function:
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
\input texinfo @c -*-texinfo-* -
@setfilename pop3.info
@setchapternewpage off
@finalout
@comment This is part of the GNU Mailutils manual.
@comment Copyright (C) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@comment See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@code{/* Prefix @emph{ pop3_ } is reserved */}
@code{/* Prefix "mu_pop3_" is reserved */}
@code{#include <mailutils/pop3.h>}
@end example
......@@ -58,307 +63,195 @@ 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 2 minutes. On the server side, there is also an idle timeout of 10 minutes
before the POP3 server closes the connection. Although the @cite{RFC 1939} specifies that the minimum default timeout to be ten
minutes many servers has shorter idle period, care should be taken to at least send a @code{pop3_noop ()} between lengthy period
of idle time. Once a successful connection is established with @code{pop3_connect ()}, two built-ins 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. The functions @code{pop3_list_all ()}, @code{pop3_uidl_all ()} and
@code{pop3_capa ()} provide the information by going throught there iterators; @code{pop3_list_iterate ()}, @code{pop3_uidl_iterate ()}
and @code{pop3_capa_iterate ()}. Downloading of messages is done via a two methods @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 functions @code{pop3_retr ()} or @code{pop3_top ()} initiates the
dowloading of the message, the content is retrive with @code{pop_retr_read ()} or @code{pop3_top_read ()}.
@cindex mu_pop3_t
An opaque structure @var{mu_pop3_t} is use as a handle for the session, it is allocated and initialized by
calling @code{mu_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{mu_pop3_set_timeout ()}, the default is 2 minutes. On the server side, there is also an idle
timeout of 10 minutes before the POP3 server closes the connection, although the @cite{RFC 1939} specifies that the minimum
default timeout to be ten minutes, many servers have shorter idle period, care should be taken to at least send a
@code{mu_pop3_noop ()} between lengthy period of idle time. Once a successful connection is established with
@code{mu_pop3_connect ()}, two built-ins authentications are provided @code{mu_pop3_apop ()} or
@code{mu_pop3_user ()}/@code{mu_pop3_pass ()}. The @code{mu_pop3_stat ()} and @code{mu_pop3_list ()} functions can be use to
get the number and size of messages. The functions @code{mu_pop3_list_all ()}, @code{mu_pop3_uidl_all ()} and
@code{mu_pop3_capa ()} provide the information by going through there list iterators. Downloading of messages is done via a two methods
@code{mu_pop3_retr ()} or @code{mu_pop3_top ()}; @strong{Caution: Some Internet Service Providers do not permit to leave mail on
server and the message will be deleted once downloaded}.
The functions @code{mu_pop3_retr ()} or @code{mu_pop3_top ()} initiates the downloading of the message.
POP3 provides only a single channel for operation, it means only one operation can be done at a time, all the functions
will return POP3_OPERATION_IN_PROGRESS if a different operation is call during another.
will return @code{EINPROGRESS}.
@subsubsection Callbacks
The POP3 library does not provide any callbacks, the approach is to leave flow control and policy outside of the
library. The functions do minimal state checking, for example when sending RETR with @code{mu_pop3_retr()}
it is the responsibility of the user to go through the entire message on the stream, any other call will fail.
To reset the state or break the downloading, the user should disconnect @code{mu_pop3_disconnect()} and reconnect
@code{mu_pop3_connect()}, after a sufficient waiting period, @strong{Some POP3 server, move the maildrop to a different
location after a sudden disconnect, it is necessary to wait before working on the same mailbox, if not the user may
receive a ``Mailbox busy''}.
@example
@group
int pop3_list_cb (mu_pop3_t pop3, int msgno, int (*callback_list)(int msgno, size_t octet))
@{
size_t octet = 0;
int status = mu_pop3_list (pop3, msgno, &octet);
if (status == 0)
@{
callback_retr (msgno, octect);
@}
return status;
@}
@end group
@end example
@subsubsection Initialization
@cindex POP3 Initialization
@deftypefun int pop3_create (pop3_t *@var{pop3})
@deftypefun int mu_pop3_create (mu_pop3_t *@var{pop3})
Allocate and initialize a @var{pop3}, only memory is allocated.
Errors:
@table @code
@item POP3_NO_MEMORY
@item POP3_INVALID_PARAMETER
@item ENOMEM
@item EINVAL
@end table
@end deftypefun
@deftypefun void pop3_destroy (pop3_t *@var{pop3})
@deftypefun void mu_pop3_destroy (mu_pop3_t *@var{pop3})
When a POP3 session is finished, any data use by the library is release.
@end deftypefun
@deftypefun int pop3_connect (pop3_t @var{pop3}, const char *@var{hostname}, int @var{port}, int @var{flags})
@deftypefun int mu_pop3_connect (mu_pop3_t @var{pop3})
A connection is established on @var{hostname:port}, if there was any previous connection it is close first. If non-blocking the
function should be recalled until the return value is not POP3_TRY_AGAIN or POP3_IN_PROGRESS.
A connection is established on the carrier, if there was any previous connection it is close first. If non-blocking the
function should be recalled until the return value is not EAGAIN or EINPROGRESS.
Errors:
@table @code
@item POP3_NO_MEMORY
@item POP3_TRY_AGAIN
@item POP3_TIMEOUT
@item POP3_CONN_REFUSED
@item POP3_NO_CONN
@item POP3_INTERRUPTED
@item ENOMEM
@item EAGAIN
@item ETIMEDOUT
@item EIO
@item EINTR
@end table
@end deftypefun
@deftypefun int pop3_disconnect (pop3_t @var{pop3})
@deftypefun int mu_pop3_disconnect (mu_pop3_t @var{pop3})
Disconnect an establised POP3 session.
Disconnect an established POP3 session.
Errors:
@table @code
@item POP3_NO_CONN
@item POP3_INTERRUPTED
@item EIO
@item EINTR
@end table
@end deftypefun
@cindex POP3 carrier
@deftypefun int pop3_set_carrier (pop3_t @var{pop3}, pop3_carrier_t @var{carrier})
@deftypefun int mu_pop3_set_carrier (mu_pop3_t @var{pop3}, stream_t @var{carrier})
The pop3 library abstracts the creation of the stream to the server and let the user overrides the access methods. The default,
when no special carrier is provided, is to provide a carrier implemented with sockets and the use of @code{select ()}.
Set the stream to be use as the carrier to the server , for example tcp_stream.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item EINVAL
@end table
@deftp {Data Type} pop3_carrier_t
The @code{pop3_carrier_t} is defined as follows:
@example
@group
struct _pop3_carrier;
typedef struct _pop3_carrier* pop3_carrier_t;
#define POP3_CARRIER_NON_BLOCKING 1
struct _pop3_carrier @{
int (*open) (pop3_carrier_t, const char *hostname, int port, int flags);
int (*close) (pop3_carrier_t);
int (*read) (pop3_carrier_t, void *, size_t, size_t *);
int (*write) (pop3_carrier_t, const void *, size_t, size_t *);
int (*is_readready) (pop3_carrier_t, int timeout_seconds, int *ready);
int (*is_writeready) (pop3_carrier_t, int timeout_seconds, int *ready);
void (*destroy) (pop3_carrier_t *carrier);
void *data;
@};
@end group
@end example
@end deftp
The errors return by the carrier functions
@table @code
@item POP3_CARRIER_BAD
@item POP3_CARRIER_TRY_AGAIN
@item POP3_CARRIER_TIMEOUT
@item POP3_CARRIER_CONN_REFUSED
@item POP3_CARRIER_NOT_CONNECTED
@item POP3_CARRIER_INTERRUPTED
@end table
@end deftypefun
@subsubsection Authentication State
@cindex POP3 APOP
@deftypefun int pop3_apop (pop3_t @var{pop3}, const char *@var{user}, const char *@var{secret})
@deftypefun int mu_pop3_apop (mu_pop3_t @var{pop3}, 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 way to authenticate. 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 timestamp given by the server in the greeting followed by
to @code{mu_pop3_apop ()}, the MD5 digest is calculated by applying the time-stamp given by the server in the greeting followed by
the @var{secret}.
@end deftypefun
@cindex POP3 USER
@deftypefun int pop3_user (pop3_t, const char *@var{user})
@deftypefun int mu_pop3_user (mu_pop3_t @var{pop3}, const char *@var{user})
Sends the USER command.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item any carrier errors.
@item EINVAL
@item EACCES
@end table
@end deftypefun
@cindex POP3 PASS
@deftypefun int pop3_pass (pop3_t, const char *@var{passwd})
@deftypefun int mu_pop3_pass (mu_pop3_t @var{pop3}, const char *@var{passwd})
Sends the PASS, to authenticate after the USER command.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item any carrier errors
@item EINVAL
@item EACCES
@end table
@end deftypefun
@cindex POP3 CAPA
@deftypefun int pop3_capa (pop3_t @var{pop3})
The CAPA command is send to the sever and the list of capabilities is retrieve by calling @code{pop3_capa_iterate()}.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_capa_iterate (pop3_t @var{pop3}, char **@var{capa})
@deftypefun int mu_pop3_capa (mu_pop3_t @var{pop3})
To iterate through the capabilities response from the server, this function should be call in the loop. @var{capa} will be set
to @code{NULL} to indicate termination. Any other operations then @code{pop3_capa_iterate ()} will return
@var{POP3_OPERATION_IN_PROGRESS} until the CAPA command is complete.
The CAPA command is send to the sever and the list of capabilities is retrieve by calling @code{mu_pop3_capa_iterate()}.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item any carrier errors.
@item EINVAL
@item EACCES
@end table
@end deftypefun
@example
#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>
/* Assuming the pop3 is a valid connection. */
void print_capabilities (pop3_t pop3)
@{
status = pop3_capa (pop3);
if (status == 0)
@{
char *capa;
while ((status = pop3_capa_iterate(pop3, &capa) == 0) && capa != NULL)
@{
printf ("CAPA: %s\n", capa);
free (capa);
@}
@}
else
printf ("NONE\n");
@}
@end example
@subsubsection Transaction State
@cindex POP3 DELE
@deftypefun int pop3_dele (pop3_t @var{pop3}, unsigned @var{msgno})
@deftypefun int mu_pop3_dele (mu_pop3_t @var{pop3}, 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.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
@cindex POP3 LIST
@cindex struct pop3_list
@cindex struct mu_pop3_list
@deftypefun int pop3_list (pop3_t @var{pop3}, unsigned @var{msgno}, size_t *@var{size})
@deftypefun int mu_pop3_list (mu_pop3_t @var{pop3}, unsigned @var{msgno}, size_t *@var{size})
Sends a List for a specific @var{msgno} and returns the @var{size}.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_list_all (pop3_t @var{pop3})
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 ()}.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_list_iterate (pop3_t @var{pop3}, unsigned int *@var{msgno}, sie_t *@var{size})
To iterate through the capabilities response from the server, this function should be call in the loop. @var{msgno} will be set
to @code{0} to indicate termination. Any other operations then @code{pop3_list_iterate ()} will return
@var{POP3_OPERATION_IN_PROGRESS} until the LIST command is complete.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
@example
#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>
/* Assuming pop3 is a valid session. */
void print_list (pop3_t pop3)
@{
status = pop3_list_all (pop3);
if (status == 0)
@{
unsigned int msgno = 0;
size_t size = 0;
while ((status = pop3_list_iterate (pop3, &msgno, &size)) == 0 && msgno != 0)
@{
printf ("LIST: %u %d\n", msgno, size);
@}
@}
else
printf ("NONE\n");
@}
@end example
@cindex POP3 NOOP
@deftypefun int pop3_noop (pop3_t @var{pop3})
@deftypefun int mu_pop3_noop (mu_pop3_t @var{pop3})
Sends a NOOP, useful to reset the timeout on the server.
......@@ -373,26 +266,10 @@ Errors:
@cindex POP3 RETR
@deftypefun int pop3_retr (pop3_t @var{pop3}, unsigned @var{msgno})
If successful @code{pop3_retr_read} should be call to download the message, byte-stuff lines or handle internally, CRLFs are
converted to LF. All other operations will fail until the downloaed is complete by the caller.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_retr_read (pop3_t @var{pop3}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
@deftypefun int mu_pop3_retr (mu_pop3_t @var{pop3}, unsigned @var{msgno}, stream_t *@var{stream})
After a @code{pop3_retr ()}, this function is use to get the content of the message, it will fill the @var{buffer} up to
a maximum of @var{len} and return in @var{nread} how much the @var{buffer} contains. If @var{nread} is zero, it signals
the termination of the command. Any other operations then @code{pop3_retr_read ()} will return
@var{POP3_OPERATION_IN_PROGRESS} until the RETR command is completed.
If successful @code{stream} should be call to download the message, byte-stuff lines or handle internally, CRLFs are
converted to LF. All other operations will fail until the downloaded is complete by the caller.
Errors:
@table @code
......@@ -408,14 +285,15 @@ Errors:
#include <mailutils/pop3.h>
int
print_message (pop3_t pop3, unsigned int msgno)
print_message (mu_pop3_t pop3, unsigned int msgno)
@{
int status = pop3_retr (pop3, msgno);
stream_t stream;
int status = mu_pop3_retr (pop3, msgno, &stream);
if (status == 0)
@{
size_t n = 0;
char buf[128];
while ((status = pop_retr_read (pop3, buf, sizeof buf, &n)) == 0) && n > 0)
while ((status = stream_readline (stream, buf, sizeof buf, &n)) == 0) && n > 0)
@{
printf ("%s", buf);
@}
......@@ -426,33 +304,16 @@ print_message (pop3_t pop3, unsigned int msgno)
@cindex POP3 TOP
@deftypefun int pop3_top (pop3_t @var{pop3}, unsigned int @var{msgno}, unsigned int @var{lines})
@deftypefun int mu_pop3_top (mu_pop3_t @var{pop3}, unsigned int @var{msgno}, unsigned int @var{lines}, stream_t *@var{stream})
If successful @code{pop3_top_read} should be call to download the header, byte-stuff lines or handle internally, CRLFs are
If successful @code{stream} should be call to download the header, byte-stuff lines or handle internally, CRLFs are
converted to LF. All other operations will failed until the operation is completed by the caller.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_top_read (pop3_t @var{pop3}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
After a @code{pop3_top ()}, this function is use to get the content of the message, it will fill the @var{buffer} up to
a maximum of @var{len} and return in @var{nread} how much the @var{buffer} contains. If @var{nread} is zero, it signals
the termination of the command. Any other operations then @code{pop3_retr_read ()} will return
@var{POP3_OPERATION_IN_PROGRESS} until the TOP command is completed.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
......@@ -461,15 +322,15 @@ Errors:
#include <mailutils/pop3.h>
int
print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
print_top (mu_pop3_t pop3, unsigned int msgno, unsigned int lines)
@{
int status = pop3_top (pop3, msgno, lines);
stream_t stream;
int status = mu_pop3_top (pop3, msgno, lines, &stream);
if (status == 0)
@{
size_t n = 0;
char buf[128];
while ((status = pop3_top_read (pop3, buf, sizeof buf, &n)) == 0)
&& n > 0)
while ((status = stream_readline (stream, buf, sizeof buf, &n)) == 0) && n > 0)
printf ("%s", buf);
@}
return status;
......@@ -479,75 +340,57 @@ print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
@cindex POP3 RSET
@deftypefun int pop3_rset (pop3_t @var{pop3})
@deftypefun int mu_pop3_rset (mu_pop3_t @var{pop3})
Sends a RSET to unmark the messages marked as deleted.
Sends a RSET to unmarked the messages marked as deleted.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
@cindex POP3 STAT
@deftypefun int pop3_stat (pop3_t @var{pop3}, unsigned @var{msgno}, unsigned *@var{msg_count}, size_t *@var{size})
@deftypefun int mu_pop3_stat (mu_pop3_t @var{pop3}, 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.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
@cindex POP3 UIDL
@deftypefun int pop3_uidl (pop3_t @var{pop3}, unsigned int @var{msgno}, char **@var{uidl})
@deftypefun int mu_pop3_uidl (mu_pop3_t @var{pop3}, unsigned int @var{msgno}, char **@var{uidl})
The UIDL is return in @var{uidl}, the string must be @code{free ()}'ed, by the caller.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_uidl_all (pop3_t @var{pop3})
A UIDL command is executed. The call should iterate with @code{pop3_uidl_iterate ()} to fetch the response.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item EINVAL
@item EACCES
@item EINPROGRESS
@item any carrier errors.
@end table
@end deftypefun
@deftypefun int pop3_uidl_iterate (pop3_t @var{pop3}, unsigned int *@var{msgno}, char **@var{uidl})
@deftypefun int mu_pop3_uidl_all (mu_pop3_t @var{pop3}, list_t *@var{list})
To iterate through the uidl responses from the server, @code{pop3_uidl_iterate ()} should be call in a loop, @var{msgno} will be set
to zero to indicate termination. Any other operations then @code{pop3_uidl;_iterate ()} will return
@var{POP3_OPERATION_IN_PROGRESS} until the UIDL command is completed. The @var{uidl} is @code{malloc()}
and should be @code{free()} by the caller.
A UIDL command is executed. The call should iterate through the @code{list} to fetch the response.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
......@@ -556,21 +399,32 @@ Errors:
#include <stdlib.h>
#include <mailutils/pop3.h>
void print_uidl (pop3_t pop3)
void print_uidl (mu_pop3_t pop3)
@{
status = pop3_uidl_all (pop3);
list_t list;
status = mu_pop3_uidl_all (pop3, &list);
if (status == 0)
@{
unsigned int msgno;
char *uidl;
while (pop3_uidl_iterate (pop3, &msgno, &uidl) == 0 && msgno != 0)
iterator_t itr;
int rc;
rc = iterator_create (&itr, list);
if (rc)
lperror ("iterator_create", rc);
for (iterator_first (itr); !iterator_is_done (itr); iterator_next (itr))
@{
printf ("LIST: %d %s\n", msgno, uidl);
free (uidl);
char *text;
rc = iterator_current (itr, (void**) &text);
if (rc)
lperror ("iterator_current", rc);
printf ("%s\n", text);
@}
iterator_destroy (&itr);
list_destroy(&list);
@}
else
printf ("NONE\n");
@}
@end example
......@@ -578,89 +432,84 @@ void print_uidl (pop3_t pop3)
@subsubsection Update State
@cindex POP3 QUIT
@deftypefun int pop3_quit (pop3_t)
@deftypefun int mu_pop3_quit (mu_pop3_t @var{pop3})
QUIT will be send to enter the update state, if the command is successfull, the connection is close and any statein
QUIT will be send to enter the update state, if the command is successful, the connection is close and any state
the library is cleared. On the server side, all messages marked deleted before closing the connection will be removed..
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item POP3_OPERATION_DENIED
@item POP3_OPERATION_IN_PROGRESS
@item any carrier errors.
@item EINVAL
@item EACCES
@item EINPROGRESS
@end table
@end deftypefun
@subsubsection Help functions
@deftypefun int pop3_writeline (pop3_t, const char *@var{format}, ...);
@deftypefun int mu_pop3_writeline (mu_pop3_t @var{pop3}, const char *@var{format}, ...);
Copy in the internal buffer of @code{pop3_t} the formatted string, @code{pop3_send ()} should be called later to flush the string
Copy in the internal buffer of @code{mu_pop3_t} the formatted string, @code{mu_pop3_send ()} should be called later to flush the string
to the POP3 server.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item any carrier errors.
@item EINVAL
@end table
@end deftypefun
@deftypefun int pop3_sendline (pop3_t, const char *@var{cmd});
@deftypefun int mu_pop3_sendline (mu_pop3_t @var{pop3}, const char *@var{cmd});
Cover function for @code{pop3_writeline ()} and @code{pop3_send ()}.
Cover function for @code{mu_pop3_writeline ()} and @code{mu_pop3_send ()}.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item any carrier errors.
@item EINVAL
@end table
@end deftypefun
@deftypefun int pop3_send (pop3_t);
@deftypefun int mu_pop3_send (mu_pop3_t @var{pop3});
Flushes out the strings written by @code{pop3_writeline ()} in the internal buffer to the channel.
Flushes out the strings written by @code{mu_pop3_writeline ()} in the internal buffer to the channel.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item any carrier errors.
@item EINVAL
@end table
@end deftypefun
@deftypefun int pop3_response (pop3_t, char *@var{buffer}, size_t @var{len}, size_t *@var{plen})
@deftypefun int mu_pop3_response (mu_pop3_t @var{pop3}, 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.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item any carrier errors.
@item EINVAL
@end table
@end deftypefun
@subsubsection Timeout
@cindex Pop3 Timeout
@deftypefun int pop3_set_timeout (pop3_t, int @var{timeout})
@deftypefun int mu_pop3_set_timeout (mu_pop3_t @var{pop3}, 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.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item EINVAL
@end table
@end deftypefun
@deftypefun int pop3_get_timeout (pop3_t, int *@var{timeout})
@deftypefun int mu_pop3_get_timeout (mu_pop3_t @var{pop3}, int *@var{timeout})
Get the timeout time for I/O on the carrier. The @var{timeout} is given in milliseconds.
Errors:
@table @code
@item POP3_INVALID_PARAMETER
@item EINVAL
@end table
@end deftypefun
......