Soup Miscellaneous Utilities: libsoup Reference Manual

## Soup Miscellaneous Utilities Soup Miscellaneous Utilities — Miscellaneous functions |

## Functions

SoupDate * | soup_date_new ()
SoupDate * | soup_date_new_from_string ()
SoupDate * | soup_date_new_from_time_t ()
SoupDate * | soup_date_new_from_now ()
char * | soup_date_to_string ()
time_t | soup_date_to_time_t ()
void | soup_date_to_timeval ()
gboolean | soup_date_is_past ()
int | soup_date_get_day ()
int | soup_date_get_hour ()
int | soup_date_get_minute ()
int | soup_date_get_month ()
int | soup_date_get_offset ()
int | soup_date_get_second ()
int | soup_date_get_utc ()
int | soup_date_get_year ()
void | soup_date_free ()
guint | soup_headers_parse_request ()
gboolean | soup_headers_parse_response ()
gboolean | soup_headers_parse_status_line ()
gboolean | soup_headers_parse ()
GSList * | soup_header_parse_list ()
GSList * | soup_header_parse_quality_list ()
void | soup_header_free_list ()
gboolean | soup_header_contains ()
GHashTable * | soup_header_parse_param_list ()
GHashTable * | soup_header_parse_semi_param_list ()
void | soup_header_free_param_list ()
void | soup_header_g_string_append_param ()
void | soup_header_g_string_append_param_quoted ()
gboolean | soup_str_case_equal ()
guint | soup_str_case_hash ()
GSource * | soup_add_completion ()
GSource * | soup_add_idle ()
GSource * | soup_add_io_watch ()
GSource * | soup_add_timeout ()

## Types and Values

| SoupDate
enum | SoupDateFormat

## Object Hierarchy

        GBoxed
        ╰── SoupDate

## Includes

    #include <libsoup/soup.h>

## Description

## Functions

### soup_date_new ()

    SoupDate *
    soup_date_new (int year,
                   int month,
                   int day,
                   int hour,
                   int minute,
                   int second);

Creates a SoupDate representing the indicated time, UTC.

#### Parameters

year | the year (1-9999) |
month | the month (1-12) |
day | the day of the month (1-31, as appropriate for `month` ) |
hour | the hour (0-23) |
minute | the minute (0-59) |
second | the second (0-59, or up to 61 for leap seconds) |

#### Returns

a new SoupDate

### soup_date_new_from_string ()

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

#### Parameters

date_string | the date in some plausible format |

#### Returns

a new SoupDate, or `NULL` if `date_string` could not be parsed.

[nullable]

### soup_date_new_from_time_t ()

    SoupDate *
    soup_date_new_from_time_t (time_t when);

Creates a SoupDate corresponding to `when`

#### Parameters

when | a time_t |

#### Returns

a new SoupDate

### soup_date_new_from_now ()

    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.

If `offset_seconds` would indicate a time not expressible as a

time_t, the return value will be clamped into range.

#### Parameters

offset_seconds | offset from current time |

#### Returns

a new SoupDate

### soup_date_to_string ()

    char *
    soup_date_to_string (SoupDate *date,
                         SoupDateFormat format);

Converts `date` to a string in the format described by `format` .

#### Parameters

date | a SoupDate |
format | the format to generate the date in |

#### Returns

`date` as a string

### soup_date_to_time_t ()

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

#### Parameters

date | a SoupDate |

#### Returns

`date` as a time_t

### soup_date_to_timeval ()

    void
    soup_date_to_timeval (SoupDate *date,
                          GTimeVal *time);

Converts `date` to a GTimeVal.

#### Parameters

date | a SoupDate |
time | a GTimeVal structure in which to store the converted time. | [out]

Since: 2.24

### soup_date_is_past ()

    gboolean
    soup_date_is_past (SoupDate *date);

Determines if `date` is in the past.

#### Parameters

date | a SoupDate |

#### Returns

`TRUE` if `date` is in the past

Since: 2.24

### soup_date_get_day ()

    int
    soup_date_get_day (SoupDate *date);

Gets `date` 's day.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's day

Since: 2.32

### soup_date_get_hour ()

    int
    soup_date_get_hour (SoupDate *date);

Gets `date` 's hour.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's hour

Since: 2.32

### soup_date_get_minute ()

    int
    soup_date_get_minute (SoupDate *date);

Gets `date` 's minute.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's minute

Since: 2.32

### soup_date_get_month ()

    int
    soup_date_get_month (SoupDate *date);

Gets `date` 's month.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's month

Since: 2.32

### soup_date_get_offset ()

    int
    soup_date_get_offset (SoupDate *date);

