url.c File Reference

---

Detailed Description

URL handling of specific formats.

Author:

Raphael Manfredi

Date:

2002-2003

#include "common.h"
#include "glib-missing.h"
#include "host_addr.h"
#include "url.h"
#include "misc.h"
#include "walloc.h"
#include "override.h"

Defines
#define	ESCAPE_CHAR   '%'
#define	D(x)   { (x), CONST_STRLEN(x) }
Enumerations
enum	escape_mask { PATH_MASK = (1 << 0), QUERY_MASK = (1 << 1), FIX_MASK = (1 << 2), SHELL_MASK = (1 << 3) }
Functions
gboolean	is_transparent_char (const gint c, const enum escape_mask m)
gchar *	url_escape_mask (const gchar *url, guint8 mask)
	Escape undesirable characters using xx, where xx is an hex code.
gint	url_escape_mask_into (const gchar *url, gchar *target, gint len, guint8 mask)
	Escape undesirable characters using xx, where xx is an hex code.
gchar *	url_escape (const gchar *url)
	Escape undesirable characters using xx, where xx is an hex code.
gchar *	url_escape_query (const gchar *url)
	Same as url_escape() except for:.
gchar *	url_escape_shell (const gchar *url)
	Escapes the given string for safe use in a shell or file: URL.
char *	url_from_absolute_path (const gchar *path)
	Creates a file: URL from the given absolute path and escapes it properly for safe use in a shell too.
gint	url_escape_into (const gchar *url, gchar *target, gint len)
	Escape undesirable characters using xx, where xx is an hex code.
gchar *	url_fix_escape (const gchar *url)
	Don't touch '?', '&', '=', ':', HH.
gchar *	url_escape_cntrl (const gchar *url)
	Escape control characters using xx, where xx is an hex code.
gchar *	url_unescape (gchar *url, gboolean inplace)
	Unescape string, in-place if `inplace' is TRUE.
url_params_t *	url_params_parse (gchar *query)
	Parse all the parameters in the URL query string.
const gchar *	url_params_get (url_params_t *up, const gchar *name)
	Get the value of a parameter, or NULL if the parameter is not present.
void	free_params_kv (gpointer key, gpointer value, gpointer unused_udata)
void	url_params_free (url_params_t *up)
	Dispose of the url_params_t structure.
gboolean	url_safe_char (gchar c, url_policy_t p)
gchar *	url_normalize (gchar *url, url_policy_t pol)
	Attention: NB: May modify ``url'' in all cased; pass a copy if necessary!
Variables
const guint8	is_transparent [96]
	Reserved chars: ";", "/", "?", ":", "@", "=" and "&" Unsafe chars : " ", '"', "<", ">", "#", and "%" Misc chars : "{", "}", "|", "\", "^", "~", "[", "]" and "`".
const char	hex_alphabet [] = "0123456789ABCDEF"

---

Define Documentation

#define D (  x   )     { (x), CONST_STRLEN(x) }

#define ESCAPE_CHAR   '%'

---

Enumeration Type Documentation

enum escape_mask

Enumeration values: PATH_MASK  QUERY_MASK  FIX_MASK  SHELL_MASK

---

Function Documentation

void free_params_kv (  gpointer  key, gpointer  value, gpointer  unused_udata )  [static]

gboolean is_transparent_char (  const gint  c, const enum escape_mask  m )  [inline, static]

gchar* url_escape (  const gchar *  url  )

Escape undesirable characters using xx, where xx is an hex code. Returns: argument if no escaping is necessary, or a new string otherwise.

gchar* url_escape_cntrl (  const gchar *  url  )

Escape control characters using xx, where xx is an hex code. Returns: argument if no escaping is necessary, or a new string otherwise.

gint url_escape_into (  const gchar *  url, gchar *  target, gint  len )

Escape undesirable characters using xx, where xx is an hex code. This is done in the `target' buffer, whose size is `len'. Returns: amount of characters written into buffer (not counting trailing NUL), or -1 if the buffer was too small.

