Next: , Previous: Locker, Up: libmailbox

3.1.14 URL

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 RFC 2368.

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 143. 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 RFC 2192.

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 RFC 2368.

URL Functions

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

— Function: int mu_url_create (mu_url_t *url, const char *name)

Create the url data structure, but do not parse it.

— Function: void mu_url_destroy (mu_url_t *url)

Destroy the url and free its resources.

— Function: int mu_url_parse (mu_url_t)

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: int mu_url_get_scheme (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_user (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_passwd (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_auth (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_host (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_port (const mu_url_t, long *)
— Function: int mu_url_get_path (const mu_url_t, char *, size_t, size_t *)
— Function: int mu_url_get_query (const mu_url_t, char *, size_t, size_t *)
— Function: const char* mu_url_to_string (const mu_url_t)
— Function: int mu_url_is_scheme (mu_url_t, const char *scheme)
— Function: int mu_url_is_same_scheme (mu_url_t, mu_url_t)
— Function: int mu_url_is_same_user (mu_url_t, mu_url_t)
— Function: int mu_url_is_same_path (mu_url_t, mu_url_t)
— Function: int mu_url_is_same_host (mu_url_t, mu_url_t)
— Function: int mu_url_is_same_port (mu_url_t, mu_url_t)
— Function: char * mu_url_decode (const char *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().

— Function: int mu_url_is_ticket (mu_url_t ticket, mu_url_t url)
Example
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     #include <stdlib.h>
     #include <stdio.h>
     #include <string.h>
     #include <mailutils/errno.h>
     #include <mailutils/url.h>
     
     int
     main ()
     {
       char str[1024];
       char buffer[1024];
       long port = 0;
       int len = sizeof (buffer);
       mu_url_t u = NULL;
     
       while (fgets (str, sizeof (str), stdin) != NULL)
         {
           int rc;
     
           str[strlen (str) - 1] = '\0';     /* chop newline */
           if (strspn (str, " \t") == strlen (str))
             continue;               /* skip empty lines */
           if ((rc = mu_url_create (&u, str)) != 0)
             {
               fprintf (stderr, "mu_url_create %s ERROR: [%d] %s",
                        str, rc, mu_strerror (rc));
               exit (1);
             }
           if ((rc = mu_url_parse (u)) != 0)
             {
               printf ("%s => FAILED: [%d] %s\n",
                       str, rc, mu_strerror (rc));
               continue;
             }
           printf ("%s => SUCCESS\n", str);
     
           mu_url_get_scheme (u, buffer, len, NULL);
           printf ("\tscheme <%s>\n", buffer);
     
           mu_url_get_user (u, buffer, len, NULL);
           printf ("\tuser <%s>\n", buffer);
     
           mu_url_get_passwd (u, buffer, len, NULL);
           printf ("\tpasswd <%s>\n", buffer);
     
           mu_url_get_auth (u, buffer, len, NULL);
           printf ("\tauth <%s>\n", buffer);
     
           mu_url_get_host (u, buffer, len, NULL);
           printf ("\thost <%s>\n", buffer);
     
           mu_url_get_port (u, &port);
           printf ("\tport %ld\n", port);
     
           mu_url_get_path (u, buffer, len, NULL);
           printf ("\tpath <%s>\n", buffer);
     
           mu_url_get_query (u, buffer, len, NULL);
           printf ("\tquery <%s>\n", buffer);
     
           mu_url_destroy (&u);
     
         }
       return 0;
     }