Modified Files:

encoding.texi headers.texi mailbox.texi mailer.texi mailutils.texi sfrom.c.texi url.texi updating Added Files: body.texi message.texi updating

Modified Files:
encoding.texi headers.texi mailbox.texi mailer.texi mailutils.texi sfrom.c.texi url.texi updating Added Files: body.texi message.texi updating
Alain Magloire
Commit 0fe6a874 ... 0fe6a874807c5711a60738e2a502498126dbd2cb authored 2000-02-06 20:17:54 +0000 by Alain Magloire
Showing 9 changed files with 308 additions and 128 deletions
doc/body.texi
doc/encoding.texi
doc/headers.texi
doc/mailbox.texi
doc/mailer.texi
doc/mailutils.texi
doc/message.texi
doc/sfrom.c.texi
doc/url.texi
--- a/doc/body.texi 0 → 100644
View file @0fe6a87
+++ b/doc/body.texi 0 → 100644
View file @0fe6a87
+The @code{body_t} type contains a @code{header_t}, a content and
+optionnaly another @code{body_t} part.
+@section Init/Destroy
+@deftypefun int body_init (body_t *@var{msg}, const mailbox_t @var{mbx})
+Private.
+@end deftypefun
+@deftypefun void body_destroy (body_t *@var{msg})
+The ressources allocate for clone @var{msg} are freed.
+@end deftypefun
+@deftypefun int body_get_header (body_t @var{msg}, header_t *@var{hdr})
+@end deftypefun
+@deftypefun int body_get_content (body_t @var{msg}, char *buffer, size_t len, size_t *n)
+@end deftypefun
+@deftypefun int body_get_type (body_t @var{msg}, char *buffer, size_t len, size_t *n)
+@end deftypefun
--- a/doc/encoding.texi
View file @0fe6a87
+++ b/doc/encoding.texi
View file @0fe6a87
-@subsection RFC1522
+@section RFC1522
 @cindex RFC1522
-@subsection Quoted Printable
+@section Quoted Printable
 @cindex Quoted Printable
-@subsection Base64
+@section Base64
 @cindex Base64
--- a/doc/headers.texi
View file @0fe6a87
+++ b/doc/headers.texi
View file @0fe6a87
 So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII
 characters will be encoded.
-@subsubsection Init/Destroy
+@section Init/Destroy
 The header should be initiliaze before any use.
 @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
 @defmac MU_HDR_RFC822
 Supports rfc 822, header style.
@@ -18,15 +17,16 @@ Supports rfc 822, header style.
 Supports rfc 1522, encoding policy.
 @end defmac
+@end deftypefun
 @deftypefun void header_destroy (header_t *@var{hdr})
-The ressources allocate for @var{hdr} or freed.
+The ressources allocate for @var{hdr} are 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
 Some basic macros is already provided for rfc822.
@@ -109,6 +109,8 @@ Some basic macros is already provided for rfc822.
          "MIME-Version"
 @end defmac
+@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}.
@@ -131,15 +133,7 @@ Field-name @var{fn} is extract form @var{blurb} of size @var{bl} and put in
 @var{n}.
 @end deftypefun
-@subsection Headers Macros
+@section Headers Regex
-@cindex Headers Macros
-@subsection Headers Parsed
-@cindex Headers Parsed
-Return a hash table, a dictionnary,  ???
-@subsection Headers Regex
 @cindex Headers Regex
 Using regular expression ?
--- a/doc/mailbox.texi
View file @0fe6a87
+++ b/doc/mailbox.texi
View file @0fe6a87
--- a/doc/mailer.texi
View file @0fe6a87
+++ b/doc/mailer.texi
View file @0fe6a87
 Mail Delivery is done here. Nothing is implemented and the API is still shaky.
-@subsubsection Init/Destroy
+@section Init/Destroy
 Initialize the mailer object.
 @deftypefun int mailer_init (mailer_t *@var{mailer}, const char *@var{name}, int @var{flag})
 Not Implemented.
-@end deftypefun
 @defmac MU_ML_PROGRAM
 Program like sendmail, mail, mailx to deliver the mail
@@ -21,11 +20,14 @@ Contact the host directly with SMTP.
 Use MPP protocol.
 @end defmac
+@end deftypefun
 @deftypefun int mailer_destroy (mailer_r *@var{mailer})
 Not Implemented.
 @end deftypefun
-@subsubsection User/Passwd
+@section User/Passwd
 On some mailer like MMP you need to identify.
@@ -37,7 +39,7 @@ Not Implemented.
 Not Implemented.
 @end deftypefun
