Creates a #SoupAddress from @name and @port. The #SoupAddress's IP
address may not be available right away; the caller can call
soup_address_resolve_async() or soup_address_resolve_sync() to
force a DNS resolution.
a #SoupAddress
a hostname or physical address
a port number
Returns a #SoupAddress corresponding to the "any" address
for @family (or %NULL if @family isn't supported), suitable for
passing to soup_socket_server_new().
the new #SoupAddress
the address family
the port number (usually %SOUP_ADDRESS_ANY_PORT)
Returns a #SoupAddress equivalent to @sa (or %NULL if @sa's
address family isn't supported)
the new #SoupAddress
a pointer to a sockaddr
size of @sa
Tests if @addr1 and @addr2 have the same IP address. This method
can be used with soup_address_hash_by_ip() to create a
#GHashTable that hashes on IP address.
This would be used to distinguish hosts in situations where
different virtual hosts on the same IP address should be considered
the same. Eg, if "www.example.com" and "www.example.net" have the
same IP address, then a single #SoupConnection can be used to talk
to either of them.
See also soup_address_equal_by_name(), which compares by name
rather than by IP address.
address.
whether or not @addr1 and @addr2 have the same IP
a #SoupAddress with a resolved IP address
another #SoupAddress with a resolved IP address
Tests if @addr1 and @addr2 have the same "name". This method can be
used with soup_address_hash_by_name() to create a #GHashTable that
hashes on address "names".
Comparing by name normally means comparing the addresses by their
hostnames. But if the address was originally created using an IP
address literal, then it will be compared by that instead.
In particular, if "www.example.com" has the IP address 10.0.0.1,
and @addr1 was created with the name "www.example.com" and @addr2
was created with the name "10.0.0.1", then they will compare as
unequal for purposes of soup_address_equal_by_name().
This would be used to distinguish hosts in situations where
different virtual hosts on the same IP address should be considered
different. Eg, for purposes of HTTP authentication or cookies, two
hosts with the same IP address but different names are considered
to be different hosts.
See also soup_address_equal_by_ip(), which compares by IP address
rather than by name.
whether or not @addr1 and @addr2 have the same name
a #SoupAddress with a resolved name
another #SoupAddress with a resolved name
A hash function (for #GHashTable) that corresponds to
soup_address_equal_by_ip(), qv
the IP-based hash value for @addr.
a #SoupAddress
A hash function (for #GHashTable) that corresponds to
soup_address_equal_by_name(), qv
the named-based hash value for @addr.
a #SoupAddress
Creates a new #GSocketAddress corresponding to @addr (which is assumed
to only have one socket address associated with it).
a new #GSocketAddress
Returns the hostname associated with @addr.
This method is not thread-safe; if you call it while @addr is being
resolved in another thread, it may return garbage. You can use
soup_address_is_resolved() to safely test whether or not an address
is resolved before fetching its name or address.
the hostname, or %NULL if it is not known.
Returns the physical address associated with @addr as a string.
(Eg, "127.0.0.1"). If the address is not yet known, returns %NULL.
This method is not thread-safe; if you call it while @addr is being
resolved in another thread, it may return garbage. You can use
soup_address_is_resolved() to safely test whether or not an address
is resolved before fetching its name or address.
the physical address, or %NULL
Returns the port associated with @addr.
the port
Returns the sockaddr associated with @addr, with its length in
*@len. If the sockaddr is not yet known, returns %NULL.
This method is not thread-safe; if you call it while @addr is being
resolved in another thread, it may return garbage. You can use
soup_address_is_resolved() to safely test whether or not an address
is resolved before fetching its name or address.
the sockaddr, or %NULL
return location for sockaddr length
Tests if @addr has already been resolved. Unlike the other
#SoupAddress "get" methods, this is safe to call when @addr might
be being resolved in another thread.
%TRUE if @addr has been resolved.
Asynchronously resolves the missing half of @addr (its IP address
if it was created with soup_address_new(), or its hostname if it
was created with soup_address_new_from_sockaddr() or
soup_address_new_any().)
If @cancellable is non-%NULL, it can be used to cancel the
resolution. @callback will still be invoked in this case, with a
status of %SOUP_STATUS_CANCELLED.
It is safe to call this more than once on a given address, from the
same thread, with the same @async_context (and doing so will not
result in redundant DNS queries being made). But it is not safe to
call from multiple threads, or with different @async_contexts, or
mixed with calls to soup_address_resolve_sync().
the #GMainContext to call @callback from
a #GCancellable object, or %NULL
callback to call with the result
data for @callback
Synchronously resolves the missing half of @addr, as with
soup_address_resolve_async().
If @cancellable is non-%NULL, it can be used to cancel the
resolution. soup_address_resolve_sync() will then return a status
of %SOUP_STATUS_CANCELLED.
It is safe to call this more than once, even from different
threads, but it is not safe to mix calls to
soup_address_resolve_sync() with calls to
soup_address_resolve_async() on the same address.
%SOUP_STATUS_CANCELLED.
%SOUP_STATUS_OK, %SOUP_STATUS_CANT_RESOLVE, or
a #GCancellable object, or %NULL
The callback function passed to soup_address_resolve_async().
the #SoupAddress that was resolved
%SOUP_STATUS_OK, %SOUP_STATUS_CANT_RESOLVE, or %SOUP_STATUS_CANCELLED
the user data that was passed to soup_address_resolve_async()
The supported address families.
The abstract base class for handling authentication. Specific HTTP
Authentication mechanisms are implemented by its subclasses, but
applications never need to be aware of the specific subclasses
being used.
Creates a new #SoupAuth of type @type with the information from
This is called by #SoupSession; you will normally not create auths
yourself.
created
the new #SoupAuth, or %NULL if it could not be
the type of auth to create (a subtype of #SoupAuth)
the #SoupMessage the auth is being created for
the WWW-Authenticate/Proxy-Authenticate header
Call this on an auth to authenticate it; normally this will cause
the auth's message to be requeued with the new authentication info.
This does not cause the password to be saved to persistent storage;
see soup_auth_save_password() for that.
the username provided by the user or client
the password provided by the user or client
Generates an appropriate "Authorization" header for @msg. (The
session will only call this if soup_auth_is_authenticated()
returned %TRUE.)
the "Authorization" header, which must be freed.
the #SoupMessage to be authorized
Returns a list of paths on the server which @auth extends over.
(All subdirectories of these paths are also assumed to be part
of @auth's protection space, unless otherwise discovered not to
be.)
paths, which can be freed with soup_auth_free_protection_space().
the list of
the URI of the request that @auth was generated in response to.
Tests if @auth has been given a username and password
%TRUE if @auth has been given a username and password
Updates @auth with the information from @msg and @auth_header,
possibly un-authenticating it. As with soup_auth_new(), this is
normally only used by #SoupSession.
unauthenticated) #SoupAuth. %FALSE if something about @auth_params
could not be parsed or incorporated into @auth at all.
%TRUE if @auth is still a valid (but potentially
the #SoupMessage @auth is being updated for
Call this on an auth to authenticate it; normally this will cause
the auth's message to be requeued with the new authentication info.
This does not cause the password to be saved to persistent storage;
see soup_auth_save_password() for that.
the username provided by the user or client
the password provided by the user or client
Frees @space.
the return value from soup_auth_get_protection_space()
Generates an appropriate "Authorization" header for @msg. (The
session will only call this if soup_auth_is_authenticated()
returned %TRUE.)
the "Authorization" header, which must be freed.
the #SoupMessage to be authorized
Returns the host that @auth is associated with.
the hostname
Gets an opaque identifier for @auth, for use as a hash key or the
like. #SoupAuth objects from the same server with the same
identifier refer to the same authentication domain (eg, the URLs
associated with them take the same usernames and passwords).
the identifier
Returns a list of paths on the server which @auth extends over.
(All subdirectories of these paths are also assumed to be part
of @auth's protection space, unless otherwise discovered not to
be.)
paths, which can be freed with soup_auth_free_protection_space().
the list of
the URI of the request that @auth was generated in response to.
Returns @auth's realm. This is an identifier that distinguishes
separate authentication spaces on a given server, and may be some
string that is meaningful to the user. (Although it is probably not
localized.)
the realm name
Returns @auth's scheme name. (Eg, "Basic", "Digest", or "NTLM")
the scheme name
Tests if @auth has been given a username and password
%TRUE if @auth has been given a username and password
Tests whether or not @auth is associated with a proxy server rather
than an "origin" server.
%TRUE or %FALSE
Updates @auth with the information from @msg and @auth_header,
possibly un-authenticating it. As with soup_auth_new(), this is
normally only used by #SoupSession.
unauthenticated) #SoupAuth. %FALSE if something about @auth_params
could not be parsed or incorporated into @auth at all.
%TRUE if @auth is still a valid (but potentially
the #SoupMessage @auth is being updated for
the WWW-Authenticate/Proxy-Authenticate header
%TRUE if @auth is still a valid (but potentially
the #SoupMessage @auth is being updated for
the list of
the URI of the request that @auth was generated in response to.
the username provided by the user or client
the password provided by the user or client
%TRUE if @auth has been given a username and password
the "Authorization" header, which must be freed.
the #SoupMessage to be authorized
Checks if @msg authenticates to @domain via @username and
#SoupAuthDomainGenericAuthCallback.
whether or not the message is authenticated
a #SoupMessage
a username
a password
Checks if @msg contains appropriate authorization for @domain to
accept it. Mirroring soup_auth_domain_covers(), this does not check
whether or not @domain <emphasis>cares</emphasis> if @msg is
authorized.
This is used by #SoupServer internally and is probably of no use to
anyone else.
fact it has authenticated. %NULL otherwise.
the username that @msg has authenticated as, if in
a #SoupMessage
Adds @path to @domain, such that requests under @path on @domain's
server will require authentication (unless overridden by
soup_auth_domain_remove_path() or soup_auth_domain_set_filter()).
You can also add paths by setting the %SOUP_AUTH_DOMAIN_ADD_PATH
property, which can also be used to add one or more paths at
construct time.
the path to add to @domain
Sets the callback that @domain will use to authenticate incoming
requests. For each request containing authorization, @domain will
invoke the callback, and then either accept or reject the request
based on @callback's return value.
You can also set the auth callback by setting the
%SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK and
%SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA properties, which can also be
used to set the callback at construct time.
the callback
data to pass to @auth_callback
destroy notifier to free @user_data when @domain is destroyed
Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to @msg,
requesting that the client authenticate, and sets @msg's status
accordingly.
This is used by #SoupServer internally and is probably of no use to
anyone else.
a #SoupMessage
Checks if @msg authenticates to @domain via @username and
#SoupAuthDomainGenericAuthCallback.
whether or not the message is authenticated
a #SoupMessage
a username
a password
Checks if @domain requires @msg to be authenticated (according to
its paths and filter function). This does not actually look at
whether @msg <emphasis>is</emphasis> authenticated, merely whether
or not it needs to be.
This is used by #SoupServer internally and is probably of no use to
anyone else.
%TRUE if @domain requires @msg to be authenticated
a #SoupMessage
Sets the callback that @domain will use to authenticate incoming
requests. For each request containing authorization, @domain will
invoke the callback, and then either accept or reject the request
based on @callback's return value.
You can also set the auth callback by setting the
%SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK and
%SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA properties, which can also be
used to set the callback at construct time.
the callback
data to pass to @auth_callback
destroy notifier to free @user_data when @domain is destroyed
Gets the realm name associated with @domain
@domain's realm
Removes @path from @domain, such that requests under @path on
This is not simply an undo-er for soup_auth_domain_add_path(); it
can be used to "carve out" a subtree that does not require
authentication inside a hierarchy that does. Note also that unlike
with soup_auth_domain_add_path(), this cannot be overridden by
adding a filter, as filters can only bypass authentication that
would otherwise be required, not require it where it would
otherwise be unnecessary.
You can also remove paths by setting the
%SOUP_AUTH_DOMAIN_REMOVE_PATH property, which can also be used to
remove one or more paths at construct time.
the path to remove from @domain
Adds @filter as an authentication filter to @domain. The filter
gets a chance to bypass authentication for certain requests that
would otherwise require it. Eg, it might check the message's path
in some way that is too complicated to do via the other methods, or
it might check the message's method, and allow GETs but not PUTs.
The filter function returns %TRUE if the request should still
require authentication, or %FALSE if authentication is unnecessary
for this request.
To help prevent security holes, your filter should return %TRUE by
default, and only return %FALSE under specifically-tested
circumstances, rather than the other way around. Eg, in the example
above, where you want to authenticate PUTs but not GETs, you should
check if the method is GET and return %FALSE in that case, and then
return %TRUE for all other methods (rather than returning %TRUE for
PUT and %FALSE for all other methods). This way if it turned out
(now or later) that some paths supported additional methods besides
GET and PUT, those methods would default to being NOT allowed for
unauthenticated users.
You can also set the filter by setting the %SOUP_AUTH_DOMAIN_FILTER
and %SOUP_AUTH_DOMAIN_FILTER_DATA properties, which can also be
used to set the filter at construct time.
the auth filter for @domain
data to pass to @filter
destroy notifier to free @filter_data when @domain is destroyed
Sets @auth_callback as an authentication-handling callback for
authenticated via a domain-specific auth callback (eg,
#SoupAuthDomainDigestAuthCallback), the generic auth callback
will be invoked. See #SoupAuthDomainGenericAuthCallback for information
on what the callback should do.
the auth callback
data to pass to @auth_callback
destroy notifier to free @auth_data when @domain is destroyed
Creates a #SoupAuthDomainBasic. You must set the
%SOUP_AUTH_DOMAIN_REALM parameter, to indicate the realm name to be
returned with the authentication challenge to the client. Other
parameters are optional.
the new #SoupAuthDomain
name of first option, or %NULL
Callback used by #SoupAuthDomainBasic for authentication purposes.
The application should verify that @username and @password and valid
and return %TRUE or %FALSE.
If you are maintaining your own password database (rather than
using the password to authenticate against some other system like
PAM or a remote server), you should make sure you know what you are
doing. In particular, don't store cleartext passwords, or
easily-computed hashes of cleartext passwords, even if you don't
care that much about the security of your server, because users
will frequently use the same password for multiple sites, and so
compromising any site with a cleartext (or easily-cracked) password
database may give attackers access to other more-interesting sites
as well.
%TRUE if @username and @password are valid
the domain
the message being authenticated
the username provided by the client
the password provided by the client
the data passed to soup_auth_domain_basic_set_auth_callback()
whether or not the message is authenticated
a #SoupMessage
a username
a password
Creates a #SoupAuthDomainDigest. You must set the
%SOUP_AUTH_DOMAIN_REALM parameter, to indicate the realm name to be
returned with the authentication challenge to the client. Other
parameters are optional.
the new #SoupAuthDomain
name of first option, or %NULL
Encodes the username/realm/password triplet for Digest
authentication. (That is, it returns a stringified MD5 hash of
the form that is needed as the return value of
#SoupAuthDomainDigest's auth handler.
For security reasons, you should store the encoded hash, rather
than storing the cleartext password itself and calling this method
only when you need to verify it. This way, if your server is
compromised, the attackers will not gain access to cleartext
passwords which might also be usable at other sites. (Note also
that the encoded password returned by this method is identical to
the encoded password stored in an Apache .htdigest file.)
the encoded password
a username
an auth realm name
the password for @username in @realm
Callback used by #SoupAuthDomainDigest for authentication purposes.
The application should look up @username in its password database,
and return the corresponding encoded password (see
soup_auth_domain_digest_encode_password()).
valid user. @domain will free the password when it is done with it.
the encoded password, or %NULL if @username is not a
the domain
the message being authenticated
the username provided by the client
the data passed to soup_auth_domain_digest_set_auth_callback()
The prototype for a #SoupAuthDomain filter; see
soup_auth_domain_set_filter() for details.
%TRUE if @msg requires authentication, %FALSE if not.
a #SoupAuthDomain
a #SoupMessage
the data passed to soup_auth_domain_set_filter()
The prototype for a #SoupAuthDomain generic authentication callback.
The callback should look up the user's password, call
soup_auth_domain_check_password(), and use the return value from
that method as its own return value.
In general, for security reasons, it is preferable to use the
auth-domain-specific auth callbacks (eg,
#SoupAuthDomainBasicAuthCallback and
#SoupAuthDomainDigestAuthCallback), because they don't require
keeping a cleartext password database. Most users will use the same
password for many different sites, meaning if any site with a
cleartext password database is compromised, accounts on other
servers might be compromised as well. For many of the cases where
#SoupServer is used, this is not really relevant, but it may still
be worth considering.
%TRUE if @msg is authenticated, %FALSE if not.
a #SoupAuthDomain
the #SoupMessage being authenticated
the username from @msg
the data passed to soup_auth_domain_set_generic_auth_callback()
A data buffer, generally used to represent a chunk of a
#SoupMessageBody.
situations you may need to cast it to #guchar or another type.
Creates a new #SoupBuffer containing @length bytes from @data.
the new #SoupBuffer.
how @data is to be used by the buffer
data
length of @data
Creates a new #SoupBuffer containing @length bytes from @data.
This function is exactly equivalent to soup_buffer_new() with
%SOUP_MEMORY_TAKE as first argument; it exists mainly for
convenience and simplifying language bindings.
the new #SoupBuffer.
data
length of @data
Creates a new #SoupBuffer containing @length bytes from @data. When
the #SoupBuffer is freed, it will call @owner_dnotify, passing
For example, you could use this to create a buffer containing data
returned from libxml without needing to do an extra copy:
<informalexample><programlisting>
xmlDocDumpMemory (doc, &xmlbody, &len);
return soup_buffer_new_with_owner (xmlbody, len, xmlbody,
(GDestroyNotify)xmlFree);
</programlisting></informalexample>
In this example, @data and @owner are the same, but in other cases
they would be different (eg, @owner would be a object, and @data
would be a pointer to one of the object's fields).
the new #SoupBuffer.
data
length of @data
pointer to an object that owns @data
a function to free/unref @owner when the buffer is freed
Makes a copy of @buffer. In reality, #SoupBuffer is a refcounted
type, and calling soup_buffer_copy() will normally just increment
the refcount on @buffer and return it. However, if @buffer was
created with #SOUP_MEMORY_TEMPORARY memory, then soup_buffer_copy()
will actually return a copy of it, so that the data in the copy
will remain valid after the temporary buffer is freed.
the new (or newly-reffed) buffer
Frees @buffer. (In reality, as described in the documentation for
soup_buffer_copy(), this is actually an "unref" operation, and may
or may not actually free @buffer.)
This function exists for use by language bindings, because it's not
currently possible to get the right effect by annotating the fields
of #SoupBuffer.
the pointer to the buffer data is stored here
the length of the buffer data is stored here
Gets the "owner" object for a buffer created with
soup_buffer_new_with_owner().
the owner pointer
Creates a new #SoupBuffer containing @length bytes "copied" from
any data, but will instead simply reference the same data as
the new #SoupBuffer.
offset within @parent to start at
number of bytes to copy from @parent
The prototype for a chunk allocation callback. This should allocate
a new #SoupBuffer and return it for the I/O layer to read message
body data off the network into.
If @max_len is non-0, it indicates the maximum number of bytes that
could be read, based on what is known about the message size. Note
that this might be a very large number, and you should not simply
try to allocate that many bytes blindly. If @max_len is 0, that
means that libsoup does not know how many bytes remain to be read,
and the allocator should return a buffer of a size that it finds
convenient.
If the allocator returns %NULL, the message will be paused. It is
up to the application to make sure that it gets unpaused when it
becomes possible to allocate a new buffer.
the new buffer (or %NULL)
the #SoupMessage the chunk is being allocated for
the maximum length that will be read, or 0.
the data passed to soup_message_set_chunk_allocator()
A #SoupClientContext provides additional information about the
client making a particular request. In particular, you can use
soup_client_context_get_auth_domain() and
soup_client_context_get_auth_user() to determine if HTTP
authentication was used successfully.
soup_client_context_get_address() and/or
soup_client_context_get_host() can be used to get information for
logging or debugging purposes. soup_client_context_get_socket() may
also be of use in some situations (eg, tracking when multiple
requests are made on the same connection).
Retrieves the #SoupAddress associated with the remote end
of a connection.
remote end of a connection.
the #SoupAddress associated with the
Checks whether the request associated with @client has been
authenticated, and if so returns the #SoupAuthDomain that
authenticated it.
%NULL if the request was not authenticated.
a #SoupAuthDomain, or
Checks whether the request associated with @client has been
authenticated, and if so returns the username that the client
authenticated as.
was not authenticated.
the authenticated-as user, or %NULL if the request
Retrieves the IP address associated with the remote end of a
connection. (If you want the actual hostname, you'll have to call
soup_client_context_get_address() and then call the appropriate
#SoupAddress method to resolve it.)
connection.
the IP address associated with the remote end of a
Retrieves the #SoupSocket that @client is associated with.
If you are using this method to observe when multiple requests are
made on the same persistent HTTP connection (eg, as the ntlm-test
test program does), you will need to pay attention to socket
destruction as well (either by using weak references, or by
connecting to the #SoupSocket::disconnected signal), so that you do
not get fooled when the allocator reuses the memory address of a
previously-destroyed socket to represent a new socket.
associated with.
the #SoupSocket that @client is
Creates a new #SoupContentSniffer.
a new #SoupContentSniffer
An HTTP cookie.
generated from a string that appears to have no name, then @name
will be the empty string.
host/domain, to restrict this cookie to. If @domain starts with
".", that indicates a domain (which matches the string after the
".", or any hostname that has @domain as a suffix). Otherwise, it
is a hostname and must match exactly.
"expires" attribute, or the "max-age" attribute specified in RFC
2109. If @expires is %NULL, it indicates that neither "expires" nor
"max-age" was specified, and the cookie expires at the end of the
session.
If @http_only is set, the cookie should not be exposed to untrusted
code (eg, javascript), so as to minimize the danger posed by
cross-site scripting attacks.
Creates a new #SoupCookie with the given attributes. (Use
soup_cookie_set_secure() and soup_cookie_set_http_only() if you
need to set those attributes on the returned cookie.)
-1 to not include the attribute (indicating that the cookie expires
with the current session), 0 for an already-expired cookie, or a
lifetime in seconds. You can use the constants
%SOUP_COOKIE_MAX_AGE_ONE_HOUR, %SOUP_COOKIE_MAX_AGE_ONE_DAY,
%SOUP_COOKIE_MAX_AGE_ONE_WEEK and %SOUP_COOKIE_MAX_AGE_ONE_YEAR (or
multiples thereof) to calculate this value. (If you really care
about setting the exact time that the cookie will expire, use
soup_cookie_set_expires().)
a new #SoupCookie.
cookie name
cookie value
cookie domain or hostname
cookie path, or %NULL
max age of the cookie, or -1 for a session cookie
Tests if @cookie should be sent to @uri.
(At the moment, this does not check that @cookie's domain matches
But don't rely on that; it may change in the future.)
not
%TRUE if @cookie should be sent to @uri, %FALSE if
a #SoupURI
Copies @cookie.
a copy of @cookie
Checks if the @cookie's domain and @host match in the sense that
%TRUE if the domains match, %FALSE otherwise
a URI
Frees @cookie
Gets @cookie's domain
@cookie's domain
Gets @cookie's expiration time
owned by @cookie and should not be modified or freed.
@cookie's expiration time, which is
Gets @cookie's HttpOnly attribute
@cookie's HttpOnly attribute
Gets @cookie's name
@cookie's name
Gets @cookie's path
@cookie's path
Gets @cookie's secure attribute
@cookie's secure attribute
Gets @cookie's value
@cookie's value
Sets @cookie's domain to @domain
the new domain
Sets @cookie's expiration time to @expires. If @expires is %NULL,
client's session.
(This sets the same property as soup_cookie_set_max_age().)
the new expiration time, or %NULL
Sets @cookie's HttpOnly attribute to @http_only. If %TRUE, @cookie
will be marked as "http only", meaning it should not be exposed to
web page scripts or other untrusted code.
the new value for the HttpOnly attribute
Sets @cookie's max age to @max_age. If @max_age is -1, the cookie
is a session cookie, and will expire at the end of the client's
session. Otherwise, it is the number of seconds until the cookie
expires. You can use the constants %SOUP_COOKIE_MAX_AGE_ONE_HOUR,
%SOUP_COOKIE_MAX_AGE_ONE_DAY, %SOUP_COOKIE_MAX_AGE_ONE_WEEK and
%SOUP_COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate
this value. (A value of 0 indicates that the cookie should be
considered already-expired.)
(This sets the same property as soup_cookie_set_expires().)
the new max age
Sets @cookie's name to @name
the new name
Sets @cookie's path to @path
the new path
Sets @cookie's secure attribute to @secure. If %TRUE, @cookie will
only be transmitted from the client to the server over secure
(https) connections.
the new value for the secure attribute
Sets @cookie's value to @value
the new value
Serializes @cookie in the format used by the Cookie header (ie, for
returning a cookie from a #SoupSession to a server).
the header
Serializes @cookie in the format used by the Set-Cookie header
(ie, for sending a cookie from a #SoupServer to a client).
the header
Creates a new #SoupCookieJar. The base #SoupCookieJar class does
not support persistent storage of cookies; use a subclass for that.
a new #SoupCookieJar
Adds @cookie to @jar, emitting the 'changed' signal if we are modifying
an existing cookie or adding a valid new cookie ('valid' means
that the cookie's expire date is not in the past).
a #SoupCookie
Constructs a #GSList with every cookie inside the @jar.
The cookies in the list are a copy of the original, so
you have to free them when you are done with them.
the @jar.
a #GSList with all the cookies in
Deletes @cookie from @jar, emitting the 'changed' signal.
a #SoupCookie
the #SoupCookieJarAcceptPolicy set in the @jar
Retrieves (in Cookie-header form) the list of cookies that would
be sent with a request to @uri.
If @for_http is %TRUE, the return value will include cookies marked
"HttpOnly" (that is, cookies that the server wishes to keep hidden
from client-side scripting operations such as the JavaScript
document.cookies property). Since #SoupCookieJar sets the Cookie
header itself when making the actual HTTP request, you should
almost certainly be setting @for_http to %FALSE if you are calling
this.
cookies for @uri.
the cookies, in string form, or %NULL if there are no
a #SoupURI
whether or not the return value is being passed directly to an HTTP operation
Sets @policy as the cookie acceptance policy for @jar.
a #SoupCookieJarAcceptPolicy
Adds @cookie to @jar, exactly as though it had appeared in a
Set-Cookie header returned from a request to @uri.
Keep in mind that if the #SoupCookieJarAcceptPolicy
%SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY is set you'll need to use
soup_cookie_jar_set_cookie_with_first_party(), otherwise the jar
will have no way of knowing if the cookie is being set by a third
party or not.
the URI setting the cookie
the stringified cookie to set
Adds @cookie to @jar, exactly as though it had appeared in a
Set-Cookie header returned from a request to @uri. @first_party
will be used to reject cookies coming from third party resources in
case such a security policy is set in the @jar.
the URI setting the cookie
the URI for the main document
the stringified cookie to set
Creates a #SoupCookieJarText.
cookies. If @read_only is %FALSE, then the non-session cookies will
be written to @filename when the 'changed' signal is emitted from
the jar. (If @read_only is %TRUE, then the cookie jar will only be
used for this session, and changes made to it will be lost when the
jar is destroyed.)
the new #SoupCookieJar
the filename to read to/write from
%TRUE if @filename is read-only
A date and time. The date is assumed to be in the (proleptic)
Gregorian calendar. The time is in UTC if @utc is %TRUE. Otherwise,
the time is a local time, and @offset gives the offset from UTC in
minutes (such that adding @offset to the time would give the
correct UTC time). If @utc is %FALSE and @offset is 0, then the
%SoupDate represents a "floating" time with no associated timezone
information.
Creates a #SoupDate representing the indicated time, UTC.
a new #SoupDate
the year (1-9999)
the month (1-12)
the day of the month (1-31, as appropriate for @month)
the hour (0-23)
the minute (0-59)
the second (0-59, or up to 61 for leap seconds)
Creates a #SoupDate representing a time @offset_seconds after the
current time (or before it, if @offset_seconds is negative). If
offset_seconds is 0, returns the current time.
If @offset_seconds would indicate a time not expressible as a
#time_t, the return value will be clamped into range.
a new #SoupDate
offset from current time
Parses @date_string and tries to extract a date from it. This
recognizes all of the "HTTP-date" formats from RFC 2616, all ISO
8601 formats containing both a time and a date, RFC 2822 dates,
and reasonable approximations thereof. (Eg, it is lenient about
whitespace, leading "0"s, etc.)
be parsed.
a new #SoupDate, or %NULL if @date_string could not
the date in some plausible format
Creates a #SoupDate corresponding to @when
a new #SoupDate
a #time_t
Copies @date.
Frees @date.
Gets @date's day.
@date's day
Gets @date's hour.
@date's hour
Gets @date's minute.
@date's minute
Gets @date's month.
@date's month
Gets @date's offset from UTC.
returns %FALSE but soup_date_get_offset() returns 0, that means the
date is a "floating" time with no associated offset information.
@date's offset from UTC. If soup_date_get_utc()
Gets @date's second.
@date's second
Gets @date's UTC flag
%TRUE if @date is UTC.
Gets @date's year.
@date's year
Determines if @date is in the past.
%TRUE if @date is in the past
Converts @date to a string in the format described by @format.
@date as a string
the format to generate the date in
Converts @date to a %time_t.
If @date is not representable as a %time_t, it will be clamped into
range. (In particular, some HTTP cookies have expiration dates
after "Y2.038k" (2038-01-19T03:14:07Z).)
@date as a %time_t
Converts @date to a #GTimeVal.
a #GTimeVal structure in which to store the converted time.
Date formats that soup_date_to_string() can use.
UTC. @SOUP_DATE_ISO8601_XMLRPC uses the time as given, ignoring the
offset completely. @SOUP_DATE_RFC2822 and the other ISO 8601
variants use the local time, appending the offset information if
available.
This enum may be extended with more values in future releases.
How a message body is encoded for transport
Represents the parsed value of the "Expect" header.
Indicates the HTTP protocol version being used.
These represent the known HTTP status code values, plus various
network and internal errors.
Creates a new #SoupLogger with the given debug level. If @level is
%SOUP_LOGGER_LOG_BODY, @max_body_size gives the maximum number of
bytes of the body that will be logged. (-1 means "no limit".)
If you need finer control over what message parts are and aren't
logged, use soup_logger_set_request_filter() and
soup_logger_set_response_filter().
a new #SoupLogger
the debug level
the maximum body size to output, or -1
Sets @logger to watch @session and print debug information for
its messages.
(The session will take a reference on @logger, which will be
removed when you call soup_logger_detach(), or when the session is
destroyed.)
a #SoupSession
Stops @logger from watching @session.
a #SoupSession
Sets up an alternate log printing routine, if you don't want
the log to go to %stdout.
the callback for printing logging output
data to pass to the callback
a #GDestroyNotify to free @printer_data
Sets up a filter to determine the log level for a given request.
For each HTTP request @logger will invoke @request_filter to
determine how much (if any) of that request to log. (If you do not
set a request filter, @logger will just always log requests at the
level passed to soup_logger_new().)
the callback for request debugging
data to pass to the callback
a #GDestroyNotify to free @filter_data
Sets up a filter to determine the log level for a given response.
For each HTTP response @logger will invoke @response_filter to
determine how much (if any) of that response to log. (If you do not
set a response filter, @logger will just always log responses at
the level passed to soup_logger_new().)
the callback for response debugging
data to pass to the callback
a #GDestroyNotify to free @filter_data
The prototype for a logging filter. The filter callback will be
invoked for each request or response, and should analyze it and
return a #SoupLoggerLogLevel value indicating how much of the
message to log. Eg, it might choose between %SOUP_LOGGER_LOG_BODY
and %SOUP_LOGGER_LOG_HEADERS depending on the Content-Type.
the message to log
a #SoupLoggerLogLevel value indicating how much of
the #SoupLogger
the message being logged
the data passed to soup_logger_set_request_filter() or soup_logger_set_response_filter()
Describes the level of logging output to provide.
The prototype for a custom printing callback.
will be %SOUP_LOGGER_LOG_HEADERS if @data is header data.
to print; the printer is expected to add a terminating newline.
To get the effect of the default printer, you would do:
<informalexample><programlisting>
printf ("%c %s\n", direction, data);
</programlisting></informalexample>
the #SoupLogger
the level of the information being printed.
a single-character prefix to @data
data to print
the data passed to soup_logger_set_printer()
Describes how #SoupBuffer should use the data passed in by the
caller.
See also soup_buffer_new_with_owner(), which allows to you create a
buffer containing data which is owned by another object.
Represents an HTTP message being sent or received.
%SOUP_STATUS_OK, though of course it might actually be an unknown
status code. @reason_phrase is the actual text returned from the
server, which may or may not correspond to the "standard"
description of @status_code. At any rate, it is almost certainly
not localized, and not very descriptive even if it is in the user's
language; you should not use @reason_phrase in user-visible
messages. Rather, you should look at @status_code, and determine an
end-user-appropriate message based on that and on what you were
trying to do.
As described in the #SoupMessageBody documentation, the
be filled in at all times. When they are filled in, they will be
terminated with a '\0' byte (which is not included in the %length),
so you can use them as ordinary C strings (assuming that you know
that the body doesn't have any other '\0' bytes).
For a client-side #SoupMessage, @request_body's %data is usually
filled in right before libsoup writes the request to the network,
but you should not count on this; use soup_message_body_flatten()
if you want to ensure that %data is filled in. @response_body's
%data will be filled in before #SoupMessage::finished is emitted.
For a server-side #SoupMessage, @request_body's %data will be
filled in before #SoupMessage::got_body is emitted.
To prevent the %data field from being filled in at all (eg, if you
are handling the data from a #SoupMessage::got_chunk, and so don't
need to see it all at the end), call
soup_message_body_set_accumulate() on @response_body or
Creates a new empty #SoupMessage, which will connect to @uri
be parsed).
the new #SoupMessage (or %NULL if @uri could not
the HTTP method for the created request
the destination endpoint (as a string)
Creates a new empty #SoupMessage, which will connect to @uri
the new #SoupMessage
the HTTP method for the created request
the destination endpoint (as a #SoupURI)
Emits the %finished signal, indicating that @msg has been completely
processed.
Emits the %got_body signal, indicating that the IO layer finished
reading the body for @msg.
Emits the %got_chunk signal, indicating that the IO layer finished
reading a chunk of @msg's body.
the newly-read chunk
Emits the %got_headers signal, indicating that the IO layer
finished reading the (non-informational) headers for @msg.
Emits the %got_informational signal, indicating that the IO layer
read a complete informational (1xx) response for @msg.
Emits the %restarted signal, indicating that @msg should be
requeued.
Emits the %wrote_body signal, indicating that the IO layer finished
writing the body for @msg.
Emits the %wrote_chunk signal, indicating that the IO layer
finished writing a chunk of @msg's body.
Emits the %wrote_headers signal, indicating that the IO layer
finished writing the (non-informational) headers for @msg.
Emits the %wrote_informational signal, indicating that the IO layer
finished writing an informational (1xx) response for @msg.
Adds a signal handler to @msg for @signal, as with
only be run if @msg has a header named @header, and it will only be
run if no earlier handler cancelled or requeued the message.
If @signal is one of the "got" signals (eg, "got_headers"), or
"finished" or "restarted", then @header is matched against the
incoming message headers (that is, the #request_headers for a
client #SoupMessage, or the #response_headers for a server
#SoupMessage). If @signal is one of the "wrote" signals, then
the handler ID from g_signal_connect()
signal to connect the handler to.
HTTP response header to match against
the header handler
data to pass to @handler_cb
Adds a signal handler to @msg for @signal, as with
only be run if @msg has the status @status_code, and it will only
be run if no earlier handler cancelled or requeued the message.
is set. For a client #SoupMessage, this means it can't be a "wrote"
signal. For a server #SoupMessage, this means it can't be a "got"
signal.
the handler ID from g_signal_connect()
signal to connect the handler to.
status code to match against
the header handler
data to pass to @handler_cb
Emits the %content_sniffed signal, indicating that the IO layer
finished sniffing the content type for @msg. If content sniffing
will not be performed, due to the sniffer deciding to trust the
Content-Type sent by the server, this signal is emitted immediately
after %got_headers, with %NULL as @content_type.
a #GHashTable with the parameters
This disables the actions of #SoupSessionFeature<!-- -->s with the
given @feature_type (or a subclass of that type) on @msg, so that
session. Eg, passing #SOUP_TYPE_PROXY_RESOLVER for @feature_type
will disable proxy handling and cause @msg to be sent directly to
the indicated origin server, regardless of system proxy
configuration.
You must call this before queueing @msg on a session; calling it on
a message that has already been queued is undefined. In particular,
you cannot call this on a message that is being requeued after a
redirect or authentication.
the #GType of a #SoupSessionFeature
Emits the %finished signal, indicating that @msg has been completely
processed.
Gets the address @msg's URI points to. After first setting the
URI on a message, this will be unresolved, although the message's
session will resolve it before sending the message.
the address @msg's URI points to
the @msg's first party #SoupURI
Gets the flags on @msg
the flags
Gets the HTTP version of @msg. This is the minimum of the
version from the request and the version from the response.
the HTTP version
If @msg is using https, this retrieves the #GTlsCertificate
associated with its connection, and the #GTlsCertificateFlags showing
what problems, if any, have been found with that certificate.
%TRUE if @msg uses https, %FALSE if not
@msg's TLS certificate
the verification status of @certificate
Gets @msg's URI
the URI @msg is targeted for.
Emits the %got_body signal, indicating that the IO layer finished
reading the body for @msg.
Emits the %got_chunk signal, indicating that the IO layer finished
reading a chunk of @msg's body.
the newly-read chunk
Emits the %got_headers signal, indicating that the IO layer
finished reading the (non-informational) headers for @msg.
Emits the %got_informational signal, indicating that the IO layer
read a complete informational (1xx) response for @msg.
Determines whether or not @msg's connection can be kept alive for
further requests after processing @msg, based on the HTTP version,
Connection header, etc.
%TRUE or %FALSE.
Emits the %restarted signal, indicating that @msg should be
requeued.
Sets an alternate chunk-allocation function to use when reading
call @allocator, which should return a #SoupBuffer. (See
#SoupChunkAllocator for additional details.) Libsoup will then read
data from the network into that buffer, and update the buffer's
%length to indicate how much data it read.
Generally, a custom chunk allocator would be used in conjunction
with soup_message_body_set_accumulate() %FALSE and
#SoupMessage::got_chunk, as part of a strategy to avoid unnecessary
copying of data. However, you cannot assume that every call to the
allocator will be followed by a call to your %got_chunk handler; if
an I/O error occurs, then the buffer will be unreffed without ever
having been used. If your buffer-allocation strategy requires
special cleanup, use soup_buffer_new_with_owner() rather than doing
the cleanup from the %got_chunk handler.
The other thing to remember when using non-accumulating message
bodies is that the buffer passed to the %got_chunk handler will be
unreffed after the handler returns, just as it would be in the
non-custom-allocated case. If you want to hand the chunk data off
to some other part of your program to use later, you'll need to ref
the #SoupBuffer (or its owner, in the soup_buffer_new_with_owner()
case) to ensure that the data remains valid.
the chunk allocator callback
data to pass to @allocator
destroy notifier to free @user_data when @msg is destroyed
Sets @first_party as the main document #SoupURI for @msg. For
details of when and how this is used refer to the documentation for
#SoupCookieJarAcceptPolicy.
the #SoupURI for the @msg's first party
Sets the specified flags on @msg.
a set of #SoupMessageFlags values
Sets the HTTP version on @msg. The default version is
%SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain
functionality from being used.
the HTTP version
Convenience function to set the request body of a #SoupMessage. If
MIME Content-Type of the body
a #SoupMemoryUse describing how to handle @req_body
a data buffer containing the body of the message request.
the byte length of @req_body.
Convenience function to set the response body of a #SoupMessage. If
MIME Content-Type of the body
a #SoupMemoryUse describing how to handle @resp_body
a data buffer containing the body of the message response.
the byte length of @resp_body.
Sets @msg's status code to @status_code. If @status_code is a
known value, it will also set @msg's reason_phrase.
an HTTP status code
Sets @msg's status code and reason phrase.
an HTTP status code
a description of the status
Sets @msg's URI to @uri. If @msg has already been sent and you want
to re-send it with the new URI, you need to call
soup_session_requeue_message().
the new #SoupURI
Emits the %wrote_body signal, indicating that the IO layer finished
writing the body for @msg.
Emits the %wrote_body_data signal, indicating that the IO layer
finished writing a portion of @msg's body.
the data written
Emits the %wrote_chunk signal, indicating that the IO layer
finished writing a chunk of @msg's body.
Emits the %wrote_headers signal, indicating that the IO layer
finished writing the (non-informational) headers for @msg.
Emits the %wrote_informational signal, indicating that the IO layer
finished writing an informational (1xx) response for @msg.
A #SoupMessage request or response body.
Note that while @length always reflects the full length of the
message body, @data is normally %NULL, and will only be filled in
after soup_message_body_flatten() is called. For client-side
messages, this automatically happens for the response body after it
has been fully read, unless you set the
%SOUP_MESSAGE_OVERWRITE_CHUNKS flags. Likewise, for server-side
messages, the request body is automatically filled in after being
read.
As an added bonus, when @data is filled in, it is always terminated
with a '\0' byte (which is not reflected in @length).
Creates a new #SoupMessageBody. #SoupMessage uses this internally; you
will not normally need to call it yourself.
a new #SoupMessageBody.
Appends @length bytes from @data to @body according to @use.
how to use @data
data to append
length of @data
Appends the data from @buffer to @body. (#SoupMessageBody uses
#SoupBuffers internally, so this is normally a constant-time
operation that doesn't actually require copying the data in
a #SoupBuffer
Appends @length bytes from @data to @body.
This function is exactly equivalent to soup_message_body_apppend()
with %SOUP_MEMORY_TAKE as second argument; it exists mainly for
convenience and simplifying language bindings.
data to append
length of @data
Tags @body as being complete; Call this when using chunked encoding
after you have appended the last chunk.
Fills in @body's data field with a buffer containing all of the
data in @body (plus an additional '\0' byte not counted by @body's
length field).
(You must free this buffer if you do not want it.)
a #SoupBuffer containing the same data as @body.
Frees @body. You will not normally need to use this, as
#SoupMessage frees its associated message bodies automatically.
Gets the accumulate flag on @body; see
soup_message_body_set_accumulate() for details.
the accumulate flag for @body.
Gets a #SoupBuffer containing data from @body starting at @offset.
The size of the returned chunk is unspecified. You can iterate
through the entire body by first calling
soup_message_body_get_chunk() with an offset of 0, and then on each
successive call, increment the offset by the length of the
previously-returned chunk.
If @offset is greater than or equal to the total length of @body,
then the return value depends on whether or not
soup_message_body_complete() has been called or not; if it has,
then soup_message_body_get_chunk() will return a 0-length chunk
(indicating the end of @body). If it has not, then
soup_message_body_get_chunk() will return %NULL (indicating that
currently available).
a #SoupBuffer, or %NULL.
an offset
Handles the #SoupMessageBody part of receiving a chunk of data from
the network. Normally this means appending @chunk to @body, exactly
as with soup_message_body_append_buffer(), but if you have set
This is a low-level method which you should not normally need to
use.
a #SoupBuffer received from the network
Sets or clears the accumulate flag on @body. (The default value is
%TRUE.) If set to %FALSE, @body's %data field will not be filled in
after the body is fully sent/received, and the chunks that make up
In particular, if you set this flag to %FALSE on an "incoming"
message body (that is, the %response_body of a client-side message,
or %request_body of a server-side message), this will cause each
chunk of the body to be discarded after its corresponding
#SoupMessage::got_chunk signal is emitted. (This is equivalent to
setting the deprecated %SOUP_MESSAGE_OVERWRITE_CHUNKS flag on the
message.)
If you set this flag to %FALSE on the %response_body of a
server-side message, it will cause each chunk of the body to be
discarded after its corresponding #SoupMessage::wrote_chunk signal
is emitted.
(If you set the flag to %FALSE on the %request_body of a
client-side message, it will block the accumulation of chunks into
discarded after being written like in the server-side
%response_body case, because the request body needs to be kept
around in case the request needs to be sent a second time due to
redirection or authentication.)
whether or not to accumulate body chunks in @body
Deletes all of the data in @body.
Handles the #SoupMessageBody part of writing a chunk of data to the
network. Normally this is a no-op, but if you have set @body's
accumulate flag to %FALSE, then this will cause @chunk to be
discarded to free up memory.
This is a low-level method which you should not need to use, and
there are further restrictions on its proper use which are not
documented here.
a #SoupBuffer returned from soup_message_body_get_chunk()
the newly-read chunk
Various flags that can be set on a #SoupMessage to alter its
behavior.
Creates a #SoupMessageHeaders. (#SoupMessage does this
automatically for its own headers. You would only need to use this
method if you are manually parsing or generating message headers.)
a new #SoupMessageHeaders
the type of headers
Appends a new header with name @name and value @value to @hdrs. (If
there is an existing header with name @name, then this creates a
second one, which is only allowed for list-valued headers; see also
soup_message_headers_replace().)
The caller is expected to make sure that @name and @value are
syntactically correct.
the header name to add
the new value of @name
Clears @hdrs.
Calls @func once for each header value in @hdrs.
Beware that unlike soup_message_headers_get(), this processes the
headers in exactly the way they were added, rather than
concatenating multiple same-named headers into a single value.
(This is intentional; it ensures that if you call
soup_message_headers_append() multiple times with the same name,
then the I/O code will output multiple copies of the header when
sending the message to the remote implementation, which may be
required for interoperability in some cases.)
You may not modify the headers from @func.
callback function to run for each header
data to pass to @func
Frees @hdrs.
Frees the array of ranges returned from soup_message_headers_get_ranges().
an array of #SoupRange
Gets the value of header @name in @hdrs.
This method was supposed to work correctly for both single-valued
and list-valued headers, but because some HTTP clients/servers
mistakenly send multiple copies of headers that are supposed to be
single-valued, it sometimes returns incorrect results. To fix this,
the methods soup_message_headers_get_one() and
soup_message_headers_get_list() were introduced, so callers can
explicitly state which behavior they are expecting.
soup_message_headers_get_list() instead.
as with soup_message_headers_get_list().
header name
Looks up the "Content-Disposition" header in @hdrs, parses it, and
returns its value in *@disposition and *@params. @params can be
%NULL if you are only interested in the disposition-type.
In HTTP, the most common use of this header is to set a
disposition-type of "attachment", to suggest to the browser that a
response should be saved to disk rather than displayed in the
browser. If @params contains a "filename" parameter, this is a
suggestion of a filename to use. (If the parameter value in the
header contains an absolute or relative path, libsoup will truncate
it down to just the final path component, so you do not need to
test this yourself.)
Content-Disposition is also used in "multipart/form-data", however
this is handled automatically by #SoupMultipart and the associated
form methods.
header, %FALSE if not (in which case *@disposition and *@params
will be unchanged).
%TRUE if @hdrs contains a "Content-Disposition"
return location for the disposition-type, or %NULL
return location for the Content-Disposition parameters, or %NULL
Gets the message body length that @hdrs declare. This will only
be non-0 if soup_message_headers_get_encoding() returns
%SOUP_ENCODING_CONTENT_LENGTH.
the message body length declared by @hdrs.
Parses @hdrs's Content-Range header and returns it in @start,
was specified as "*", then @total_length will be set to -1.
containing a byte range which could be parsed, %FALSE otherwise.
%TRUE if @hdrs contained a "Content-Range" header
return value for the start of the range
return value for the end of the range
return value for the total length of the resource, or %NULL if you don't care.
Looks up the "Content-Type" header in @hdrs, parses it, and returns
its value in *@content_type and *@params. @params can be %NULL if you
are only interested in the content type itself.
or NULL if @hdrs does not contain that header or it cannot be
parsed (in which case *@params will be unchanged).
a string with the value of the "Content-Type" header
return location for the Content-Type parameters (eg, "charset"), or %NULL
Gets the message body encoding that @hdrs declare. This may not
always correspond to the encoding used on the wire; eg, a HEAD
response may declare a Content-Length or Transfer-Encoding, but
it will never actually include a body.
the encoding declared by @hdrs.
Gets the expectations declared by @hdrs's "Expect" header.
Currently this will either be %SOUP_EXPECTATION_CONTINUE or
%SOUP_EXPECTATION_UNRECOGNIZED.
the contents of @hdrs's "Expect" header
Gets the value of header @name in @hdrs. Use this for headers whose
values are comma-delimited lists, and which are therefore allowed
to appear multiple times in the headers. For non-list-valued
headers, use soup_message_headers_get_one().
If @name appears multiple times in @hdrs,
soup_message_headers_get_list() will concatenate all of the values
together, separated by commas. This is sometimes awkward to parse
(eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal
with it anyway, because the HTTP spec explicitly states that this
transformation is allowed, and so an upstream proxy could do the
same thing.
the header's value or %NULL if not found.
header name
Gets the value of header @name in @hdrs. Use this for headers whose
values are <emphasis>not</emphasis> comma-delimited lists, and
which therefore can only appear at most once in the headers. For
list-valued headers, use soup_message_headers_get_list().
If @hdrs does erroneously contain multiple copies of the header, it
is not defined which one will be returned. (Ideally, it will return
whichever one makes libsoup most compatible with other HTTP
implementations.)
the header's value or %NULL if not found.
header name
Parses @hdrs's Range header and returns an array of the requested
byte ranges. The returned array must be freed with
soup_message_headers_free_ranges().
If @total_length is non-0, its value will be used to adjust the
returned ranges to have explicit start and end values, and the
returned ranges will be sorted and non-overlapping. If
as described under #SoupRange, and some of the ranges may be
redundant.
byte ranges which could be parsed, %FALSE otherwise (in which case
%TRUE if @hdrs contained a "Range" header containing
the total_length of the response body
return location for an array of #SoupRange
the length of the returned array
Removes @name from @hdrs. If there are multiple values for @name,
they are all removed.
the header name to remove
Replaces the value of the header @name in @hdrs with @value. (See
also soup_message_headers_append().)
The caller is expected to make sure that @name and @value are
syntactically correct.
the header name to replace
the new value of @name
Sets the "Content-Disposition" header in @hdrs to @disposition,
optionally with additional parameters specified in @params.
See soup_message_headers_get_content_disposition() for a discussion
of how Content-Disposition is used in HTTP.
the disposition-type
additional parameters, or %NULL
Sets the message body length that @hdrs will declare, and sets
You do not normally need to call this; if @hdrs is set to use
Content-Length encoding, libsoup will automatically set its
Content-Length header for you immediately before sending the
headers. One situation in which this method is useful is when
generating the response to a HEAD request; Calling
soup_message_headers_set_content_length() allows you to put the
correct content length into the response without needing to waste
memory by filling in a response body which won't actually be sent.
the message body length
Sets @hdrs's Content-Range header according to the given values.
(Note that @total_length is the total length of the entire resource
that this is a range of, not simply @end - @start + 1.)
the start of the range
the end of the range
the total length of the resource, or -1 if unknown
Sets the "Content-Type" header in @hdrs to @content_type,
optionally with additional parameters specified in @params.
the MIME type
additional parameters, or %NULL
Sets the message body encoding that @hdrs will declare. In particular,
you should use this if you are going to send a request or response in
chunked encoding.
a #SoupEncoding
Sets @hdrs's "Expect" header according to @expectations.
Currently %SOUP_EXPECTATION_CONTINUE is the only known expectation
value. You should set this value on a request if you are sending a
large message body (eg, via POST or PUT), and want to give the
server a chance to reject the request after seeing just the headers
(eg, because it will require authentication before allowing you to
post, or because you're POSTing to a URL that doesn't exist). This
saves you from having to transmit the large request body when the
server is just going to ignore it anyway.
the expectations to set
Sets @hdrs's Range header to request the indicated range.
If you need to request multiple ranges, use
soup_message_headers_set_ranges().
the start of the range to request
the end of the range to request
Sets @hdrs's Range header to request the indicated ranges. (If you
only want to request a single range, you can use
soup_message_headers_set_range().)
an array of #SoupRange
the length of @range
The callback passed to soup_message_headers_foreach().
the header name
the header value
the data passed to soup_message_headers_foreach()
An opaque type used to iterate over a %SoupMessageHeaders
structure.
After intializing the iterator with
soup_message_headers_iter_init(), call
soup_message_headers_iter_next() to fetch data from it.
You may not modify the headers while iterating over them.
Initializes @iter for iterating @hdrs.
a %SoupMessageHeaders
Yields the next name/value pair in the %SoupMessageHeaders being
iterated by @iter. If @iter has already yielded the last header,
then soup_message_headers_iter_next() will return %FALSE and @name
and @value will be unchanged.
if the end of the headers has been reached.
%TRUE if another name and value were returned, %FALSE
pointer to a variable to return the header name in
pointer to a variable to return the header value in
Value passed to soup_message_headers_new() to set certain default
behaviors.
Represents a multipart HTTP message body, parsed according to the
syntax of RFC 2046. Of particular interest to HTTP are
<literal>multipart/byte-ranges</literal> and
<literal>multipart/form-data</literal>.
Although the headers of a #SoupMultipart body part will contain the
full headers from that body part, libsoup does not interpret them
according to MIME rules. For example, each body part is assumed to
have "binary" Content-Transfer-Encoding, even if its headers
explicitly state otherwise. In other words, don't try to use
#SoupMultipart for handling real MIME multiparts.
Creates a new empty #SoupMultipart with a randomly-generated
boundary string. Note that @mime_type must be the full MIME type,
including "multipart/".
a new empty #SoupMultipart of the given @mime_type
the MIME type of the multipart to create.
Parses @headers and @body to form a new #SoupMultipart
be parsed or wasn't multipart).
a new #SoupMultipart (or %NULL if the message couldn't
the headers of the HTTP message to parse
the body of the HTTP message to parse
Adds a new MIME part containing @body to @multipart, using
"Content-Disposition: form-data", as per the HTML forms
specification. See soup_form_request_new_from_multipart() for more
details.
the name of the control associated with this file
the name of the file, or %NULL if not known
the MIME type of the file, or %NULL if not known
the file data
Adds a new MIME part containing @data to @multipart, using
"Content-Disposition: form-data", as per the HTML forms
specification. See soup_form_request_new_from_multipart() for more
details.
the name of the control associated with @data
the body data
Adds a new MIME part to @multipart with the given headers and body.
(The multipart will make its own copies of @headers and @body, so
you should free your copies if you are not using them for anything
else.)
the MIME part headers
the MIME part body
Frees @multipart
Gets the number of body parts in @multipart
the number of body parts in @multipart
Gets the indicated body part from @multipart.
which case @headers and @body won't be set)
%TRUE on success, %FALSE if @part is out of range (in
the part number to get (counting from 0)
return location for the MIME part headers
return location for the MIME part body
Serializes @multipart to @dest_headers and @dest_body.
the headers of the HTTP message to serialize @multipart to
the body of the HTTP message to serialize @multipart to
Asynchronously determines a proxy URI to use for @msg and calls
the #SoupURI you want a proxy for
the #GMainContext to invoke @callback in
a #GCancellable, or %NULL
callback to invoke with the proxy address
data for @callback
Synchronously determines a proxy URI to use for @uri. If @uri
should be sent via proxy, *@proxy_uri will be set to the URI of the
proxy, else it will be set to %NULL.
error.
%SOUP_STATUS_OK if successful, or a transport-level
the #SoupURI you want a proxy for
a #GCancellable, or %NULL
on return, will contain the proxy URI
Asynchronously determines a proxy URI to use for @msg and calls
the #SoupURI you want a proxy for
the #GMainContext to invoke @callback in
a #GCancellable, or %NULL
callback to invoke with the proxy address
data for @callback
Synchronously determines a proxy URI to use for @uri. If @uri
should be sent via proxy, *@proxy_uri will be set to the URI of the
proxy, else it will be set to %NULL.
error.
%SOUP_STATUS_OK if successful, or a transport-level
the #SoupURI you want a proxy for
a #GCancellable, or %NULL
on return, will contain the proxy URI
Callback for soup_proxy_uri_resolver_get_proxy_uri_async()
the #SoupProxyURIResolver
a #SoupKnownStatusCode
the resolved proxy URI, or %NULL
data passed to soup_proxy_uri_resolver_get_proxy_uri_async()
the #SoupURI you want a proxy for
the #GMainContext to invoke @callback in
a #GCancellable, or %NULL
callback to invoke with the proxy address
data for @callback
%SOUP_STATUS_OK if successful, or a transport-level
the #SoupURI you want a proxy for
a #GCancellable, or %NULL
on return, will contain the proxy URI
Represents a byte range as used in the Range header.
If @end is non-negative, then @start and @end represent the bounds
of of the range, counting from %0. (Eg, the first 500 bytes would be
represented as @start = %0 and @end = %499.)
If @end is %-1 and @start is non-negative, then this represents a
range starting at @start and ending with the last byte of the
requested resource body. (Eg, all but the first 500 bytes would be
If @end is %-1 and @start is negative, then it represents a "suffix
range", referring to the last -@start bytes of the resource body.
(Eg, the last 500 bytes would be @start = %-500 and @end = %-1.)
SSL-related I/O errors.
Creates a new #SoupServer.
a new #SoupServer
name of first property to set
Adds an authentication domain to @server. Each auth domain will
have the chance to require authentication for each request that
comes in; normally auth domains will require authentication for
requests on certain paths that they have been set up to watch, or
that meet other criteria set by the caller. If an auth domain
determines that a request requires authentication (and the request
doesn't contain authentication), @server will automatically reject
the request with an appropriate status (401 Unauthorized or 407
Proxy Authentication Required). If the request used the
"100-continue" Expectation, @server will reject it before the
request body is sent.
a #SoupAuthDomain
Adds a handler to @server for requests under @path. See the
documentation for #SoupServerCallback for information about
how callbacks should behave.
If @path is %NULL or "/", then this will be the default handler for
all requests that don't have a more specific handler. Note though
that if you want to handle requests to the special "*" URI, you
must explicitly register a handler for "*"; the default handler
will not be used for that case.
the toplevel path for the handler
callback to invoke for requests under @path
data for @callback
destroy notifier to free @user_data
Stops processing for @server and closes its socket. This implies
the effects of soup_server_quit(), but additionally closes the
listening socket. Note that messages currently in progress will
continue to be handled, if the main loop associated with the
server is resumed or kept running.
After calling this function, @server is no longer functional, so it
has nearly the same effect as destroying @server entirely. The
function is thus useful mainly for language bindings without
explicit control over object lifetime.
Gets @server's async_context. This does not add a ref to the
context, so you will need to ref it yourself if you want it to
outlive its server.
@server's #GMainContext, which may be %NULL
Gets @server's listening socket. You should treat this as
read-only; writing to it or modifiying it may cause @server to
malfunction.
the listening socket.
Gets the TCP port that @server is listening on. This is most useful
when you did not request a specific port (or explicitly requested
%SOUP_ADDRESS_ANY_PORT).
the port @server is listening on.
Checks whether @server is running plain http or https.
In order for a server to run https, you must set the
%SOUP_SERVER_SSL_CERT_FILE and %SOUP_SERVER_SSL_KEY_FILE properties
to provide it with an SSL certificate to use.
%TRUE if @server is serving https.
Pauses I/O on @msg. This can be used when you need to return from
the server handler without having the full response ready yet. Use
soup_server_unpause_message() to resume I/O.
a #SoupMessage associated with @server.
Stops processing for @server. Call this to clean up after
soup_server_run_async(), or to terminate a call to soup_server_run().
and stop a server as many times as you want.
Removes @auth_domain from @server.
a #SoupAuthDomain
Removes the handler registered at @path.
the toplevel path for the handler
Starts @server, causing it to listen for and process incoming
connections. Unlike soup_server_run_async(), this creates a
#GMainLoop and runs it, and it will not return until someone calls
soup_server_quit() to stop the server.
Starts @server, causing it to listen for and process incoming
connections.
The server actually runs in @server's #GMainContext. It will not
actually perform any processing unless the appropriate main loop is
running. In the simple case where you did not set the server's
%SOUP_SERVER_ASYNC_CONTEXT property, this means the server will run
whenever the glib main loop is running.
Resumes I/O on @msg. Use this to resume after calling
soup_server_pause_message(), or after adding a new chunk to a
chunked response.
I/O won't actually resume until you return to the main loop.
a #SoupMessage associated with @server.
A callback used to handle requests to a #SoupServer. The callback
will be invoked after receiving the request body; @msg's %method,
%request_headers, and %request_body fields will be filled in.
Request-URI, subject to certain assumptions. By default,
#SoupServer decodes all percent-encoding in the URI path, such that
"/foo%<!-- -->2Fbar" is treated the same as "/foo/bar". If your
server is serving resources in some non-POSIX-filesystem namespace,
you may want to distinguish those as two distinct paths. In that
case, you can set the %SOUP_SERVER_RAW_PATHS property when creating
the #SoupServer, and it will leave those characters undecoded. (You
may want to call soup_uri_normalize() to decode any percent-encoded
characters that you aren't handling specially.)
according to the rules for HTML form handling. Although this is the
only commonly-used query string format in HTTP, there is nothing
that actually requires that HTTP URIs use that format; if your
server needs to use some other format, you can just ignore @query,
and call soup_message_get_uri() and parse the URI's query field
yourself.
After determining what to do with the request, the callback must at
a minimum call soup_message_set_status() (or
soup_message_set_status_full()) on @msg to set the response status
code. Additionally, it may set response headers and/or fill in the
response body.
If the callback cannot fully fill in the response before returning
(eg, if it needs to wait for information from a database, or
another network server), it should call soup_server_pause_message()
to tell #SoupServer to not send the response right away. When the
response is ready, call soup_server_unpause_message() to cause it
to be sent.
To send the response body a bit at a time using "chunked" encoding,
first call soup_message_headers_set_encoding() to set
%SOUP_ENCODING_CHUNKED on the %response_headers. Then call
soup_message_body_append() (or soup_message_body_append_buffer())
to append each chunk as it becomes ready, and
soup_server_unpause_message() to make sure it's running. (The
server will automatically pause the message if it is using chunked
encoding but no more chunks are available.) When you are done, call
soup_message_body_complete() to indicate that no more chunks are
coming.
the #SoupServer
the message being processed
the path component of @msg's Request-URI
the parsed query component of @msg's Request-URI
additional contextual information about the client
the data passed to @soup_server_add_handler
Causes @session to immediately finish processing @msg (regardless
of its current state) with a final status_code of @status_code. You
may call this at any time after handing @msg off to @session; if
the complete response, then it will close the request's connection.
Note that with non-idempotent requests (eg, %POST, %PUT, %DELETE)
it is possible that you might cancel the request after the server
acts on it, but before it returns a response, leaving the remote
resource in an unknown state.
If the message is cancelled while its response body is being read,
then the response body in @msg will be left partially-filled-in.
The response headers, on the other hand, will always be either
empty or complete.
For messages queued with soup_session_queue_message() (and
cancelled from the same thread), the callback will be invoked
before soup_session_cancel_message() returns.
the message to cancel
status code to set on @msg (generally %SOUP_STATUS_CANCELLED)
Queues the message @msg for sending. All messages are processed
while the glib main loop runs. If @msg has been processed before,
any resources related to the time it was last sent are freed.
Upon message completion, the callback specified in @callback will
be invoked (in the thread associated with @session's async
context). If after returning from this callback the message has not
been requeued, @msg will be unreffed.
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
a pointer passed to @callback.
This causes @msg to be placed back on the queue to be attempted
again.
the message to requeue
Synchronously send @msg. This call will not return until the
transfer is finished successfully or there is an unrecoverable
error.
the HTTP status code of the response
the message to send
Cancels all pending requests in @session.
Adds @feature's functionality to @session. You can also add a
feature to the session at construct time by using the
%SOUP_SESSION_ADD_FEATURE property.
an object that implements #SoupSessionFeature
If @feature_type is the type of a class that implements
#SoupSessionFeature, this creates a new feature of that type and
adds it to @session as with soup_session_add_feature(). You can use
this when you don't need to customize the new feature in any way.
If @feature_type is not a #SoupSessionFeature type, this gives
each existing feature on @session the chance to accept @feature_type
as a "subfeature". This can be used to add new #SoupAuth types,
for instance.
You can also add a feature to the session at construct time by
using the %SOUP_SESSION_ADD_FEATURE_BY_TYPE property.
a #GType
Causes @session to immediately finish processing @msg (regardless
of its current state) with a final status_code of @status_code. You
may call this at any time after handing @msg off to @session; if
the complete response, then it will close the request's connection.
Note that with non-idempotent requests (eg, %POST, %PUT, %DELETE)
it is possible that you might cancel the request after the server
acts on it, but before it returns a response, leaving the remote
resource in an unknown state.
If the message is cancelled while its response body is being read,
then the response body in @msg will be left partially-filled-in.
The response headers, on the other hand, will always be either
empty or complete.
For messages queued with soup_session_queue_message() (and
cancelled from the same thread), the callback will be invoked
before soup_session_cancel_message() returns.
the message to cancel
status code to set on @msg (generally %SOUP_STATUS_CANCELLED)
Gets @session's async_context. This does not add a ref to the
context, so you will need to ref it yourself if you want it to
outlive its session.
be %NULL
@session's #GMainContext, which may
Gets the first feature in @session of type @feature_type. For
features where there may be more than one feature of a given type,
use soup_session_get_features().
feature is owned by @session.
a #SoupSessionFeature, or %NULL. The
the #GType of the feature to get
Gets the first feature in @session of type @feature_type, provided
that it is not disabled for @msg. As with
soup_session_get_feature(), this should only be used for features
where @feature_type is only expected to match a single feature. In
particular, if there are two matching features, and the first is
disabled on @msg, and the second is not, then this will return
%NULL, not the second feature.
feature is owned by @session.
a #SoupSessionFeature, or %NULL. The
the #GType of the feature to get
a #SoupMessage
Generates a list of @session's features of type @feature_type. (If
you want to see all features, you can pass %G_TYPE_SESSION_FEATURE
for @feature_type.)
free the list, but not its contents
a list of features. You must
the #GType of the class of features to get
Pauses HTTP I/O on @msg. Call soup_session_unpause_message() to
resume I/O.
a #SoupMessage currently running on @session
Queues the message @msg for sending. All messages are processed
while the glib main loop runs. If @msg has been processed before,
any resources related to the time it was last sent are freed.
Upon message completion, the callback specified in @callback will
be invoked (in the thread associated with @session's async
context). If after returning from this callback the message has not
been requeued, @msg will be unreffed.
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
a pointer passed to @callback.
Removes @feature's functionality from @session.
a feature that has previously been added to @session
Removes all features of type @feature_type (or any subclass of
from the session at construct time by using the
%SOUP_SESSION_REMOVE_FEATURE_BY_TYPE property.
a #GType
This causes @msg to be placed back on the queue to be attempted
again.
the message to requeue
Synchronously send @msg. This call will not return until the
transfer is finished successfully or there is an unrecoverable
error.
the HTTP status code of the response
the message to send
Resumes HTTP I/O on @msg. Use this to resume after calling
soup_session_pause_message().
If @msg is being sent via blocking I/O, this will resume reading or
writing immediately. If @msg is using non-blocking I/O, then
reading or writing won't resume until you return to the main loop.
a #SoupMessage currently running on @session
Creates an asynchronous #SoupSession with the default options.
the new session.
Creates an asynchronous #SoupSession with the specified options.
the new session.
name of first property to set
Prototype for the callback passed to soup_session_queue_message(),
qv.
the session
the message that has finished
the data passed to soup_session_queue_message
the message to queue
a #SoupSessionCallback which will be called after the message completes or when an unrecoverable error occurs.
a pointer passed to @callback.
the message to requeue
the HTTP status code of the response
the message to send
the message to cancel
status code to set on @msg (generally %SOUP_STATUS_CANCELLED)
An object that implement some sort of optional feature for
#SoupSession.
The interface implemented by #SoupSessionFeature<!-- -->s.
Creates an synchronous #SoupSession with the default options.
the new session.
Creates an synchronous #SoupSession with the specified options.
the new session.
name of first property to set
Creates a new (disconnected) socket
the new socket
name of first property to set (or %NULL)
Begins asynchronously connecting to @sock's remote address. The
socket will call @callback when it succeeds or fails (but not
before returning from this function).
If @cancellable is non-%NULL, it can be used to cancel the
connection. @callback will still be invoked in this case, with a
status of %SOUP_STATUS_CANCELLED.
a #GCancellable, or %NULL
callback to call after connecting
data to pass to @callback
Attempt to synchronously connect @sock to its remote address.
If @cancellable is non-%NULL, it can be used to cancel the
connection, in which case soup_socket_connect_sync() will return
%SOUP_STATUS_CANCELLED.
a success or failure code.
a #GCancellable, or %NULL
Disconnects @sock. Any further read or write attempts on it will
fail.
Returns the #SoupAddress corresponding to the local end of @sock.
the #SoupAddress
Returns the #SoupAddress corresponding to the remote end of @sock.
the #SoupAddress
Tests if @sock is connected to another host
%TRUE or %FALSE.
Tests if @sock is set up to do SSL. Note that this simply means
that the %SOUP_SOCKET_SSL_CREDENTIALS property has been set; it
does not mean that soup_socket_start_ssl() has been called.
%TRUE if @sock has SSL credentials set
Makes @sock start listening on its local address. When connections
come in, @sock will emit %new_connection.
whether or not @sock is now listening.
Attempts to read up to @len bytes from @sock into @buffer. If some
data is successfully read, soup_socket_read() will return
%SOUP_SOCKET_OK, and *@nread will contain the number of bytes
actually read (which may be less than @len).
If @sock is non-blocking, and no data is available, the return
value will be %SOUP_SOCKET_WOULD_BLOCK. In this case, the caller
can connect to the #SoupSocket::readable signal to know when there
socket first. #SoupSocket::readable is only emitted after
soup_socket_read() returns %SOUP_SOCKET_WOULD_BLOCK, and it is only
emitted once. See the documentation for #SoupSocket:non-blocking.)
%SOUP_SOCKET_EOF if the socket is no longer connected, or
%SOUP_SOCKET_ERROR on any other error, in which case @error will
also be set).
a #SoupSocketIOStatus, as described above (or
buffer to read into
size of @buffer in bytes
on return, the number of bytes read into @buffer
a #GCancellable, or %NULL
Like soup_socket_read(), but reads no further than the first
occurrence of @boundary. (If the boundary is found, it will be
included in the returned data, and *@got_boundary will be set to
%TRUE.) Any data after the boundary will returned in future reads.
soup_socket_read_until() will almost always return fewer than @len
up until the end of the boundary, and if the boundary is not found,
then it will leave the last <literal>(boundary_len - 1)</literal>
bytes in its internal buffer, in case they form the start of the
boundary string. Thus, @len normally needs to be at least 1 byte
longer than @boundary_len if you want to make any progress at all.
as for soup_socket_read()
buffer to read into
size of @buffer in bytes
boundary to read until
length of @boundary in bytes
on return, the number of bytes read into @buffer
on return, whether or not the data in @buffer ends with the boundary string
a #GCancellable, or %NULL
Starts using SSL on @socket, expecting to find a host named
success or failure
hostname of the SSL server
a #GCancellable
Starts using SSL on @socket.
success or failure
a #GCancellable
Attempts to write @len bytes from @buffer to @sock. If some data is
successfully written, the return status will be %SOUP_SOCKET_OK,
and *@nwrote will contain the number of bytes actually written
(which may be less than @len).
If @sock is non-blocking, and no data could be written right away,
the return value will be %SOUP_SOCKET_WOULD_BLOCK. In this case,
the caller can connect to the #SoupSocket::writable signal to know
emitted after soup_socket_write() returns %SOUP_SOCKET_WOULD_BLOCK,
and it is only emitted once. See the documentation for
#SoupSocket:non-blocking.)
%SOUP_SOCKET_EOF or %SOUP_SOCKET_ERROR. @error will be set if the
return value is %SOUP_SOCKET_ERROR.)
a #SoupSocketIOStatus, as described above (or
data to write
size of @buffer, in bytes
on return, number of bytes written
a #GCancellable, or %NULL
The callback function passed to soup_socket_connect_async().
the #SoupSocket
an HTTP status code indicating success or failure
the data passed to soup_socket_connect_async()
Return value from the #SoupSocket IO methods.
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.
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.
(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.
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
to use when it is not specified in the URI).
an empty string either; if the input URI has no path, the parsed
#SoupURI will have a @path of "/".
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.)
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.)
a #SoupURI, or %NULL.
a URI
Copies @uri
a copy of @uri, which must be freed with soup_uri_free()
Makes a copy of @uri, considering only the protocol, host, and port
the new #SoupUri
Tests whether or not @uri1 and @uri2 are equal in all parts
%TRUE or %FALSE
another #SoupURI
Frees @uri.
Gets @uri's fragment.
@uri's fragment.
Gets @uri's host.
@uri's host.
Gets @uri's password.
@uri's password.
Gets @uri's path.
@uri's path.
Gets @uri's port.
@uri's port.
Gets @uri's query.
@uri's query.
Gets @uri's scheme.
@uri's scheme.
Gets @uri's user.
@uri's user.
Parses @uri_string relative to @base.
a parsed #SoupURI.
the URI
Sets @uri's fragment to @fragment.
the fragment
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.
the hostname or IP address, or %NULL
Sets @uri's password to @password.
the password, or %NULL
Sets @uri's path to @path.
the path
Sets @uri's port to @port. If @port is 0, @uri will not have an
explicitly-specified port.
the port, or 0
Sets @uri's query to @query.
the query
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.
name of the first form field to encode into query
Sets @uri's query to the result of encoding @form according to the
HTML form rules. See soup_form_encode_hash() for more information.
a #GHashTable containing HTML form information
Sets @uri's scheme to @scheme. This will also set @uri's port to
the default port for @scheme, if known.
the URI scheme
Sets @uri's user to @user.
the username, or %NULL
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.
a string representing @uri, which the caller must free.
if %TRUE, output just the path and query portions
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.)
%TRUE or %FALSE
Adds @function to be executed from inside @async_context with the
default priority. Use this when you want to complete an action in
with g_source_destroy().
a #GSource, which can be removed from @async_context
the #GMainContext to dispatch the I/O watch in, or %NULL for the default context
the callback to invoke
user data to pass to @function
Adds an idle event as with g_idle_add(), but using the given
If you want @function to run "right away", use
soup_add_completion(), since that sets a higher priority on the
#GSource than soup_add_idle() does.
with g_source_destroy().
a #GSource, which can be removed from @async_context
the #GMainContext to dispatch the I/O watch in, or %NULL for the default context
the callback to invoke at idle time
user data to pass to @function
Adds an I/O watch as with g_io_add_watch(), but using the given
with g_source_destroy().
a #GSource, which can be removed from @async_context
the #GMainContext to dispatch the I/O watch in, or %NULL for the default context
the #GIOChannel to watch
the condition to watch for
the callback to invoke when @condition occurs
user data to pass to @function
Adds a timeout as with g_timeout_add(), but using the given
with g_source_destroy().
a #GSource, which can be removed from @async_context
the #GMainContext to dispatch the I/O watch in, or %NULL for the default context
the timeout interval, in milliseconds
the callback to invoke at timeout time
user data to pass to @function
Parses @header and returns a #SoupCookie. (If @header contains
multiple cookies, only the first one will be parsed.)
If @header does not have "path" or "domain" attributes, they will
be defaulted from @origin. If @origin is %NULL, path will default
to "/", but domain will be left as %NULL. Note that this is not a
valid state for a #SoupCookie, and you will need to fill in some
appropriate string for the domain if you want to actually make use
of the cookie.
parsed, or contained an illegal "domain" attribute for a cookie
originating from @origin.
a new #SoupCookie, or %NULL if it could not be
a cookie string (eg, the value of a Set-Cookie header)
origin of the cookie, or %NULL
Frees @cookies.
a #GSList of #SoupCookie
Parses @msg's Cookie request header and returns a #GSList of
#SoupCookie<!-- -->s. As the "Cookie" header, unlike "Set-Cookie",
only contains cookie names and values, none of the other
#SoupCookie fields will be filled in. (Thus, you can't generally
pass a cookie returned from this method directly to
soup_cookies_to_response().)
of #SoupCookie<!-- -->s, which can be freed with
soup_cookies_free().
a #GSList
a #SoupMessage containing a "Cookie" request header
Parses @msg's Set-Cookie response headers and returns a #GSList of
#SoupCookie<!-- -->s. Cookies that do not specify "path" or
"domain" attributes will have their values defaulted from @msg.
of #SoupCookie<!-- -->s, which can be freed with
soup_cookies_free().
a #GSList
a #SoupMessage containing a "Set-Cookie" response header
Serializes a #GSList of #SoupCookie into a string suitable for
setting as the value of the "Cookie" header.
the serialization of @cookies
a #GSList of #SoupCookie
Adds the name and value of each cookie in @cookies to @msg's
"Cookie" request. (If @msg already has a "Cookie" request header,
these cookies will be appended to the cookies already present. Be
careful that you do not append the same cookies twice, eg, when
requeuing a message.)
a #GSList of #SoupCookie
a #SoupMessage
Appends a "Set-Cookie" response header to @msg for each cookie in
a #GSList of #SoupCookie
a #SoupMessage
Decodes @form, which is an urlencoded dataset as defined in the
HTML 4.01 spec.
table containing the name/value pairs from @encoded_form, which you
can free with g_hash_table_destroy().
a hash
data of type "application/x-www-form-urlencoded"
Decodes the "multipart/form-data" request in @msg; this is a
convenience method for the case when you have a single file upload
control in a form. (Or when you don't have any file upload
controls, but are still using "multipart/form-data" anyway.) Pass
the name of the file upload control in @file_control_name, and
soup_form_decode_multipart() will extract the uploaded file data
into @filename, @content_type, and @file. All of the other form
control data will be returned (as strings, as with
soup_form_decode()) in the returned #GHashTable.
You may pass %NULL for @filename and/or @content_type if you do not
care about those fields. soup_form_decode_multipart() may also
return %NULL in those fields if the client did not provide that
information. You must free the returned filename and content-type
with g_free(), and the returned file data with soup_buffer_free().
If you have a form with more than one file upload control, you will
need to decode it manually, using soup_multipart_new_from_message()
and soup_multipart_get_part().
table containing the name/value pairs (other than
g_hash_table_destroy(). On error, it will return %NULL.
a hash
a #SoupMessage containing a "multipart/form-data" request body
the name of the HTML file upload control, or %NULL
return location for the name of the uploaded file
return location for the MIME type of the uploaded file
return location for the uploaded file data
Encodes the given field names and values into a value of type
"application/x-www-form-urlencoded", as defined in the HTML 4.01
spec.
This method requires you to know the names of the form fields (or
at the very least, the total number of fields) at compile time; for
working with dynamic forms, use soup_form_encode_hash() or
soup_form_encode_datalist().
the encoded form
name of the first form field
Encodes @form_data_set into a value of type
"application/x-www-form-urlencoded", as defined in the HTML 4.01
spec. Unlike soup_form_encode_hash(), this preserves the ordering
of the form elements, which may be required in some situations.
the encoded form
a datalist containing name/value pairs
Encodes @form_data_set into a value of type
"application/x-www-form-urlencoded", as defined in the HTML 4.01
spec.
Note that the HTML spec states that "The control names/values are
listed in the order they appear in the document." Since this method
takes a hash table, it cannot enforce that; if you care about the
ordering of the form fields, use soup_form_encode_datalist().
the encoded form
a hash table containing name/value pairs (as strings)
See soup_form_encode(). This is mostly an internal method, used by
various other methods such as soup_uri_set_query_from_fields() and
soup_form_request_new().
the encoded form
name of the first form field
pointer to additional values, as in soup_form_encode()
Creates a new %SoupMessage and sets it up to send the given data
to @uri via @method. (That is, if @method is "GET", it will encode
the form data into @uri's query field, and if @method is "POST", it
will encode it into the %SoupMessage's request_body.)
the new %SoupMessage
the HTTP method, either "GET" or "POST"
the URI to send the form data to
name of the first form field
Creates a new %SoupMessage and sets it up to send @form_data_set to
the new %SoupMessage
the HTTP method, either "GET" or "POST"
the URI to send the form data to
the data to send to @uri
Creates a new %SoupMessage and sets it up to send @form_data_set to
the new %SoupMessage
the HTTP method, either "GET" or "POST"
the URI to send the form data to
the data to send to @uri
Creates a new %SoupMessage and sets it up to send @multipart to
To send a <literal>"multipart/form-data"</literal> POST, first
create a #SoupMultipart, using %SOUP_FORM_MIME_TYPE_MULTIPART as
the MIME type. Then use soup_multipart_append_form_string() and
soup_multipart_append_form_file() to add the value of each form
control to the multipart. (These are just convenience methods, and
you can use soup_multipart_append_part() if you need greater
control over the part headers.) Finally, call
soup_form_request_new_from_multipart() to serialize the multipart
structure and create a #SoupMessage.
the new %SoupMessage
the URI to send the form data to
a "multipart/form-data" #SoupMultipart
Parses @header to see if it contains the token @token (matched
case-insensitively). Note that this can't be used with lists
that have qvalues.
whether or not @header contains @token
An HTTP header suitable for parsing with soup_header_parse_list()
a token
Frees @list.
a #GSList returned from soup_header_parse_list() or soup_header_parse_quality_list()
Frees @param_list.
a #GHashTable returned from soup_header_parse_param_list() or soup_header_parse_semi_param_list()
Appends something like <literal>@name=@value</literal> to @string,
taking care to quote @value if needed, and if so, to escape any
quotes or backslashes in @value.
Alternatively, if @value is a non-ASCII UTF-8 string, it will be
appended using RFC2231 syntax. Although in theory this is supposed
to work anywhere in HTTP that uses this style of parameter, in
reality, it can only be used portably with the Content-Disposition
"filename" parameter.
If @value is %NULL, this will just append @name to @string.
a #GString being used to construct an HTTP header value
a parameter name
a parameter value, or %NULL
Appends something like <literal>@name="@value"</literal> to
a #GString being used to construct an HTTP header value
a parameter name
a parameter value
Parses a header whose content is described by RFC2616 as
"#something", where "something" does not itself contain commas,
except as part of quoted-strings.
allocated strings
a #GSList of list elements, as
a header value
Parses a header which is a comma-delimited list of something like:
<literal>token [ "=" ( token | quoted-string ) ]</literal>.
Tokens that don't have an associated value will still be added to
the resulting hash table, but with a %NULL value.
This also handles RFC2231 encoding (which in HTTP is mostly used
for giving UTF8-encoded filenames in the Content-Disposition
header).
#GHashTable of list elements, which can be freed with
soup_header_free_param_list().
a
a header value
Parses a header whose content is a list of items with optional
"qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding,
Accept-Language, TE).
If @unacceptable is not %NULL, then on return, it will contain the
items with qvalue 0. Either way, those items will be removed from
the main list.
allocated strings), highest-qvalue first.
a #GSList of acceptable values (as
a header value
on return, will contain a list of unacceptable values
Parses a header which is a semicolon-delimited list of something
Tokens that don't have an associated value will still be added to
the resulting hash table, but with a %NULL value.
This also handles RFC2231 encoding (which in HTTP is mostly used
for giving UTF8-encoded filenames in the Content-Disposition
header).
#GHashTable of list elements, which can be freed with
soup_header_free_param_list().
a
a header value
Parses the headers of an HTTP request or response in @str and
stores the results in @dest. Beware that @dest may be modified even
on failure.
This is a low-level method; normally you would use
soup_headers_parse_request() or soup_headers_parse_response().
success or failure
the header string (including the Request-Line or Status-Line, and the trailing blank line)
length of @str up to (but not including) the terminating blank line.
#SoupMessageHeaders to store the header values in
Parses the headers of an HTTP request in @str and stores the
results in @req_method, @req_path, @ver, and @req_headers.
Beware that @req_headers may be modified even on failure.
HTTP error to be returned to the client if they could not be.
%SOUP_STATUS_OK if the headers could be parsed, or an
the header string (including the trailing blank line)
length of @str up to (but not including) the terminating blank line.
#SoupMessageHeaders to store the header values in
if non-%NULL, will be filled in with the request method
if non-%NULL, will be filled in with the request path
if non-%NULL, will be filled in with the HTTP version
Parses the headers of an HTTP response in @str and stores the
results in @ver, @status_code, @reason_phrase, and @headers.
Beware that @headers may be modified even on failure.
success or failure.
the header string (including the trailing blank line)
length of @str up to (but not including) the terminating blank line.
#SoupMessageheaders to store the header values in
if non-%NULL, will be filled in with the HTTP version
if non-%NULL, will be filled in with the status code
if non-%NULL, will be filled in with the reason phrase
Parses the HTTP Status-Line string in @status_line into @ver,
either "\0" or "\r\n".
%TRUE if @status_line was parsed successfully.
an HTTP Status-Line
if non-%NULL, will be filled in with the HTTP version
if non-%NULL, will be filled in with the status code
if non-%NULL, will be filled in with the reason phrase
The quark used as %SOUP_SSL_ERROR
The quark used as %SOUP_SSL_ERROR
Looks up the stock HTTP description of @status_code. This is used
by soup_message_set_status() to get the correct text to go with a
given status code.
<emphasis>There is no reason for you to ever use this
function.</emphasis> If you wanted the textual description for the
%status_code of a given #SoupMessage, you should just look at the
message's %reason_phrase. However, you should only do that for use
in debugging messages; HTTP reason phrases are not localized, and
are not generally very descriptive anyway, and so they should never
be presented to the user directly. Instead, you should create you
own error messages based on the status code, and on what you were
trying to do.
the (terse, English) description of @status_code
an HTTP status code
Turns %SOUP_STATUS_CANT_RESOLVE into
%SOUP_STATUS_CANT_RESOLVE_PROXY and %SOUP_STATUS_CANT_CONNECT into
%SOUP_STATUS_CANT_CONNECT_PROXY. Other status codes are passed
through unchanged.
the "proxified" equivalent of @status_code.
a status code
Compares @v1 and @v2 in a case-insensitive manner
%TRUE if they are equal (modulo case)
an ASCII string
another ASCII string
Hashes @key in a case-insensitive manner.
the hash code.
ASCII string to hash
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).
the decoded URI part.
a URI part
This %<!-- -->-encodes the given URI part and returns the escaped
version in allocated memory, which the caller must free when it is
done.
the encoded URI part
a URI part
additional reserved characters to escape (or %NULL)
Compares @v1 and @v2, considering only the scheme, host, and port.
and port.
whether or not the URIs are equal in scheme, host,
a #SoupURI
a #SoupURI
Hashes @key, considering only the scheme, host, and port.
a hash
a #SoupURI
%<!-- -->-decodes any "unreserved" characters (or characters in
"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
<literal>http://example.com/foo/b%<!-- -->61r</literal> into
<literal>http://example.com/foo/bar</literal>, which is guaranteed
to mean the same thing. However, "/" is "reserved", so
<literal>http://example.com/foo%<!-- -->2Fbar</literal> 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).
the normalized URI part
a URI part
reserved characters to unescape (or %NULL)
Appends the provided value of type @type to @array as with
g_value_array_append(). (The provided data is copied rather than
being inserted directly.)
a #GValueArray
a #GType
Appends the provided values into @array as with
g_value_array_append(). (The provided data is copied rather than
being inserted directly.)
a #GValueArray
the type of the first value to add
Creates a #GValueArray from the provided arguments, which must
consist of pairs of a #GType and a value of that type, terminated
by %G_TYPE_INVALID. (The array will contain copies of the provided
data rather than pointing to the passed-in data directly.)
a new #GValueArray, or %NULL if an error occurred.
arguments to create a #GValueArray from
Gets the @index_ element of @array and stores its value into the
provided location.
and type @type, %FALSE if not.
%TRUE if @array contained a value with index @index_
a #GValueArray
the index to look up
a #GType
Inserts the provided value of type @type into @array as with
g_value_array_insert(). (The provided data is copied rather than
being inserted directly.)
a #GValueArray
the index to insert at
a #GType
Creates a new %GValueArray. (This is just a wrapper around
g_value_array_new(), for naming consistency purposes.)
a new %GValueArray
Creates a new %GValueArray and copies the provided values
into it.
a new %GValueArray
the type of the first value to add
Extracts a #GValueArray into the provided arguments, which must
consist of pairs of a #GType and a value of pointer-to-that-type,
terminated by %G_TYPE_INVALID. The returned values will point to the
same memory as the values in the array.
success or failure
a #GValueArray
arguments to extract @array into
Inserts the provided value of type @type into @hash. (Unlike with
g_hash_table_insert(), both the key and the value are copied).
a value hash
the key
a #GType
Inserts the given data into @hash. As with
soup_value_hash_insert(), the keys and values are copied rather
than being inserted directly.
a value hash
the key for the first value
Inserts @value into @hash. (Unlike with g_hash_table_insert(), both
the key and the value are copied).
a value hash
the key
a value
Looks up @key in @hash and stores its value into the provided
location.
type @type, %FALSE if not.
%TRUE if @hash contained a value with key @key and
a value hash
the key to look up
a #GType
Looks up a number of keys in @hash and returns their values.
if any were missing; note that you will generally need to
initialize each destination variable to a reasonable default
value, since there is no way to tell which keys were found
and which were not.
%TRUE if all of the keys were found, %FALSE
a value hash
the first key to look up
Creates a #GHashTable whose keys are strings and whose values
are #GValue.
empty #GHashTable
a new
Creates a #GHashTable whose keys are strings and whose values
are #GValue, and initializes it with the provided data. As
with soup_value_hash_insert(), the keys and values are copied
rather than being inserted directly.
#GHashTable, initialized with the given values
a new
the key for the first value
This creates an XML-RPC fault response and returns it as a string.
(To create a successful response, use
soup_xmlrpc_build_method_response().)
the text of the fault
the fault code
a printf()-style format string
This creates an XML-RPC methodCall and returns it as a string.
This is the low-level method that soup_xmlrpc_request_new() and
soup_xmlrpc_call() are built on.
#GValueArray, you can just pass its %values and %n_values fields.)
The correspondence between glib types and XML-RPC types is:
For structs, use a #GHashTable that maps strings to #GValue;
soup_value_hash_new() and related methods can help with this.
the text of the methodCall, or %NULL on error
the name of the XML-RPC method
arguments to @method
length of @params
This creates a (successful) XML-RPC methodResponse and returns it
as a string. To create a fault response, use
soup_xmlrpc_build_fault().
The glib type to XML-RPC type mapping is as with
soup_xmlrpc_build_method_call(), qv.
the text of the methodResponse, or %NULL on error
the return value
Parses @method_call to get the name and parameters, and puts
the parameters into variables of the appropriate types.
The parameters are handled similarly to
terminated by %G_TYPE_INVALID, except that values are pointers to
variables of the indicated type, rather than values of the type.
See also soup_xmlrpc_parse_method_call(), which can be used if
you don't know the types of the parameters.
success or failure.
the XML-RPC methodCall string
the length of @method_call, or -1 if it is NUL-terminated
on return, the methodName from @method_call
Parses @method_response and extracts the return value into
a variable of the correct type.
If @method_response is a fault, the return value will be unset,
and @error will be set to an error of type %SOUP_XMLRPC_FAULT, with
the error #code containing the fault code, and the error #message
containing the fault string. (If @method_response cannot be parsed
at all, soup_xmlrpc_extract_method_response() will return %FALSE,
but @error will be unset.)
response was of the wrong type, or contained a fault.
%TRUE if a return value was parsed, %FALSE if the
the XML-RPC methodResponse string
the length of @method_response, or -1 if it is NUL-terminated
error return value
the expected type of the return value
Parses @method_call to get the name and parameters, and returns the
parameter values in a #GValueArray; see also
soup_xmlrpc_extract_method_call(), which is more convenient if you
know in advance what the types of the parameters will be.
success or failure.
the XML-RPC methodCall string
the length of @method_call, or -1 if it is NUL-terminated
on return, the methodName from @method_call
on return, the parameters from @method_call
Parses @method_response and returns the return value in @value. If
will be set to an error of type %SOUP_XMLRPC_FAULT, with the error
#code containing the fault code, and the error #message containing
the fault string. (If @method_response cannot be parsed at all,
soup_xmlrpc_parse_method_response() will return %FALSE, but @error
will be unset.)
response could not be parsed, or contained a fault.
%TRUE if a return value was parsed, %FALSE if the
the XML-RPC methodResponse string
the length of @method_response, or -1 if it is NUL-terminated
on return, the return value from @method_call
Creates an XML-RPC methodCall and returns a #SoupMessage, ready
to send, for that method call.
The parameters are passed as type/value pairs; ie, first a #GType,
and then a value of the appropriate type, finally terminated by
%G_TYPE_INVALID.
indicated XML-RPC request.
a #SoupMessage encoding the
URI of the XML-RPC service
the name of the XML-RPC method to invoke at @uri
Sets the status code and response body of @msg to indicate an
unsuccessful XML-RPC call, with the error described by @fault_code
and @fault_format.
an XML-RPC request
the fault code
a printf()-style format string
Sets the status code and response body of @msg to indicate a
successful XML-RPC call, with a return value given by @type and the
following varargs argument, of the type indicated by @type.
an XML-RPC request
the type of the response value