![]() |
![]() |
![]() |
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. |