## st-transfer

st-transfer — functions for transferring data over the network.

## Synopsis

    struct      STTransferSession;
    enum        STTransferFlags;
    void        (*STTransferLineCallback)       (const char *line,
                                                 gpointer data);
    STTransferSession* st_transfer_session_new  (void);
    void        st_transfer_session_free        (STTransferSession *session);
    gboolean    st_transfer_session_get         (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 char **headers,
                                                 char **body,
                                                 GError **err);
    gboolean    st_transfer_session_get_binary  (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 char **headers,
                                                 guint8 **body,
                                                 unsigned int *body_len,
                                                 GError **err);
    gboolean    st_transfer_session_get_by_line (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 STTransferLineCallback header_cb,
                                                 gpointer header_data,
                                                 STTransferLineCallback body_cb,
                                                 gpointer body_data,
                                                 GError **err);
    char*       st_transfer_escape              (const char *url);
    char*       st_transfer_get_full            (const char *url,
                                                 GError **err);
    gboolean    st_transfer_get_lines           (const char *url,
                                                 STTransferLineCallback cb,
                                                 gpointer data,
                                                 GError **err);
    char*       st_transfer_get_full_with_session
                                                (STTransferSession *session,
                                                 const char *url,
                                                 GError **err);
    gboolean    st_transfer_get_lines_with_session
                                                (STTransferSession *session,
                                                 const char *url,
                                                 STTransferLineCallback cb,
                                                 gpointer data,
                                                 GError **err);

## Description

## Details

### struct STTransferSession

    struct STTransferSession;

### enum STTransferFlags

    typedef enum
    {
      ST_TRANSFER_PASS_NEWLINE		= 1 << 0,
      ST_TRANSFER_UTF8			= 1 << 1,
      ST_TRANSFER_PARSE_HTTP_CHARSET	= 1 << 2,
      ST_TRANSFER_PARSE_HTML_CHARSET	= 1 << 3
    } STTransferFlags;

`ST_TRANSFER_PASS_NEWLINE` | specifies that the line terminator should be included in the line passed to `STTransferLineCallback()`.
`ST_TRANSFER_UTF8` | specifies that `st_transfer_session_get()` should fail if the body cannot be converted to UTF-8, and that `st_transfer_session_get_by_line()` should skip the body lines which cannot be converted to UTF-8.
`ST_TRANSFER_PARSE_HTTP_CHARSET` | specifies that charset information should be extracted from the HTTP Content-Type header, if present. To be used along with ST_TRANSFER_UTF8.
`ST_TRANSFER_PARSE_HTML_CHARSET` | specifies that charset information should be extracted from the http-equiv="Content-Type" meta tag of the HTML header, if present. To be used along with ST_TRANSFER_UTF8.

### STTransferLineCallback ()

    void        (*STTransferLineCallback)       (const char *line,
                                                 gpointer data);

Specifies the type of function to pass to `st_transfer_session_get_by_line()`.

The function will be called whenever a line has been transferred.

`line` : | a line. If ST_TRANSFER_PASS_NEWLINE was used, the line terminator is included. If ST_TRANSFER_UTF8 was used, the line is valid UTF-8.
`data` : | data pointer passed to `st_transfer_session_get_by_line()`.

### st_transfer_session_new ()

    STTransferSession* st_transfer_session_new  (void);

Creates a new transfer session.

Returns : | the new session, which should be freed with `st_transfer_session_free()` when no longer needed.

### st_transfer_session_free ()

    void        st_transfer_session_free        (STTransferSession *session);

Destroys `session`.

`session` : | the transfer session to destroy.

### st_transfer_session_get ()

    gboolean    st_transfer_session_get         (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 char **headers,
                                                 char **body,
                                                 GError **err);

Gets the data located at `url`.

