SoupConnection

## 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

## Object Hierarchy

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

## Properties

      "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

## 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
`...` : |
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.

## Properties

### 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.

## 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.