Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 0fe6a874 0fe6a874807c5711a60738e2a502498126dbd2cb by Alain Magloire
Options

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
1 parent 831780e1
Expand all
Inline Side-by-side
Showing 9 changed files with 321 additions and 141 deletions
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
@subsection RFC1522
@section RFC1522
@cindex RFC1522
@subsection Quoted Printable
@section Quoted Printable
@cindex Quoted Printable
@subsection Base64
@section Base64
@cindex Base64
......
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
@cindex Headers Macros
@subsection Headers Parsed
@cindex Headers Parsed
Return a hash table, a dictionnary, ???
@subsection Headers Regex
@section Headers Regex
@cindex Headers Regex
Using regular expression ?
......
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
@subsection Mailto
@cindex Mailto
The URL mailto: should be supported.
TODO: example of mailto, and mailing lists,
@subsection SMTP
@section 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
we provide the magic.
This is not a protocol, but on must site the delivery of mail is done via
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.
......
......@@ -100,30 +100,60 @@ 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.
* Mailbox:: Mailbox API.
* Mailer:: Protocol Use to Send Mail.
* URL:: Unified Ressource Locator.
* Headers:: Headers API.
* Mime:: Mime API.
* Encoding:: Encoding API.
* Reporting Bugs:: Reporting Bugs.
* Acknowledgement:: Thanks and Credits.
* Concept Index:: Topics in this Manual.
* Index:: All @sc{Mailutils} Functions.
* 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 ::
* Index:: All @sc{Mailutils} Functions.
@end menu
@node Introduction, Mailbox, Top, Top
@node Introduction, Mailbox, Top, Top
@comment node-name, next, previous, up
@chapter Introduction
@cindex Introduction
@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
Jakob Kaivo @email{jkaivo@@ndn.net},
Jeff Bailey @email{jbailey@@gnu.org},
Sean Perry @email{shaleh@@debian.org},
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.
......
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
......@@ -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 = 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);
@}
@}
mail = (argc == 2) ? argv[1] : getenv ("MAIL");
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);
......
@comment See rfc2368, rfc2369, rfc2384
Instead of providing different functions to create a mailbox_t and mailer_t the
information is encoded in the form of a URL.
@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}
A mailbox and mailer can be describe in a URL, the string will contain the
necessary information to initialize @code{mailbox_t}, or @code{mailer_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
file://path
@section File
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
mmdf://path
@example
@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
mh://path
@example
@url{mmdf://path}
@url{mh://path}
@end example
Description of the fields and examples are needed.
@section Mailto
@subsection Mailto
mailto://
After setting a mailer, @url{mailto:} is use to tell the mailer where
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
mmp://
For more complete information see @cite{rfc2368}.
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
......