Gets `date` 's offset from UTC.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's offset from UTC. If `soup_date_get_utc()` returns `FALSE` but `soup_date_get_offset()` returns 0, that means the date is a "floating" time with no associated offset information.

Since: 2.32

### soup_date_get_second ()

    int
    soup_date_get_second (SoupDate *date);

Gets `date` 's second.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's second

Since: 2.32

### soup_date_get_utc ()

    int
    soup_date_get_utc (SoupDate *date);

Gets `date` 's UTC flag

#### Parameters

date | a SoupDate |

#### Returns

`TRUE` if `date` is UTC.

Since: 2.32

### soup_date_get_year ()

    int
    soup_date_get_year (SoupDate *date);

Gets `date` 's year.

#### Parameters

date | a SoupDate |

#### Returns

`date` 's year

Since: 2.32

### soup_date_free ()

    void
    soup_date_free (SoupDate *date);

Frees `date` .

#### Parameters

date | a SoupDate |

Since: 2.24

### soup_headers_parse_request ()

    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.

#### Parameters

str | the headers (up to, but not including, the trailing blank line) |
len | length of `str` |
req_headers | SoupMessageHeaders to store the header values in |
req_method | if non-`NULL`, will be filled in with the request method. | [out][allow-none]
req_path | if non-`NULL`, will be filled in with the request path. | [out][allow-none]
ver | if non-`NULL`, will be filled in with the HTTP version. | [out][allow-none]

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

### soup_headers_parse_response ()

    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.

#### Parameters

str | the headers (up to, but not including, the trailing blank line) |
len | length of `str` |
headers | SoupMessageHeaders to store the header values in |
ver | if non-`NULL`, will be filled in with the HTTP version. | [out][allow-none]
status_code | if non-`NULL`, will be filled in with the status code. | [out][allow-none]
reason_phrase | if non-`NULL`, will be filled in with the reason phrase. | [out][allow-none]

#### Returns

success or failure.

### soup_headers_parse_status_line ()

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

#### Parameters

status_line | an HTTP Status-Line |
ver | if non-`NULL`, will be filled in with the HTTP version. | [out][allow-none]
status_code | if non-`NULL`, will be filled in with the status code. | [out][allow-none]
reason_phrase | if non-`NULL`, will be filled in with the reason phrase. | [out][allow-none]

#### Returns

`TRUE` if `status_line` was parsed successfully.

### soup_headers_parse ()

    gboolean
    soup_headers_parse (const char *str,
                        int len,
                        SoupMessageHeaders *dest);

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

#### Parameters

str | the header string (including the Request-Line or Status-Line, but not the trailing blank line) |
len | length of `str` |
dest | SoupMessageHeaders to store the header values in |

#### Returns

success or failure

Since: 2.26

### soup_header_parse_list ()

    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.

#### Parameters

header | a header value |

#### Returns

a GSList of list elements, as allocated strings.

[transfer full][element-type utf8]

### soup_header_parse_quality_list ()

    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.

#### Parameters

header | a header value |
unacceptable | on return, will contain a list of unacceptable values. | [out][allow-none][transfer full][element-type utf8]

#### Returns

a GSList of acceptable values (as allocated strings), highest-qvalue first.

[transfer full][element-type utf8]

### soup_header_free_list ()

    void
    soup_header_free_list (GSList *list);

Frees `list` .

[skip]

#### Parameters

list | a GSList returned from `soup_header_parse_list()` or `soup_header_parse_quality_list()` |

### soup_header_contains ()

    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.

#### Parameters

header | An HTTP header suitable for parsing with `soup_header_parse_list()` |
token | a token |

#### Returns

whether or not `header` contains `token`

### soup_header_parse_param_list ()

    GHashTable *
    soup_header_parse_param_list (const char *header);

Parses a header which is a comma-delimited 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.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

#### Parameters

header | a header value |

#### Returns

a GHashTable of list elements, which can be freed with `soup_header_free_param_list()`.

[element-type utf8 utf8][transfer full]

### soup_header_parse_semi_param_list ()

    GHashTable *
    soup_header_parse_semi_param_list (const char *header);

Parses a header which is a semicolon-delimited 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.

This also handles RFC5987 encoding (which in HTTP is mostly used for giving UTF8-encoded filenames in the Content-Disposition header).

#### Parameters

header | a header value |

#### Returns

a GHashTable of list elements, which can be freed with `soup_header_free_param_list()`.

[element-type utf8 utf8][transfer full]

Since: 2.24

### soup_header_free_param_list ()

    void
    soup_header_free_param_list (GHashTable *param_list);

Frees `param_list` .

#### Parameters

