encoding.texi headers.texi mailbox.texi mailer.texi mime.texi

 	sfrom.c.texi url.texi

new files describing each facette of mailutils.

+@subsection RFC1522
+@cindex RFC1522
+
+@subsection Quoted Printable
+@cindex Quoted Printable
+
+@subsection Base64
+@cindex Base64
+

+So far we plan support for RFC822 and RFC1522;
+
+@deftypefun int header_init (header_t *@var{hdr}, const char *@var{blurb}, size_t @var{len}, int @var{flag})
+Initialize a @var{hdr} to a supported type.  If @var{blurb} is not NULL, it is
+parsed. @var{Flag} can be set to RFC8222 or RFC1522 so far onlyr rfc822  is
+supported.
+@end deftypefun
+@deftypefun void header_destroy (header_t *@var{hdr})
+The ressources allocate for @var{hdr} or freed.
+@end deftypefun
+
+@deftypefun int header_set_value (header_t @var{hdr}, const char *@var{fn}, const char *@var{fv}, size_t n, int @var{replace})
+Set the field-name @var{fn} to field-value @var{fv} of size @var{n} in
+@var{hdr}.  If @var{replace} is non-zero the initial value is replace, if zero
+it is append.
+@end deftypefun
+
+@deftypefun int header_get_value (header_t @var{hdr}, const char *fn, char *fv, size_t len, size_t *n)
+Value of field-name @var{fn} is return in buffer @var{fv} of size @var{len}.
+The number of bytes written is put in @var{n}.
+@end deftypefun
+
+@deftypefun int header_get_mvalue (header_t @var{hdr}, const char *fn, char **fv, size_t *n)
+Value of field-name @var{fn} is return in allocated buffer @var{fn} from
+@code{malloc(3)}. The number of bytes written is put in @var{n}.
+@end deftypefun
+
+@deftypefun int header_gvalue (const char *@var{blurb}, size_t @var{bl}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n})
+Field-name @var{fn} is extract form @var{blurb} of size @var{bl} and put in
+buffer @var{fv} of size @var{len}.
+The number of bytes written is put in @var{n}.
+@end deftypefun
+
+@deftypefun int header_gmvalue (const char *@var{blurb}, size_t @var{bl}, const char *@var{fn}, char **@var{fv}, size_t *@var{nv})
+Field-name @var{fn} is extract form @var{blurb} of size @var{bl} and put in
+@code{malloc(3)}ted buffer @var{fv}.  The number of bytes written is put in
+@var{n}.
+@end deftypefun
+
+@subsection Headers Macros
+@cindex Headers Macros
+
+@subsection Headers Parsed
+@cindex Headers Parsed
+
+Return a hash table, a dictionnary,  ???
+
+@subsection Headers Regex
+@cindex Headers Regex
+
+Using regular expression ?

