Node:URL, Next:Parse822, Previous:Locker, Up:libmailbox

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://[email protected]>
<pop://asterix;AUTH=*@france.com>
<pop://falbala;[email protected]>
<pop://obelix;[email protected]:2000>
<pop://obelix:[email protected]: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://[email protected]>
<imap://asterix;AUTH=*@imap.france.com>
<imap://asterix:[email protected]>

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://[email protected]?body=subscribe>
<mailto://[email protected]?Subject=hello&body=subscribe>

For more complete information see rfc2368.

URL functions

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

int url_create (url_t *url, const char *name)

Function

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

void url_destroy (url_t *)

Function

Destroy the url and free it's resources.

int url_parse (url_t url)

Function

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.

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* string)

Function

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

#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_errstring (rc));
          exit (1);
        }
      if ((rc = url_parse (u)) != 0)
        {
          printf ("%s => FAILED: [%d] %s\n",
                  str, rc, mu_errstring (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;
}