URI

URI — Uniform Resource Identifier (URI)

Synopsis


#include <gnet.h>


                    GURI;
GURI*               gnet_uri_new                        (const gchar *uri);
GURI*               gnet_uri_new_fields                 (const gchar *scheme,
                                                         const gchar *hostname,
                                                         const gint port,
                                                         const gchar *path);
GURI*               gnet_uri_new_fields_all             (const gchar *scheme,
                                                         const gchar *userinfo,
                                                         const gchar *hostname,
                                                         const gint port,
                                                         const gchar *path,
                                                         const gchar *query,
                                                         const gchar *fragment);
GURI*               gnet_uri_clone                      (const GURI *uri);
void                gnet_uri_delete                     (GURI *uri);
void                gnet_uri_escape                     (GURI *uri);
void                gnet_uri_unescape                   (GURI *uri);
gchar*              gnet_uri_get_string                 (const GURI *uri);
void                gnet_uri_set_scheme                 (GURI *uri,
                                                         const gchar *scheme);
void                gnet_uri_set_userinfo               (GURI *uri,
                                                         const gchar *userinfo);
void                gnet_uri_set_hostname               (GURI *uri,
                                                         const gchar *hostname);
void                gnet_uri_set_port                   (GURI *uri,
                                                         gint port);
void                gnet_uri_set_path                   (GURI *uri,
                                                         const gchar *path);
void                gnet_uri_set_query                  (GURI *uri,
                                                         const gchar *query);
void                gnet_uri_set_fragment               (GURI *uri,
                                                         const gchar *fragment);
guint               gnet_uri_hash                       (gconstpointer p);
gboolean            gnet_uri_equal                      (gconstpointer p1,
                                                         gconstpointer p2);
gboolean            gnet_uri_parse_inplace              (GURI *guri,
                                                         gchar *uri,
                                                         gchar *hostname,
                                                         gsize len);

Description

A URI is a Uniform Resource Identifier, similar to a URL. This module provides functions for creating and manipulating URIs. A URI is represented by GURI. All fields in the GURI structure are publicly readable.

Create a URI from a string by calling gnet_uri_new(). To get the string representation back, call gnet_uri_get_string(). To escape a URI call gnet_uri_escape(), and to unescape it call gnet_uri_unescape(). Network protocols use escaped URIs. People use unescaped URIs.

Details

GURI

typedef struct {
  gchar* scheme;
  gchar* userinfo;
  gchar* hostname;
  gint   port;
  gchar* path;
  gchar* query;
  gchar* fragment;
} GURI;

The GURI structure represents a URI. All fields in this structure are publicly readable.

gchar *scheme;

Scheme (or protocol)

gchar *userinfo;

User info

gchar *hostname;

Host name

gint port;

Port number

gchar *path;

Path

gchar *query;

Query

gchar *fragment;

Fragment

gnet_uri_new ()

GURI*               gnet_uri_new                        (const gchar *uri);

Creates a GURI from a string. Empty fields are set to NULL. The parser does not validate the URI -- it will accept some malformed URI. URIs are usually in the form scheme://userinfohostname:port/path?queryfragment

URIs created from user input are typically unescaped. URIs created from machine input (e.g. received over the internet) are typically escaped.

uri :

URI string

Returns :

a new GURI, or NULL if there was a failure.

gnet_uri_new_fields ()

GURI*               gnet_uri_new_fields                 (const gchar *scheme,
                                                         const gchar *hostname,
                                                         const gint port,
                                                         const gchar *path);

Creates a GURI from the fields. This function uses the most common fields. Use gnet_uri_new_fields_all() to specify all fields.

scheme :

scheme

hostname :

host name

port :

port

path :

path

Returns :

a new GURI.

gnet_uri_new_fields_all ()

GURI*               gnet_uri_new_fields_all             (const gchar *scheme,
                                                         const gchar *userinfo,
                                                         const gchar *hostname,
                                                         const gint port,
                                                         const gchar *path,
                                                         const gchar *query,
                                                         const gchar *fragment);

Creates a GURI from all fields.

scheme :

scheme

userinfo :

user info

hostname :

host name

port :

port

path :

path

query :

query

fragment :

fragment

Returns :

a new GURI.

gnet_uri_clone ()

GURI*               gnet_uri_clone                      (const GURI *uri);

Copies a GURI.

uri :

a GURI

Returns :

a copy of uri.