+Mail boxes come in different formats and may be on a remote hosts,
+only accessible through a Mail Delivery Agent(MDA).  Regardeless
+of the format and the protocol use, some common actions are needed like
+reading, saving, deleting, scaning ... Those actions are provided via a
+unify API mailbox_t.
+
+All functions of the mailbox_t API return 0 if succesfull or non-zero
+otherwise.
+
+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}.
+@end deftypefun
+
+@deftypefun int mailbox_destroy (mailbox_t *@var{mbx})
+All ressources allocated is release if the stream is not open,
+@code{mailbox_close()} is call.
+@end deftypefun
+
+Opening and closing mailbox can be done any number of times. But be warn
+on some cases like POP3, when opening, the lock can be persistent until
+the stream is close as required by the RFC.
+
+@deftypefun int mailbox_open (mailbox_t @var{mbx}, int @var{flag})
+Open the mailbox box stream. This funtion will call @code{mailbox_scan()}.
+@end deftypefun
+
+@deftypefun int mailbox_close (mailbox_t @var{mbx})
+Close the streams and release the locks.
+@end deftypefun
+
+Message can be mark for deletion but the action of removing them is only
+taken when calling @code{mailbox_expunge()}.
+
+@deftypefun int mailbox_delete (mailbox_t @var{mbx}, size_t @var{msgno})
+Mark @var{msgno} for deletion.
+@end deftypefun
+
+@deftypefun int mailbox_undelete (mailbox_t @var{mbx}, size_t @var{msgno})
+UnMark @var{msgno} for deletion.
+@end deftypefun
+
+@deftypefun int mailbox_is_deleted (mailbox_t @var{mbx}, size_t @var{msgno})
+Return 1 if @var{msgno} is mark deleted.
+@end deftypefun
+
+@deftypefun int mailbox_expunge (mailbox_t @var{mbx})
+All msgs marked for deletion will be remove and the mailbox updated.
+@end deftypefun
+
+Certain mailboxes allow to append new messages to the existing folder.
+
+@deftypefun int mailbox_create_envelope (mailbox_t @var{mbx}, size_t *@var{msgno})
+Create an envelope, @var{msgno} will contain a uniq number for this envelope.
+@end deftypefun
+
+@deftypefun int mailbox_set_header (mailbox_t @var{mbx}, size_t @var{msgno}, const char *@var{header}, size_t @var{len}, int @var{replace})
+Fill the header of new envelope @var{msgno}.  If @var{replace} is zero the
+buffer @var{header} will be append, otherwise it will overwrite any
+existing one.
+@end deftypefun
+
+@deftypefun int mailbox_set_body (mailbox_t @var{mbx}, size_t @var{msgno}, const char *@var{body}, size_t @var{len}, int @var{replace})
+Fill the body of new envelope @var{msgno}.  If @var{replace} is zero the buffer
+@var{body} will be append, otherwise it will overwrite any existing one.
+@end deftypefun
+
+@deftypefun int mailbox_append (mailbox_t @var{mbx}, size_t @var{msgno})
+@var{msgno} given from @code{mailbox_new_message()} will be append to
+the mailbox.
+@end deftypefun
+
+@deftypefun int mailbox_destroy_envelope (mailbox_t @var{mbx}, size_t @var{msgno})
+Ressources allocated to envelope @var{msgno} will be release.  This function
+should be call after @code{mailbox_append()}.
+@end deftypefun
+
+Reading the message body and header.
+
+@deftypefun int mailbox_get_body (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char *@var{buffer}, size_t @var{len}, size_t *@var{read})
+Read the body of message @var{msgno} starting at offset @var{off} in
+@var{buffer} of size @var{len}. The number of byte read is return in
+@var{nread}.
+@end deftypefun
+@deftypefun int mailbox_get_mbody (mailbox_t @var{mbx}, size_t @var{msgno}, off_t @var{off}, char **@var{buffer}, size_t *@var{read})
+A buffer allocate with @code{malloc()} is return containing the body of
+message @var{msgno} starting at offset @var{off} in @var{buffer}.
+The number of byte read is return 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})
+Read the header of message @var{msgno} starting at offset @var{off} in
+@var{buffer} of size @var{len}. The number of byte read is return 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})
+A buffer allocate with @code{malloc()} is return containing the header of
+message @var{msgno} starting at offset @var{off} in @var{buffer}.
+The number of byte read is return in @var{nread}.
+@end deftypefun
+
+Most mailbox provides locking before changing there content.  functions
+will grab the lock before doing any destructive action.  They are also
+provide here for accesssing the folder outside the API in that case the
+lock should be grab and unlock.  There is also another level of internal
+locking to provide synchronisation to the mailbox_t object.
+
+@deftypefun int mailbox_lock (mailbox_t @var{mbx}, int @var{flag})
+Grab the lock.  In some case, i.e Unix mbox this may involve creating
+a .lock file in the spool directory.
+@end deftypefun
+
+@deftypefun int mailbox_unlock (mailbox_t @var{mbx})
+Release the lock.
+@end deftypefun
+
+Ownership and group. When creating certain mailbox, you can set the
+owner/group.
+
+@deftypefun int mailbox_set_owner (mailbox_t @var{mbx}, uid_t @var{uid})
+Set the owner to @var{uid}.  If the Mailbox was not @code{mailbox_open()}
+the action is delayed until the stream is open.
+@end deftypefun
+@deftypefun int mailbox_set_group (mailbox_t @var{mbx}, gid_t @var{gid})
+Set the group to @var{gid}.  If the Mailbox was not @code{mailbox_open()}
+the action is delayed until the stream is open.
+@end deftypefun
+
+Setting timeout and notifications.
+
+@deftypefun int mailbox_set_timeout (mailbox_t @var{mbx}, size_t @var{millis})
+Not Implemented.
+@end deftypefun
+@deftypefun int mailbox_get_timeout (mailbox_t @var{mbx}, size_t @var{millis})
+Not Implemented.
+@end deftypefun
+@deftypefun int mailbox_set_refresh (mailbox_t @var{mbx}, size_t @var{millis})
+Not Implemented.
+@end deftypefun
+@deftypefun int mailbox_get_refresh (mailbox_t @var{mbx}, size_t @var{millis})
+Not Implemented.
+@end deftypefun
+@deftypefun int mailbox_set_notification (mailbox_t @var{mbx}, ...)
+Not Implemented.
+@end deftypefun
+
+
+Instead of providing different functions to create a mailbox_t the
+information is encoded in the form of a URL.
+
+@table @samp
+@item POP3 Post Office Protocol, Not Implemented.
+pop://<user>;AUTH=<auth>@@<host>:<port>
+@item IMAP, not implemented
+imap://
+@item QMAIL, not implemented
+qmail://
+@item Unix mbox
+file://
+@item MMDF, not implemented
+mmdf://
+@item SMail, not implemented
+smail://
+@end table
+
+The URL will contain the necessary information to initialize @code{mailbox_t}
+properly.
+
+
+All mailbox implementations provide this minimum set of the API and more
+if need be.
+
+@subsection Unix Mbox
+@cindex Unix Mbox
+
+TODO: describe particularities and mail locking policy,
+describe the flags use in _open(..);
+
+@subsection POP3 Mbox
+@cindex POP3 Mbox
+
+TODO: describe timeout policies,
+ describe the flags use in _open(..),
+ describe Different authorisation supported.
+
+@subsection IMAP Mbox
+@cindex IMAP Mbox
+
+Not implemented.
+
+@subsection QMail Mbox
+@cindex QMail Mbox
+
+Not implemented.
+
+@subsection MMDF Mbox
+@cindex MMDF Mbox
+
+Not implemented.

