## soup-misc

soup-misc — Miscellaneous functions

## Synopsis

                SoupMD5Context;
    void        soup_md5_init                   (SoupMD5Context *ctx);
    void        soup_md5_update                 (SoupMD5Context *ctx,
                                                 gconstpointer buf,
                                                 gsize len);
    void        soup_md5_final                  (SoupMD5Context *ctx,
                                                 guchar digest[16]);
    void        soup_md5_final_hex              (SoupMD5Context *ctx,
                                                 char digest[33]);

    char*       soup_base64_decode              (const gchar *text,
                                                 int *out_len);
    char*       soup_base64_encode              (const char *text,
                                                 int len);
    int         soup_base64_decode_step         (const guchar *in,
                                                 int len,
                                                 guchar *out,
                                                 int *state,
                                                 guint *save);
    int         soup_base64_encode_step         (const guchar *in,
                                                 int len,
                                                 gboolean break_lines,
                                                 guchar *out,
                                                 int *state,
                                                 int *save);
    int         soup_base64_encode_close        (const guchar *in,
                                                 int inlen,
                                                 gboolean break_lines,
                                                 guchar *out,
                                                 int *state,
                                                 int *save);

    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);
    guint       soup_signal_connect_once        (gpointer instance,
                                                 const char *detailed_signal,
                                                 GCallback c_handler,
                                                 gpointer data);

    time_t      soup_date_parse                 (const char *timestamp);
    time_t      soup_date_iso8601_parse         (const char *timestamp);
    char*       soup_date_generate              (time_t when);
    void        soup_gmtime                     (const time_t *when,
                                                 struct tm *tm);
    time_t      soup_mktime_utc                 (struct tm *tm);

    char*       soup_header_param_copy_token    (GHashTable *tokens,
                                                 char *t);
    char*       soup_header_param_decode_token  (char **in);
    void        soup_header_param_destroy_hash  (GHashTable *table);
    GHashTable* soup_header_param_parse_list    (const char *header);
    gboolean    soup_headers_parse_request      (const char *str,
                                                 int len,
                                                 GHashTable *dest,
                                                 char **req_method,
                                                 char **req_path,
                                                 SoupHttpVersion *ver);
    gboolean    soup_headers_parse_response     (const char *str,
                                                 int len,
                                                 GHashTable *dest,
                                                 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_str_case_equal             (gconstpointer v1,
                                                 gconstpointer v2);
    guint       soup_str_case_hash              (gconstpointer key);

## Description

## Details

### SoupMD5Context

    typedef struct {
    } SoupMD5Context;

### soup_md5_init ()

    void        soup_md5_init                   (SoupMD5Context *ctx);

Initialise an md5 buffer.

`ctx` : | md5 context

### soup_md5_update ()

    void        soup_md5_update                 (SoupMD5Context *ctx,
                                                 gconstpointer buf,
                                                 gsize len);

Update context to reflect the concatenation of another buffer full of bytes. Use this to progressively construct an md5 hash.

`ctx` : | conetxt object used for md5 computaion
`buf` : | buffer to add
`len` : | buffer length

### soup_md5_final ()

    void        soup_md5_final                  (SoupMD5Context *ctx,
                                                 guchar digest[16]);

Performs the final md5 transformation on the context, and then copies the resulting md5 hash to a buffer

`ctx` : | context containing the calculated md5
`digest` : | 16 bytes buffer

### soup_md5_final_hex ()

    void        soup_md5_final_hex              (SoupMD5Context *ctx,
                                                 char digest[33]);

As `soup_md5_final()`, but copies the final md5 hash to a buffer as a NUL-terminated hexadecimal string

`ctx` : | context containing the calculated md5
`digest` : | 33 bytes buffer (32 hex digits plus NUL)

### soup_base64_decode ()

    char*       soup_base64_decode              (const gchar *text,
                                                 int *out_len);

`text` : |
`out_len` : |
Returns : |

### soup_base64_encode ()

    char*       soup_base64_encode              (const char *text,
                                                 int len);

Encode a sequence of binary data into it's Base-64 stringified representation.

`text` : | the binary data to encode.
`len` : | the length of `text`.
Returns : | The Base-64 encoded string representing `text`.

### soup_base64_decode_step ()

    int         soup_base64_decode_step         (const guchar *in,
                                                 int len,
                                                 guchar *out,
                                                 int *state,
                                                 guint *save);

`in` : |
`len` : |
`out` : |
`state` : |
`save` : |
Returns : |

### soup_base64_encode_step ()

    int         soup_base64_encode_step         (const guchar *in,
                                                 int len,
                                                 gboolean break_lines,
                                                 guchar *out,
                                                 int *state,
                                                 int *save);

`in` : |
`len` : |
`break_lines` : |
`out` : |
`state` : |
`save` : |
Returns : |

### soup_base64_encode_close ()

    int         soup_base64_encode_close        (const guchar *in,
                                                 int inlen,
                                                 gboolean break_lines,
                                                 guchar *out,
                                                 int *state,
                                                 int *save);

`in` : |
`inlen` : |
`break_lines` : |
`out` : |
`state` : |
`save` : |
Returns : |

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

    guint       soup_signal_connect_once        (gpointer instance,
                                                 const char *detailed_signal,
                                                 GCallback c_handler,
                                                 gpointer data);

Connects a GCallback function to a signal as with `g_signal_connect()`, but automatically removes the signal handler after its first invocation.

`instance` : | an object
`detailed_signal` : | "signal-name" or "signal-name::detail" to connect to
`c_handler` : | the GCallback to connect
`data` : | data to pass to `c_handler` calls
Returns : | the signal handler id

### soup_date_parse ()

    time_t      soup_date_parse                 (const char *timestamp);

Parses `timestamp` and returns its value as a time_t.

`timestamp` : | a timestamp, in any of the allowed HTTP 1.1 formats
Returns : | the time_t corresponding to `timestamp`, or -1 if `timestamp` couldn't be parsed.

### soup_date_iso8601_parse ()

    time_t      soup_date_iso8601_parse         (const char *timestamp);

Converts `timestamp` to a `time_t` value. `timestamp` can be in any of the iso8601 formats that specify both a date and a time.

`timestamp` : | an ISO8601 timestamp
Returns : | the `time_t` corresponding to `timestamp`, or -1 on error.

### soup_date_generate ()

    char*       soup_date_generate              (time_t when);

Generates an HTTP 1.1 Date header corresponding to `when`.

`when` : | the time to generate a timestamp for
Returns : | the timestamp, which the caller must free.

### soup_gmtime ()

    void        soup_gmtime                     (const time_t *when,
                                                 struct tm *tm);

Expands `when` into `tm` (as a UTC time). This is just a wrapper around `gmtime_r()` (or `gmtime()` on lame platforms). (The Microsoft C library on Windows doesn't have `gmtime_r()`, but its `gmtime()` is in fact thread-safe as it uses a per-thread buffer, so it's not totally lame ;-)

`when` : | a time_t
`tm` : | a struct tm to be filled in with the expansion of `when`

### soup_mktime_utc ()

    time_t      soup_mktime_utc                 (struct tm *tm);

Converts `tm` to a time_t. Unlike with `mktime()`, `tm` is interpreted as being a UTC time.

`tm` : | the UTC time
Returns : | `tm` as a time_t

### soup_header_param_copy_token ()

    char*       soup_header_param_copy_token    (GHashTable *tokens,
                                                 char *t);

`tokens` : |
`t` : |
Returns : |

### soup_header_param_decode_token ()

    char*       soup_header_param_decode_token  (char **in);

`in` : |
Returns : |

### soup_header_param_destroy_hash ()

    void        soup_header_param_destroy_hash  (GHashTable *table);

`table` : |

### soup_header_param_parse_list ()

    GHashTable* soup_header_param_parse_list    (const char *header);

`header` : |
Returns : |

### soup_headers_parse_request ()

    gboolean    soup_headers_parse_request      (const char *str,
                                                 int len,
                                                 GHashTable *dest,
                                                 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 `dest`.

`str` : | the header string (including the trailing blank line)
`len` : | length of `str` up to (but not including) the terminating blank line.
`dest` : | GHashTable 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 : | success or failure.

### soup_headers_parse_response ()

    gboolean    soup_headers_parse_response     (const char *str,
                                                 int len,
                                                 GHashTable *dest,
                                                 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 `dest`.

`str` : | the header string (including the trailing blank line)
`len` : | length of `str` up to (but not including) the terminating blank line.
`dest` : | GHashTable 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_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.