GNU MAILUTILS offers a general purpose library whose aim is to provide a rich set of functions for accessing different mailbox formats and mailers.
For more information on,
/* 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.
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.
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.
Allocate and initialize a pop3 handle.
MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
When a POP3 session is finished, the structure must be free ()'ed to
reclaim memory.
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
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
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 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
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");
}
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Sends the User command.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
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
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
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
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
Set the timeout time for I/O on the carrier. The default is 10 minutes. The timeout is given in milliseconds.
Get the timeout time for I/O on the carrier. The timeout is given in milliseconds.
/* Prefix imap4_ is reserved */#include <mailutils/imap4.h>
Internet Message Access Protocol - Version (4rev1). Not implemented.
/* Prefix mbox_ is reserved */#include <mailutils/mbox.h>
The most common mailbox format on UNIX platform is mbox. Mbox file is messages separated by the special format string.
From SP envelope-sender SP date [SP moreinfo]
"From "
envelope-sender
date
asctime ()
moreinfo
A mbox_t is created, initialized and destroyed by mbox_create ()
and mbox_destroy (). When opening, mbox_open () will do a quick
check to see if the format is a valid format or an empty file. The scanning
of the mailbox is done by mbox_scan ().
The function, mbox_scan (), takes callback functions called during the
scanning to provide information. The scanning will cache some of the headers
fields for speed. Closing the mailbox, mbox_close () will free
any resources like, headers cache, locks etc ... All the messages with
attributes marked deleted will only be removed on mbox_expunge ().
If only the attributes need to be save but the messages not removed, this
can be done by mbox_save_attributes (). New messages are added with
mbox_append (). Attributes are saved in the Status: header
field, Read is 'R', Seen is 'O', Deleted is 'd' and Reply is 'r'.
Allocate and initialize a mbox handle.
MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
When a POP3 session is finished, the structure must be free ()'ed to
reclaim memory.
Another type of stream can be provided to work on, the carrier is set in the mbox_t handle. Any previous carrier stream in the handle, will be close and release. Since the parsing code maintain only the offsets off the message the carrier stream must be seekable.
MU_ERROR_INVALID_PARAMETER
Return the mbox_t carrier. If none was set, a new file stream will be created.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Open carrier stream with filename and flags. The stream will be quickly examine to see if it is a mbox format.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
MU_ERROR_NO_ENTRY
MU_ERROR_NO_ACCESS
MU_ERROR_NOT_SUPPORTED
Close the carrier stream and resources particular to the mailbox.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Return the uidnext, if the mbox_t was not scan mbox_scan ()
is called first.
MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()
Return the uidvalidity, if the mbox_t was not scan mbox_scan ()
is called first.
MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()
Return an attribute to indicate the status of message number msgno.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Return an allocated string in sep containing the value "From " separating
each message in Unix mbox format. The string should be free ()ed by
the caller.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
The variable sep should contain a valid "From " separator that will be use when the expunging.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Return a stream to read the header of message msgno. The stream should be destroy after usage.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Use stream when expunging for message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the number of lines of message msgno.
MU_ERROR_INVALID_PARAMETER
Return a stream to read the body of message msgno. The stream should be destroy after usage.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Use stream when expunging for message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the number of lines of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of mailbox.
MU_ERROR_INVALID_PARAMETER
Save the changes to the messages back to the mailbox, but do not remove messages mark for deletion in the process.
MU_ERROR_INVALID_PARAMETER
Mark msgno for deletion.
MU_ERROR_INVALID_PARAMETER
Unmark msgno if it was marked for deletion.
MU_ERROR_INVALID_PARAMETER
Save the changes to the mailbox and in the process remove all messages marked for deletion.
MU_ERROR_INVALID_PARAMETER
Append to the mailbox an rfc822 message represented by stream. The variable sep should contain a valid "From " separator or NULL to get the default.
MU_ERROR_INVALID_PARAMETER
Append to the mailbox an rfc822 message represented by a header, hstream, and a body, bstream. The variable sep should contain a valid "From " separator or NULL to get the default.
MU_ERROR_INVALID_PARAMETER
Start scanning the mailbox for new messages. The variable start can be
a message number starting point. The result of the scanning will be in
count. The scanning will trigger the mbox_newmsg_cb() callback
for each new message and mbox_progress_cb () at different interval
to notify progression. The return values of the those callback should be
0 is different then 0 the scanning will be stop an the function returns
MU_ERROR_INTERRUPTED.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_INTERRUPTED
MU_ERROR_NO_MEMORY
Set the callback function for progress. The variable arg will be pass back in the callback as the second argument.
MU_ERROR_INVALID_PARAMETER
Set the callback function for new messages. The variable arg will be pass back in the callback as the second argument.
MU_ERROR_INVALID_PARAMETER
/* Prefix mh_ is reserved */#include <mailutils/mh.h>
Mail Handler mailbox format. Not implemented.
/* Prefix maildir_ is reserved */#include <mailutils/maildir.h>
QMail mailbox format. Not implemented.
/* Prefix smtp_ is reserved */#include <mailutils/smtp.h>
Simple Mail Transfer Protocol. Not implemented.
/* Prefix sendmail_ is reserved */#include <mailutils/sendmail.h>
Spawning Sendmail daemon to deliver mail. Not implemented.
/* Prefix nntp_ is reserved */#include <mailutils/nntp.h>
Network News Transfer Protocol. Not implemented.
/* Prefix parse822_ is reserved */#include <mailutils/parse822.h>
Internet Message Format, see Address node for the discussion.
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 (®istrar);
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
...
/* 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) |
\-----------------/
/* Prefix mailbox_ is reserved */#include <mailutils/mailbox.h>
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) |
\-----------------/
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
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
ENOMEM
mailbox_create () based on the environment
variable $MAIL or the string formed by
_PATH_MAILDIR/user" or $LOGNAME if user is null,
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
stream_create for flag's description.
The return value is 0 on success and a code number on error conditions:
EAGAIN
EINPROGRESS
EBUSY
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
auth_t object on creation.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
/* Prefix mailer_ is reserved */#include <mailutils/mailer.h>
The API is still shaky and undefined.
#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 |
+-----------------------+
/* Prefix envelope_ is reserved */#include <mailutils/envelope.h>
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.
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.
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.
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.
/* 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.
Some basic macros are already provided for rfc822.
MU_HDR_RETURN_PATH
MU_HDR_RECEIVED
MU_HDR_DATE
MU_HDR_FROM
MU_HDR_RESENT_FROM
MU_HDR_SUBJECT
MU_HDR_SENDER
MU_HDR_RESENT_SENDER
MU_HDR_TO
MU_HDR_RESENT_TO
MU_HDR_CC
MU_HDR_RESENT_CC
MU_HDR_BCC
MU_HDR_RESENT_BCC
MU_HDR_REPLY_TO
MU_HDR_RESENT_REPLY_TO
MU_HDR_MESSAGE_ID
MU_HDR_RESENT_MESSAGE_ID
MU_HDR_IN_REPLY_TO
MU_HDR_ENCRYPTED
MU_HDR_PRECEDENCE
MU_HDR_STATUS
MU_HDR_CONTENT_LENGTH
MU_HDR_CONTENT_TYPE
MU_HDR_MIME_VERSION
/* Prefix body_ is reserved */#include <mailutils/body.h>
/* Prefix attribute_ is reserved */#include <mailutils/attribute.h>
#include <mailutils/stream.h>
MU_STREAM_READ
MU_STREAM_WRITE
MU_STREAM_RDWR
MU_STREAM_APPEND
MU_STREAM_CREAT
MU_STREAM_NONBLOCK
MU_STREAM_NO_CHECK
MU_STREAM_STATE_OPEN
stream_open.
MU_STREAM_STATE_READ
stream_read or stream_readline.
MU_STREAM_STATE_WRITE
stream_write.
MU_STREAM_STATE_CLOSE
stream_close.
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);
}
/* Prefix iterator_ is reserved */#include <mailutils/iterator.h>
/* 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.
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;
}
/* 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
null.
address_t object is used to hold information about a parsed
RFC822 address list, and is an opaque
data structure to the user. Functions are provided to retrieve information
about an address in the address list.
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0
length for a unix-mbox.
The return value is 0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0
length for a unix-mbox.
The return value is 0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
1 if this address is just the name of a group,
0 otherwise. This is faster than checking if the address has
a non-zero length personal, and a zero-length local_part and domain.
yes can be null, though that doesn't serve much purpose other
than determining that no refers to an address.
Currently, there is no way to determine the end of the group.
The return value is 0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
null, the count is 0. If count is
not null, the count will be written to *count.
The return value is 0.
#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>
MU_LOCKER_RDLOCK
MU_LOCKER_WRLOCK
MU_LOCKER_PID
MU_LOCKER_FCNTL
MU_LOCKER_TIME
A mailbox or a mailer can be described in a URL, the string will contain the
necessary information to initialize mailbox_t, or mailer_t
properly.
The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is
pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]orpop://[<user>[:<passwd>]@]<host>[:<port>]
If :port is omitted the default value is 110. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.
pop://obelix@gaulois.orgpop://asterix;AUTH=*@france.compop://falbala;AUTH=+APOP@france.compop://obelix;AUTH=+APOP@village.gaulois.org:2000pop://obelix:menhir@village.gaulois.org:2000
For more complete information see rfc2368.
The IMAP URL scheme contains an IMAP server, optional port number and