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