Prev Up Home libsoup Reference Manual Next

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

Signal Prototypes


"authenticate"
            void        user_function      (SoupConnection *conn,
                                            SoupMessage *msg,
                                            gchar *auth_type,
                                            gchar *auth_realm,
                                            gpointer username,
                                            gpointer password,
                                            gpointer user_data);
"connect-result"
            void        user_function      (SoupConnection *conn,
                                            gint status,
                                            gpointer user_data);
"disconnected"
            void        user_function      (SoupConnection *conn,
                                            gpointer user_data);
"reauthenticate"
            void        user_function      (SoupConnection *conn,
                                            SoupMessage *msg,
                                            gchar *auth_type,
                                            gchar *auth_realm,
                                            gpointer username,
                                            gpointer password,
                                            gpointer user_data);

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.

Properties

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

Signals

The "authenticate" signal

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

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

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

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

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.
<< SoupAuth SoupConnectionNTLM >>