@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

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

@subsection 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=<auth>]@@]<host>[:<port>]}
 or
@url{pop://[<user>[:<passwd>]@@]<host>[:<port>]}
@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}
@url{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
@url{pop://obelix:menhir@@village.gaulois.org:2000}
@end example

For more complete information see @cite{rfc2368}.

@subsection IMAP
The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism.  The general form is

@example
@url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]}
 or
@url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]}
@end example

If @emph{:port} is omitted the default value is 220. 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{imap://obelix@@imap.gaulois.org}
@url{imap://asterix;AUTH=*@@imap.france.com}
@url{imap://asterix:potion@@imap.france.com}
@end example

For more complete information see @cite{rfc2192}.

@subsection 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

@subsection 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}.

@subsection URL functions

Helper functions are provided to retrieve and set the @emph{URL} fields.

@deftypefun int  url_create (url_t *@var{url}, const char *@var{name})
Create and the @var{url} data structure, but do not parse it.
@end deftypefun

@deftypefun void url_destroy (url_t *)
Destroy the url and free it's resources.
@end deftypefun

@deftypefun int  url_parse (url_t @var{url})
Parses the url, after calling this the get functions can be called.

The syntax, condensed from RFC 1738, and extended with the ;auth=
of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:

@example
url =
    scheme ":" [ "//"

    [ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]

    host [ ":" port ]

    [ ( "/" urlpath ) | ( "?" query ) ] ]
@end example

This is a generalized URL syntax, and may not be exactly appropriate
for any particular scheme.

@end deftypefun

@deftypefun const char* url_to_string (const url_t @var{url})
@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_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

@deftypefun char* url_decode (const char* @var{string})
Decodes an RFC 1738 % encoded string, returning the decoded string in
allocated memory. If the string is not encoded, this degenerates to
a strdup().
@end deftypefun

@section Example
@example
@include url-parse.inc
@end example