-@subsubsection Open/Close
+@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})
@@ -48,15 +50,15 @@ Not Implemented.
 Not Implemented.
 @end deftypefun
-@subsubsection Sending
+@section Sending
 Sending a message.
-@deftypefun int mailer_create_envelope (mailer_t @var{mailer}, size_t *)
+@deftypefun int mailer_new_message (mailer_t @var{mailer}, size_t *)
 Not Implemented.
 @end deftypefun
-@deftypefun int mailer_set_body (mailer_t @var{mailer}, char *, size_t)
+@deftypefun int mailer_set_content (mailer_t @var{mailer}, char *, size_t)
 Not Implemented.
 @end deftypefun
@@ -67,11 +69,11 @@ Not Implemented.
 @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_envelope (mailer_t @var{mailer}, size_t)
+@deftypefun int mailer_send_message (mailer_t @var{mailer}, size_t)
 Not Implemented.
 @end deftypefun
-@subsubsection Timeout
+@section Timeout
 @deftypefun int mailer_set_timeout (mailer_t @var{mailer}, size_t)
 Not Implemented.
 @end deftypefun
@@ -80,42 +82,26 @@ Not Implemented.
 Not Implemented.
 @end deftypefun
+@section SMTP
-@subsection Mailto
-@cindex Mailto
-The URL mailto: should be supported.
-TODO: example of mailto, and mailing lists,
-@subsection SMTP
 @cindex SMTP
 TODO: todo
-@subsection UUCP
+@section UUCP
 @cindex UUCP
 Yeurk ! It this to old ? Is it worth it ?
-@subsection Sendmail
+@section Program
 @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
+This is not a protocol, but on must site the delivery of mail is done via
-we provide the magic.
+a program, @command{/usr/lib/sendmail}, @command{/bin/mailx},
+@command{/bin/mail}, @dots{}
-@subsection MPP
+@section MPP
 @cindex MPP
-Mail Posting Protocol.
+Mail Posting Protocol.  Not Implemented.
--- a/doc/mailutils.texi
View file @0fe6a87
+++ b/doc/mailutils.texi
View file @0fe6a87
@@ -100,18 +100,19 @@ by the Foundation.
 This document was produced for version @value{VERSION} of @sc{gnu}
 @sc{mailutils}.
 @end ifinfo
 @menu
-* Introduction::              GNU @sc{Mailutils}  Programmer's manual.
+* Introduction::                GNU @sc{mailutils}
 * Mailbox::                     Mailbox API.
 * Mailer::                      Protocol Use to Send Mail.
 * URL::                         Unified Ressource Locator.
+* Message::                     Message API.
+* Body::                        Body API.
 * Headers::                     Headers API.
 * Mime::                        Mime API.
 * Encoding::                    Encoding API.
 * Reporting Bugs::              Reporting Bugs.
 * Acknowledgement::             Thanks and Credits.
-* Concept Index::             Topics in this Manual.
+* Concept Index ::
 * Index::                       All @sc{Mailutils} Functions.
 @end menu
@@ -122,8 +123,37 @@ This document was produced for version @value{VERSION} of @sc{gnu}
 @sc{gnu} @sc{Mailutils} offers a general purpose library aimed to provide
 a rich set of functions for accessing different mailbox formats and mailers.
-For example writing a simple from command that will list @var{From} and
-@var{Subject} of a folder.
+@example
+@group
+                             USER Client
+                         -------------------
+                            |           |
+              +-------------+           +-------------+
+              |                                       |
+         /-----------\                          /-----------\
+         | mailbox_t |                          | mailer_t  |
+         \-----------/                          \-----------/
+              |                                       |
+              +--------------------+------------------+
+                                   |
+                          /------------------\
+                          |     message_t    |
+                          \------------------/
+                          | body_t | header_t|
+                          +------------------+
+                                   |
+              +--------------------+----------------+
+              |                                      |
+           -------                            ////////////////
+          (_______)                           //    LAN     //
+          (_______)                           ////////////////
+          (_______)
+@end group
+@end example
+For example writing a simple @command{from} command that will list @emph{From}
+and @emph{Subject} of a folder.
 @example
 @include sfrom.c.texi
@@ -136,21 +166,35 @@ For example writing a simple from command that will list @var{From} and
 @include mailbox.texi
-@node Mailer, URL , Mailbox, Top
+@node Mailer, URL, Mailbox, Top
 @comment  node-name,  next,  previous,  up
 @chapter Mailer
 @cindex Mailer
 @include mailer.texi
-@node URL, Headers , Mailer, Top
+@node URL, Message, Mailer, Top
 @comment  node-name,  next,  previous,  up
 @chapter URL
 @cindex URL
 @include url.texi
