![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
Synopsis
#include <libsoup/soup.h> 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
Properties
"async-context" gpointer : Read / Write / Construct Only "clean-dispose" gboolean : 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 "ssl-strict" gboolean : Read / Write / Construct Only "timeout" guint : Read / Write "tls-certificate" GTlsCertificate* : Read "tls-errors" GTlsCertificateFlags : Read "trusted-certificate" gboolean : Read
Signals
"disconnected" : Run Last "new-connection" : Run First "readable" : Run Last "writable" : Run Last
Description
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.
Details
soup_socket_new ()
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 |
SoupSocketCallback ()
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()
|
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. [scope async] |
|
data to pass to callback
|
soup_socket_connect_sync ()
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. |
soup_socket_listen ()
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.
|
soup_socket_start_ssl ()
gboolean soup_socket_start_ssl (SoupSocket *sock
,GCancellable *cancellable
);
Starts using SSL on socket
.
|
the socket |
|
a GCancellable |
Returns : |
success or failure |
soup_socket_start_proxy_ssl ()
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 |
soup_socket_is_ssl ()
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
|
soup_socket_disconnect ()
void soup_socket_disconnect (SoupSocket *sock
);
Disconnects sock
. Any further read or write attempts on it will
fail.
|
a SoupSocket |
soup_socket_is_connected ()
gboolean soup_socket_is_connected (SoupSocket *sock
);
Tests if sock
is connected to another host
|
a SoupSocket |
Returns : |
TRUE or FALSE .
|
soup_socket_get_local_address ()
SoupAddress * soup_socket_get_local_address (SoupSocket *sock
);
Returns the SoupAddress corresponding to the local end of sock
.
|
a SoupSocket |
Returns : |
the SoupAddress. [transfer none] |
soup_socket_get_remote_address ()
SoupAddress * soup_socket_get_remote_address (SoupSocket *sock
);
Returns the SoupAddress corresponding to the remote end of sock
.
|
a SoupSocket |
Returns : |
the SoupAddress. [transfer none] |
enum SoupSocketIOStatus
typedef enum { SOUP_SOCKET_OK, SOUP_SOCKET_WOULD_BLOCK, SOUP_SOCKET_EOF, SOUP_SOCKET_ERROR } SoupSocketIOStatus;
Return value from the SoupSocket IO methods.
soup_socket_read ()
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".)
|
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).
|
soup_socket_read_until ()
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.
|
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()
|
soup_socket_write ()
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".)
|
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 .)
|
SOUP_SSL_ERROR
#define SOUP_SSL_ERROR soup_ssl_error_quark()
A GError domain representing an SSL error. Used with SoupSSLError.
enum SoupSSLError
typedef enum { SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ, SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE, SOUP_SSL_ERROR_CERTIFICATE, SOUP_SSL_ERROR_HANDSHAKE_FAILED } SoupSSLError;
SSL-related I/O errors.
SOUP_SOCKET_LOCAL_ADDRESS
#define SOUP_SOCKET_LOCAL_ADDRESS "local-address"
Alias for the "local-address" property. (Address of local end of socket.)
SOUP_SOCKET_REMOTE_ADDRESS
#define SOUP_SOCKET_REMOTE_ADDRESS "remote-address"
Alias for the "remote-address" property. (Address of remote end of socket.)
SOUP_SOCKET_FLAG_NONBLOCKING
#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"
Alias for the "non-blocking" property. (Whether or not the socket uses non-blocking I/O.)
SOUP_SOCKET_IS_SERVER
#define SOUP_SOCKET_IS_SERVER "is-server"
Alias for the "is-server" property. (Whether or not the socket is a server socket.)
SOUP_SOCKET_SSL_CREDENTIALS
#define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds"
Alias for the "ssl-credentials" property. (SSL credential information.)
SOUP_SOCKET_ASYNC_CONTEXT
#define SOUP_SOCKET_ASYNC_CONTEXT "async-context"
Alias for the "async-context" property. (The socket's GMainContext.)
SOUP_SOCKET_TIMEOUT
#define SOUP_SOCKET_TIMEOUT "timeout"
Alias for the "timeout" property. (The timeout in seconds for blocking socket I/O operations.)
Property Details
The "async-context"
property
"async-context" gpointer : Read / Write / Construct Only
The GMainContext to dispatch this socket's async I/O in.
The "clean-dispose"
property
"clean-dispose" gboolean : Write / Construct Only
Warn on unclean dispose.
Default value: FALSE
The "is-server"
property
"is-server" gboolean : Read
Whether or not the socket is a server socket.
Default value: FALSE
The "local-address"
property
"local-address" SoupAddress* : Read / Write / Construct Only
Address of local end of socket.
The "non-blocking"
property
"non-blocking" gboolean : Read / Write
Whether or not the socket uses non-blocking I/O.
SoupSocket's I/O methods are designed around the idea of
using a single codepath for both synchronous and
asynchronous I/O. If you want to read off a SoupSocket,
the "correct" way to do it is to call soup_socket_read()
or
soup_socket_read_until()
repeatedly until you have read
everything you want. If it returns SOUP_SOCKET_WOULD_BLOCK
at any point, stop reading and wait for it to emit the
"readable" signal. Then go back to the
reading-as-much-as-you-can loop. Likewise, for writing to a
SoupSocket, you should call soup_socket_write()
either
until you have written everything, or it returns
SOUP_SOCKET_WOULD_BLOCK
(in which case you wait for
"writable" and then go back into the loop).
Code written this way will work correctly with both
blocking and non-blocking sockets; blocking sockets will
simply never return SOUP_SOCKET_WOULD_BLOCK
, and so the
code that handles that case just won't get used for them.
Default value: TRUE
The "remote-address"
property
"remote-address" SoupAddress* : Read / Write / Construct Only
Address of remote end of socket.
The "ssl-creds"
property
"ssl-creds" gpointer : Read / Write
SSL credential information, passed from the session to the SSL implementation.
The "ssl-strict"
property
"ssl-strict" gboolean : Read / Write / Construct Only
Whether certificate errors should be considered a connection error.
Default value: TRUE
The "timeout"
property
"timeout" guint : Read / Write
Value in seconds to timeout a blocking I/O.
Default value: 0
The "tls-certificate"
property
"tls-certificate" GTlsCertificate* : Read
The peer's TLS certificate.
The "tls-errors"
property
"tls-errors" GTlsCertificateFlags : Read
Errors with the peer's TLS certificate.
Signal Details
The "disconnected"
signal
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. |
The "new-connection"
signal
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. |
The "readable"
signal
void user_function (SoupSocket *sock, gpointer user_data) : Run Last
Emitted when an async socket is readable. See
soup_socket_read()
, soup_socket_read_until()
and
"non-blocking".
|
the socket |
|
user data set when the signal handler was connected. |
The "writable"
signal
void user_function (SoupSocket *sock, gpointer user_data) : Run Last
Emitted when an async socket is writable. See
soup_socket_write()
and "non-blocking".
|
the socket |
|
user data set when the signal handler was connected. |