4.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

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

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 url_create (url_t *url, const char *name)

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

Function: void url_destroy (url_t *url)

Destroy the url and free its resources.

Function: int url_parse (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 url_get_scheme (const url_t, char *, size_t, size_t *)

Function: int url_get_user (const url_t, char *, size_t, size_t *)

Function: int url_get_passwd (const url_t, char *, size_t, size_t *)

Function: int url_get_auth (const url_t, char *, size_t, size_t *)

Function: int url_get_host (const url_t, char *, size_t, size_t *)

Function: int url_get_port (const url_t, long *)

Function: int url_get_path (const url_t, char *, size_t, size_t *)

Function: int url_get_query (const url_t, char *, size_t, size_t *)

Function: const char* url_to_string (const url_t)

Function: int url_is_scheme (url_t, const char *scheme)

Function: int url_is_same_scheme (url_t, url_t)

Function: int url_is_same_user (url_t, url_t)

Function: int url_is_same_path (url_t, url_t)

Function: int url_is_same_host (url_t, url_t)

Function: int url_is_same_port (url_t, url_t)

Function: char* 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 url_is_ticket (url_t ticket, url_t url)

Example

#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);
  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 = url_create (&u, str)) != 0)
        {
          fprintf (stderr, "url_create %s ERROR: [%d] %s",
                   str, rc, mu_strerror (rc));
          exit (1);
        }
      if ((rc = url_parse (u)) != 0)
        {
          printf ("%s => FAILED: [%d] %s\n",
                  str, rc, mu_strerror (rc));
          continue;
        }
      printf ("%s => SUCCESS\n", str);

      url_get_scheme (u, buffer, len, NULL);
      printf ("\tscheme <%s>\n", buffer);

      url_get_user (u, buffer, len, NULL);
      printf ("\tuser <%s>\n", buffer);

      url_get_passwd (u, buffer, len, NULL);
      printf ("\tpasswd <%s>\n", buffer);

      url_get_auth (u, buffer, len, NULL);
      printf ("\tauth <%s>\n", buffer);

      url_get_host (u, buffer, len, NULL);
      printf ("\thost <%s>\n", buffer);

      url_get_port (u, &port);
      printf ("\tport %ld\n", port);

      url_get_path (u, buffer, len, NULL);
      printf ("\tpath <%s>\n", buffer);

      url_get_query (u, buffer, len, NULL);
      printf ("\tquery <%s>\n", buffer);

      url_destroy (&u);

    }
  return 0;
}