Indices
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,
Wherever the mail is and whatever format it is stored in, it is operated
upon using the same set of functions. To unified the C API,
GNU Mailutils offers a heteroclite set of objects that work in
aggregation to do operations on
emails. Each object does 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 |
+--------------+
As an example, here is a simplified version of from command. It
lists 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/mailutils.h>
int
main (int argc, const char **argv)
{
char *from;
char *subject;
mailbox_t mbox;
int status;
size_t msgno, total = 0;
/* 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_default (&mbox, argv[1]);
if (status != 0)
{
fprintf (stderr, "mailbox_create: %s\n", mu_errstring (status));
exit (EXIT_FAILURE);
}
status = mailbox_open (mbox, MU_STREAM_READ);
if (status != 0)
{
fprintf (stderr, "mailbox_open: %s\n", mu_errstring (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",
mu_errstring (status));
exit (EXIT_FAILURE);
}
if (header_aget_value (hdr, MU_HEADER_FROM, &from))
from = strdup ("(NO FROM)");
if (header_aget_value (hdr, MU_HEADER_SUBJECT, &subject))
subject = strdup("(NO SUBJECT)");
printf ("%s\t%s\n", from, subject);
free (from);
free (subject);
}
mailbox_close (mbox);
mailbox_destroy (&mbox);
return 0;
}
Here is a sample output produced by this program:
% MAIL=pop://alain@localhost ./sfrom Passwd: xxxx Jim Meyering <meyering@foo.org> fetish(shellutils) beta Franç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) |
\-----------------/
| int folder_create (folder_t *, const char *url) | Function |
| void folder_destroy (folder_t *) | Function |
| int folder_open (folder_t, int flag) | Function |
| int folder_close (folder_t) | Function |
| int folder_delete (folder_t, const char *mailbox) | Function |
| int folder_rename (folder_t, const char *, const char *mailbox) | Function |
| int folder_subscribe (folder_t, const char *mailbox) | Function |
| int folder_unsubscribe (folder_t, const char *mailbox) | Function |
| int folder_list (folder_t, const char *ref, const char *wcard, iterator_t *) | Function |
| int folder_lsub (folder_t, const char *ref, const char *wcar, iterator_t *) | Function |
| int folder_get_stream (folder_t, stream_t *) | Function |
| int folder_set_stream (folder_t, stream_t) | Function |
| int folder_get_observable (folder_t, observable_t *) | Function |
| int folder_get_debug (folder_t, debug_t *) | Function |
| int folder_set_debug (folder_t, debug_t) | Function |
| int folder_get_authority (folder_t, authority_t *) | Function |
| int folder_set_authority (folder_t, authority_t) | Function |
| int folder_get_url (folder_t, url_t *) | Function |
| int folder_set_url (folder_t, url_t) | Function |
/* Prefix mailbox_ is reserved */#include <mailutils/mailbox.h>
| mailbox_t | Data Type |
The mailbox_t object is used to hold information and it is an opaque
data structure to the user. Functions are provided to retrieve information
from the data structure.
|
mailbox_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
( alain ) | | url_t *-|----+ | port |
----------- | |-----------------+ | hostname |
( jakob *-)----+ | observer_t *-| | file |
----------- |-----------------+ | ... |
( jeff ) | stream_t | \-----------/
----------- |-----------------|
( sean ) | locker_t |
---------- |-----------------|
| message_t(1) |
|-----------------|
| message_t(2) |
| ...... |
| message_t(n) |
\-----------------/
| int mailbox_append_message (mailbox_t mbox, message_t message) | Function |
|
The message is appended to the mailbox mbox.
The return value is
|
| int mailbox_close (mailbox_t mbox) | Function |
|
The stream attach to mbox is closed.
The return value is
|
| int mailbox_create (mailbox_t *pmbox, const char *name) | Function |
The function mailbox_create allocates and initializes pmbox.
The concrete mailbox type instantiate is based on the scheme of the url name.
The return value is
|
| int mailbox_create_default (mailbox_t *pmbox, const char *name) | Function |
Create a mailbox with mailbox_create () based on the environment
variable $MAIL or the string formed by
_PATH_MAILDIR/user" or $LOGNAME if user is null,
|
| void mailbox_destroy (mailbox_t *pmbox) | Function |
| Destroys and releases resources held by pmbox. |
| int mailbox_expunge (mailbox_t mbox) | Function |
|
All messages marked for deletion are removed.
The return value is
|
| int mailbox_get_folder (mailbox_t mbox, folder_t *folder) | Function |
|
Get the folder.
The return value is
|
| int mailbox_get_debug (mailbox_t mbox, debug_t *debug) | Function |
Get a debug object.
The return value is 0 on success and a code number on error conditions:
|
| int mailbox_get_locker (mailbox_t mbox, locker_t *plocker) | Function |
|
Return the locker object.
The return value is
|
| int mailbox_get_message (mailbox_t mbox, size_t msgno, message_t *pmessage) | Function |
|
Retrieve message number msgno, pmessage is allocated and
initialized.
The return value is
|
| int mailbox_get_observable (mailbox_t mbox mbox, observable_t*observable) | Function |
|
Get the observable object.
The return value is
|
| int mailbox_get_property (mailbox_t mbox, property_t *property) | Function |
Get the property object.
The return value is 0 on success and a code number on error conditions:
|
| int mailbox_get_size (mailbox_t mbox, off_t *psize) | Function |
|
Gives the mbox size.
The return value is
|
| int mailbox_get_stream (mailbox_t mbox, stream_t *pstream) | Function |
|
The mailbox stream is put in pstream.
The return value is
|
| int mailbox_get_ticket (mailbox_t mbox, ticket_t ticket) | Function |
The return value is 0 on success and a code number on error conditions:
|
| int mailbox_get_url (mailbox_t mbox, url_t *purl) | Function |
|
Gives the constructed url.
The return value is
|
| int mailbox_is_modified (mailbox_t mbox) | Function |
|
Check if the mailbox been modified by an external source.
The return value is
|
| int mailbox_message_unseen (mailbox_t mbox, size_t *pnumber); | Function |
|
Give the number of first unseen message in mbox.
The return value is
|
| int mailbox_messages_count (mailbox_t mbox, size_t *pnumber); | Function |
|
Give the number of messages in mbox.
The return value is
|
| int mailbox_messages_recent (mailbox_t mbox, size_t *pnumber); | Function |
|
Give the number of recent messages in mbox.
The return value is
|
| int mailbox_open (mailbox_t mbox, int flag) | Function |
A connection is open, if no stream was provided, a stream
is created based on the mbox type. The flag can be OR'ed.
See stream_create for flag's description.
The return value is
|
| int mailbox_scan (mailbox_t mbox, size_t msgno, size_t *pcount); | Function |
|
Scan the mailbox for new messages starting at message msgno.
The return value is
|
| int mailbox_set_locker (mailbox_t mbox, locker_t locker) | Function |
|
Set the type of locking done by the mbox.
The return value is
|
| int mailbox_set_stream (mailbox_t mbox, stream_t stream) | Function |
|
Set the stream connection to use for the mailbox.
The return value is
|
| int mailbox_set_ticket (mailbox_t mbox, ticket_t ticket) | Function |
The ticket will be set on the auth_t object on creation.
The return value is
|
| int mailbox_uidnext (mailbox_t mbox, size_t *pnumber); | Function |
|
Give the next predicted uid for mbox.
The return value is
|
| int mailbox_uidvalidity (mailbox_t mbox, size_t *pnumber); | Function |
|
Give the uid validity of mbox.
The return value is
|
/* Prefix mailer_ is reserved */#include <mailutils/mailer.h>
The API is still changing.
| int mailer_create (mailer_t *, const char *) | Function |
| void mailer_destroy (mailer_t *) | Function |
| int mailer_open (mailer_t, int flags) | Function |
| int mailer_close (mailer_t) | Function |
| int mailer_send_message (mailer_t mailer, message_t msg, address_t from, address_t to); | Function |
|
If from is not NULL, it must contain a single fully qualified RFC2822 email address which will be used as the envelope from address. This is the address to which delivery status notifications are sent, so it never matters what it is set to until it REALLY matters. This is equivalent to sendmail's -f flag. The default for from is provided by the specific mailer. If to is not NULL, then the message will be sent to the list of addresses that it specifies. The default for to is to use the contents of the standard "To:", "Cc:", and "Bcc:" fields, this is equivalent to sendmail's -t flag. Note: the previous implementation of mailer_send_message() was equivalent to having both from and to be NULL. |
| int mailer_get_property (mailer_t, property_t *) | Function |
| int mailer_get_stream (mailer_t, stream_t *) | Function |
| int mailer_set_stream (mailer_t, stream_t) | Function |
| int mailer_get_debug (mailer_t, debug_t *) | Function |
| int mailer_set_debug (mailer_t, debug_t) | Function |
| int mailer_get_observable (mailer_t, observable_t *) | Function |
| int mailer_get_url (mailer_t, url_t *) | Function |
Some possible use cases the API must support are:
- original submission
1 - fill in header addresses
2 - mailer_send_message(mailer, msg, NULL, NULL);
- from will be filled in if missing,
- bcc's will be deleted before delivery to a non-bcc address,
- message-id and date will be added, if missing,
- a to: or apparently-to: will be added if non is present (for RFC compliance)
- MTA-style .forward ( and sieve-style redirect )
1 - get the envelope from of the message to be forwarded
2 - mailer_send_message(mailer, msg, from, to)
- MUA-style bounce
1 - add Resent-[to,from,....]
2 - mailer_send_message(mailer, msg, NULL, to)
- DSN "bounce"
1 - compose DSN
2 - mailer_deliver(mailer, msg, address_t( "<>" ), to)
Don't want mail loops, so the null but valid SMTP address of <> is the envelope from.
/sbin/sendmail isn't always sendmail... sometimes its a sendmail-compatible wrapper, so assume /sbin/sendmail understands only a recipient list, -f and -oi, these seem to be pretty basic. Cross fingers.
Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying -f if there was a from, and supplying the recipient list from the to (if there is no recipient list, assume it will read the message contents for the recipients).
Note: since the stdout and stderr of sendmail is closed, we have no way of ever giving feedback on failure. Also, what should the return code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM, which is less than descriptive!
This mailer does NOT canonicalize the message. This must be done before sending the message, or it may be assumed that the MTA will do so.
It does blind out the Bcc: header before sending, though.
Note: mutt always puts the recipient addresses on the command line, even bcc ones, do we strip the bcc before forwarding with SMTP?
An address that has no domain is not and RFC822 email address. What do I do with them? Should the user of the API be responsible for determining what is mean by email to "john" means? Or should the be able to configure sendmail to decide globally what this means. If so, we can pass the address to sendmail, but we have to decide for SMTP! So, right now these addresses are rejected. This could be changed.
#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 |
+-----------------------+
| void message_create (message_t *msg, void *owner) | Function |
| void message_destroy (message_t *msg, void *owner) | Function |
| The resources allocate for msg are freed. |
| int message_get_header (message_t msg, header_t *pheader) | Function |
| Retrieve msg header. |
| int message_set_header (message_t msg, header_t header, void *owner) | Function |
| int message_get_body (message_t msg, body_t *pbody) | Function |
| int message_set_body (message_t msg, body_t body, void *owner) | Function |
| int message_is_multipart (message_t msg, int *pmulti) | Function |
| Set *pmulti to non-zero value if msg is multi-part. |
| int message_get_num_parts (message_t msg, size_t *nparts) | Function |
| int message_get_part (message_t msg, size_t part, message_t *msg) | Function |
| int message_get_stream (message_t msg, stream_t *pstream) | Function |
| int message_set_stream (message_t msg, stream_t stream,void *owner ) | Function |
| int message_get_attribute (message_t msg, attribute_t *pattribute) | Function |
| int message_set_attribute (message_t msg, attribute_t attribute, void *owner) | Function |
| int message_get_envelope (message_t msg, envelope_t *penvelope) | Function |
| int message_set_envelope (message_t msg, envelope_t envelope, void *owner) | Function |
| int message_get_uid (message_t msg, size_t *uid) | Function |
| int message_get_uidl (message_t msg, char *buffer, size_t buflen, size_t *pwriten) | Function |
| int message_set_uidl (message_t msg, int (*_get_uidl)(message_t, char *, size_t, size_t *), void *owner) | Function |
| int message_get_observable (message_t msg, observable_t *observable) | Function |
| int message_create_attachment (const char *content_type, const char *encoding, const char *filename, message_t *newmsg) | Function |
| int message_save_attachment (message_t msg, const char *filename, void **data) | Function |
| int message_encapsulate (message_t msg, message_t *newmsg, void **data) | Function |
| int message_unencapsulate (message_t msg, message_t *newmsg, void **data); | Function |
/* Prefix envelope_ is reserved */#include <mailutils/envelope.h>
| int envelope_date (envelope_t, char *, size_t, size_t *); | Function |
|
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. |
| int envelope_sender (envelope_t, char *, size_t, size_t *); | Function |
|
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. |
| int envelope_get_message (envelope_t, message_t *); | Function |
| int envelope_create (envelope_t *, void *); | Function |
| Primarily for internal use. |
| void envelope_destroy (envelope_t *, void *); | Function |
| Primarily for internal use. |
| int envelope_set_sender (envelope_t, int (*_sender) __P ((envelope_t, char *, size_t, size_t*)), void *); | Function |
|
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. |
| int envelope_set_date (envelope_t, int (*_date) __P ((envelope_t, char *, size_t, size_t *)), void *); | Function |
|
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.
| int header_create (header_t *hdr, const char *blurb, size_t len, void *owner) | Function |
| Initialize a hdr to a supported type. If blurb is not NULL, it is parsed. |
| void header_destroy (header_t *hdr, void *owner) | Function |
| The resources allocated for hdr are freed. |
| int header_set_value (header_t hdr, const char *fn, const char *fv, size_t n, int replace) | Function |
|
Set the field-name fn to field-value fv of size n in
hdr. If replace is non-zero the initial value is replaced, if zero
it is appended.
Some basic macros are already provided for rfc822.
|
| int header_get_value (header_t hdr, const char *fn, char *fv, size_t len, size_t *n) | Function |
| Value of field-name fn is returned in buffer fv of size len. The number of bytes written is put in n. |
| int header_aget_value (header_t hdr, const char *fn, char **fv) | Function |
| The value is allocated. |
| int header_get_stream (header_t hdr, stream_t *pstream) | Function |
| int header_set_size (header_t hdr, size_t *size) | Function |
| int header_set_lines (header_t hdr, size_t *lpines) | Function |
/* Prefix body_ is reserved */#include <mailutils/body.h>
| int body_create (body_t *body, void *owner) | Function |
| Initialize an object bdy. |
| void body_destroy (body_t *pbody) | Function |
| The resources allocate are release. |
| int body_get_stream (body_t body, stream_t *pstream) | Function |
| int body_set_stream (body_t body, stream_t stream, void *owner) | Function |
| int body_get_filename __P ((body_t body, char *buffer, size_tbuflen, size_t *pwriten) | Function |
| int body_set_filename (body_t body, const char*buffer) | Function |
| int body_size (body_t body, size_t*psize) | Function |
| int body_lines (body_t body, size_t *plines) | Function |
/* Prefix attribute_ is reserved */#include <mailutils/attribute.h>
| int attribute_create (attribute_t *pattribute) | Function |
| void attribute_destroy (attribute_t *pattribute) | Function |
| int attribute_is_seen (attribute_t attribute) | Function |
| int attribute_is_answered (attribute_t attribute) | Function |
| int attribute_is_flagged (attribute_t attribute) | Function |
| int attribute_is_deleted (attribute_t attribute) | Function |
| int attribute_is_draft (attribute_t attribute) | Function |
| int attribute_is_recent (attribute_t attribute) | Function |
| int attribute_is_read (attribute_t attribute) | Function |
| int attribute_set_seen (attribute_t attribute) | Function |
| int attribute_set_answered (attribute_t attribute) | Function |
| int attribute_set_flagged (attribute_t attribute) | Function |
| int attribute_set_deleted (attribute_t attribute) | Function |
| int attribute_set_draft (attribute_t attribute) | Function |
| int attribute_set_recent (attribute_t attribute) | Function |
| int attribute_set_read (attribute_t attribute) | Function |
| int attribute_unset_seen (attribute_t attribute) | Function |
| int attribute_unset_answered (attribute_t attribute) | Function |
| int attribute_unset_flagged (attribute_t attribute) | Function |
| int attribute_unset_deleted (attribute_t attribute) | Function |
| int attribute_unset_draft (attribute_t attribute) | Function |
| int attribute_unset_recent (attribute_t attribute) | Function |
| int attribute_unset_read (attribute_t attribute) | Function |
| int attribute_is_equal (attribute_t att1, attribute_t att2) | Function |
| int attribute_copy (attribute_t dst, attribute_t src) | Function |
| int string_to_attribute (const char *buf, attribute_t *pattr) | Function |
| int attribute_to_string (attribute_t attr, char *buf, size_t len, size_t *pwriten) | Function |
#include <mailutils/stream.h>
These generic flags are interpreted as appropriate to the specific streams.
MU_STREAM_READ
MU_STREAM_WRITE
MU_STREAM_RDWR
MU_STREAM_APPEND
MU_STREAM_CREAT
MU_STREAM_NONBLOCK
MU_STREAM_NO_CHECK
MU_STREAM_NO_CLOSE
| int file_stream_create (stream_t *pstream, const char *filename, int flags) | Function |
| int tcp_stream_create (stream_t *pstream, const char *host, int port, int flags) | Function |
| int mapfile_stream_create (stream_t *pstream, const char *filename, int flags) | Function |
| int memory_stream_create (stream_t *pstream, const char *filename, int flags) | Function |
| int encoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding) | Function |
| int decoder_stream_create (stream_t *pstream, stream_t iostream, const char *encoding) | Function |
| int stdio_stream_create (stream_t *pstream, FILE* stdio, int flags) | Function |
| If MU_STREAM_NO_CLOSE is specified, fclose() will not be called on stdio when the stream is closed. |
| void stream_destroy (stream_t *pstream, void *owner) | Function |
| int stream_open (stream_t stream) | Function |
| int stream_close (stream_t stream) | Function |
| int stream_is_seekable (stream_t stream) | Function |
| int stream_get_fd (stream_t stream, int *pfd) | Function |
| int stream_read (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten) | Function |
| int stream_readline (stream_t stream, char *buffer, size_t buflen, off_t offset, size_t *pwriten) | Function |
| int stream_size (stream_t stream, off_t *psize) | Function |
| int stream_truncate (stream_t stream, off_t size) | Function |
| int stream_write (stream_t stream, const char *buffer, size_t buflen, off_t offset, size_t *pwriten) | Function |
| int stream_setbufsiz (stream_t stream, size_t size) | Function |
| int stream_flush (stream_t stream) | Function |
These functions will typically only be useful to implementors of streams.
| int stream_create (stream_t *pstream, int flags, void *owner) | Function |
| Used to implement a new kind of stream. |
| int stream_get_flags (stream_t stream, int *pflags) | Function |
| int stream_get_state (stream_t stream, int *pstate) | Function |
|
An example using tcp_stream_create to make a simple web client:
/* This is an example program to illustrate the use of stream functions.
It connects to a remote HTTP server and prints the contents of its
index page */
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <mailutils/mailutils.h>
const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];
int
main ()
{
int ret, off = 0, fd;
stream_t stream;
size_t nb;
fd_set fds;
ret = tcp_stream_create (&stream, "www.gnu.org", 80, MU_STREAM_NONBLOCK);
if (ret != 0)
{
mu_error ( "tcp_stream_create: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
connect_again:
ret = stream_open (stream);
if (ret != 0)
{
if (ret == EAGAIN)
{
ret = stream_get_fd (stream, &fd);
if (ret != 0)
{
mu_error ( "stream_get_fd: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
FD_ZERO (&fds);
FD_SET (fd, &fds);
select (fd + 1, NULL, &fds, NULL, NULL);
goto connect_again;
}
mu_error ( "stream_open: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
ret = stream_get_fd (stream, &fd);
if (ret != 0)
{
mu_error ( "stream_get_fd: %s\n", mu_errstring (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;
}
mu_error ( "stream_write: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
if (nb != strlen (wbuf))
{
mu_error ( "stream_write: %s\n", "nb != wbuf length");
exit (EXIT_FAILURE);
}
do
{
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);
}
else
{
mu_error ( "stream_read: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
}
write (2, rbuf, nb);
}
while (nb || ret == EAGAIN);
ret = stream_close (stream);
if (ret != 0)
{
mu_error ( "stream_close: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
stream_destroy (&stream, NULL);
exit (EXIT_SUCCESS);
}
/* Prefix iterator_ is reserved */#include <mailutils/iterator.h>
| int iterator_create (iterator_t *) | Function |
| void iterator_destroy (iterator_t *) | Function |
| int iterator_first (iterator_t) | Function |
| int iterator_next (iterator_t) | Function |
| int iterator_current (iterator_t, void **pitem) | Function |
| int iterator_is_done (iterator_t) | Function |
/* 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.
| int auth_create (auth_t *pauth, void *owner) | Function |
| void auth_destroy (auth_t *pauth, void *owner) | Function |
| int auth_prologue (auth_t auth) | Function |
| int auth_authenticate (auth_t auth, char **user, char **passwd) | Function |
| int auth_epilogue (auth_t auth) | Function |
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;
}
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./* Prefix address_ is reserved */#include <mailutils/address.h>
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.
| address_t | Data Type |
The 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.
|
| int address_create (address_t *addr, const char *string) | Function |
|
This function allocates and initializes addr by parsing the
RFC822 address-list string.
The return value is
|
| int address_createv (address_t *addr, const char *sv, size_t len) | Function |
This function allocates and initializes addr by parsing the
array of pointers to RFC822 address-lists in sv. If len is
-1, then sv must be null-terminated in the fashion of argv,
otherwise len is the length of the array.
The return value is
|
| void address_destroy (address_t *addr) | Function |
| The addr is destroyed. |
| int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the noth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry. Note that the entry may be valid, but be a group name. In this case success
is returned, but the length of the address is The return value is
|
| int address_aget_email (address_t *addr, size_t no, char** bufp) | Function |
|
As above, but mallocs the email address, if present, and write a pointer to it into bufp. bufp will be The return value is
|
| int address_get_personal (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the display-name describing the noth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard. A group is a kind of a special case. It has a display-name, followed by an optional mailbox-list. The display-name will be allocated an address all it's own, but all the other elements (local-part, domain, etc.) will be zero-length. So "a group: ;" is valid, will have a count of 1, but address_get_email(), and all the rest, will return zero-length output. The return value is
|
| int address_get_comments (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the comments extracted while parsing the noth email address. These comments have no defined meaning, and are not currently collected. The return value is
|
| int address_get_email (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the email addr-spec extracted while
parsing the noth email address. This will be The return value is
|
| int address_get_local_part (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the local-part of an email addr-spec extracted while parsing the noth email address. The return value is
|
| int address_get_domain (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the domain of an email addr-spec extracted while
parsing the noth email address. This will be The return value is
|
| int address_get_route (address_t *addr, size_t no, char* buf, size_t len, size_t* n) | Function |
|
Accesses the route of an email addr-spec extracted while parsing the noth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at <mailutils/parse822.h>. The return value is
|
| int address_is_group (address_t *addr, size_t no, size_t len, int* yes) | Function |
|
Sets *yes to yes can be Currently, there is no way to determine the end of the group. The return value is
|
| int address_to_string (address_t *addr, char* buf, size_t len, size_t* n) | Function |
|
Returns the entire address list as a single RFC822 formatted address list. The return value is
|
| int address_get_count (address_t addr, size_t* count) | Function |
|
Returns a count of the addresses in the address list. If addr is The return value is |
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <mailutils/address.h>
#include <mailutils/errno.h>
#include <mailutils/mutil.h>
#define EPARSE ENOENT
static int
parse (const char *str)
{
size_t no = 0;
size_t pcount = 0;
int status;
char buf[BUFSIZ];
address_t address = NULL;
mu_set_user_email_domain ("localhost");
status = address_create (&address, str);
address_get_count (address, &pcount);
if (status)
{
printf ("%s=> error %s\n\n", str, mu_errname (status));
return 0;
}
else
{
printf ("%s=> pcount %lu\n", str, (unsigned long) pcount);
}
for (no = 1; no <= pcount; no++)
{
size_t got = 0;
int isgroup;
address_is_group (address, no, &isgroup);
printf ("%lu ", (unsigned long) 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>
| int locker_create (locker_t * plocker, char *filename, size_t len, int flags) | Function |
| void locker_destroy (locker_t * plocker) | Function |
| int locker_lock (locker_t locker, int flag) | Function |
|
| int locker_touchlock (locker_t locker) | Function |
| int locker_unlock (locker_t locker) | Function |
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>]> or <pop://[<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.org> <pop://asterix;AUTH=*@france.com> <pop://falbala;AUTH=+APOP@france.com> <pop://obelix;AUTH=+APOP@village.gaulois.org:2000> <pop://obelix:menhir@village.gaulois.org:2000>
For more complete information see rfc2368.
The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism. The general form is
<imap://[<user>[;AUTH=<type>]]@<host>[:port][/<mailbox>]> or <imap://[<user>[:<passwd>]]@<host>[:port][/<mailbox>]>
If :port is omitted the default value is 220. 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.
<imap://obelix@imap.gaulois.org> <imap://asterix;AUTH=*@imap.france.com> <imap://asterix:potion@imap.france.com>
For more complete information see rfc2192.
Local folder should be handle by this URL. It is preferable to let
the mailbox recognize the type of mailbox and take the appropriate
action.
<file://path> <file://var/mail/user> <file://home/obelix/Mail>
For MMDF, MH local mailboxes URLs are provided, but it is preferable to
use <file://path> and let the library figure out which one.
<mmdf://path> <mh://path>
After setting a mailer, <mailto:> is used to tell the mailer where
and to whom the message is for.
<mailto://hostname>
Mailto can be used to generate short messages, for example to subscribe
to mailing lists.
<mailto://bug-mailutils@gnu.org?body=subscribe> <mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe>
For more complete information see rfc2368.
Helper functions are provided to retrieve and set the URL fields.
| int url_create (url_t *url, const char *name) | Function |
| Create and the url data structure, but do not parse it. |
| void url_destroy (url_t *) | Function |
| Destroy the url and free it's resources. |
| int url_parse (url_t url) | Function |
|
Parses the url, after calling this the get functions can be called.
The syntax, condensed from RFC 1738, and extended with the ;auth=
of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:
url =
scheme ":" [ "//"
[ user [ ( ":" password ) | ( ";auth=" auth ) ] "¨]
host [ ":" port ]
[ ( "/" urlpath ) | ( "?" query ) ] ]
This is a generalized URL syntax, and may not be exactly appropriate for any particular scheme. |
| const char* url_to_string (const url_t url) | Function |
| int url_get_scheme (const url_t url, char *schem, size_t len, size_t *n) | Function |
| int url_get_user (const url_t url, char *usr, size_t len, size_t *n) | Function |
| int url_get_passwd (const url_t url, char *passwd, size_t len, size_t *n) | Function |
| int url_get_host (const url_t url, char *host, size_t len, size_t *n) | Function |
| int url_get_port (const url_t url, long *port) | Function |
| int url_get_path (const url_t url, char *path, size_t len, size_t *n) | Function |
| int url_get_query (const url_t url, char *query, size_tlen, size_t *n) | Function |
| char* url_decode (const char* string) | Function |
| Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup(). |
#include <stdio.h>
#include <string.h>
#include <mailutils/errno.h>
#include <mailutils/url.h>
int
main ()
{
char str[1024];
char buffer[1024];
long port = 0;
int len = sizeof (buffer);
url_t u = NULL;
while (fgets (str, sizeof (str), stdin) != NULL)
{
int rc;
str[strlen (str) - 1] = '\0'; /* chop newline */
if (strspn (str, " \t") == strlen (str))
continue; /* skip empty lines */
if ((rc = url_create (&u, str)) != 0)
{
fprintf (stderr, "url_create %s ERROR: [%d] %s",
str, rc, mu_errstring (rc));
exit (1);
}
if ((rc = url_parse (u)) != 0)
{
printf ("%s => FAILED: [%d] %s\n",
str, rc, mu_errstring (rc));
continue;
}
printf ("%s => SUCCESS\n", str);
url_get_scheme (u, buffer, len, NULL);
printf ("\tscheme <%s>\n", buffer);
url_get_user (u, buffer, len, NULL);
printf ("\tuser <%s>\n", buffer);
url_get_passwd (u, buffer, len, NULL);
printf ("\tpasswd <%s>\n", buffer);
url_get_auth (u, buffer, len, NULL);
printf ("\tauth <%s>\n", buffer);
url_get_host (u, buffer, len, NULL);
printf ("\thost <%s>\n", buffer);
url_get_port (u, &port);
printf ("\tport %ld\n", port);
url_get_path (u, buffer, len, NULL);
printf ("\tpath <%s>\n", buffer);
url_get_query (u, buffer, len, NULL);
printf ("\tquery <%s>\n", buffer);
url_destroy (&u);
}
return 0;
}
/* Prefix parse822_ is reserved */#include <mailutils/parse822.h>
Internet Message Format, see Address node for the discussion.
| int parse822_address_list (address_t* a, const char* s) | Function |
| int parse822_mail_box (const char** p, const char* e, address_t* a) | Function |
| int parse822_group (const char** p, const char* e, address_t* a) | Function |
| int parse822_address (const char** p, const char* e, address_t* a) | Function |
| int parse822_route_addr (const char** p, const char* e, address_t* a) | Function |
| int parse822_route (const char** p, const char* e, char** route) | Function |
| int parse822_addr_spec (const char** p, const char* e, address_t* a) | Function |
| int parse822_unix_mbox (const char** p, const char* e, address_t* a) | Function |
| int parse822_local_part (const char** p, const char* e, char** local_part) | Function |
| int parse822_domain (const char** p, const char* e, char** domain) | Function |
| int parse822_sub_domain (const char** p, const char* e, char** sub_domain) | Function |
| int parse822_domain_ref (const char** p, const char* e, char** domain_ref) | Function |
| int parse822_domain_literal (const char** p, const char* e, char** domain_literal) | Function |
| int parse822_quote_string (char** quoted, const char* raw) | Function |
| int parse822_quote_local_part (char** quoted, const char* raw) | Function |
| int parse822_field_body (const char** p, const char *e, char** fieldbody) | Function |
| int parse822_field_name (const char** p, const char *e, char** fieldname) | Function |
The functions from libmailbox library get user information from
the system user database. The library libmuauth extends this
functionality, allowing libmailbox functions to obtain
information about a user from several places, like SQL database,
etc. The method used is described in detail in authentication.
This chapter contains a very succinct description of the underlying
library mechanism.
| mu_auth_fp | Data Type |
|
This is a pointer to authentication or authorization data. It
is defined as follows:
typedef int (*mu_auth_fp) (void *return_data,
void *key,
void *func_data,
void *call_data);
Its arguments are:
|
| mu_auth_data | Data Type |
|
The struct mu_auth_data {
/* These are from struct passwd */
char *name; /* user name */
char *passwd; /* user password */
uid_t uid; /* user id */
gid_t gid; /* group id */
char *gecos; /* real name */
char *dir; /* home directory */
char *shell; /* shell program */
/* */
char *mailbox; /* Path to the user's system mailbox */
int change_uid; /* Should the uid be changed? */
};
|
| mu_auth_module | Data Type |
|
The struct mu_auth_module {
char *name; /* Module name */
struct argp *argp; /* Corresponding argp structure */
mu_auth_fp authenticate; /* Authentication function ... */
void *authenticate_data; /* ... and its specific data */
mu_auth_fp auth_by_name; /* Get user info by user name */
void *auth_by_name_data; /* ... and its specific data */
mu_auth_fp auth_by_uid; /* Get user info by user id */
void *auth_by_uid_data; /* ... and its specific data */
};
|
| void mu_auth_init (void) | Function |
|
This function registers the command line capability "auth". It must be
called after registering |
| void MU_AUTH_REGISTER_ALL_MODULES (void) | Function |
|
This macro registers all default modules and calls |
| int mu_auth_data_alloc (struct mu_auth_data **ptr, const char *name, const char *passwd, uid_t uid, gid_t gid, const char *gecos, const char *dir, const char *shell, const char *mailbox, int change_uid) | Function |
|
Create a |
| void mu_auth_data_free (struct mu_auth_data *ptr) | Function |
|
Free the |
| void mu_auth_register_module (struct mu_auth_module *mod) | Function |
|
Register the module defined by the mod argument. |
| int mu_auth_runlist (list_t flist, void *return_data, void *key, void *call_data); | Function |
|
The list is expected to contain The function returns 0 if none of the functions from |
| struct mu_auth_data * mu_get_auth_by_name (const char *username) | Function |
|
Search the information about given user by its username. Similar to
system's |
| struct mu_auth_data * mu_get_auth_by_uid (uid_t uid) | Function |
Search the information about given user by its uid. Similar to
system's getpwuid call).
|
| int mu_authenticate (struct mu_auth_data *auth_data, char *pass) | Function |
|
Authenticate the user whose data are in auth_data using password pass. Return 0 if the user is authenticated. |
| int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data); | Function |
|
The "not-supported" module. Always returns |
| mu_auth_system_module | Variable |
|
This module is always registered even if |
| mu_auth_generic_module | Variable |
|
This module is always registered even if |
| mu_auth_pam_module | Variable |
|
Implements PAM authentication. Both authorization handlers are
|
| mu_auth_sql_module | Variable |
|
Implements authentication and authorization via MySQL database. The
credentials for accessing the database are taken from global variables
|
| mu_auth_virtual_module | Variable |
|
Implements |
To link your program against libmuauth, obtain loader arguments
by running mailutils-config as follows:
mailutils-config --link auth
See mailutils-config, for more information about this utility.
Here is a sample Makefile fragment:
MU_LDFLAGS=`mailutils-config --link auth`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
If your program will be using only default modules provided by the
library, then it will suffice to call
MU_AUTH_REGISTER_ALL_MODULES() somewhere near the start of
your program. As an example, consider the following code fragment
(it is taken from the imap4d daemon):
int
main (int argc, char **argv)
{
struct group *gr;
int status = EXIT_SUCCESS;
state = STATE_NONAUTH; /* Starting state in non-auth. */
MU_AUTH_REGISTER_ALL_MODULES ();
mu_argp_parse (&argp, &argc, &argv, 0, imap4d_capa,
NULL, &daemon_param);
...
Otherwise, if your program will use it's own modules, first register
them with mu_auth_register_module and then call
mu_auth_init(), e.g.:
struct mu_auth_module radius_module = {
...
};
struct mu_auth_module ext_module = {
...
};
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
mu_auth_init ();
...
These two approaches may be combined, allowing you to use both your
modules and the ones provided by Mailutils. Consider the example below:
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
MU_AUTH_REGISTER_ALL_MODULES ();
...
}
The library libmu_scm provides an interface between Mailutils
and Guile, allowing to access the Mailutils functionality from a
Scheme program. For more information about Guile, refer to
Overview. For information
about Scheme programming language, See Top.
Functions Provided by libmu_scm
Using libmu_scm
| mu-address-get-personal ADDRESS NUM | Scheme Function |
| Return personal part of an email address. |
| mu-address-get-comments ADDRESS NUM | Scheme Function |
| mu-address-get-email ADDRESS NUM | Scheme Function |
| Return email part of an email address. |
| mu-address-get-domain ADDRESS NUM | Scheme Function |
| Return domain part of an email address |
| mu-address-get-local ADDRESS NUM | Scheme Function |
| Return local part of an email address. |
| mu-address-get-count ADDRESS | Scheme Function |
| Return number of parts in email address. |
| mu-mailbox-open URL MODE | Scheme Function |
| Opens a mailbox specified by URL. |
| mu-mailbox-close MBOX | Scheme Function |
| Closes mailbox MBOX |
| mu-mailbox-get-url MBOX | Scheme Function |
| Returns the URL of the mailbox. |
| mu-mailbox-get-port MBOX MODE | Scheme Function |
Returns a port associated with the contents of the MBOX.
MODE is a string defining operation mode of the stream. It may
contain any of the two characters: r for reading, w for
writing.
|
| mu-mailbox-get-message MBOX MSGNO | Scheme Function |
| Retrieve from MBOX message # MSGNO. |
| mu-mailbox-messages-count MBOX | Scheme Function |
| Returns number of messages in the mailbox. |
| mu-mailbox-expunge MBOX | Scheme Function |
| Expunges deleted messages from the mailbox. |