![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
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
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
optname1 : |
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()
.
sock : |
the SoupSocket |
status : |
an HTTP status code indicating success or failure |
user_data : |
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
.
sock : |
a client SoupSocket (which must not already be connected) |
cancellable : |
a GCancellable, or NULL
|
callback : |
callback to call after connecting |
user_data : |
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
.
sock : |
a client SoupSocket (which must not already be connected) |
cancellable : |
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
.
sock : |
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
.
sock : |
the socket |
cancellable : |
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
.
sock : |
the socket |
ssl_host : |
hostname of the SSL server |
cancellable : |
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.
sock : |
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.
sock : |
a SoupSocket |
gboolean soup_socket_is_connected (SoupSocket *sock);
Tests if sock
is connected to another host
sock : |
a SoupSocket |
Returns : | TRUE or FALSE .
|
SoupAddress* soup_socket_get_local_address (SoupSocket *sock);
Returns the SoupAddress corresponding to the local end of sock
.
sock : |
a SoupSocket |
Returns : | the SoupAddress |
SoupAddress* soup_socket_get_remote_address (SoupSocket *sock);
Returns the SoupAddress corresponding to the remote end of sock
.
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 (which may be less than len
).
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. "readable" is only emitted after
soup_socket_read()
returns SOUP_SOCKET_WOULD_BLOCK
, and it is only
emitted once. See the documentation for "non-blocking".)
sock : |
the socket |
buffer : |
buffer to read into |
len : |
size of buffer in bytes
|
nread : |
on return, the number of bytes read into buffer
|
cancellable : |
a GCancellable, or NULL
|
error : |
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.
soup_socket_read_until()
will almost always return fewer than len
bytes: if the boundary is found, then it will only return the bytes
up until the end of the boundary, and if the boundary is not found,
then it will leave the last (boundary_len - 1)
bytes in its internal buffer, in case they form the start of the
boundary string. Thus, len
normally needs to be at least 1 byte
longer than boundary_len
if you want to make any progress at all.
sock : |
the socket |
buffer : |
buffer to read into |
len : |
size of buffer in bytes
|
boundary : |
boundary to read until |
boundary_len : |
length of boundary in bytes
|
nread : |
on return, the number of bytes read into buffer
|
got_boundary : |
on return, whether or not the data in buffer
ends with the boundary string
|
cancellable : |
a GCancellable, or NULL
|
error : |
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 return status will be SOUP_SOCKET_OK
,
and *nwrote
will contain the number of bytes actually written
(which may be less than len
).
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 soup_socket_write()
returns SOUP_SOCKET_WOULD_BLOCK
,
and it is only emitted once. See the documentation for
"non-blocking".)
sock : |
the socket |
buffer : |
data to write |
len : |
size of buffer , in bytes
|
nwrote : |
on return, number of bytes written |
cancellable : |
a GCancellable, or NULL
|
error : |
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 .)
|
#define SOUP_SSL_ERROR soup_ssl_error_quark()
A GError domain representing an SSL error. Used with SoupSSLError.
typedef enum { SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ, SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE, SOUP_SSL_ERROR_CERTIFICATE } SoupSSLError;
SSL-related I/O errors.
#define SOUP_SOCKET_LOCAL_ADDRESS "local-address"
Alias for the "local-address" property. (Address of local end of socket.)
#define SOUP_SOCKET_REMOTE_ADDRESS "remote-address"
Alias for the "remote-address" property. (Address of remote end of socket.)
#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"
Alias for the "non-blocking" property. (Whether or not the socket uses non-blocking I/O.)
#define SOUP_SOCKET_IS_SERVER "is-server"
Alias for the "is-server" property. (Whether or not the socket is a server socket.)
#define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds"
Alias for the "ssl-credentials" property. (SSL credential information.)
#define SOUP_SOCKET_ASYNC_CONTEXT "async-context"
Alias for the "async-context" property. (The socket's GMainContext.)