gnet_uri_delete ()

void                gnet_uri_delete                     (GURI *uri);

Deletes a GURI.

uri :

a GURI

gnet_uri_escape ()

void                gnet_uri_escape                     (GURI *uri);

Escapes the fields in a GURI. Network protocols use escaped URIs. People use unescaped URIs.

uri :

a GURI

gnet_uri_unescape ()

void                gnet_uri_unescape                   (GURI *uri);

Unescapes the fields in the URI. Network protocols use escaped URIs. People use unescaped URIs.

uri :

a GURI

gnet_uri_get_string ()

gchar*              gnet_uri_get_string                 (const GURI *uri);

Gets a string representation of a GURI. This function does not escape or unescape the fields first. Call gnet_uri_escape() or gnet_uri_unescape first if necessary.

uri :

a GURI

Returns :

a string.

gnet_uri_set_scheme ()

void                gnet_uri_set_scheme                 (GURI *uri,
                                                         const gchar *scheme);

Sets a GURI's scheme.

uri :

a GURI

scheme :

scheme

gnet_uri_set_userinfo ()

void                gnet_uri_set_userinfo               (GURI *uri,
                                                         const gchar *userinfo);

Sets a GURI's user info.

uri :

a GURI

userinfo :

user info

gnet_uri_set_hostname ()

void                gnet_uri_set_hostname               (GURI *uri,
                                                         const gchar *hostname);

Sets a GURI's host name.

uri :

a GURI

hostname :

host name

gnet_uri_set_port ()

void                gnet_uri_set_port                   (GURI *uri,
                                                         gint port);

Set a GURI's port.

uri :

a GURI

port :

port

gnet_uri_set_path ()

void                gnet_uri_set_path                   (GURI *uri,
                                                         const gchar *path);

Set a GURI's path.

uri :

a GURI

path :

path

gnet_uri_set_query ()

void                gnet_uri_set_query                  (GURI *uri,
                                                         const gchar *query);

Set a GURI's query.

uri :

a GURI

query :

query

gnet_uri_set_fragment ()

void                gnet_uri_set_fragment               (GURI *uri,
                                                         const gchar *fragment);

Set a GURI's fragment.

uri :

a GURI

fragment :

fragment

gnet_uri_hash ()

guint               gnet_uri_hash                       (gconstpointer p);

Creates a hash code for p for use with GHashTable.

p :

a GURI

Returns :

hash code for p.

gnet_uri_equal ()

gboolean            gnet_uri_equal                      (gconstpointer p1,
                                                         gconstpointer p2);

Compares two GURI's for equality.

p1 :

a GURI

p2 :

another GURI

Returns :

TRUE if they are equal; FALSE otherwise.

gnet_uri_parse_inplace ()

gboolean            gnet_uri_parse_inplace              (GURI *guri,
                                                         gchar *uri,
                                                         gchar *hostname,
                                                         gsize len);

This function parses an URI string very efficiently and without allocating any memory on the heap. It does this by modifying the passed-in string uri and changing field separators into string terminators in place. The result will then be put into the already-allocated and usually uninitialised, GURI structure guri.

Because the slash (') which separates the hostname from the path in an URI is needed as the first character of the path, it cannot be turned into a string terminator for the hostname. This makes it necessary for the caller (ie. you) to pass in an array where the hostname can be put.

If the URI has been parsed successfully, the fields of the GURI structure will either point into the given string uri (or to hostname in case of the hostname field), or be NULL. No freeing or de-initialising of the GURI structure is required.

The only gnet_uri_*() functions you are allowed to call with this URI structure are gnet_uri_clone(), gnet_uri_equal(), gnet_uri_hash(), gnet_uri_get_string() and gnet_uri_unescape() (the latter unescapes the string fragments in place, so is safe to use here).

You must not call any other gnet_uri_*() functions with this GURI, especially not any gnet_uri_set() functions.

Under normal circumstances, you should never need to use this function. Use gnet_uri_new() instead.

guri :

pointer to an uninitialised GURI structure (usually on the stack)

uri :

a writable URI string (which will be modified by this function!)

hostname :

a preallocated array of size len, into which the hostname will be copied if the URI has a hostname. This array should live as long as guri may be used, since guri might reference it. You may pass NULL here if you know your URIs won't contain a hostname field

len :

Returns :

TRUE if uri was parsed successfully and GURI is usable, or FALSE if there was a failure.

Since 2.0.8