SoupConnection

SoupConnection — a single possibly-persistent HTTP connection

Synopsis

SoupConnection*     soup_connection_new                 (const char *propname1,
                                                         ...);
void                (*SoupConnectionCallback)           (SoupConnection *conn,
                                                         guint status,
                                                         gpointer data);
void                soup_connection_connect_async       (SoupConnection *conn,
                                                         SoupConnectionCallback callback,
                                                         gpointer user_data);
guint               soup_connection_connect_sync        (SoupConnection *conn);
void                soup_connection_disconnect          (SoupConnection *conn);
gboolean            soup_connection_is_in_use           (SoupConnection *conn);
time_t              soup_connection_last_used           (SoupConnection *conn);
void                soup_connection_send_request        (SoupConnection *conn,
                                                         SoupMessage *req);
void                soup_connection_authenticate        (SoupConnection *conn,
                                                         SoupMessage *msg,
                                                         const char *auth_type,
                                                         const char *auth_realm,
                                                         char **username,
                                                         char **password);
void                soup_connection_reauthenticate      (SoupConnection *conn,
                                                         SoupMessage *msg,
                                                         const char *auth_type,
                                                         const char *auth_realm,
                                                         char **username,
                                                         char **password);
void                soup_connection_release             (SoupConnection *conn);
void                soup_connection_reserve             (SoupConnection *conn);
#define             SOUP_CONNECTION_ORIGIN_URI
#define             SOUP_CONNECTION_PROXY_URI
#define             SOUP_CONNECTION_SSL_CREDENTIALS
#define             SOUP_CONNECTION_MESSAGE_FILTER
#define             SOUP_CONNECTION_ASYNC_CONTEXT
#define             SOUP_CONNECTION_TIMEOUT

Description

SoupConnection represents a single connection to an HTTP server (possibly via a proxy). Connection objects are created and destroyed automatically by SoupSession.

Details

soup_connection_new ()

SoupConnection*     soup_connection_new                 (const char *propname1,
                                                         ...);

Creates an HTTP connection. You must set at least one of SOUP_CONNECTION_ORIGIN_URI or SOUP_CONNECTION_PROXY_URI. If you set an origin server URI but no proxy URI, this will be a direct connection. If you set a proxy URI and an https origin server URI, this will be a tunnel. Otherwise it will be an http proxy connection.

You must call soup_connection_connect_async() or soup_connection_connect_sync() to connect it after creating it.

propname1 :

name of first property to set

... :

value of propname1, followed by additional property/value pairs

Returns :

the new connection (not yet ready for use).

SoupConnectionCallback ()

void                (*SoupConnectionCallback)           (SoupConnection *conn,
                                                         guint status,
                                                         gpointer data);

The callback function passed to soup_connection_connect_async().

conn :

the SoupConnection

status :

an HTTP status code indicating success or failure

data :

the data passed to soup_connection_connect_async()

soup_connection_connect_async ()

void                soup_connection_connect_async       (SoupConnection *conn,
                                                         SoupConnectionCallback callback,
                                                         gpointer user_data);

Asynchronously connects conn.

conn :

the connection

callback :

callback to call when the connection succeeds or fails

user_data :

data for callback

soup_connection_connect_sync ()

guint               soup_connection_connect_sync        (SoupConnection *conn);

Synchronously connects conn.

conn :

the connection

Returns :

the soup status

soup_connection_disconnect ()

void                soup_connection_disconnect          (SoupConnection *conn);

Disconnects conn's socket and emits a disconnected signal. After calling this, conn will be essentially useless.

conn :

a connection

soup_connection_is_in_use ()

gboolean            soup_connection_is_in_use           (SoupConnection *conn);

Tests whether or not conn is in use.

conn :

a connection

Returns :

TRUE if there is currently a request being processed on conn.

soup_connection_last_used ()

time_t              soup_connection_last_used           (SoupConnection *conn);

Returns the last time a response was received on conn.

conn :

a SoupConnection.

Returns :

the last time a response was received on conn, or 0 if conn has not been used yet.

soup_connection_send_request ()

void                soup_connection_send_request        (SoupConnection *conn,
                                                         SoupMessage *req);

Sends req on conn. This is a low-level function, intended for use by SoupSession.

conn :

a SoupConnection

req :

a SoupMessage

soup_connection_authenticate ()

void                soup_connection_authenticate        (SoupConnection *conn,
                                                         SoupMessage *msg,
                                                         const char *auth_type,
                                                         const char *auth_realm,
                                                         char **username,
                                                         char **password);

Emits the authenticate signal on conn. For use by SoupConnection subclasses.

conn :

a SoupConnection

msg :

the message to authenticate

auth_type :

type of authentication to use

auth_realm :

authentication realm

username :

on successful return, will contain the username to authenticate with

password :

on successful return, will contain the password to authenticate with

soup_connection_reauthenticate ()

void                soup_connection_reauthenticate      (SoupConnection *conn,
                                                         SoupMessage *msg,
                                                         const char *auth_type,
                                                         const char *auth_realm,
                                                         char **username,
                                                         char **password);

Emits the reauthenticate signal on conn. For use by SoupConnection subclasses.

conn :

a SoupConnection

msg :

the message to authenticate

auth_type :

type of authentication to use

auth_realm :

authentication realm

username :

on successful return, will contain the username to authenticate with

password :

on successful return, will contain the password to authenticate with

soup_connection_release ()

void                soup_connection_release             (SoupConnection *conn);

Marks conn as not "in use". This can be used to cancel the effect of a soup_connection_reserve(). It is not necessary to call this after soup_connection_send_request().

conn :

a SoupConnection

soup_connection_reserve ()

void                soup_connection_reserve             (SoupConnection *conn);

Marks conn as "in use" despite not actually having a message on it. This is used by SoupSession to keep it from accidentally trying to queue two messages on the same connection from different threads at the same time.

conn :

a SoupConnection

SOUP_CONNECTION_ORIGIN_URI

#define SOUP_CONNECTION_ORIGIN_URI      "origin-uri"

An alias for the "origin-uri" property.


SOUP_CONNECTION_PROXY_URI

#define SOUP_CONNECTION_PROXY_URI       "proxy-uri"

An alias for the "proxy-uri" property.


SOUP_CONNECTION_SSL_CREDENTIALS

#define SOUP_CONNECTION_SSL_CREDENTIALS "ssl-creds"

An alias for the "ssl-creds" property.


SOUP_CONNECTION_MESSAGE_FILTER

#define SOUP_CONNECTION_MESSAGE_FILTER  "message-filter"

An alias for the "message-filter" property.


SOUP_CONNECTION_ASYNC_CONTEXT

#define SOUP_CONNECTION_ASYNC_CONTEXT   "async-context"

An alias for the "async-context" property.


SOUP_CONNECTION_TIMEOUT

#define SOUP_CONNECTION_TIMEOUT		"timeout"

An alias for the "timeout" property.