SoupConnection

SoupConnection — a single possibly-persistent HTTP connection

Synopsis




struct              SoupConnection;
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

Object Hierarchy


  GObject
   +----SoupConnection
         +----SoupConnectionNTLM

Properties


  "async-context"            gpointer              : Read / Write / Construct Only
  "message-filter"           gpointer              : Read / Write
  "origin-uri"               gpointer              : Read / Write / Construct Only
  "proxy-uri"                gpointer              : Read / Write / Construct Only
  "ssl-creds"                gpointer              : Read / Write / Construct Only
  "timeout"                  guint                 : Read / Write

Signals


  "authenticate"                                   : Run First
  "connect-result"                                 : Run First
  "disconnected"                                   : Run First
  "reauthenticate"                                 : Run First

Description

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

Details

struct SoupConnection

struct SoupConnection;

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.

Property Details

The "async-context" property

  "async-context"            gpointer              : Read / Write / Construct Only

GMainContext to dispatch this connection's async I/O in.

The "message-filter" property

  "message-filter"           gpointer              : Read / Write

Message filter object for this connection.

The "origin-uri" property

  "origin-uri"               gpointer              : Read / Write / Construct Only

The HTTP origin server to use for this connection.

The "proxy-uri" property

  "proxy-uri"                gpointer              : Read / Write / Construct Only

The HTTP Proxy to use for this connection.

The "ssl-creds" property

  "ssl-creds"                gpointer              : Read / Write / Construct Only

Opaque SSL credentials for this connection.

The "timeout" property

  "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

Signal Details

The "authenticate" signal

void                user_function                      (SoupConnection *conn,
                                                        SoupMessage    *msg,
                                                        gchar          *auth_type,
                                                        gchar          *auth_realm,
                                                        gpointer        username,
                                                        gpointer        password,
                                                        gpointer        user_data)       : Run First

Emitted when the connection requires authentication. (SoupConnectionNTLM makes use of this.)

conn :

 the connection

msg :

 the SoupMessage being sent

auth_type :

 the authentication type

auth_realm :

 the realm being authenticated to

username :

 the signal handler should set this to point to the provided username

password :

 the signal handler should set this to point to the provided password

user_data :

 user data set when the signal handler was connected.

The "connect-result" signal

void                user_function                      (SoupConnection *conn,
                                                        gint            status,
                                                        gpointer        user_data)      : Run First

Emitted when a connection attempt succeeds or fails. This is used internally by soup_connection_connect_async().

conn :

 the connection

status :

 the status

user_data :

 user data set when the signal handler was connected.

The "disconnected" signal

void                user_function                      (SoupConnection *conn,
                                                        gpointer        user_data)      : Run First

Emitted when the connection's socket is disconnected, for whatever reason.

conn :

 the connection

user_data :

 user data set when the signal handler was connected.

The "reauthenticate" signal

void                user_function                      (SoupConnection *conn,
                                                        SoupMessage    *msg,
                                                        gchar          *auth_type,
                                                        gchar          *auth_realm,
                                                        gpointer        username,
                                                        gpointer        password,
                                                        gpointer        user_data)       : Run First

Emitted when the authentication data acquired by a previous authenticate or reauthenticate signal fails.

conn :

 the connection

msg :

 the SoupMessage being sent

auth_type :

 the authentication type

auth_realm :

 the realm being authenticated to

username :

 the signal handler should set this to point to the provided username

password :

 the signal handler should set this to point to the provided password

user_data :

 user data set when the signal handler was connected.