`session` : | a transfer session.
`url` : | the URL of the data to get.
`flags` : | the transfer flags. Valid flags are ST_TRANSFER_UTF8, ST_TRANSFER_PARSE_HTTP_CHARSET and ST_TRANSFER_PARSE_HTML_CHARSET.
`headers` : | a location to return the header data, or `NULL`. The returned data is guaranteed to be valid ASCII.
`body` : | a location to return the body data, or `NULL`. If ST_TRANSFER_UTF8 is used, the returned data is guaranteed to be valid UTF-8.
`err` : | a location to store errors, or `NULL`.
Returns : | `FALSE` if there was an error (in such case, `err` will be set). If `TRUE` is returned, strings will be stored at `headers` and `body`. They should be freed when no longer needed.

### st_transfer_session_get_binary ()

    gboolean    st_transfer_session_get_binary  (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 char **headers,
                                                 guint8 **body,
                                                 unsigned int *body_len,
                                                 GError **err);

Gets the binary data located at `url`.

`session` : | a transfer session.
`url` : | the URL of the data to get.
`flags` : | must be 0.
`headers` : | a location to return the header data, or `NULL`. The returned data is guaranteed to be valid ASCII.
`body` : | a location to return the body data, or `NULL`. If set, `body_len` must also be set.
`body_len` : | a location to return the body length, or `NULL`.
`err` : | a location to store errors, or `NULL`.
Returns : | `FALSE` if there was an error (in such case, `err` will be set). If `TRUE` is returned, a string will be stored at `headers` and a character buffer will be stored at `body`. They both should be freed when no longer needed.

### st_transfer_session_get_by_line ()

    gboolean    st_transfer_session_get_by_line (STTransferSession *session,
                                                 const char *url,
                                                 STTransferFlags flags,
                                                 STTransferLineCallback header_cb,
                                                 gpointer header_data,
                                                 STTransferLineCallback body_cb,
                                                 gpointer body_data,
                                                 GError **err);

Gets the data located at `url`, splitting it into lines and passing them to `header_cb` and `body_cb`.

`session` : | a transfer session.
`url` : | the URL of the data to get.
`flags` : | the transfer flags. Valid flags are ST_TRANSFER_PASS_NEWLINE, ST_TRANSFER_UTF8, ST_TRANSFER_PARSE_HTTP_CHARSET and ST_TRANSFER_PARSE_HTML_CHARSET.
`header_cb` : | a function to call when a header line arrives, or `NULL`. The line passed to the function is guaranteed to be valid ASCII.
`header_data` : | data to pass to `header_cb`.
`body_cb` : | a function to call when a body line arrives, or `NULL`. If ST_TRANSFER_UTF8 is used, the line passed to the function is guaranteed to be valid UTF-8.
`body_data` : | data to pass to `body_cb`.
`err` : | a location to store errors, or `NULL`.
Returns : | `FALSE` if there was an error (in such case, `err` will be set).

### st_transfer_escape ()

    char*       st_transfer_escape              (const char *url);

Escapes unsafe characters of `url` using standard percent notation.

`url` : | an URL or URL part to escape.
Returns : | `url` with unsafe characters escaped. The returned string must be freed when no longer needed.

### st_transfer_get_full ()

    char*       st_transfer_get_full            (const char *url,
                                                 GError **err);

### Warning

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

`url` : |
`err` : |
Returns : |

### st_transfer_get_lines ()

    gboolean    st_transfer_get_lines           (const char *url,
                                                 STTransferLineCallback cb,
                                                 gpointer data,
                                                 GError **err);

### Warning

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

`url` : |
`cb` : |
`data` : |
`err` : |
Returns : |

### st_transfer_get_full_with_session ()

    char*       st_transfer_get_full_with_session
                                                (STTransferSession *session,
                                                 const char *url,
                                                 GError **err);

### Warning

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

`session` : |
`url` : |
`err` : |
Returns : |

### st_transfer_get_lines_with_session ()

    gboolean    st_transfer_get_lines_with_session
                                                (STTransferSession *session,
                                                 const char *url,
                                                 STTransferLineCallback cb,
                                                 gpointer data,
                                                 GError **err);

### Warning

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

`session` : |
`url` : |
`cb` : |
`data` : |
`err` : |
Returns : |

## See Also

st-sgml-ref