Soup Miscellaneous Utilities

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

## Synopsis

    #include <libsoup/soup.h>

                        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_to_timeval                (SoupDate *date,
                                                             GTimeVal *time);
    gboolean            soup_date_is_past                   (SoupDate *date);
    int                 soup_date_get_day                   (SoupDate *date);
    int                 soup_date_get_hour                  (SoupDate *date);
    int                 soup_date_get_minute                (SoupDate *date);
    int                 soup_date_get_month                 (SoupDate *date);
    int                 soup_date_get_offset                (SoupDate *date);
    int                 soup_date_get_second                (SoupDate *date);
    int                 soup_date_get_utc                   (SoupDate *date);
    int                 soup_date_get_year                  (SoupDate *date);
    void                soup_date_free                      (SoupDate *date);

    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);
    gboolean            soup_headers_parse                  (const char *str,
                                                             int len,
                                                             SoupMessageHeaders *dest);

    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);
    GHashTable *        soup_header_parse_semi_param_list   (const char *header);
    void                soup_header_free_param_list         (GHashTable *param_list);
    void                soup_header_g_string_append_param   (GString *string,
                                                             const char *name,
                                                             const char *value);
    void                soup_header_g_string_append_param_quoted
                                                            (GString *string,
                                                             const char *name,
                                                             const char *value);

    gboolean            soup_str_case_equal                 (gconstpointer v1,
                                                             gconstpointer v2);
    guint               soup_str_case_hash                  (gconstpointer key);

    GSource *           soup_add_completion                 (GMainContext *async_context,
                                                             GSourceFunc function,
                                                             gpointer data);
    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);

## Object Hierarchy

      GBoxed
       +----SoupDate

## Description

## Details

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

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

    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.

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

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

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

`date_string` : | the date in some plausible format
Returns : | a new SoupDate, or `NULL` if `date_string` could not be parsed.

### soup_date_new_from_time_t ()

    SoupDate *          soup_date_new_from_time_t           (time_t when);

Creates a SoupDate corresponding to `when`

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

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

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

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

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

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

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

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

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

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

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

`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

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

`date` : | a SoupDate
Returns : | `date`'s year

Since 2.32

### soup_date_free ()

    void                soup_date_free                      (SoupDate *date);

Frees `date`.

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

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

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

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

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

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

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

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

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

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

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

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

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

`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

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

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

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

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

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

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