@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 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.

@subheading POP3
The POP URL scheme contains a POP server, optional port number
and the authentication mechanism.  The general form is

@smallexample
@group
@url{pop://[<@var{user}>[;AUTH=<@var{auth}>]@@]<@var{host}>[:<@var{port}>]}
 or
@url{pop://[<@var{user}>[:<@var{passwd}>]@@]<@var{host}>[:<@var{port}>]}
@end group
@end smallexample

If @emph{:port} is omitted the default value is 110. Different forms of
authentication can be specified with @emph{;AUTH=@var{type}}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.

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

For more complete information see @cite{RFC 2368}.

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

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

If @emph{:port} is omitted the default value is 143. Different forms of
authentication can be specified with @emph{;AUTH=@var{type}}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.

@smallexample
@url{imap://obelix@@imap.gaulois.org}
@url{imap://asterix;AUTH=*@@imap.france.com}
@url{imap://asterix:potion@@imap.france.com}
@end smallexample

For more complete information see @cite{RFC 2192}.

@subheading 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.

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

For MMDF, MH local mailboxes URLs are provided,  but it is preferable to
use @url{file://@var{path}} and let the library figure out which one.

@smallexample
@group
@url{mmdf://@var{path}}
@url{mh://@var{path}}
@end group
@end smallexample

@subheading Mailto

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

@smallexample
@url{mailto://@var{hostname}}
@end smallexample

Mailto can be used to generate short messages, for example to subscribe
to mailing lists.

@smallexample
@url{mailto://bug-mailutils@@gnu.org?body=subscribe}
@url{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
@end smallexample

For more complete information see @cite{RFC 2368}.

@c
@c URL Functions
@c

@subheading 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 the url data structure, but do not parse it.
@end deftypefun

@deftypefun void url_destroy (url_t *@var{url})
Destroy the url and free its resources.
@end deftypefun

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

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

@smallexample
@group
url =
    scheme ":" [ "//"

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

    @var{host} [ ":" @var{port} ]

    [ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
@end group
@end smallexample

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

@deftypefun  int url_get_scheme (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_user (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_passwd (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_auth (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_host (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_port (const url_t, long *)
@end deftypefun

@deftypefun  int url_get_path (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int url_get_query (const url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  {const char*} url_to_string (const url_t)
@end deftypefun

@deftypefun  int url_is_scheme (url_t, const char *@var{scheme})
@end deftypefun

@deftypefun  int url_is_same_scheme (url_t, url_t)
@end deftypefun

@deftypefun  int url_is_same_user (url_t, url_t)
@end deftypefun

@deftypefun  int url_is_same_path (url_t, url_t)
@end deftypefun

@deftypefun  int url_is_same_host (url_t, url_t)
@end deftypefun

@deftypefun  int url_is_same_port (url_t, url_t)
@end deftypefun

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

@deftypefun  int url_is_ticket (url_t @var{ticket}, url_t @var{url})
@end deftypefun

@subheading Example
@smallexample
@include url-parse.inc
@end smallexample