## soup-misc

soup-misc — Miscellaneous functions

## Synopsis

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

    xmlNode*            soup_xml_real_node                  (xmlNode *node);

## Description

## Details

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

`text` : |
`len` : |
Returns : |

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

Beware that `dest` 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.
`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`.

Beware that `dest` 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.
`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.

### soup_xml_real_node ()

    xmlNode*            soup_xml_real_node                  (xmlNode *node);

Finds the first "real" node (ie, not a comment or whitespace) at or after `node` at its level in the tree.

Return: a node, or `NULL`

`node` : | an `xmlNodePtr`
Returns : |