manpagez: man pages & more
html files: libsoup-2.4
Home | html | info | man

Soup Miscellaneous Utilities

Soup Miscellaneous Utilities — Miscellaneous functions

Types and Values

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, assumming it to be in UTC.

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

soup_date_to_timeval is deprecated and should not be used in newly-written code.

Do not use GTimeVal, as it's not Y2038-safe.

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


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_parse_param_list_strict ()

GHashTable *
soup_header_parse_param_list_strict (const char *header);

A strict version of soup_header_parse_param_list() that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use soup_header_parse_param_list() instead.

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list() or NULL if there are duplicate elements.

[element-type utf8 utf8][transfer full][nullable]

Since: 2.66


soup_header_parse_semi_param_list_strict ()

GHashTable *
soup_header_parse_semi_param_list_strict
                               (const char *header);

A strict version of soup_header_parse_semi_param_list() that bails out if there are duplicate parameters. Note that this function will treat RFC5987-encoded parameters as duplicated if an ASCII version is also present. For header fields that might contain RFC5987-encoded parameters, use soup_header_parse_semi_param_list() instead.

Parameters

header

a header value

 

Returns

a GHashTable of list elements, which can be freed with soup_header_free_param_list() or NULL if there are duplicate elements.

[element-type utf8 utf8][transfer full][nullable]

Since: 2.66


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

 
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.