gchar* url_escape_mask (  const gchar *  url, guint8  mask )  [static]

Escape undesirable characters using xx, where xx is an hex code. Parameters: `url'  no brief description. `mask'  tells us whether we're escaping an URL path or a query string. Returns: argument if no escaping is necessary, or a new string otherwise.

gint url_escape_mask_into (  const gchar *  url, gchar *  target, gint  len, guint8  mask )  [static]

Escape undesirable characters using xx, where xx is an hex code. This is done in the `target' buffer, whose size is `len'. `mask' tells us whether we're escaping an URL path or a query string. Returns: amount of characters written into buffer (not counting trailing NUL), or -1 if the buffer was too small.

gchar* url_escape_query (  const gchar *  url  )

Same as url_escape() except for:. '+' is also escaped for the query string. ':' is not escaped. Returns: argument if no escaping is necessary, or a new string otherwise.

gchar* url_escape_shell (  const gchar *  url  )

Escapes the given string for safe use in a shell or file: URL. Returns: argument if no escaping is necessary, or a new string otherwise.

gchar* url_fix_escape (  const gchar *  url  )

Don't touch '?', '&', '=', ':', HH.

char* url_from_absolute_path (  const gchar *  path  )

Creates a file: URL from the given absolute path and escapes it properly for safe use in a shell too. Returns: A new string or NULL on failure.

gchar* url_normalize (  gchar *  url, url_policy_t  pol )

Attention: NB: May modify ``url'' in all cased; pass a copy if necessary! Returns: NULL if ``url'' isn't a valid resp. allowed URL. Otherwise, it returns either a pointer to the original URL or a g_malloc()ed modified copy which has to be g_free()ed. The URL is validated according to the specified policy. Unnecessary parts such as ":80" (for the port) and "/./" are removed: the hostname is forced to lowercase; a base URI "/" is appended if missing. This allows comparing different variants of the same URL to detect duplicates.

void url_params_free (  url_params_t *  up  )

Dispose of the url_params_t structure.

const gchar* url_params_get (  url_params_t *  up, const gchar *  name )

Get the value of a parameter, or NULL if the parameter is not present. The value returned has already been URL-unescaped.

url_params_t* url_params_parse (  gchar *  query  )

Parse all the parameters in the URL query string. All parameter values are stored in their URL-unescaped form, but parameter names are NOT un-escaped. Returns: an url_params_t object that can be queried for later... or NULL if the argument isn't valid encoded.

gboolean url_safe_char (  gchar  c, url_policy_t  p )  [static]

gchar* url_unescape (  gchar *  url, gboolean  inplace )

Unescape string, in-place if `inplace' is TRUE. Returns the argument if un-escaping is NOT necessary, a new string otherwise unless in-place decoding was requested. Returns: NULL if the argument isn't valid encoded.

---

Variable Documentation

const char hex_alphabet[] = "0123456789ABCDEF" [static]

const guint8 is_transparent[96] [static]

Initial value: { 0x0,0x0,0x0,0x0,0x7,0x0,0x4,0x0, 0x7,0x7,0x7,0x0,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0x6,0x0,0x0,0x4,0x0,0x4, 0x0,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0x0,0x0,0x0,0x0,0xf, 0x0,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0xf,0xf,0xf,0xf,0xf, 0xf,0xf,0xf,0x0,0x0,0x0,0x0,0x0, } Reserved chars: ";", "/", "?", ":", "@", "=" and "&" Unsafe chars : " ", '"', "<", ">", "#", and "%" Misc chars : "{", "}", "|", "\", "^", "~", "[", "]" and "`". * - * - * - Bit 0 encodes regular transparent set (pathnames, '/' is transparent). Bit 1 encodes regular transparent set minus '+' (query string). Bit 2 encodes the set for fixing an incomplete escaping. Bit 3 encodes the set for use in a shell.

---