| libsoup Reference Manual | ||||
|---|---|---|---|---|
struct SoupSocket; SoupSocket* soup_socket_new (const char *optname1, ...); guint soup_socket_connect (SoupSocket *sock, SoupAddress *remote_addr); gboolean soup_socket_listen (SoupSocket *sock, SoupAddress *local_addr); gboolean soup_socket_start_ssl (SoupSocket *sock); gboolean soup_socket_start_proxy_ssl (SoupSocket *sock, const char *ssl_host); void soup_socket_disconnect (SoupSocket *sock); gboolean soup_socket_is_connected (SoupSocket *sock); void (*SoupSocketCallback) (SoupSocket *sock, guint status, gpointer user_data); void (*SoupSocketListenerCallback) (SoupSocket *listener, SoupSocket *sock, gpointer user_data); SoupSocket* soup_socket_client_new_async (const char *hostname, guint port, gpointer ssl_creds, SoupSocketCallback callback, gpointer user_data); SoupSocket* soup_socket_client_new_sync (const char *hostname, guint port, gpointer ssl_creds, guint *status_ret); SoupSocket* soup_socket_server_new (SoupAddress *local_addr, gpointer ssl_creds, SoupSocketListenerCallback callback, gpointer user_data); 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); SoupSocketIOStatus soup_socket_read_until (SoupSocket *sock, gpointer buffer, gsize len, gconstpointer boundary, gsize boundary_len, gsize *nread, gboolean *got_boundary); SoupSocketIOStatus soup_socket_write (SoupSocket *sock, gconstpointer buffer, gsize len, gsize *nwrote); #define SOUP_SOCKET_FLAG_NONBLOCKING #define SOUP_SOCKET_FLAG_NODELAY #define SOUP_SOCKET_FLAG_REUSEADDR #define SOUP_SOCKET_FLAG_CLOEXEC #define SOUP_SOCKET_TIMEOUT #define SOUP_SOCKET_IS_SERVER #define SOUP_SOCKET_SSL_CREDENTIALS #define SOUP_SOCKET_ASYNC_CONTEXT
"async-context" gpointer : Read / Write / Construct Only "cloexec" gboolean : Read / Write "is-server" gboolean : Read "nodelay" gboolean : Read / Write "non-blocking" gboolean : Read / Write "reuseaddr" gboolean : Read / Write "ssl-creds" gpointer : Read / Write "timeout" guint : Read / Write
"connect-result" : Run First "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 |
guint soup_socket_connect (SoupSocket *sock, SoupAddress *remote_addr);
If SOUP_SOCKET_FLAG_NONBLOCKING has been set on the socket, this
begins asynchronously connecting to the given address. The socket
will emit connect_result when it succeeds or fails (but not before
returning from this function).
If SOUP_SOCKET_FLAG_NONBLOCKING has not been set, this will
attempt to synchronously connect.
|
a client SoupSocket (which must not already be connected) |
|
address to connect to |
Returns : |
SOUP_STATUS_CONTINUE if connecting asynchronously,
otherwise a success or failure code.
|
gboolean soup_socket_listen (SoupSocket *sock, SoupAddress *local_addr);
Makes sock start listening on the given interface and port. When
connections come in, sock will emit new_connection.
|
a server SoupSocket (which must not already be connected or listening) |
|
Local address to bind to. |
Returns : |
whether or not sock is now listening.
|
gboolean soup_socket_start_ssl (SoupSocket *sock);
Starts using SSL on socket.
|
the socket |
Returns : |
success or failure |
gboolean soup_socket_start_proxy_ssl (SoupSocket *sock, const char *ssl_host);
Starts using SSL on socket, expecting to find a host named
ssl_host.
|
the socket |
|
hostname of the SSL server |
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.
|
void (*SoupSocketCallback) (SoupSocket *sock, guint status, gpointer user_data);
The callback function passed to soup_socket_client_new_async().
|
the SoupSocket |
|
an HTTP status code indicating success or failure |
|
the data passed to soup_socket_client_new_async()
|
void (*SoupSocketListenerCallback) (SoupSocket *listener, SoupSocket *sock, gpointer user_data);
The callback function passed to soup_socket_server_new(), which
receives new connections.
|
the listening SoupSocket |
|
the newly-received SoupSocket |
|
the data passed to soup_socket_server_new().
|
SoupSocket* soup_socket_client_new_async (const char *hostname, guint port, gpointer ssl_creds, SoupSocketCallback callback, gpointer user_data);
Creates a connection to hostname and port. callback will be
called when the connection completes (or fails).
Uses the default GMainContext. If you need to use an alternate
context, use soup_socket_new() and soup_socket_connect() directly.
|
remote machine to connect to |
|
remote port to connect to |
|
SSL credentials structure, or NULL if not SSL
|
|
callback to call when the socket is connected |
|
data for callback
|
Returns : |
the new socket (not yet ready for use). |
SoupSocket* soup_socket_client_new_sync (const char *hostname, guint port, gpointer ssl_creds, guint *status_ret);
Creates a connection to hostname and port. If status_ret is not
NULL, it will contain a status code on return.
SoupSocket* soup_socket_server_new (SoupAddress *local_addr, gpointer ssl_creds, SoupSocketListenerCallback callback, gpointer user_data);
Create and open a new SoupSocket listening on the specified
address. callback will be called each time a client connects,
with a new SoupSocket.
Uses the default GMainContext. If you need to use an alternate
context, use soup_socket_new() and soup_socket_listen() directly.
|
Local address to bind to. (Use soup_address_any_new() to
accept connections on any local address)
|
|
SSL credentials, or NULL if this is not an SSL server
|
|
Callback to call when a client connects |
|
data to pass to callback.
|
Returns : |
a new SoupSocket, or NULL if there was a failure. |
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);
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
|
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).
|
SoupSocketIOStatus soup_socket_read_until (SoupSocket *sock, gpointer buffer, gsize len, gconstpointer boundary, gsize boundary_len, gsize *nread, gboolean *got_boundary);
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
|
Returns : |
as for soup_socket_read()
|
SoupSocketIOStatus soup_socket_write (SoupSocket *sock, gconstpointer buffer, gsize len, gsize *nwrote);
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 |
Returns : |
a SoupSocketIOStatus, as described above (or
SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR).
|
#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"
An alias for the "non-blocking" property.
#define SOUP_SOCKET_FLAG_NODELAY "nodelay"
An alias for the "nodelay" property.
#define SOUP_SOCKET_FLAG_REUSEADDR "reuseaddr"
An alias for the "reuseaddr" property.
#define SOUP_SOCKET_FLAG_CLOEXEC "cloexec"
An alias for the "cloexec" property.
#define SOUP_SOCKET_IS_SERVER "is-server"
An alias for the "is-server" property.
#define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds"
An alias for the "ssl-creds" property.
async-context" property"async-context" gpointer : Read / Write / Construct Only
The GMainContext to dispatch this socket's async I/O in.
cloexec" property"cloexec" gboolean : Read / Write
Whether or not the socket will be closed automatically on exec().
Default value: FALSE
is-server" property"is-server" gboolean : Read
Whether or not the socket is a server socket.
Default value: FALSE
nodelay" property"nodelay" gboolean : Read / Write
Whether or not the socket uses TCP NODELAY.
Default value: TRUE
non-blocking" property"non-blocking" gboolean : Read / Write
Whether or not the socket uses non-blocking I/O.
Default value: TRUE
reuseaddr" property"reuseaddr" gboolean : Read / Write
Whether or not the socket uses the TCP REUSEADDR flag.
Default value: TRUE
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, gint status, gpointer user_data) : Run First
Emitted when a connection attempt succeeds or fails. This
is used internally by soup_socket_client_new_async().
|
the socket |
|
the status |
|
user data set when the signal handler was connected. |
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() or soup_socket_server_new()) receives a
new connection.
|
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. |