SoupSocket

SoupSocket — a network socket

Synopsis




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_IS_SERVER
#define     SOUP_SOCKET_SSL_CREDENTIALS

Object Hierarchy


  GObject
   +----SoupSocket

Properties


  "is-server"            gboolean              : Read
  "nodelay"              gboolean              : Read / Write
  "non-blocking"         gboolean              : Read / Write
  "reuseaddr"            gboolean              : Read / Write
  "ssl-creds"            gpointer              : Read / Write

Signal Prototypes


"connect-result"
            void        user_function      (SoupSocket *sock,
                                            gint status,
                                            gpointer user_data);
"disconnected"
            void        user_function      (SoupSocket *sock,
                                            gpointer user_data);
"new-connection"
            void        user_function      (SoupSocket *sock,
                                            SoupSocket *new,
                                            gpointer user_data);
"readable"  void        user_function      (SoupSocket *sock,
                                            gpointer user_data);
"writable"  void        user_function      (SoupSocket *sock,
                                            gpointer user_data);

Description

Details

struct SoupSocket

struct SoupSocket;


soup_socket_new ()

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

soup_socket_connect ()

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.

soup_socket_listen ()

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.

soup_socket_start_ssl ()

gboolean    soup_socket_start_ssl           (SoupSocket *sock);

Starts using SSL on socket.

sock : the socket
Returns : success or failure

soup_socket_start_proxy_ssl ()

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.

sock : the socket
ssl_host : hostname of the SSL server
Returns : success or failure

soup_socket_disconnect ()

void        soup_socket_disconnect          (SoupSocket *sock);

Disconnects sock. Any further read or write attempts on it will fail.

sock : a SoupSocket

soup_socket_is_connected ()

gboolean    soup_socket_is_connected        (SoupSocket *sock);

Tests if sock is connected to another host

sock : a SoupSocket
Returns : TRUE or FALSE.

SoupSocketCallback ()

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 : the data passed to soup_socket_client_new_async()

SoupSocketListenerCallback ()

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().

soup_socket_client_new_async ()

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).

soup_socket_client_new_sync ()

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.

soup_socket_server_new ()

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.

soup_socket_get_local_address ()

SoupAddress* soup_socket_get_local_address  (SoupSocket *sock);

Returns the SoupAddress corresponding to the local end of sock.

sock : a SoupSocket
Returns : the SoupAddress

soup_socket_get_remote_address ()

SoupAddress* soup_socket_get_remote_address (SoupSocket *sock);

Returns the SoupAddress corresponding to the remote end of sock.

sock : a SoupSocket
Returns : the SoupAddress

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_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

soup_socket_read ()

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).

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);

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()

soup_socket_write ()

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).

SOUP_SOCKET_FLAG_NONBLOCKING

#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"

An alias for the "non-blocking" property.


SOUP_SOCKET_FLAG_NODELAY

#define SOUP_SOCKET_FLAG_NODELAY     "nodelay"

An alias for the "nodelay" property.


SOUP_SOCKET_FLAG_REUSEADDR

#define SOUP_SOCKET_FLAG_REUSEADDR   "reuseaddr"

An alias for the "reuseaddr" property.


SOUP_SOCKET_IS_SERVER

#define SOUP_SOCKET_IS_SERVER        "is-server"

An alias for the "is-server" property.


SOUP_SOCKET_SSL_CREDENTIALS

#define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"

An alias for the "ssl-creds" property.

Properties

The "is-server" property

  "is-server"            gboolean              : Read

Whether or not the socket is a server socket.

Default value: FALSE


The "nodelay" property

  "nodelay"              gboolean              : Read / Write

Whether or not the socket uses TCP NODELAY.

Default value: TRUE


The "non-blocking" property

  "non-blocking"         gboolean              : Read / Write

Whether or not the socket uses non-blocking I/O.

Default value: TRUE


The "reuseaddr" property

  "reuseaddr"            gboolean              : Read / Write

Whether or not the socket uses the TCP REUSEADDR flag.

Default value: TRUE


The "ssl-creds" property

  "ssl-creds"            gpointer              : Read / Write

SSL credential information, passed from the session to the SSL implementation.

Signals

The "connect-result" signal

void        user_function                  (SoupSocket *sock,
                                            gint status,
                                            gpointer user_data);

Emitted when a connection attempt succeeds or fails. This is used internally by soup_socket_client_new_async().

sock : the socket
status : the status
user_data :user data set when the signal handler was connected.

The "disconnected" signal

void        user_function                  (SoupSocket *sock,
                                            gpointer user_data);

Emitted when the socket is disconnected, for whatever reason.

sock : the socket
user_data :user data set when the signal handler was connected.

The "new-connection" signal

void        user_function                  (SoupSocket *sock,
                                            SoupSocket *new,
                                            gpointer user_data);

Emitted when a listening socket (set up with soup_socket_listen() or soup_socket_server_new()) receives a new connection.

sock : the socket
new : the new socket
user_data :user data set when the signal handler was connected.

The "readable" signal

void        user_function                  (SoupSocket *sock,
                                            gpointer user_data);

Emitted when an async socket is readable. See soup_socket_read() and soup_socket_read_until().

sock : the socket
user_data :user data set when the signal handler was connected.

The "writable" signal

void        user_function                  (SoupSocket *sock,
                                            gpointer user_data);

Emitted when an async socket is writable. See soup_socket_write().

sock : the socket
user_data :user data set when the signal handler was connected.