![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
SoupDate; enum SoupDateFormat; SoupDate* soup_date_new (int year, int month, int day, int hour, int minute, int second); SoupDate* soup_date_new_from_string (const char *date_string); SoupDate* soup_date_new_from_time_t (time_t when); SoupDate* soup_date_new_from_now (int offset_seconds); char* soup_date_to_string (SoupDate *date, SoupDateFormat format); time_t soup_date_to_time_t (SoupDate *date); void soup_date_free (SoupDate *date); GHashTable* soup_form_decode (const char *encoded_form); char* soup_form_encode (const char *first_field, ...); char* soup_form_encode_datalist (GData **form_data_set); char* soup_form_encode_hash (GHashTable *form_data_set); char* soup_form_encode_valist (const char *first_field, va_list args); SoupMessage* soup_form_request_new (const char *method, const char *uri, const char *first_field, ...); SoupMessage* soup_form_request_new_from_datalist (const char *method, const char *uri, GData **form_data_set); SoupMessage* soup_form_request_new_from_hash (const char *method, const char *uri, GHashTable *form_data_set); guint soup_headers_parse_request (const char *str, int len, SoupMessageHeaders *req_headers, char **req_method, char **req_path, SoupHTTPVersion *ver); gboolean soup_headers_parse_response (const char *str, int len, SoupMessageHeaders *headers, SoupHTTPVersion *ver, guint *status_code, char **reason_phrase); gboolean soup_headers_parse_status_line (const char *status_line, SoupHTTPVersion *ver, guint *status_code, char **reason_phrase); GSList* soup_header_parse_list (const char *header); GSList* soup_header_parse_quality_list (const char *header, GSList **unacceptable); void soup_header_free_list (GSList *list); gboolean soup_header_contains (const char *header, const char *token); GHashTable* soup_header_parse_param_list (const char *header); void soup_header_free_param_list (GHashTable *param_list); gboolean soup_str_case_equal (gconstpointer v1, gconstpointer v2); guint soup_str_case_hash (gconstpointer key); GSource* soup_add_idle (GMainContext *async_context, GSourceFunc function, gpointer data); GSource* soup_add_io_watch (GMainContext *async_context, GIOChannel *chan, GIOCondition condition, GIOFunc function, gpointer data); GSource* soup_add_timeout (GMainContext *async_context, guint interval, GSourceFunc function, gpointer data); extern const gboolean soup_ssl_supported;
typedef struct { int year; int month; int day; int hour; int minute; int second; gboolean utc; int offset; } SoupDate;
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.
int |
the year, 1 to 9999 |
int |
the month, 1 to 12 |
int |
day of the month, 1 to 31 |
int |
hour of the day, 0 to 23 |
int |
minute, 0 to 59 |
int |
second, 0 to 59 (or up to 61 in the case of leap seconds) |
gboolean |
TRUE if the date is in UTC
|
int |
offset from UTC |
typedef enum { SOUP_DATE_HTTP = 1, SOUP_DATE_COOKIE, SOUP_DATE_RFC2822, SOUP_DATE_ISO8601_COMPACT, SOUP_DATE_ISO8601_FULL, SOUP_DATE_ISO8601 = SOUP_DATE_ISO8601_FULL, SOUP_DATE_ISO8601_XMLRPC } SoupDateFormat;
Date formats that soup_date_to_string()
can use.
SOUP_DATE_HTTP
and SOUP_DATE_COOKIE
always coerce the time to
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.
RFC 1123 format, used by the HTTP "Date" header. Eg "Sun, 06 Nov 1994 08:49:37 GMT" | |
The format for the "Expires" timestamp in the Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT". | |
RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100" | |
ISO 8601 date/time with no optional punctuation. Eg, "19941106T094937-0100". | |
ISO 8601 date/time with all optional punctuation. Eg, "1994-11-06T09:49:37-01:00". | |
An alias for SOUP_DATE_ISO8601_FULL .
|
|
ISO 8601 date/time as used by XML-RPC. Eg, "19941106T09:49:37". |
SoupDate* soup_date_new (int year, int month, int day, int hour, int minute, int second);
Creates a SoupDate representing the indicated time, UTC.
|
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) |
Returns : |
a new SoupDate |
SoupDate* soup_date_new_from_string (const char *date_string);
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.)
|
the date in some plausible format |
Returns : |
a new SoupDate |
SoupDate* soup_date_new_from_time_t (time_t when);
Creates a SoupDate corresponding to when
|
a time_t |
Returns : |
a new SoupDate |
SoupDate* soup_date_new_from_now (int offset_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.
|
offset from current time |
Returns : |
a new SoupDate |
char* soup_date_to_string (SoupDate *date, SoupDateFormat format);
Converts date
to a string in the format described by format
.
|
a SoupDate |
|
the format to generate the date in |
Returns : |
date as a string
|
time_t soup_date_to_time_t (SoupDate *date);
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).)
|
a SoupDate |
Returns : |
date as a time_t
|
GHashTable* soup_form_decode (const char *encoded_form);
Decodes form
, which is an urlencoded dataset as defined in the
HTML 4.01 spec.
|
data of type "application/x-www-form-urlencoded" |
Returns : |
a hash table containing the name/value pairs from
encoded_form , which you can free with g_hash_table_destroy() .
|
char* soup_form_encode (const char *first_field, ...);
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()
.
|
name of the first form field |
|
value of first_field , followed by additional field names
and values, terminated by NULL .
|
Returns : |
the encoded form |
char* soup_form_encode_datalist (GData **form_data_set);
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.
|
a datalist containing name/value pairs |
Returns : |
the encoded form |
char* soup_form_encode_hash (GHashTable *form_data_set);
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()
.
|
a hash table containing name/value pairs (as strings) |
Returns : |
the encoded form |
char* soup_form_encode_valist (const char *first_field, va_list args);
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()
.
|
name of the first form field |
|
pointer to additional values, as in soup_form_encode()
|
Returns : |
the encoded form |
SoupMessage* soup_form_request_new (const char *method, const char *uri, const char *first_field, ...);
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 HTTP method, either "GET" or "POST" |
|
the URI to send the form data to |
|
name of the first form field |
|
value of first_field , followed by additional field names
and values, terminated by NULL .
|
Returns : |
the new SoupMessage
|
SoupMessage* soup_form_request_new_from_datalist (const char *method, const char *uri, GData **form_data_set);
Creates a new SoupMessage
and sets it up to send form_data_set
to
uri
via method
, as with soup_form_request_new()
.
|
the HTTP method, either "GET" or "POST" |
|
the URI to send the form data to |
|
the data to send to uri
|
Returns : |
the new SoupMessage
|
SoupMessage* soup_form_request_new_from_hash (const char *method, const char *uri, GHashTable *form_data_set);
Creates a new SoupMessage
and sets it up to send form_data_set
to
uri
via method
, as with soup_form_request_new()
.
|
the HTTP method, either "GET" or "POST" |
|
the URI to send the form data to |
|
the data to send to uri
|
Returns : |
the new SoupMessage
|
guint soup_headers_parse_request (const char *str, int len, SoupMessageHeaders *req_headers, char **req_method, char **req_path, SoupHTTPVersion *ver);
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.
|
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
|
Returns : |
SOUP_STATUS_OK if the headers could be parsed, or an
HTTP error to be returned to the client if they could not be.
|
gboolean soup_headers_parse_response (const char *str, int len, SoupMessageHeaders *headers, SoupHTTPVersion *ver, guint *status_code, char **reason_phrase);
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.
|
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
|
Returns : |
success or failure. |
gboolean soup_headers_parse_status_line (const char *status_line, SoupHTTPVersion *ver, guint *status_code, char **reason_phrase);
Parses the HTTP Status-Line string in status_line
into ver
,
status_code
, and reason_phrase
. status_line
must be terminated by
either "\0" or "\r\n".
GSList* soup_header_parse_list (const char *header);
Parses a header whose content is described by RFC2616 as "something", where "something" does not itself contain commas, except as part of quoted-strings.
|
a header value |
Returns : |
a GSList of list elements, as allocated strings |
GSList* soup_header_parse_quality_list (const char *header, GSList **unacceptable);
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.
|
a header value |
|
on return, will contain a list of unacceptable values |
Returns : |
a GSList of acceptable values (as allocated strings), highest-qvalue first. |
void soup_header_free_list (GSList *list);
Frees list
.
|
a GSList returned from soup_header_parse_list() or
soup_header_parse_quality_list()
|
gboolean soup_header_contains (const char *header, const char *token);
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.
|
An HTTP header suitable for parsing with
soup_header_parse_list()
|
|
a token |
Returns : |
whether or not header contains token
|
GHashTable* soup_header_parse_param_list (const char *header);
Parses a header which is a list of something like token [ "=" ( token | quoted-string ) ]
Tokens that don't have an associated value will still be added to
the resulting hash table, but with a NULL
value.
|
a header value |
Returns : |
a GHashTable of list elements. |
void soup_header_free_param_list (GHashTable *param_list);
Frees param_list
.
|
a GHashTable returned from soup_header_parse_param_list()
|
gboolean soup_str_case_equal (gconstpointer v1, gconstpointer v2);
Compares v1
and v2
in a case-insensitive manner
|
an ASCII string |
|
another ASCII string |
Returns : |
TRUE if they are equal (modulo case)
|
guint soup_str_case_hash (gconstpointer key);
Hashes key
in a case-insensitive manner.
|
ASCII string to hash |
Returns : |
the hash code. |
GSource* soup_add_idle (GMainContext *async_context, GSourceFunc function, gpointer data);
Adds an idle event as with g_idle_add()
, but using the given
async_context
.
|
the GMainContext to dispatch the idle event in, or
NULL for the default context
|
|
the callback to invoke at idle time |
|
user data to pass to function
|
Returns : |
a GSource, which can be removed from async_context
with g_source_destroy() .
|
GSource* soup_add_io_watch (GMainContext *async_context, GIOChannel *chan, GIOCondition condition, GIOFunc function, gpointer data);
Adds an I/O watch as with g_io_add_watch()
, but using the given
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
|
Returns : |
a GSource, which can be removed from async_context
with g_source_destroy() .
|
GSource* soup_add_timeout (GMainContext *async_context, guint interval, GSourceFunc function, gpointer data);
Adds a timeout as with g_timeout_add()
, but using the given
async_context
.
|
the GMainContext to dispatch the timeout 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
|
Returns : |
a GSource, which can be removed from async_context
with g_source_destroy() .
|