param_list | a GHashTable returned from `soup_header_parse_param_list()` or `soup_header_parse_semi_param_list()`. | [element-type utf8 utf8]

### soup_header_g_string_append_param ()

    void
    soup_header_g_string_append_param (GString *string,
                                       const char *name,
                                       const char *value);

Appends something like ``name` =`value`` 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 RFC5987 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` .

#### Parameters

string | a GString being used to construct an HTTP header value |
name | a parameter name |
value | a parameter value, or `NULL` |

Since: 2.26

### soup_header_g_string_append_param_quoted ()

    void
    soup_header_g_string_append_param_quoted
                                   (GString *string,
                                    const char *name,
                                    const char *value);

Appends something like ``name` ="`value` "` to `string` , taking care to escape any quotes or backslashes in `value` .

If `value` is (non-ASCII) UTF-8, this will instead use RFC 5987 encoding, just like `soup_header_g_string_append_param()`.

#### Parameters

string | a GString being used to construct an HTTP header value |
name | a parameter name |
value | a parameter value |

Since: 2.30

### soup_str_case_equal ()

    gboolean
    soup_str_case_equal (gconstpointer v1,
                         gconstpointer v2);

Compares `v1` and `v2` in a case-insensitive manner

#### Parameters

v1 | an ASCII string |
v2 | another ASCII string |

#### Returns

`TRUE` if they are equal (modulo case)

### soup_str_case_hash ()

    guint
    soup_str_case_hash (gconstpointer key);

Hashes `key` in a case-insensitive manner.

#### Parameters

key | ASCII string to hash |

#### Returns

the hash code.

### soup_add_completion ()

    GSource *
    soup_add_completion (GMainContext *async_context,
                         GSourceFunc function,
                         gpointer data);

Adds `function` to be executed from inside `async_context` with the default priority. Use this when you want to complete an action in `async_context` 's main loop, as soon as possible.

[skip]

#### Parameters

async_context | the GMainContext to dispatch the I/O watch in, or `NULL` for the default context. | [allow-none]
function | the callback to invoke |
data | user data to pass to `function` |

#### Returns

a GSource, which can be removed from `async_context` with `g_source_destroy()`.

Since: 2.24

### soup_add_idle ()

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

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.

[skip]

#### Parameters

async_context | the GMainContext to dispatch the I/O watch in, or `NULL` for the default context. | [allow-none]
function | the callback to invoke at idle time |
data | user data to pass to `function` |

#### Returns

a GSource, which can be removed from `async_context` with `g_source_destroy()`.

### soup_add_io_watch ()

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

[skip]

#### Parameters

async_context | the GMainContext to dispatch the I/O watch in, or `NULL` for the default context. | [allow-none]
chan | the GIOChannel to watch |
condition | the condition to watch for |
function | the callback to invoke when `condition` occurs |
data | user data to pass to `function` |

#### Returns

a GSource, which can be removed from `async_context` with `g_source_destroy()`.

### soup_add_timeout ()

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

[skip]

#### Parameters

async_context | the GMainContext to dispatch the I/O watch in, or `NULL` for the default context. | [allow-none]
interval | the timeout interval, in milliseconds |
function | the callback to invoke at timeout time |
data | user data to pass to `function` |

#### Returns

a GSource, which can be removed from `async_context` with `g_source_destroy()`.

## Types and Values

### SoupDate

    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.

#### Members

int `year`; | the year, 1 to 9999 |
int `month`; | the month, 1 to 12 |
int `day`; | day of the month, 1 to 31 |
int `hour`; | hour of the day, 0 to 23 |
int `minute`; | minute, 0 to 59 |
int `second`; | second, 0 to 59 (or up to 61 in the case of leap seconds) |
gboolean `utc`; | `TRUE` if the date is in UTC |
int `offset`; | offset from UTC |

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

#### Members

SOUP_DATE_HTTP | RFC 1123 format, used by the HTTP "Date" header. Eg "Sun, 06 Nov 1994 08:49:37 GMT" |
SOUP_DATE_COOKIE | The format for the "Expires" timestamp in the Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT". |
SOUP_DATE_RFC2822 | RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100" |
SOUP_DATE_ISO8601_COMPACT | ISO 8601 date/time with no optional punctuation. Eg, "19941106T094937-0100". |
SOUP_DATE_ISO8601_FULL | ISO 8601 date/time with all optional punctuation. Eg, "1994-11-06T09:49:37-01:00". |
SOUP_DATE_ISO8601 | An alias for `SOUP_DATE_ISO8601_FULL` . |
SOUP_DATE_ISO8601_XMLRPC | ISO 8601 date/time as used by XML-RPC. Eg, "19941106T09:49:37". |