Soup Miscellaneous Utilities

Soup Miscellaneous Utilities — Miscellaneous functions

Synopsis




                    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);
void                soup_date_free                      (SoupDate *date);

GHashTable*         soup_form_decode_urlencoded         (const char *encoded_form);
char*               soup_form_encode_urlencoded         (GHashTable *form_data_set);
char*               soup_form_encode_urlencoded_list    (GData **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              gboolean soup_ssl_supported;

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)

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

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.

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

void                soup_date_free                      (SoupDate *date);

Frees date.

date :

a SoupDate

soup_form_decode_urlencoded ()

GHashTable*         soup_form_decode_urlencoded         (const char *encoded_form);

Decodes form, which is an urlencoded dataset as defined in the HTML 4.01 spec.

encoded_form :

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

soup_form_encode_urlencoded ()

char*               soup_form_encode_urlencoded         (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 spec states that "The control names/values are listed in the order they appear in the document." Since soup_form_encode_urlencoded() takes a hash table, this cannot be enforced; if you care about the ordering of the form fields, use soup_form_encode_urlencoded_list().

form_data_set :

a hash table containing name/value pairs

Returns :

the encoded form

soup_form_encode_urlencoded_list ()

char*               soup_form_encode_urlencoded_list    (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_urlencoded(), this preserves the ordering of the form elements, which may be required in some situations.

form_data_set :

a hash table containing name/value pairs

Returns :

the encoded form

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 header string (including the trailing blank line)

len :

length of str up to (but not including) the terminating blank line.

req_headers :

SoupMessageHeaders to store the header values in

req_method :

if non-NULL, will be filled in with the request method

req_path :

if non-NULL, will be filled in with the request path

ver :

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.

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 header string (including the trailing blank line)

len :

length of str up to (but not including) the terminating blank line.

headers :

SoupMessageheaders to store the header values in

ver :

if non-NULL, will be filled in with the HTTP version

status_code :

if non-NULL, will be filled in with the status code

reason_phrase :

if non-NULL, will be filled in with the reason phrase

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

status_code :

if non-NULL, will be filled in with the status code

reason_phrase :

if non-NULL, will be filled in with the reason phrase

Returns :

TRUE if status_line was parsed successfully.

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

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

Returns :

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

soup_header_free_list ()

void                soup_header_free_list               (GSList *list);

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

header :

a header value

Returns :

a GHashTable of list elements.

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

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

async_context :

the GMainContext to dispatch the idle event in, or NULL for the default context

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

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 timeout in, or NULL for the default context

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

soup_ssl_supported

extern gboolean soup_ssl_supported;

Can be used to test if libsoup was compiled with ssl support.