![]() | ![]() | ![]() | libsoup Reference Manual | ![]() |
---|
SoupSocketSoupSocket — |
#define SOUP_SOCKET_FLAG_NONBLOCKING #define SOUP_SOCKET_FLAG_NODELAY #define SOUP_SOCKET_FLAG_REUSEADDR #define SOUP_SOCKET_IS_SERVER #define SOUP_SOCKET_SSL_CREDENTIALS 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); 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);
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 |
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.
sock : | a client SoupSocket (which must not already be connected) |
remote_addr : | 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.
sock : | a server SoupSocket (which must not already be connected or listening) |
local_addr : | 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.
sock : | the socket |
Returns : | success or failure |
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. |
void (*SoupSocketCallback) (SoupSocket *sock, guint status, gpointer user_data);
The callback function passed to soup_socket_client_new_async().
sock : | the SoupSocket |
status : | an HTTP status code indicating success or failure |
user_data : |
void (*SoupSocketListenerCallback) (SoupSocket *listener, SoupSocket *sock, gpointer user_data);
The callback function passed to soup_socket_server_new(), which receives new connections.
listener : | the listening SoupSocket |
sock : | the newly-received SoupSocket |
user_data : | 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).
hostname : | remote machine to connect to |
port : | remote port to connect to |
ssl_creds : | SSL credentials structure, or NULL if not SSL |
callback : | callback to call when the socket is connected |
user_data : | 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.
hostname : | remote machine to connect to |
port : | remote port to connect to |
ssl_creds : | SSL credentials structure, or NULL if not SSL |
status_ret : | pointer to return the soup status in |
Returns : | the new socket, or NULL if it could not connect. |
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.
local_addr : | Local address to bind to. (Use soup_address_any_new() to accept connections on any local address) |
ssl_creds : | SSL credentials, or NULL if this is not an SSL server |
callback : | Callback to call when a client connects |
user_data : | 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.
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.
SOUP_SOCKET_OK | Success |
SOUP_SOCKET_WOULD_BLOCK | Cannot read/write any more at this time |
SOUP_SOCKET_EOF | End of file |
SOUP_SOCKET_ERROR | Other error |
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.)
sock : | the socket |
buffer : | buffer to read into |
len : | size of buffer in bytes |
nread : | 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.
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 |
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.)
sock : | the socket |
buffer : | data to write |
len : | size of buffer, in bytes |
nwrote : | on return, number of bytes written |
Returns : | a SoupSocketIOStatus, as described above (or SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR). |
<< SoupSoapMessage | soup-ssl >> |