SoupURI: libsoup Reference Manual

## SoupURI SoupURI — URIs |

## Functions

SoupURI * | soup_uri_new_with_base ()
SoupURI * | soup_uri_new ()
char * | soup_uri_to_string ()
SoupURI * | soup_uri_copy ()
SoupURI * | soup_uri_copy_host ()
gboolean | soup_uri_equal ()
gboolean | soup_uri_host_equal ()
guint | soup_uri_host_hash ()
void | soup_uri_free ()
char * | soup_uri_encode ()
char * | soup_uri_decode ()
char * | soup_uri_normalize ()
gboolean | soup_uri_uses_default_port ()
#define | SOUP_URI_IS_VALID()
#define | SOUP_URI_VALID_FOR_HTTP()
void | soup_uri_set_scheme ()
const char * | soup_uri_get_scheme ()
void | soup_uri_set_user ()
const char * | soup_uri_get_user ()
void | soup_uri_set_password ()
const char * | soup_uri_get_password ()
void | soup_uri_set_host ()
const char * | soup_uri_get_host ()
void | soup_uri_set_port ()
guint | soup_uri_get_port ()
void | soup_uri_set_path ()
const char * | soup_uri_get_path ()
void | soup_uri_set_query ()
void | soup_uri_set_query_from_form ()
void | soup_uri_set_query_from_fields ()
const char * | soup_uri_get_query ()
void | soup_uri_set_fragment ()
const char * | soup_uri_get_fragment ()

## Types and Values

| SoupURI
#define | SOUP_URI_SCHEME_HTTP
#define | SOUP_URI_SCHEME_HTTPS
#define | SOUP_URI_SCHEME_DATA
#define | SOUP_URI_SCHEME_FILE
#define | SOUP_URI_SCHEME_FTP
#define | SOUP_URI_SCHEME_RESOURCE
#define | SOUP_URI_SCHEME_WS
#define | SOUP_URI_SCHEME_WSS

## 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` .

[constructor]

#### 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, or `NULL` |
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