+
+Mail Delivery is done here. Nothing is implemented and the API is still shaky.
+
+@deftypefun int mailer_init (mailer_t *@var{mailer}, const char *@var{name}, int @var{flag})
+Not Implemented.
+@end deftypefun
+
+@deftypefun int mailer_destroy (mailer_r *@var{mailer})
+Not Implemented.
+@end deftypefun
+
+@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
+
+@deftypefun int mailer_open (mailer_t @var{mailer}, int @var{flag})
+Not Implemented.
+@end deftypefun
+
+@deftypefun int mailer_close (mailer_t @var{mailer})
+Not Implemented.
+@end deftypefun
+
+@deftypefun int mailer_set_body (mailer_t @var{mailer}, char *, size_t)
+Not Implemented.
+@end deftypefun
+
+@deftypefun int mailer_set_header (mailer_t @var{mailer}, char *, size_t)
+Not Implemented.
+@end deftypefun
+
+@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.
+@end deftypefun
+
+@deftypefun int mailer_send_envelope (mailer_t @var{mailer}, size_t)
+Not Implemented.
+@end deftypefun
+
+
+@subsection Mailto
+@cindex Mailto
+The URL mailto: is supported.
+
+TODO: example of mailto, and mailing lists,
+
+@subsection SMTP
+@cindex SMTP
+
+TODO: todo
+
+@subsection UUCP
+@cindex UUCP
+
+Yeurk ! It this to old ? Is it worth it ?
+
+@subsection Sendmail
+@cindex Sendmail
+
+This is not a protocol, but someone may use it as the mailer, and
+we provide the magic.
+
+@subsection mailx
+@cindex mailx
+
+This is not a protocol, but someone may use it as the mailer, and
+we provide the magic.
+
+@subsection mail
+@cindex mail
+
+This is not a protocol, but someone may use it as the mailer, and
+we provide the magic.
+
+@subsection MPP
+@cindex MPP
+
+Mail Posting Protocol.

+Mime stuff in the Body.

+/* sfrom, Simple From */
+#include <stdio.h>
+#include <unistd.h>
+#include <string.h>
+#include <mailutils.h>
+#include <paths.h>
+
+#ifndef _PATH_MAILDIR
+#define _PATH_MAILDIR "/usr/spool/mail"
+#endif
+
+int main (int argc, char **argv)
+@{
+   char buffer[1024];
+   char from[64];
+   char subject[64];
+   char *header;
+   mailbox_t  mbox;
+   int status, id, msg_no;
+
+   if (argc == 2)
+     @{
+         mail = argv[1];
+     @}
+   else
+     @{
+         mail = getenv ("MAIL");
+         if (mail == NULL)
+           @{
+               char * user = getlogin ();
+               int len = strlen (_PATH_MAILDIR) + strlen (user) + 1;
+               mail = malloc (len);
+               if (mail == NULL)
+                 @{
+                    fprintf (stderr, "malloc failed\n");
+                    exit (EXIT_FAILURE);
+                 @}
+               snprintf (mail, len, "%s/%s", _PATH_MAILDIR, user);
+           @}
+     @}
+
+   status = mailbox_init (&mbox, mail, 0);
+   if (status != 0)
+     @{
+        fprintf (stderr, "mailbox_init(%s) failed\n", mail);
+        exit (EXIT_FAILURE);
+     @}
+
+   status = mailbox_open (mbox, MU_MB_ORDONLY);
+   if (status != 0)
+     @{
+        fprintf (stderr, "mailbox_open(%s), %s\n", mail);
+        exit (EXIT_FAILURE);
+     @}
+
+   mailbox_scan (mbox, &msg_total);
+
+   for (msgno = 0; msgno < msg_total; msgno++)
+      @{
+         if (mailbox_get_header (mbox, msgno, buffer,
+                                 sizeof (buffer), &size) != 0)
+           @{
+               fprintf (stderr, "header corrupted\n");
+               exit (EXIT_FAILURE);
+           @}
+         header_gvalue (buffer, size, MU_HDR_FROM, from, sizeof (from), NULL);
+         header_gvalue (buffer, size, MU_HDR_SUBJECT, subject,
+                        sizeof (subject), NULL);
+         printf ("%s %s\n", from, subject);
+      @}
+
+    mailbox_close (mbox);
+    mailbox_destroy (&mbox);
+    return 0;
+@}

+
+See rfc2368, rfc2369, rfc2384
+