A mailbox or a mailer can be described in a URL, the string will contain the necessary information to initialize mailbox_t, or mailer_t properly.

POP3
----

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

     pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]
      or
     pop://[<user>[:<passwd>]@]<host>[:<port>]

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

     pop://obelix@gaulois.org
     pop://asterix;AUTH=*@france.com
     pop://falbala;AUTH=+APOP@france.com
     pop://obelix;AUTH=+APOP@village.gaulois.org:2000
     pop://obelix:menhir@village.gaulois.org:2000

For more complete information see rfc2368.

IMAP
----

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

     imap://[<user>[;AUTH=<type>]]@<host>[:port][/<mailbox>]
      or
     imap://[<user>[:<passwd>]]@<host>[:port][/<mailbox>]

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

     imap://obelix@imap.gaulois.org
     imap://asterix;AUTH=*@imap.france.com
     imap://asterix:potion@imap.france.com

For more complete information see rfc2192.

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.

     file://path
     file://var/mail/user
     file://home/obelix/Mail

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

     mmdf://path
     mh://path

Mailto
------

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

     mailto://hostname

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

     mailto://bug-mailutils@gnu.org?body=subscribe
     mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe

For more complete information see rfc2368.

URL functions
-------------

Helper functions are provided to retrieve and set the URL fields.

 -- Function: int url_create (url_t *URL, const char *NAME)
     Create and the URL data structure, but do not parse it.

 -- Function: void url_destroy (url_t *)
     Destroy the url and free it's resources.

 -- Function: int url_parse (url_t 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:

          url =
              scheme ":" = "//"

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

              host [ ":" port ]

              [ ( "/" urlpath ) | ( "?" query ) ]

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

 -- Function: const char* url_to_string (const url_t URL)

 -- Function: int url_get_scheme (const url_t URL, char *SCHEM, size_t LEN, size_t *N)

 -- Function: int url_get_user (const url_t URL, char *USR, size_t LEN, size_t *N)

 -- Function: int url_get_passwd (const url_t URL, char *PASSWD, size_t LEN, size_t *N)

 -- Function: int url_get_host (const url_t URL, char *HOST, size_t LEN, size_t *N)

 -- Function: int url_get_port (const url_t URL, long *PORT)

 -- Function: int url_get_path (const url_t URL, char *PATH, size_t LEN, size_t *N)

 -- Function: int url_get_query (const url_t URL, char *QUERY, size_tlen, size_t *N)

 -- Function: char* url_decode (const char* s)
     Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup().

Example
=======

          [file ex-url.texi not included]