| libsoup Reference Manual | ||||
|---|---|---|---|---|
struct SoupSocket; SoupSocket* soup_socket_new (const char *optname1, ...); void (*SoupSocketCallback) (SoupSocket *sock, guint status, gpointer user_data); void soup_socket_connect_async (SoupSocket *sock, GCancellable *cancellable, SoupSocketCallback callback, gpointer user_data); guint soup_socket_connect_sync (SoupSocket *sock, GCancellable *cancellable); gboolean soup_socket_listen (SoupSocket *sock); gboolean soup_socket_start_ssl (SoupSocket *sock, GCancellable *cancellable); gboolean soup_socket_start_proxy_ssl (SoupSocket *sock, const char *ssl_host, GCancellable *cancellable); gboolean soup_socket_is_ssl (SoupSocket *sock); void soup_socket_disconnect (SoupSocket *sock); gboolean soup_socket_is_connected (SoupSocket *sock); SoupAddress* soup_socket_get_local_address (SoupSocket *sock); SoupAddress* soup_socket_get_remote_address (SoupSocket *sock); enum SoupSocketIOStatus; SoupSocketIOStatus soup_socket_read (SoupSocket *sock, gpointer buffer, gsize len, gsize *nread, GCancellable *cancellable, GError **error); SoupSocketIOStatus soup_socket_read_until (SoupSocket *sock, gpointer buffer, gsize len, gconstpointer boundary, gsize boundary_len, gsize *nread, gboolean *got_boundary, GCancellable *cancellable, GError **error); SoupSocketIOStatus soup_socket_write (SoupSocket *sock, gconstpointer buffer, gsize len, gsize *nwrote, GCancellable *cancellable, GError **error); #define SOUP_SSL_ERROR enum SoupSSLError; #define SOUP_SOCKET_LOCAL_ADDRESS #define SOUP_SOCKET_REMOTE_ADDRESS #define SOUP_SOCKET_FLAG_NONBLOCKING #define SOUP_SOCKET_IS_SERVER #define SOUP_SOCKET_SSL_CREDENTIALS #define SOUP_SOCKET_ASYNC_CONTEXT #define SOUP_SOCKET_TIMEOUT
"async-context" gpointer : Read / Write / Construct Only "is-server" gboolean : Read "local-address" SoupAddress : Read / Write / Construct Only "non-blocking" gboolean : Read / Write "remote-address" SoupAddress : Read / Write / Construct Only "ssl-creds" gpointer : Read / Write "timeout" guint : Read / Write
"disconnected" : Run Last "new-connection" : Run First "readable" : Run Last "writable" : Run Last
SoupSocket* soup_socket_new (const char *optname1, ...);
Creates a new (disconnected) socket
|
name of first property to set (or NULL)
|
|
value of optname1, followed by additional property/value pairs
|
Returns : |
the new socket |
void (*SoupSocketCallback) (SoupSocket *sock, guint status, gpointer user_data);
The callback function passed to soup_socket_connect_async().
|
the SoupSocket |
|
an HTTP status code indicating success or failure |
|
the data passed to soup_socket_connect_async()
|
void soup_socket_connect_async (SoupSocket *sock, GCancellable *cancellable, SoupSocketCallback callback, gpointer user_data);
Begins asynchronously connecting to sock's remote address. The
socket will call callback when it succeeds or fails (but not
before returning from this function).
If cancellable is non-NULL, it can be used to cancel the
connection. callback will still be invoked in this case, with a
status of SOUP_STATUS_CANCELLED.
|
a client SoupSocket (which must not already be connected) |
|
a GCancellable, or NULL
|
|
callback to call after connecting |
|
data to pass to callback
|
guint soup_socket_connect_sync (SoupSocket *sock, GCancellable *cancellable);
Attempt to synchronously connect sock to its remote address.
If cancellable is non-NULL, it can be used to cancel the
connection, in which case soup_socket_connect_sync() will return
SOUP_STATUS_CANCELLED.
|
a client SoupSocket (which must not already be connected) |
|
a GCancellable, or NULL
|
Returns : |
a success or failure code. |
gboolean soup_socket_listen (SoupSocket *sock);
Makes sock start listening on its local address. When connections
come in, sock will emit new_connection.
|
a server SoupSocket (which must not already be connected or listening) |
Returns : |
whether or not sock is now listening.
|
gboolean soup_socket_start_ssl (SoupSocket *sock, GCancellable *cancellable);
Starts using SSL on socket.
|
the socket |
|
a GCancellable |
Returns : |
success or failure |
gboolean soup_socket_start_proxy_ssl (SoupSocket *sock, const char *ssl_host, GCancellable *cancellable);
Starts using SSL on socket, expecting to find a host named
ssl_host.
|
the socket |
|
hostname of the SSL server |
|
a GCancellable |
Returns : |
success or failure |
void soup_socket_disconnect (SoupSocket *sock);
Disconnects sock. Any further read or write attempts on it will
fail.
|
a SoupSocket |
gboolean soup_socket_is_connected (SoupSocket *sock);
Tests if sock is connected to another host
|
a SoupSocket |
Returns : |
TRUE or FALSE.
|
SoupAddress* soup_socket_get_local_address (SoupSocket *sock);
Returns the SoupAddress corresponding to the local end of sock.
|
a SoupSocket |
Returns : |
the SoupAddress |
SoupAddress* soup_socket_get_remote_address (SoupSocket *sock);
Returns the SoupAddress corresponding to the remote end of sock.
|
a SoupSocket |
Returns : |
the SoupAddress |
typedef enum {
SOUP_SOCKET_OK,
SOUP_SOCKET_WOULD_BLOCK,
SOUP_SOCKET_EOF,
SOUP_SOCKET_ERROR
} SoupSocketIOStatus;
Return value from the SoupSocket IO methods.
SoupSocketIOStatus soup_socket_read (SoupSocket *sock, gpointer buffer, gsize len, gsize *nread, GCancellable *cancellable, GError **error);
Attempts to read up to len bytes from sock into buffer. If some
data is successfully read, soup_socket_read() will return
SOUP_SOCKET_OK, and *nread will contain the number of bytes
actually read.
If sock is non-blocking, and no data is available, the return
value will be SOUP_SOCKET_WOULD_BLOCK. In this case, the caller
can connect to the readable signal to know when there is more data
to read. (NB: You MUST read all available data off the socket
first. The readable signal will only be emitted after
soup_socket_read() has returned SOUP_SOCKET_WOULD_BLOCK.)
|
the socket |
|
buffer to read into |
|
size of buffer in bytes
|
|
on return, the number of bytes read into buffer
|
|
a GCancellable, or NULL
|
|
error pointer |
Returns : |
a SoupSocketIOStatus, as described above (or
SOUP_SOCKET_EOF if the socket is no longer connected, or
SOUP_SOCKET_ERROR on any other error, in which case error will
also be set).
|
SoupSocketIOStatus soup_socket_read_until (SoupSocket *sock, gpointer buffer, gsize len, gconstpointer boundary, gsize boundary_len, gsize *nread, gboolean *got_boundary, GCancellable *cancellable, GError **error);
Like soup_socket_read(), but reads no further than the first
occurrence of boundary. (If the boundary is found, it will be
included in the returned data, and *got_boundary will be set to
TRUE.) Any data after the boundary will returned in future reads.
|
the socket |
|
buffer to read into |
|
size of buffer in bytes
|
|
boundary to read until |
|
length of boundary in bytes
|
|
on return, the number of bytes read into buffer
|
|
on return, whether or not the data in buffer
ends with the boundary string
|
|
a GCancellable, or NULL
|
|
error pointer |
Returns : |
as for soup_socket_read()
|
SoupSocketIOStatus soup_socket_write (SoupSocket *sock, gconstpointer buffer, gsize len, gsize *nwrote, GCancellable *cancellable, GError **error);
Attempts to write len bytes from buffer to sock. If some data is
successfully written, the resturn status will be
SOUP_SOCKET_SUCCESS, and *nwrote will contain the number of bytes
actually written.
If sock is non-blocking, and no data could be written right away,
the return value will be SOUP_SOCKET_WOULD_BLOCK. In this case,
the caller can connect to the writable signal to know when more
data can be written. (NB: writable is only emitted after a
SOUP_SOCKET_WOULD_BLOCK.)
|
the socket |
|
data to write |
|
size of buffer, in bytes
|
|
on return, number of bytes written |
|
a GCancellable, or NULL
|
|
error pointer |
Returns : |
a SoupSocketIOStatus, as described above (or
SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR. error will be set if the
return value is SOUP_SOCKET_ERROR.)
|
typedef enum {
SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ,
SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE,
SOUP_SSL_ERROR_CERTIFICATE,
} SoupSSLError;
async-context" property"async-context" gpointer : Read / Write / Construct Only
The GMainContext to dispatch this socket's async I/O in.
is-server" property"is-server" gboolean : Read
Whether or not the socket is a server socket.
Default value: FALSE
local-address" property"local-address" SoupAddress : Read / Write / Construct Only
Address of local end of socket.
non-blocking" property"non-blocking" gboolean : Read / Write
Whether or not the socket uses non-blocking I/O.
Default value: TRUE
remote-address" property"remote-address" SoupAddress : Read / Write / Construct Only
Address of remote end of socket.
ssl-creds" property"ssl-creds" gpointer : Read / Write
SSL credential information, passed from the session to the SSL implementation.
timeout" property"timeout" guint : Read / Write
Value in seconds to timeout a blocking I/O.
Default value: 0
void user_function (SoupSocket *sock, gpointer user_data) : Run Last
Emitted when the socket is disconnected, for whatever reason.
|
the socket |
|
user data set when the signal handler was connected. |
void user_function (SoupSocket *sock, SoupSocket *new, gpointer user_data) : Run First
Emitted when a listening socket (set up with
soup_socket_listen()) receives a new connection.
You must ref the new if you want to keep it; otherwise it
will be destroyed after the signal is emitted.
|
the socket |
|
the new socket |
|
user data set when the signal handler was connected. |
void user_function (SoupSocket *sock, gpointer user_data) : Run Last
Emitted when an async socket is readable. See
soup_socket_read() and soup_socket_read_until().
|
the socket |
|
user data set when the signal handler was connected. |
void user_function (SoupSocket *sock, gpointer user_data) : Run Last
Emitted when an async socket is writable. See
soup_socket_write().
|
the socket |
|
user data set when the signal handler was connected. |