soup_uri_new_with_base ()

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

Parses uri_string relative to base .

[constructor]

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.)

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.

soup_uri_copy ()

SoupURI *
soup_uri_copy (SoupURI *uri);

Copies uri

soup_uri_copy_host ()

SoupURI *
soup_uri_copy_host (SoupURI *uri);

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

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

soup_uri_host_equal ()

gboolean
soup_uri_host_equal (gconstpointer v1,
                     gconstpointer v2);

Compares v1 and v2 , considering only the 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.

Since: 2.28

soup_uri_free ()

void
soup_uri_free (SoupURI *uri);

Frees uri .

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.

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).

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).

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.)

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.

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.

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.

soup_uri_get_scheme ()

const char *
soup_uri_get_scheme (SoupURI *uri);

Gets 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 .

soup_uri_get_user ()

const char *
soup_uri_get_user (SoupURI *uri);

Gets 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 .

soup_uri_get_password ()

const char *
soup_uri_get_password (SoupURI *uri);

Gets 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 .

soup_uri_get_host ()

const char *
soup_uri_get_host (SoupURI *uri);

Gets 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.

soup_uri_get_port ()

guint
soup_uri_get_port (SoupURI *uri);

Gets 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 .

soup_uri_get_path ()

const char *
soup_uri_get_path (SoupURI *uri);

Gets 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 .

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.

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.

soup_uri_get_query ()

const char *
soup_uri_get_query (SoupURI *uri);

Gets 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 .

soup_uri_get_fragment ()

const char *
soup_uri_get_fragment (SoupURI *uri);

Gets uri 's fragment.

Since: 2.32

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.)

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