![]() |
![]() |
![]() |
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 is libsoup's TCP socket type. While it is primarily
intended for internal use, SoupSockets are exposed in the
API in various places, and some of their methods (eg,
soup_socket_get_remote_address()
) may be useful to applications.
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 |
gboolean soup_socket_is_ssl (SoupSocket *sock);
Tests if sock
is set up to do SSL. Note that this simply means
that the SOUP_SOCKET_SSL_CREDENTIALS
property has been set; it
does not mean that soup_socket_start_ssl()
has been called.
|
a SoupSocket |
Returns : |
TRUE if sock has SSL credentials set
|
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_OK
, 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.
"disconnected"
signalvoid 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. |
"new-connection"
signalvoid 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. |
"readable"
signalvoid 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. |
"writable"
signalvoid 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. |