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_NEWLINEspecifies that the line terminator should be included in the line passed to STTransferLineCallback().
ST_TRANSFER_UTF8specifies 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_CHARSETspecifies 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_CHARSETspecifies 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