@comment See rfc2368, rfc2369, rfc2384
A mailbox and mailer can be described in a URL, the string will contain the
necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
properly.

@section POP3
The POP URL scheme contains a pop server, optional port number
and the authentication mechanism.  The general 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 forms 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}.

@section IMAP
imap://.....

Description of the fields and examples are needed.

@section File

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.

@example
@url{file://path}
@url{file://var/mail/user}
@url{file://home/obelix/Mail}
@end example

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.

@example
@url{mmdf://path}
@url{mh://path}
@end example

@section Mailto

After setting a mailer, @url{mailto:} is used to tell the mailer where
and to whom the message is for.
@example
@url{mailto://hostname}
@end example

Mailto can be used 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

For more complete information see @cite{rfc2368}.

@section URL functions

Helper functions are provided to retrieve 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 URL registration

@deftypefun int url_list_type (struct url_type @var{list}[], size_t @var{len}, 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

@section Helper functions

@example
#include <mailutils/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

@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_passwd (const url_t @var{url}, char *@var{passwd}, size_t @var{len}, 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_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_query (const url_t @var{url}, char *@var{query}, size_t{len}, size_t *@var{n})
@end deftypefun