Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit ffe2be32 ffe2be3286b3ecc63c8da3f7f9f1febda0b46f7d by Alain Magloire
Options

Modified Files: 

 	body.texi headers.texi mailbox.texi mailer.texi mailutils.texi
 	message.texi sfrom.c.texi url.texi
updating.
1 parent a56b4522
Inline Side-by-side
Showing 8 changed files with 251 additions and 107 deletions
......@@ -3,20 +3,49 @@ optionnaly another @code{body_t} part.
@section Init/Destroy
@deftypefun int body_init (body_t *@var{msg}, const mailbox_t @var{mbx})
Private.
@deftypefun int body_init (body_t *@var{bdy})
Initialize an object @var{bdy}.
@end deftypefun
@deftypefun void body_destroy (body_t *@var{msg})
The ressources allocate for clone @var{msg} are freed.
@deftypefun void body_destroy (body_t *@var{bdy})
The ressources allocate are @var{bdy} freed.
@end deftypefun
@deftypefun int body_get_header (body_t @var{msg}, header_t *@var{hdr})
@section Attributes
The body can cary header attributes if it is a mime. They also come
with the matching "set".
@deftypefun int body_get_header (body_t @var{bdy}, header_t *@var{hdr})
@end deftypefun
@deftypefun int body_get_content_type (body_t @var{bdy}, char *@var{type}, size_t @var{len})
@end deftypefun
@deftypefun int body_get_content_description (body_t @var{bdy}, char *@var{type}, size_t @var{len})
@end deftypefun
@deftypefun int body_get_content_encoding (body_t @var{bdy}, char *@var{type}, size_t @var{len})
@end deftypefun
@section Attachements
@deftypefun int body_get_content (body_t @var{msg}, char *buffer, size_t len, size_t *n)
@deftypefun int body_set_filename (body_t @var{bdy}, char *file)
Associate the body with a @var{file}.
@end deftypefun
@deftypefun int body_set_FILE (body_t @var{bdy}, FILE *fp)
Associate the body with a FILE *@var{fp}.
@end deftypefun
@deftypefun int body_get_type (body_t @var{msg}, char *buffer, size_t len, size_t *n)
@deftypefun int body_get_content (body_t @var{bdy}, off_t @var{offset}, char *buffer, size_t len, size_t *n)
@end deftypefun
@section Sub parts
A body may contain another body
@deftypefun int body_is_multipart (body_t @var{bdy})
Return non-zero value if body has a second part.
@end deftypefun
@deftypefun int body_get_body (body_t @var{bdy}, body_t *@var{sub})
Return the sub part in @var{bdy}.
@end deftypefun
@deftypefun int body_set_body (body_t @var{bdy}, body_t *@var{sub})
Set a sub part for @var{bdy}.
@end deftypefun
......
......@@ -57,7 +57,7 @@ Some basic macros is already provided for rfc822.
@defmac MU_HDR_RESENT_SENDER
"Resent-SENDER"
@end defmac
@defmac MU_HDR_TOs
@defmac MU_HDR_TO
"To"
@end defmac
@defmac MU_HDR_RESENT_TO
......
......@@ -12,8 +12,8 @@ Initializing and destroying a mailbox_t object.
@deftypefun int mailbox_init (mailbox_t *@var{mbx}, const char * @var{url}, int @var{id})
Based on the type of the @var{url}, @var{mbx} is initialize to a known type,
if @var{id} is not zero, it represents the id of the mailbox. The @var{id}
will be use instead of doing heuristic search on the @var{url}.
if @var{id} is not zero, it represents the id of the mailbox, it will be use
instead of doing heuristic search on the @var{url}.
@example
#include <mailutils.h>
@dots{}
......@@ -26,9 +26,9 @@ mailbox_init (&mbox, "file:///home/bar/.hiddenmail/bar", 0);
@end deftypefun
@deftypefun int mailbox_init_default (mailbox_t *@var{mbx}, const char * @var{user})
Initialize the default mailbox of the system as set by the mail adminstrator.
Initialize the default mailbox of the system as set by the mail administrator.
It could be hardcoded or override by a configuration
@file{$sysconfig/mailutils.conf}.
@file{$@{sysconfig@}/mailutils.conf}.
@example
#include <mailutils.h>
@dots{}
......@@ -138,7 +138,7 @@ main ()
sleep (NAP);
/* It is a good habit to close the resources.
A mailbox could be a remote host and the locking
A mailbox could be on a remote host and the locking
may interfere with normal delivery, for example with
POP, the lock is hold during the entire session.
*/
......@@ -150,8 +150,8 @@ main ()
@end example
@section Deletion
Messages can be marked for deletion but the action of removing them is only
taken when @code{mailbox_expunge} is called.
Messages can be marked for deletion but destructive action is only taken
when @code{mailbox_expunge} is called.
@deftypefun int mailbox_delete (mailbox_t @var{mbx}, size_t @var{msgno})
Mark message @var{msgno} for deletion.
......@@ -162,7 +162,7 @@ UnMark message @var{msgno} for deletion.
@end deftypefun
@deftypefun int mailbox_is_deleted (mailbox_t @var{mbx}, size_t @var{msgno})
Return 1 if message @var{msgno} is mark deleted.
Return non-zero if message @var{msgno} is mark deleted.
@end deftypefun
@deftypefun int mailbox_num_deleted (mailbox_t @var{mbx})
......@@ -171,13 +171,13 @@ Return the number of Mailbox marked to be delete.
@deftypefun int mailbox_expunge (mailbox_t @var{mbx})
All messages marked for deletion will be removed and the mailbox updated,
and notification functions executed.
and notification functions of all messages for @var{mbx} executed.
@end deftypefun
@section Message
Messages are object that hold the offsets of the message in the mailbox.
Certain mailboxes allow new messages to be appended the existing folder,
int this case the stream must be @code{mailbox_open} with the proper
@code{message_t} are objects that hold the offsets of the message in the
mailbox. Certain mailboxes allow new messages to be appended to the existing
folder, in this case the stream must be @code{mailbox_open} with the proper
permission.
@deftypefun int mailbox_new_message (mailbox_t @var{mbx}, message_t *@var{msg})
......@@ -193,7 +193,8 @@ If @var{destroy} is set non-zero @code{message_destroy} will be call after deliv
@deftypefun int mailbox_get_message (mailbox_t @var{mbx}, size_t @var{msgno}, message_t *@var{msg})
@var{msg} is initialize, be warn when doing @code{mailbox_expunge} the
offsets to the mailbox are losts and accessing the @var{msg} is undefined.
To prevent this, it is possible to @code{message_clone} or set a notification.
To prevent this, it is possible to @code{message_clone} or set a notification
to take appropriate action.
@end deftypefun
@deftypefun int mailbox_destroy_message (mailbox_t @var{mbx}, message_t @var{msg})
......@@ -215,25 +216,25 @@ Low level Reading funtions for contents and headers.
@comment @var{body} will be append, otherwise it will overwrite any existing one.
@comment @end deftypefun
@deftypefun int mailbox_get_content (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
@deftypefun int mailbox_get_content (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
Read the body of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned in
@var{nread}.
@end deftypefun
@deftypefun int mailbox_get_mcontent (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
@deftypefun int mailbox_get_mcontent (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{nread})
A buffer is allocated with @code{malloc(3)} return memory containing the body
of message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
@end deftypefun
@deftypefun int mailbox_get_header (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
@deftypefun int mailbox_get_header (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{nread})
Read the header of message @var{msgno} starting at offset @var{off} in
@var{buffer} of size @var{len}. The number of bytes read is returned
in @var{nread}.
@end deftypefun
@deftypefun int mailbox_get_mheader (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
@deftypefun int mailbox_get_mheader (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{nread})
A buffer allocate with @code{malloc(3)} is return containing the header of
message @var{msgno} starting at offset @var{off} in @var{buffer}.
The number of bytes read is returned in @var{nread}.
......@@ -251,7 +252,6 @@ locking to provide synchronisation to the mailbox_t object.
Grab the lock. In some cases, i.e Unix mbox this may involve creating
a .lock file in the spool directory.
@comment Say something about permission the program be gid on some OS.
@defmac MU_MB_RDLOCK
Read lock.
@end defmac
......@@ -261,7 +261,6 @@ Write lock.
@defmac MU_MB_RWLOCK
Read/Write lock.
@end defmac
@end deftypefun
Note on many mailboxes, RDLOCK is a noop.
......@@ -349,7 +348,8 @@ Note that all locks are held, and @var{notification} should be very small and
simple, it should not access or do any action on the mailbox doing this may
cause undefined behaviour.
@end deftypefun
@deftypefun int mailbox_set_msg_destroy_cb (mailbox_t @var{mbx}, int (*@var{notification}) (mailbox_t @var{mbx}, message_t @var{msg}, void *@var{arg}))
@end deftypefun
@section Registration and Type
......@@ -369,8 +369,8 @@ or add you own to the list.
@end deftp
@deftypefun int mailbox_list_type (struct mailbox_type *@var{mtype}, size_t @var{len}, size_t *@var{n})
The @var{mtype} array will be initialize with the list of builtin up to
@var{len}. The number of struct maiblox_type is put in @var{n}.
The @var{mtype} array will be initialize with the list of builtins up to
@var{len}. The number of struct mailbox_type is put in @var{n}.
@end deftypefun
@deftypefun int mailbox_list_mtype (struct mailbox_type **@var{mtype}, size_t *@var{n})
......@@ -386,7 +386,7 @@ Remove a mailbox @var{mtype} to the list of builtin.
@end deftypefun
@deftypefun int mailbox_get_type (struct mailbox_type **@var{mtype}, int @var{urlid})
Base on the URL @var{urlid} return the mailbox_type.
Base on the @var{urlid} return the mailbox_type.
@end deftypefun
@deftypefun int mailbox_get_name_type (mailbox_t @var{mbx}, int *@var{mbxid}, char *@var{name}, size_t @var{len}, size_t *@var{n})
......@@ -423,7 +423,7 @@ struct mailbox_type mbx_ftp =
@{
"FTP MBOX", /* name type */
(int)&mbx_ftp, /* need a uniq id */
&url_unix_type, /* url id */
&url_ftp, /* url id */
mailbox_unix_init, /* constructor */
mailbox_unix_destroy /* destructor */
@};
......
Mail Delivery is done here. Nothing is implemented and the API is still shaky.
The API is still shaky.
@section Init/Destroy
......@@ -26,28 +26,13 @@ Use MPP protocol.
Not Implemented.
@end deftypefun
@section User/Passwd
On some mailer like MMP you need to identify.
@deftypefun int mailer_user (mailer_t @var{mailer}, const char *@var{user})
Not Implemented.
@end deftypefun
@deftypefun int mailer_passwd (mailer_t @var{mailer}, const char *@var{passwd})
Not Implemented.
@end deftypefun
@section Open/Close
The mailer is spawn, if it is a program, or the host is contacted.
@deftypefun int mailer_open (mailer_t @var{mailer}, int @var{flag})
Not Implemented.
On mailer program, it is a @code{stat(2)} or ping a server for smtp.
@end deftypefun
@deftypefun int mailer_close (mailer_t @var{mailer})
Not Implemented.
Noop on most mailers.
@end deftypefun
@section Sending
......@@ -58,34 +43,20 @@ Sending a message.
Not Implemented.
@end deftypefun
@deftypefun int mailer_set_content (mailer_t @var{mailer}, char *, size_t)
Not Implemented.
@deftypefun int mailer_send (mailer_t @var{mailer}, message_t @var{msg}, int destroy)
@var{msg} is delivered
@end deftypefun
@deftypefun int mailer_set_header (mailer_t @var{mailer}, char *, size_t)
Not Implemented.
@end deftypefun
@deftypefun int mailbox_add_attachment (mailer_t, size_t msgno, const char *boundary, const char *header, FILE *file, int encoding)
@end deftypefun
@deftypefun int mailer_send_message (mailer_t @var{mailer}, size_t)
Not Implemented.
@end deftypefun
@section Timeout
@deftypefun int mailer_set_timeout (mailer_t @var{mailer}, size_t)
Not Implemented.
@end deftypefun
@deftypefun int mailer_get_timeout (mailer_t @var{mailer}, size_t)
Not Implemented.
@section Notification
@deftypefun int mailer_set_delivery_cb (mailer_t @var{mailer}, message_t @var{msg}, int *@var{notification}(mailer_t @var{mailer}, int @var{status}, size_t @var{msgno}, void *@var{arg})
On delivery @code{notification (mailer, status, msgno, arg)} is
executed.
@end deftypefun
@section SMTP
@cindex SMTP
TODO: todo
TODO: describe protocol, url, mailto url etc ..
@section UUCP
@cindex UUCP
......
......@@ -142,10 +142,10 @@ a rich set of functions for accessing different mailbox formats and mailers.
| | user |
message_t | | passwd |
+--------------+<------+ header_t +----------+
| header_t *-|-----------------------+->+-----------------+
+--------------+ body_t | | name/value[0] |
| header_t *-|-----------------------+-->+---------------+
+--------------+ body_t | | name/val[0] |
| body_t[0] *-|----->+-------------+ | | ... |
| body_t[1] | | header_t *-|--+ +-----------------+
| body_t[1] | | header_t *-|--+ +---------------+
| ... | +-------------+
+--------------+ | content |
| next_body |
......
The @code{message_t} is a convenient way to manipulate messages. It
The @code{message_t} object is a convenient way to manipulate messages. It
encapsulates the @code{header_t} attribute and the @code{body_t}.
This type, unless you ask explicitly with @code{message_clone}, only contains
references on how to retrieve the information from the mailbox.
@example
@group
+------------------+
| message_t |
+------------------+
| header_t | +----------------+
| body_t[] *-----|------------+| body_t |----* .....
| type | +----------------+
| body_count | | header_t |
+------------------+ | content |
| type |
| next body *---|----//--
+----------------+
message_t
+----------+ +------>+-----------------------+
|3 | | | header_t |
+----------+ | | |-----------------------|
|2 *-|-|---+ | body_t [0] |
+----------+ | | | body_t [1] |
|1 | | | | ... |
+----------+ | |-+ | ... |
| 0 | | | | ... |
| | | | | |
| | |-+ | |
| |-+ | |
| | | |
+----------+ +-----------------------+
@end group
@end example
@section Init/Destroy
The common way to obtain a @code{message_t} is by requesting
@code{mailbox_get_message}, or @code{mailbox_create_message} from
a specific type of mailbox, they are not explicitely created.
@code{mailbox_get_message}, or @code{mailbox_new_message} from
a specific type of mailbox, they are not explicitly created.
@example
#include <mailutils.h>
#include <stdio.h>
#include <string.h>
mailbox_t mbx;
message_t msg, clone;
mailbox_init_default (&mbx, NULL);
mailbox_open (mbx, MU_MB_RDONLY);
@dots{}
mailbox_get_message (mbx, msg_no, &msg);
/* before closing I need to make sure
that I have a copy not a reference of the message */
message_clone (msg, &clone);
/* safe to close/expunge, I got a copy */
mailbox_close (mbx);
/* ... */
message_size (clone, &size);
static int
ack (mailer, int status, message_t msg, void *arg)
@{
if (status == 0)
printf ("Ok message sent\n");
else
printf ("Error failed to deliver\n");
return 0;
@}
#define CONTENT "A GNU Generation\n"
int main ()
@{
mailer_t mailer;
message_t msg;
body_t bd;
mailer_init_default (&mailer, NULL);
mailer_new_message (&msg);
message_set_to (msg, "bug-mailutils@@gnu.org", 0);
message_set_subject (msg, "What is our generation ?", 0);
message_set_body (msg, CONTENT, strlen (CONTENT), 0);
mailer_set_delivery_cb (mailer, msg, ack, NULL);
mailer_send (mailer, msg, 1/* destroy */);
return 0;
@}
@end example
@deftypefun void message_destroy (message_t *@var{msg})
The ressources allocate for clone @var{msg} are freed.
The resources allocated when cloning @var{msg} are freed.
@end deftypefun
@section Header attributes
The @code{message_t} type provides some functions to set/retrieve some well
know header attributes.
@deftypefun int message_get_header (message_t @var{msg}, header_t *@var{hdr})
Copy the @var{msg} header in @var{hdr}.
@end deftypefun
@deftypefun int message_set_header (message_t @var{msg}, header_t @var{hdr})
Make a copy of @var{hdr} and set the @var{msg}, any previous header is freed.
@end deftypefun
The @code{message_t} provides some methosd to retrieve some well know headers.
@deftypefun int message_get_from (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@end deftypefun
@deftypefun int message_set_from (message_t @var{msg}, char *buffer, size_t len)
@end deftypefun
@deftypefun int message_get_to (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@end deftypefun
@deftypefun int message_set_to (message_t @var{msg}, char *buffer, size_t len)
@end deftypefun
@deftypefun int message_get_date (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@deftypefun int message_get_subject (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@end deftypefun
@deftypefun int message_set_subject (message_t @var{msg}, char *buffer, size_t len)
@end deftypefun
@deftypefun int message_get_cc (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@end deftypefun
@deftypefun int message_set_cc (message_t @var{msg}, char *buffer, size_t len)
@end deftypefun
@deftypefun int message_get_bcc (message_t @var{msg}, char *buffer, size_t len, size_t *n)
@end deftypefun
@deftypefun int message_set_bcc (message_t @var{msg}, char *buffer, size_t len)
@end deftypefun
@deftypefun int message_is_mime (message_t @var{msg})
Return non-zero value if message is multi-part.
@end deftypefun
@deftypefun int message_set_mime (message_t @var{msg})
By default mime is use for more then one body, but it can be set
explicitly to mime.
@end deftypefun
@section Content
@deftypefun int message_get_body (message_t @var{msg}, int @var{num}, body_t *@var{body})
Copy body number @var{num} of @var{msg} to @var{body}.
@end deftypefun
@deftypefun int message_set_body (message_t @var{msg}, int *@var{num}, body_t @var{body})
Copy @var{body} to @var{msg}, @var{num} is set.
@end deftypefun
@deftypefun int message_set_content (message_t @var{msg}, char *@var{content}, size_t @var{len})
Add @var{content} to the first body.
@end deftypefun
@section Miscellany
@deftypefun int message_is_delete (message_t @var{msg})
Return non-zero value if mark for deletion.
@end deftypefun
@deftypefun int message_get_mailbox (message_t @var{msg}, mailbox_t *mbx)
If @var{msg} is associated with a mailbox, set @var{mbx} and return
zero, otherwise @var{mbx} is unmodified and non-zero value is return.
@end deftypefun
@deftypefun int message_get_mailer (message_t @var{msg}, mailer_t *ml)
If @var{msg} is associated with a mailer, set @var{mbx} and return
zero, otherwise @var{ml} is unmodified and non-zero value is return.
@end deftypefun
@deftypefun int message_get_mid (message_t @var{msg}, char **mid)
Set @var{mid} to the message ID.
@end deftypefun
@deftypefun int message_get_msg_number (message_t @var{msg}, size_t *number)
Set @var{number} to the @var{msg} in the mailbox.
@end deftypefun
@deftypefun int message_get_body_count (message_t @var{msg}, size_t *number)
Put the body count in @var{number}.
@end deftypefun
......
/* sfrom, Simple From */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <mailutils.h>
......@@ -35,7 +36,7 @@ int main (int argc, char **argv)
for (msgno = 0; msgno < msg_total; msgno++)
@{
if (mailbox_get_header (mbox, msgno, buffer,
if (mailbox_get_header (mbox, msgno, 0, buffer,
sizeof (buffer), &size) != 0)
@{
fprintf (stderr, "header corrupted\n");
......
......@@ -91,7 +91,7 @@ Initialize and parse the @var{url}
@end example
@end deftp
@section Helper functions
@section URL registration
@deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, size_t *@var{n})
@end deftypefun
......@@ -108,6 +108,57 @@ Initialize and parse the @var{url}
@deftypefun int url_get_id (const url_t @var{url}, int *@var{id})
@end deftypefun
@section Helper functions
@example
#include <url.h>
#include <stdio.h>
#include <string.h>
int main ()
@{
char str[1024];
char buffer[1024];
long port = -1;
url_t u;
while (fgets (str, sizeof (str), stdin) != NULL)
@{
str[strlen (str) - 1] = '\0'; /* chop newline */
if (url_init (&u, str) != 0)
@{
printf ("%s --> FAILED\n", str);
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_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;
@}
@end example
@deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n})
@end deftypefun
......@@ -146,4 +197,3 @@ Initialize and parse the @var{url}
@deftypefun int url_get_mquery (const url_t @var{url}, char **@var{buf}, size_t *@var{len})
@end deftypefun
......