## SoupConnection

SoupConnection —

## Synopsis

    #define     SOUP_CONNECTION_ORIGIN_URI
    #define     SOUP_CONNECTION_PROXY_URI
    #define     SOUP_CONNECTION_SSL_CREDENTIALS
    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);

## Description

## Details

### SOUP_CONNECTION_ORIGIN_URI

    #define SOUP_CONNECTION_ORIGIN_URI      "origin-uri"

### SOUP_CONNECTION_PROXY_URI

    #define SOUP_CONNECTION_PROXY_URI       "proxy-uri"

### SOUP_CONNECTION_SSL_CREDENTIALS

    #define SOUP_CONNECTION_SSL_CREDENTIALS "ssl-creds"

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