![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
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
"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
"authenticate" void user_function (SoupConnection *conn, SoupMessage *msg, gchar *auth_type, gchar *auth_realm, gpointer username, gpointer password, gpointer user_data) : Run first "connect-result" void user_function (SoupConnection *conn, gint status, gpointer user_data) : Run first "disconnected" void user_function (SoupConnection *conn, gpointer user_data) : Run first "reauthenticate" void user_function (SoupConnection *conn, SoupMessage *msg, gchar *auth_type, gchar *auth_realm, gpointer username, gpointer password, gpointer user_data) : Run first
SoupConnection represents a single connection to an HTTP server (possibly via a proxy). Connection objects are created and destroyed automatically by SoupSession.
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). |
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() |
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 |
guint soup_connection_connect_sync (SoupConnection *conn);
Synchronously connects conn.
conn : | the connection |
Returns : | the soup status |
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 |
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. |
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. |
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 |
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 |
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 |
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 |
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 |
#define SOUP_CONNECTION_ORIGIN_URI "origin-uri"
An alias for the "origin-uri" property.
#define SOUP_CONNECTION_PROXY_URI "proxy-uri"
An alias for the "proxy-uri" property.
#define SOUP_CONNECTION_SSL_CREDENTIALS "ssl-creds"
An alias for the "ssl-creds" property.
"async-context" gpointer : Read / Write / Construct Only
GMainContext to dispatch this connection's async I/O in.
"message-filter" gpointer : Read / Write
Message filter object for this connection.
"origin-uri" gpointer : Read / Write / Construct Only
The HTTP origin server to use for this connection.
"proxy-uri" gpointer : Read / Write / Construct Only
The HTTP Proxy to use for this connection.
"ssl-creds" gpointer : Read / Write / Construct Only
Opaque SSL credentials for this connection.
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. |
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. |
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. |
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. |