![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
SoupURI; SoupURI* soup_uri_new_with_base (SoupURI *base, const char *uri_string); SoupURI* soup_uri_new (const char *uri_string); char* soup_uri_to_string (SoupURI *uri, gboolean just_path_and_query); SoupURI* soup_uri_copy (SoupURI *uri); gboolean soup_uri_equal (SoupURI *uri1, SoupURI *uri2); void soup_uri_free (SoupURI *uri); char* soup_uri_encode (const char *part, const char *escape_extra); char* soup_uri_decode (const char *part); char* soup_uri_normalize (const char *part, const char *unescape_extra); #define SOUP_URI_SCHEME_HTTP #define SOUP_URI_SCHEME_HTTPS gboolean soup_uri_uses_default_port (SoupURI *uri); #define SOUP_URI_VALID_FOR_HTTP (uri) void soup_uri_set_scheme (SoupURI *uri, const char *scheme); void soup_uri_set_user (SoupURI *uri, const char *user); void soup_uri_set_password (SoupURI *uri, const char *password); void soup_uri_set_host (SoupURI *uri, const char *host); void soup_uri_set_port (SoupURI *uri, guint port); void soup_uri_set_path (SoupURI *uri, const char *path); void soup_uri_set_query (SoupURI *uri, const char *query); void soup_uri_set_query_from_form (SoupURI *uri, GHashTable *form); void soup_uri_set_query_from_fields (SoupURI *uri, const char *first_field, ...); void soup_uri_set_fragment (SoupURI *uri, const char *fragment);
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.
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_urlencoded()
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.)
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
|
SoupURI* soup_uri_new_with_base (SoupURI *base, const char *uri_string);
Parses uri_string
relative to base
.
base : |
a base URI |
uri_string : |
the URI |
Returns : | a parsed SoupURI. |
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.)
uri_string : |
a URI |
Returns : | a SoupURI, or NULL .
|
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
.
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.
|
SoupURI* soup_uri_copy (SoupURI *uri);
Copies uri
uri : |
a SoupURI |
Returns : | a copy of uri , which must be freed with soup_uri_free()
|
gboolean soup_uri_equal (SoupURI *uri1, SoupURI *uri2);
Tests whether or not uri1
and uri2
are equal in all parts
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.
part : |
a URI part |
escape_extra : |
additional reserved characters to escape (or NULL )
|
Returns : | the encoded URI part |
char* soup_uri_decode (const char *part);
Fully %-decodes part
.
part : |
a URI part |
Returns : | the decoded URI part, or NULL if an invalid percent
code was encountered.
|
char* soup_uri_normalize (const char *part, const char *unescape_extra);
%-decodes any "unreserved" characters (or characters in
unescape_extra
) 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.
part : |
a URI part |
unescape_extra : |
reserved characters to unescape (or NULL )
|
Returns : | the normalized URI part, or NULL if an invalid percent
code was encountered.
|
#define SOUP_URI_SCHEME_HTTP (_SOUP_URI_SCHEME_HTTP ? _SOUP_URI_SCHEME_HTTP : (_SOUP_URI_SCHEME_HTTP = g_intern_static_string ("http")))
"http" as an interned string. This can be compared directly against
the value of a SoupURI's scheme
#define SOUP_URI_SCHEME_HTTPS (_SOUP_URI_SCHEME_HTTPS ? _SOUP_URI_SCHEME_HTTPS : (_SOUP_URI_SCHEME_HTTPS = g_intern_static_string ("https")))
"https" as an interned string. This can be compared directly
against the value of a SoupURI's scheme
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 and https; libsoup does not know
the default ports of other protocols.)
uri : |
a SoupURI |
Returns : | TRUE or FALSE
|
#define SOUP_URI_VALID_FOR_HTTP(uri) ((uri) && ((uri)->scheme == SOUP_URI_SCHEME_HTTP || (uri)->scheme == SOUP_URI_SCHEME_HTTPS) && (uri)->host)
Tests if uri
is a valid SoupURI for HTTP communication; that is, if
it can be used to construct a SoupMessage.
uri : |
a SoupURI |
Since 2.24
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.
uri : |
a SoupURI |
scheme : |
the URI scheme |
void soup_uri_set_user (SoupURI *uri, const char *user);
Sets uri
's user to user
.
uri : |
a SoupURI |
user : |
the username, or NULL
|
void soup_uri_set_password (SoupURI *uri, const char *password);
Sets uri
's password to password
.
uri : |
a SoupURI |
password : |
the password, or NULL
|
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.
uri : |
a SoupURI |
host : |
the hostname or IP address, or NULL
|
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.
uri : |
a SoupURI |
port : |
the port, or 0 |
void soup_uri_set_path (SoupURI *uri, const char *path);
Sets uri
's path to path
.
uri : |
a SoupURI |
path : |
the path |
void soup_uri_set_query (SoupURI *uri, const char *query);
Sets uri
's query to query
.
uri : |
a SoupURI |
query : |
the query |
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.
uri : |
a SoupURI |
form : |
a GHashTable containing HTML form information |
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.
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 .
|