url.h File Reference

Parse and identify different URL schemes. More...

#include <stddef.h>
#include <stdint.h>
#include "mutt/lib.h"

Include dependency graph for url.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	UrlQuery
	Parsed Query String. More...
struct	Url
	A parsed URL proto://user:password@host:port/path?a=1&b=2 More...

Macros
#define	U_NO_FLAGS   0
#define	U_PATH   (1 << 1)

Enumerations
enum	UrlScheme {   U_UNKNOWN , U_FILE , U_POP , U_POPS ,   U_IMAP , U_IMAPS , U_NNTP , U_NNTPS ,   U_SMTP , U_SMTPS , U_MAILTO , U_NOTMUCH }
	All recognised Url types. More...

Functions
	STAILQ_HEAD (UrlQueryList, UrlQuery)
enum UrlScheme	url_check_scheme (const char *s)
	Check the protocol of a URL. More...
void	url_free (struct Url **ptr)
	Free the contents of a URL. More...
struct Url *	url_parse (const char *src)
	Fill in Url. More...
int	url_pct_decode (char *s)
	Decode a percent-encoded string. More...
void	url_pct_encode (char *buf, size_t buflen, const char *src)
	Percent-encode a string. More...
int	url_tobuffer (struct Url *url, struct Buffer *dest, uint8_t flags)
	Output the URL string for a given Url object. More...
int	url_tostring (struct Url *url, char *buf, size_t buflen, uint8_t flags)
	Output the URL string for a given Url object. More...

Detailed Description

Parse and identify different URL schemes.

Authors

• Thomas Roessler

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file url.h.

Macro Definition Documentation

U_NO_FLAGS

#define U_NO_FLAGS   0

Definition at line 49 of file url.h.

U_PATH

#define U_PATH   (1 << 1)

Definition at line 50 of file url.h.

Enumeration Type Documentation

UrlScheme

enum UrlScheme

All recognised Url types.

Enumerator
U_UNKNOWN	Url wasn't recognised.
U_FILE	Url is file://.
U_POP	Url is pop://.
U_POPS	Url is pops://.
U_IMAP	Url is imap://.
U_IMAPS	Url is imaps://.
U_NNTP	Url is nntp://.
U_NNTPS	Url is nntps://.
U_SMTP	Url is smtp://.
U_SMTPS	Url is smtps://.
U_MAILTO	Url is mailto://.
U_NOTMUCH	Url is notmuch://.

Definition at line 33 of file url.h.

{
  U_UNKNOWN, 
  U_FILE,    
  U_POP,     
  U_POPS,    
  U_IMAP,    
  U_IMAPS,   
  U_NNTP,    
  U_NNTPS,   
  U_SMTP,    
  U_SMTPS,   
  U_MAILTO,  
  U_NOTMUCH, 
};

Function Documentation

STAILQ_HEAD()

STAILQ_HEAD	(	UrlQueryList	,
		UrlQuery
	)

url_check_scheme()

enum UrlScheme url_check_scheme

(

const char *

str

)

Check the protocol of a URL.

Parameters

str	String to check

Return values

num	Url type, e.g. U_IMAPS

Definition at line 223 of file url.c.

{
  return get_scheme(str, mutt_prex_capture(PREX_URL, str));
}

Here is the call graph for this function:

Here is the caller graph for this function:

url_free()

void url_free

(

struct Url **

ptr

)

Free the contents of a URL.

Parameters

ptr	Url to free

Definition at line 123 of file url.c.

{
  if (!ptr || !*ptr)
    return;
 
  struct Url *url = *ptr;
 
  struct UrlQueryList *l = &url->query_strings;
  while (!STAILQ_EMPTY(l))
  {
    struct UrlQuery *np = STAILQ_FIRST(l);
    STAILQ_REMOVE_HEAD(l, entries);
    // Don't free 'name', 'value': they are pointers into the 'src' string
    FREE(&np);
  }
 
  FREE(&url->src);
  FREE(ptr);
}

Here is the caller graph for this function:

url_parse()

struct Url * url_parse

(

const char *

src

)

Fill in Url.

Parameters

src	String to parse

Return values

ptr	Parsed URL
NULL	Error

Note

Caller must free returned Url with url_free()

Definition at line 236 of file url.c.