-@node Headers, Mime, URL , Top
+@node Message, Body, URL, Top
+@comment  node-name,  next,  previous,  up
+@chapter Message
+@cindex Message
+@include message.texi
+@node Body, Headers, Message, Top
+@comment  node-name,  next,  previous,  up
+@chapter Body
+@cindex Body
+@include body.texi
+@node Headers, Mime , Body, Top
 @comment  node-name,  next,  previous,  up
 @chapter Headers
 @cindex Headers
@@ -159,12 +203,12 @@ For example writing a simple from command that will list @var{From} and
 @node Mime , Encoding, Headers, Top
 @comment  node-name,  next,  previous,  up
-@subsection Mime
+@chapter Mime
 @cindex Mime
 @include mime.texi
-@node Encoding,  Reporting Bugs, Mime, Top
+@node Encoding, Reporting Bugs, Mime , Top
 @comment  node-name,  next,  previous,  up
 @chapter Encoding
 @cindex Encoding
@@ -179,14 +223,16 @@ For example writing a simple from command that will list @var{From} and
 Email bug reports to @email{bug-mailutils@@gnu.org}.
 Be sure to include the word ``mailutils'' somewhere in the ``Subject:'' field.
-@node Acknowledgement, Concept Index, Reporting Bugs, Top
+@node Acknowledgement, Concept Index , Reporting Bugs, Top
 @comment  node-name,  next,  previous,  up
 @chapter Acknowledgement
 @cindex Acknowledgement
+In no particular order,
 Jakob Kaivo @email{jkaivo@@ndn.net},
 Jeff Bailey @email{jbailey@@gnu.org},
 Sean Perry @email{shaleh@@debian.org},
+Thomas Fletcher @email{thomasf@@qnx.com}.
 @page
 @node Concept Index , Index, Acknowledgement, Top
@@ -198,7 +244,7 @@ This is a general index of all issues discussed in this manual
 @printindex cp
 @page
-@node Index,  , Concept Index, Top
+@node Index,  , Concept Index , Top
 @unnumbered Index
 This is an alphabetical list of all @sc{mailutils} functions.
--- a/doc/message.texi 0 → 100644
View file @0fe6a87
+++ b/doc/message.texi 0 → 100644
View file @0fe6a87
+The @code{message_t} 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 *---|----//--
+                                     +----------------+
+@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.
+@example
+#include <mailutils.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);
+@end example
+@deftypefun void message_destroy (message_t *@var{msg})
+The ressources allocate for clone @var{msg} are freed.
+@end deftypefun
+@deftypefun int message_get_header (message_t @var{msg}, header_t *@var{hdr})
+@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_get_to (message_t @var{msg}, char *buffer, size_t len, size_t *n)
+@end deftypefun
+@deftypefun int message_get_date (message_t @var{msg}, char *buffer, size_t len, size_t *n)
+@end deftypefun
+@deftypefun int message_get_cc (message_t @var{msg}, char *buffer, size_t len, size_t *n)
+@end deftypefun
--- a/doc/sfrom.c.texi
View file @0fe6a87
+++ b/doc/sfrom.c.texi
View file @0fe6a87
@@ -3,11 +3,6 @@
 #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)
 @{
@@ -19,32 +14,13 @@ int main (int argc, char **argv)
   int status
   size_t msgno, msg_total, size;
-   if (argc == 2)
+   mail = (argc == 2) ? argv[1] : getenv ("MAIL");
-     @{
-         mail = argv[1];
-     @}
-   else
-     @{
-         mail = getenv ("MAIL");
-         if (mail == NULL)
-           @{
-               char * user = getlogin ();
-               size_t len = strlen (_PATH_MAILDIR)
-                           + 1 /* for slash */ + strlen (user) + 1 /* null */;
-               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);
+   status = mailbox_init_default (&mbox, mail);
   if (status != 0)
     @{
-        fprintf (stderr, "mailbox_init(%s) failed\n", mail);
+        fprintf (stderr, "mailbox_init(%s) failed\n",
+                 mail ? mail : "Default");
        exit (EXIT_FAILURE);
     @}
@@ -65,7 +41,8 @@ int main (int argc, char **argv)
               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_FROM, from,
+                        sizeof (from), NULL);
         header_gvalue (buffer, size, MU_HDR_SUBJECT, subject,
                        sizeof (subject), NULL);
         printf ("%s %s\n", from, subject);
--- a/doc/url.texi
View file @0fe6a87
+++ b/doc/url.texi
View file @0fe6a87
 @comment See rfc2368, rfc2369, rfc2384
-Instead of providing different functions to create a mailbox_t and mailer_t the
+A mailbox and mailer can be describe in a URL, the string will contain the
-information is encoded in the form of a URL.
+necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
-@itemize @bullet
-@item
-POP3 Post Office Protocol, Not Implemented.
-@item
-IMAP, not implemented
-@item
-QMAIL, not implemented
-@item
-Unix mbox
-@item
-MMDF, not implemented
-@item
-SMail, not implemented
-@end itemize
-The URL will contain the necessary information to initialize @code{mailbox_t}
 properly.
-@subsection POP3
-pop://<user>;AUTH=<auth>@@<hostname>:<port>
-Description of the fields and examples are needed.
+@section POP3
+The POP URL scheme contains a pop server, optionnal port number
+and the authentication mechanism.  The genereal form is
+@example
+@url{pop://user;AUTH=type@@hostname:port}
+@url{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
+@end example
+If @emph{:port} is omitted the default value is 110. Different form of
+authentication can be specified with @emph{;AUTH=type}.
+The special string @emph{;AUTH=*} indicates that the client will use
+a default scheme base on the capability of the server.
+@example
+@url{pop://obelix@@gaulois.org}
+@url{pop://asterix;AUTH=*@@france.com}
+@url{pop://falbala;AUTH=+APOP@@france.com}
+@end example
+For more complete information see @cite{rfc2368}.
-@subsection IMAP
+@section IMAP
 imap://.....
 Description of the fields and examples are needed.
-@subsection File
+@section File
-file://path
-Description of the fields and examples are needed.
+Local folder should be handle by this URL.  It is preferable to let
+the mailbox recognise the type of mailbox and take the appropriate
+action.
-@subsection MMDF
+@example
-mmdf://path
+@url{file://path}
+@url{file://var/mail/user}
+@url{file://home/obelix/Mail}
+@end example
-Description of the fields and examples are needed.
+For MMDF, MH local mailboxes urls are provided,  but it is preferable to
+use @url{file://path} and let the library figure out which one.
-@subsection MH
+@example
-mh://path
+@url{mmdf://path}
+@url{mh://path}
+@end example
-Description of the fields and examples are needed.
+@section Mailto
-@subsection Mailto
+After setting a mailer, @url{mailto:} is use to tell the mailer where
-mailto://
+and to whom the message is for.
+@example
+@url{mailto://hostname}
+@end example
-Description of the fields and examples are needed.
+Mailto can be use to generate short messages for example to subscribe
+to mailing lists.
+@example
+@url{mailto://bug-mailutils@@gnu.org?body=subscribe}
+@url{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
+@end example
-@subsection mmp
+For more complete information see @cite{rfc2368}.
-mmp://
-Description of the fields and examples are needed.
+@section URL funtions
+Helper functions are provided to retreive and set  the @emph{URL} fields.
+@deftypefun int  url_init (url_t *@var{url}, const char *name)
+Initialize and parse the @var{url}
+@end deftypefun
+@deftypefun void url_destroy (url_t *)
+@end deftypefun
+@deftp {Data type} struct url_type
+@example
+@{
+  char *scheme;
+  size_t  len;
+  char *description;
+  int  id;
+  int  (*_init) (url_t *, const char * name);
+  void (*_destroy) (url_t *);
+@};
+@end example
+@end deftp
+@section Helper functions
+@deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_list_mtype (struct url_type **@var{mlist}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_add_type (struct url_type *@var{utype})
+@end deftypefun
+@deftypefun int url_remove_type (const struct url_type *@var{utype})
+@end deftypefun
+@deftypefun int url_get_id (const url_t @var{url}, int *@var{id})
+@end deftypefun
+@deftypefun int url_get_scheme (const url_t @var{url}, char *@var{schem}, size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_mscheme (const url_t @var{url}, char **@var{scheme}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_user (const url_t @var{url}, char *@var{usr}, size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_muser (const url_t @var{url}, char **@var{buf}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_mpasswd (const url_t @var{url}, char **@var{buf}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_host (const url_t @var{url}, char *@var{host}, size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_mhost (const url_t @var{url}, char **@var{buf}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_port (const url_t @var{url}, long *@var{port})
+@end deftypefun
+@deftypefun int url_get_path (const url_t @var{url}, char *@var{path}, size_t @var{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_mpath (const url_t @var{url}, char **@var{buffer}, size_t *@var{len})
+@end deftypefun
+@deftypefun int url_get_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n})
+@end deftypefun
+@deftypefun int url_get_mquery (const url_t @var{url}, char **@var{buf}, size_t *@var{len})
+@end deftypefun