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

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

@smallexample
@group
@indicateurl{pop://[@var{user}[;AUTH=@var{auth}]@@]@var{host}[:@var{port}]}
 or
@indicateurl{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
@indicateurl{pop://obelix@@gaulois.org}
@indicateurl{pop://asterix;AUTH=*@@france.com}
@indicateurl{pop://falbala;AUTH=+APOP@@france.com}
@indicateurl{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
@indicateurl{pop://obelix:menhir@@village.gaulois.org:2000}
@end smallexample

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

@subsubheading POP3S (POP3 Over SSL)
The POP3S URL scheme contains a POP server over SSL, optional port
number and the authentication mechanism. The general form is

@smallexample
@group
@indicateurl{pops://[@var{user}[;AUTH=@var{auth}]@@]@var{host}[:@var{port}]}
 or
@indicateurl{pops://[@var{user}[:@var{passwd}]@@]@var{host}[:@var{port}]}
@end group
@end smallexample

If @emph{:port} is omitted the default value is 995.

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

@smallexample
@group
@indicateurl{imap://[@var{user}[;AUTH=@var{type}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
 or
@indicateurl{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
@indicateurl{imap://obelix@@imap.gaulois.org}
@indicateurl{imap://asterix;AUTH=*@@imap.france.com}
@indicateurl{imap://asterix:potion@@imap.france.com}
@end smallexample

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

@subsubheading IMAPS (IMAP Over SSL)
The IMAPS URL scheme contains an IMAP server over SSL, optional port
number and the authentication mechanism. The general form is

@smallexample
@group
@indicateurl{imaps://[@var{user}[;AUTH=@var{type}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
 or
@indicateurl{imaps://[@var{user}[:@var{passwd}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
@end group
@end smallexample

If @emph{:port} is omitted the default value is 993.

@subsubheading 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
@indicateurl{file://@var{path}}
@indicateurl{file://var/mail/user}
@indicateurl{file://home/obelix/Mail}
@end group
@end smallexample

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

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

@subsubheading Mailto

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

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

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

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

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

@c
@c URL Functions
@c

@subsubheading URL Functions

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

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

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

@deftypefun  int mu_url_parse (mu_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 mu_url_get_scheme (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_user (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_passwd (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_auth (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_host (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_port (const mu_url_t, long *)
@end deftypefun

@deftypefun  int mu_url_get_path (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int mu_url_get_query (const mu_url_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  {const char*} mu_url_to_string (const mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_scheme (mu_url_t, const char *@var{scheme})
@end deftypefun

@deftypefun  int mu_url_is_same_scheme (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_user (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_path (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_host (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_port (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun {char *} mu_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 mu_url_is_ticket (mu_url_t @var{ticket}, mu_url_t @var{url})
@end deftypefun

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