{
  const regmatch_t *match = mutt_prex_capture(PREX_URL, src);
  if (!match)
    return NULL;
 
  enum UrlScheme scheme = get_scheme(src, match);
  if (scheme == U_UNKNOWN)
    return NULL;
 
  const regmatch_t *userinfo = &match[PREX_URL_MATCH_USERINFO];
  const regmatch_t *user = &match[PREX_URL_MATCH_USER];
  const regmatch_t *pass = &match[PREX_URL_MATCH_PASS];
  const regmatch_t *host = &match[PREX_URL_MATCH_HOSTNAME];
  const regmatch_t *ipvx = &match[PREX_URL_MATCH_HOSTIPVX];
  const regmatch_t *port = &match[PREX_URL_MATCH_PORT];
  const regmatch_t *path = &match[PREX_URL_MATCH_PATH];
  const regmatch_t *query = &match[PREX_URL_MATCH_QUERY];
  const regmatch_t *pathonly = &match[PREX_URL_MATCH_PATH_ONLY];
 
  struct Url *url = url_new();
  url->scheme = scheme;
  url->src = mutt_str_dup(src);
 
  /* If the scheme is not followed by two forward slashes, then it's a simple
   * path (see https://tools.ietf.org/html/rfc3986#section-3). */
  if (mutt_regmatch_start(pathonly) != -1)
  {
    url->src[mutt_regmatch_end(pathonly)] = '\0';
    url->path = url->src + mutt_regmatch_start(pathonly);
    if (url_pct_decode(url->path) < 0)
      goto err;
  }
 
  /* separate userinfo part */
  if (mutt_regmatch_end(userinfo) != -1)
  {
    url->src[mutt_regmatch_end(userinfo) - 1] = '\0';
  }
 
  /* user */
  if (mutt_regmatch_end(user) != -1)
  {
    url->src[mutt_regmatch_end(user)] = '\0';
    url->user = url->src + mutt_regmatch_start(user);
    if (url_pct_decode(url->user) < 0)
      goto err;
  }
 
  /* pass */
  if (mutt_regmatch_end(pass) != -1)
  {
    url->pass = url->src + mutt_regmatch_start(pass);
    if (url_pct_decode(url->pass) < 0)
      goto err;
  }
 
  /* host */
  if (mutt_regmatch_len(host) != 0)
  {
    url->host = url->src + mutt_regmatch_start(host);
    url->src[mutt_regmatch_end(host)] = '\0';
  }
  else if (mutt_regmatch_end(ipvx) != -1)
  {
    url->host = url->src + mutt_regmatch_start(ipvx) + 1; /* skip opening '[' */
    url->src[mutt_regmatch_end(ipvx) - 1] = '\0';         /* skip closing ']' */
  }
 
  /* port */
  if (mutt_regmatch_end(port) != -1)
  {
    url->src[mutt_regmatch_end(port)] = '\0';
    const char *ports = url->src + mutt_regmatch_start(port);
    unsigned short num;
    if (!mutt_str_atous_full(ports, &num))
    {
      goto err;
    }
    url->port = num;
  }
 
  /* path */
  if (mutt_regmatch_end(path) != -1)
  {
    url->src[mutt_regmatch_end(path)] = '\0';
    url->path = url->src + mutt_regmatch_start(path);
    if (!url->host)
    {
      /* If host is not provided, restore the '/': this is an absolute path */
      *(--url->path) = '/';
    }
    if (url_pct_decode(url->path) < 0)
      goto err;
  }
 
  /* query */
  if (mutt_regmatch_end(query) != -1)
  {
    char *squery = url->src + mutt_regmatch_start(query);
    if (!parse_query_string(&url->query_strings, squery))
      goto err;
  }
 
  return url;
 
err:
  url_free(&url);
  return NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

url_pct_decode()

int url_pct_decode

(

char *

s

)

Decode a percent-encoded string.

Parameters

s	String to decode

Return values

0	Success
-1	Error

e.g. turn "hello%20world" into "hello world" The string is decoded in-place.

Definition at line 189 of file url.c.

{
  if (!s)
    return -1;
 
  char *d = NULL;
 
  for (d = s; *s; s++)
  {
    if (*s == '%')
    {
      if ((s[1] != '\0') && (s[2] != '\0') && isxdigit((unsigned char) s[1]) &&
          isxdigit((unsigned char) s[2]) && (hexval(s[1]) >= 0) && (hexval(s[2]) >= 0))
      {
        *d++ = (hexval(s[1]) << 4) | (hexval(s[2]));
        s += 2;
      }
      else
      {
        return -1;
      }
    }
    else
      *d++ = *s;
  }
  *d = '\0';
  return 0;
}

Here is the caller graph for this function:

url_pct_encode()

void url_pct_encode	(	char *	buf,
		size_t	buflen,
		const char *	src
	)

Percent-encode a string.

Parameters

buf	Buffer for the result
buflen	Length of buffer
src	String to encode

e.g. turn "hello world" into "hello%20world"

Definition at line 151 of file url.c.

{
  static const char *hex = "0123456789ABCDEF";
 
  if (!buf)
    return;
 
  *buf = '\0';
  buflen--;
  while (src && *src && (buflen != 0))
  {
    if (strchr(" /:&%=", *src))
    {
      if (buflen < 3)
        break;
 
      *buf++ = '%';
      *buf++ = hex[(*src >> 4) & 0xf];
      *buf++ = hex[*src & 0xf];
      src++;
      buflen -= 3;
      continue;
    }
    *buf++ = *src++;
    buflen--;
  }
  *buf = '\0';
}

Here is the caller graph for this function:

url_tobuffer()

int url_tobuffer	(	struct Url *	url,
		struct Buffer *	buf,
		uint8_t	flags
	)

Output the URL string for a given Url object.

Parameters

url	Url to turn into a string
buf	Buffer for the result
flags	Flags, e.g. U_PATH

Return values

0	Success
-1	Error

Definition at line 355 of file url.c.

{
  if (!url || !buf)
    return -1;
  if (url->scheme == U_UNKNOWN)
    return -1;
 
  mutt_buffer_printf(buf, "%s:", mutt_map_get_name(url->scheme, UrlMap));
 
  if (url->host)
  {
    if (!(flags & U_PATH))
      mutt_buffer_addstr(buf, "//");
 
    if (url->user && (url->user[0] || !(flags & U_PATH)))
    {
      char str[256] = { 0 };
      url_pct_encode(str, sizeof(str), url->user);
      mutt_buffer_add_printf(buf, "%s@", str);
    }
 
    if (strchr(url->host, ':'))
      mutt_buffer_add_printf(buf, "[%s]", url->host);
    else
      mutt_buffer_add_printf(buf, "%s", url->host);
 
    if (url->port)
      mutt_buffer_add_printf(buf, ":%hu/", url->port);
    else
      mutt_buffer_addstr(buf, "/");
  }
 
  if (url->path)
    mutt_buffer_addstr(buf, url->path);
 
  if (STAILQ_FIRST(&url->query_strings))
  {
    mutt_buffer_addstr(buf, "?");
 
    char str[256] = { 0 };
    struct UrlQuery *np = NULL;
    STAILQ_FOREACH(np, &url->query_strings, entries)
    {
      url_pct_encode(str, sizeof(str), np->name);
      mutt_buffer_addstr(buf, str);
      mutt_buffer_addstr(buf, "=");
      url_pct_encode(str, sizeof(str), np->value);
      mutt_buffer_addstr(buf, str);
      if (STAILQ_NEXT(np, entries))
        mutt_buffer_addstr(buf, "&");
    }
  }
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

url_tostring()

int url_tostring	(	struct Url *	url,
		char *	dest,
		size_t	len,
		uint8_t	flags
	)

Output the URL string for a given Url object.

Parameters

url	Url to turn into a string
dest	Buffer for the result
len	Length of buffer
flags	Flags, e.g. U_PATH

Return values

0	Success
-1	Error

Definition at line 420 of file url.c.

{
  if (!url || !dest)
    return -1;
 
  struct Buffer *dest_buf = mutt_buffer_pool_get();
 
  int retval = url_tobuffer(url, dest_buf, flags);
  if (retval == 0)
    mutt_str_copy(dest, mutt_buffer_string(dest_buf), len);
 
  mutt_buffer_pool_release(&dest_buf);
 
  return retval;
}

Here is the call graph for this function:

Here is the caller graph for this function: