SoupURI

SoupURI — URIs

Object Hierarchy

    GBoxed
    ╰── SoupURI

Includes

#include <libsoup/soup.h>

Description

A SoupURI represents a (parsed) URI.

Many applications will not need to use SoupURI directly at all; on the client side, soup_message_new() takes a stringified URI, and on the server side, the path and query components are provided for you in the server callback.

Functions

soup_uri_new_with_base ()

SoupURI *
soup_uri_new_with_base (SoupURI *base,
                        const char *uri_string);

Parses uri_string relative to base .

Parameters

base

a base URI

 

uri_string

the URI

 

Returns

a parsed SoupURI.


soup_uri_new ()

SoupURI *
soup_uri_new (const char *uri_string);

Parses an absolute URI.

You can also pass NULL for uri_string if you want to get back an "empty" SoupURI that you can fill in by hand. (You will need to call at least soup_uri_set_scheme() and soup_uri_set_path(), since those fields are required.)

Parameters

uri_string

a URI.

[allow-none]

Returns

a SoupURI, or NULL if the given string was found to be invalid.

[nullable]


soup_uri_to_string ()

char *
soup_uri_to_string (SoupURI *uri,
                    gboolean just_path_and_query);

Returns a string representing uri .

If just_path_and_query is TRUE, this concatenates the path and query together. That is, it constructs the string that would be needed in the Request-Line of an HTTP request for uri .

Note that the output will never contain a password, even if uri does.

Parameters

uri

a SoupURI

 

just_path_and_query

if TRUE, output just the path and query portions

 

Returns

a string representing uri , which the caller must free.


soup_uri_copy ()

SoupURI *
soup_uri_copy (SoupURI *uri);

Copies uri

Parameters

uri

a SoupURI

 

Returns

a copy of uri , which must be freed with soup_uri_free()


soup_uri_copy_host ()

SoupURI *
soup_uri_copy_host (SoupURI *uri);

Makes a copy of uri , considering only the protocol, host, and port

Parameters

uri

a SoupURI

 

Returns

the new SoupURI

Since: 2.28


soup_uri_equal ()

gboolean
soup_uri_equal (SoupURI *uri1,
                SoupURI *uri2);

Tests whether or not uri1 and uri2 are equal in all parts

Parameters

uri1

a SoupURI

 

uri2

another SoupURI

 

Returns

TRUE or FALSE


soup_uri_host_equal ()

gboolean
soup_uri_host_equal (gconstpointer v1,
                     gconstpointer v2);

Compares v1 and v2 , considering only the scheme, host, and port.

Parameters

v1

a SoupURI with a non-NULL host member.

[type Soup.URI]

v2

a SoupURI with a non-NULL host member.

[type Soup.URI]

Returns

whether or not the URIs are equal in scheme, host, and port.

Since: 2.28


soup_uri_host_hash ()

guint
soup_uri_host_hash (gconstpointer key);

Hashes key , considering only the scheme, host, and port.

Parameters

key

a SoupURI with a non-NULL host member.

[type Soup.URI]

Returns

a hash

Since: 2.28


soup_uri_free ()

void
soup_uri_free (SoupURI *uri);

Frees uri .

Parameters

uri

a SoupURI

 

soup_uri_encode ()

char *
soup_uri_encode (const char *part,
                 const char *escape_extra);

This %-encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.

Parameters

part

a URI part

 

escape_extra

additional reserved characters to escape (or NULL).

[allow-none]

Returns

the encoded URI part


soup_uri_decode ()

char *
soup_uri_decode (const char *part);

Fully %-decodes part .

In the past, this would return NULL if part contained invalid percent-encoding, but now it just ignores the problem (as soup_uri_new() already did).

Parameters

part

a URI part

 

Returns

the decoded URI part.


soup_uri_normalize ()

char *
soup_uri_normalize (const char *part,
                    const char *unescape_extra);

%-decodes any "unreserved" characters (or characters in unescape_extra ) in part , and %-encodes any non-ASCII characters, spaces, and non-printing characters in part .

"Unreserved" characters are those that are not allowed to be used for punctuation according to the URI spec. For example, letters are unreserved, so soup_uri_normalize() will turn http://example.com/foo/b%61r into http://example.com/foo/bar, which is guaranteed to mean the same thing. However, "/" is "reserved", so http://example.com/foo%2Fbar would not be changed, because it might mean something different to the server.

In the past, this would return NULL if part contained invalid percent-encoding, but now it just ignores the problem (as soup_uri_new() already did).

Parameters

part

a URI part

 

unescape_extra

reserved characters to unescape (or NULL).

[allow-none]

Returns

the normalized URI part


soup_uri_uses_default_port ()

gboolean
soup_uri_uses_default_port (SoupURI *uri);

Tests if uri uses the default port for its scheme. (Eg, 80 for http.) (This only works for http, https and ftp; libsoup does not know the default ports of other protocols.)

Parameters

uri

a SoupURI

 

Returns

TRUE or FALSE


SOUP_URI_IS_VALID()

#define   SOUP_URI_IS_VALID(uri)       ((uri) && (uri)->scheme && (uri)->path)

Tests whether uri is a valid SoupURI; that is, that it is non-NULL and its scheme and path members are also non-NULL.

This macro does not check whether http and https URIs have a non-NULL host member.

Parameters

uri

a SoupURI

 

Returns

TRUE if uri is valid for use.

Since: 2.38


SOUP_URI_VALID_FOR_HTTP()

#define   SOUP_URI_VALID_FOR_HTTP(uri) ((uri) && ((uri)->scheme == SOUP_URI_SCHEME_HTTP || (uri)->scheme == SOUP_URI_SCHEME_HTTPS) && (uri)->host && (uri)->path)

Tests if uri is a valid SoupURI for HTTP communication; that is, if it can be used to construct a SoupMessage.

Parameters

uri

a SoupURI

 

Returns

TRUE if uri is a valid "http" or "https" URI.

Since: 2.24


soup_uri_set_scheme ()

void
soup_uri_set_scheme (SoupURI *uri,
                     const char *scheme);

Sets uri 's scheme to scheme . This will also set uri 's port to the default port for scheme , if known.

Parameters

uri

a SoupURI

 

scheme

the URI scheme

 

soup_uri_get_scheme ()

const char *
soup_uri_get_scheme (SoupURI *uri);

Gets uri 's scheme.

Parameters

uri

a SoupURI

 

Returns

uri 's scheme.

Since: 2.32


soup_uri_set_user ()

void
soup_uri_set_user (SoupURI *uri,
                   const char *user);

Sets uri 's user to user .

Parameters

uri

a SoupURI

 

user

the username, or NULL.

[allow-none]

soup_uri_get_user ()

const char *
soup_uri_get_user (SoupURI *uri);

Gets uri 's user.

Parameters

uri

a SoupURI

 

Returns

uri 's user.

Since: 2.32


soup_uri_set_password ()

void
soup_uri_set_password (SoupURI *uri,
                       const char *password);

Sets uri 's password to password .

Parameters

uri

a SoupURI

 

password

the password, or NULL.

[allow-none]

soup_uri_get_password ()

const char *
soup_uri_get_password (SoupURI *uri);

Gets uri 's password.

Parameters

uri

a SoupURI

 

Returns

uri 's password.

Since: 2.32


soup_uri_set_host ()

void
soup_uri_set_host (SoupURI *uri,
                   const char *host);

Sets uri 's host to host .

If host is an IPv6 IP address, it should not include the brackets required by the URI syntax; they will be added automatically when converting uri to a string.

http and https URIs should not have a NULL host .

Parameters

uri

a SoupURI

 

host

the hostname or IP address, or NULL.

[allow-none]

soup_uri_get_host ()

const char *
soup_uri_get_host (SoupURI *uri);

Gets uri 's host.

Parameters

uri

a SoupURI

 

Returns

uri 's host.

Since: 2.32


soup_uri_set_port ()

void
soup_uri_set_port (SoupURI *uri,
                   guint port);

Sets uri 's port to port . If port is 0, uri will not have an explicitly-specified port.

Parameters

uri

a SoupURI

 

port

the port, or 0

 

soup_uri_get_port ()

guint
soup_uri_get_port (SoupURI *uri);

Gets uri 's port.

Parameters

uri

a SoupURI

 

Returns

uri 's port.

Since: 2.32


soup_uri_set_path ()

void
soup_uri_set_path (SoupURI *uri,
                   const char *path);

Sets uri 's path to path .

Parameters

uri

a SoupURI

 

path

the non-NULL path

 

soup_uri_get_path ()

const char *
soup_uri_get_path (SoupURI *uri);

Gets uri 's path.

Parameters

uri

a SoupURI

 

Returns

uri 's path.

Since: 2.32


soup_uri_set_query ()

void
soup_uri_set_query (SoupURI *uri,
                    const char *query);

Sets uri 's query to query .

Parameters

uri

a SoupURI

 

query

the query.

[allow-none]

soup_uri_set_query_from_form ()

void
soup_uri_set_query_from_form (SoupURI *uri,
                              GHashTable *form);

Sets uri 's query to the result of encoding form according to the HTML form rules. See soup_form_encode_hash() for more information.

Parameters

uri

a SoupURI

 

form

a GHashTable containing HTML form information.

[element-type utf8 utf8]

soup_uri_set_query_from_fields ()

void
soup_uri_set_query_from_fields (SoupURI *uri,
                                const char *first_field,
                                ...);

Sets uri 's query to the result of encoding the given form fields and values according to the * HTML form rules. See soup_form_encode() for more information.

Parameters

uri

a SoupURI

 

first_field

name of the first form field to encode into query

 

...

value of first_field , followed by additional field names and values, terminated by NULL.

 

soup_uri_get_query ()

const char *
soup_uri_get_query (SoupURI *uri);

Gets uri 's query.

Parameters

uri

a SoupURI

 

Returns

uri 's query.

Since: 2.32


soup_uri_set_fragment ()

void
soup_uri_set_fragment (SoupURI *uri,
                       const char *fragment);

Sets uri 's fragment to fragment .

Parameters

uri

a SoupURI

 

fragment

the fragment.

[allow-none]

soup_uri_get_fragment ()

const char *
soup_uri_get_fragment (SoupURI *uri);

Gets uri 's fragment.

Parameters

uri

a SoupURI

 

Returns

uri 's fragment.

Since: 2.32

Types and Values

SoupURI

typedef struct {
	const char *scheme;

	char       *user;
	char       *password;

	char       *host;
	guint       port;

	char       *path;
	char       *query;

	char       *fragment;
} SoupURI;

A SoupURI represents a (parsed) URI. SoupURI supports RFC 3986 (URI Generic Syntax), and can parse any valid URI. However, libsoup only uses "http" and "https" URIs internally; You can use SOUP_URI_VALID_FOR_HTTP() to test if a SoupURI is a valid HTTP URI.

scheme will always be set in any URI. It is an interned string and is always all lowercase. (If you parse a URI with a non-lowercase scheme, it will be converted to lowercase.) The macros SOUP_URI_SCHEME_HTTP and SOUP_URI_SCHEME_HTTPS provide the interned values for "http" and "https" and can be compared against URI scheme values.

user and password are parsed as defined in the older URI specs (ie, separated by a colon; RFC 3986 only talks about a single "userinfo" field). Note that password is not included in the output of soup_uri_to_string(). libsoup does not normally use these fields; authentication is handled via SoupSession signals.

host contains the hostname, and port the port specified in the URI. If the URI doesn't contain a hostname, host will be NULL, and if it doesn't specify a port, port may be 0. However, for "http" and "https" URIs, host is guaranteed to be non-NULL (trying to parse an http URI with no host will return NULL), and port will always be non-0 (because libsoup knows the default value to use when it is not specified in the URI).

path is always non-NULL. For http/https URIs, path will never be an empty string either; if the input URI has no path, the parsed SoupURI will have a path of "/".

query and fragment are optional for all URI types. soup_form_decode() may be useful for parsing query .

Note that path , query , and fragment may contain %-encoded characters. soup_uri_new() calls soup_uri_normalize() on them, but not soup_uri_decode(). This is necessary to ensure that soup_uri_to_string() will generate a URI that has exactly the same meaning as the original. (In theory, SoupURI should leave user , password , and host partially-encoded as well, but this would be more annoying than useful.)

Members

const char *scheme;

the URI scheme (eg, "http")

 

char *user;

a username, or NULL

 

char *password;

a password, or NULL

 

char *host;

the hostname or IP address

 

guint port;

the port number on host

 

char *path;

the path on host

 

char *query;

a query for path , or NULL

 

char *fragment;

a fragment identifier within path , or NULL

 

SOUP_URI_SCHEME_HTTP

#define SOUP_URI_SCHEME_HTTP     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTP, "http")

"http" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.


SOUP_URI_SCHEME_HTTPS

#define SOUP_URI_SCHEME_HTTPS    _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTPS, "https")

"https" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.


SOUP_URI_SCHEME_DATA

#define SOUP_URI_SCHEME_DATA     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_DATA, "data")

"data" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.30


SOUP_URI_SCHEME_FILE

#define SOUP_URI_SCHEME_FILE     _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FILE, "file")

"file" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.30


SOUP_URI_SCHEME_FTP

#define SOUP_URI_SCHEME_FTP      _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FTP, "ftp")

"ftp" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.30


SOUP_URI_SCHEME_RESOURCE

#define SOUP_URI_SCHEME_RESOURCE _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_RESOURCE, "resource")

"data" as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.42


SOUP_URI_SCHEME_WS

#define SOUP_URI_SCHEME_WS       _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_WS, "ws")

"ws" (WebSocket) as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.50


SOUP_URI_SCHEME_WSS

#define SOUP_URI_SCHEME_WSS      _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_WSS, "wss")

"wss" (WebSocket over TLS) as an interned string; you can compare this directly to a SoupURI's scheme field using ==.

Since: 2.50