SoupSocket 3 LIBSOUP Library
SoupSocket

## Synopsis

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

## Description

## Details

### SOUP_SOCKET_FLAG_NONBLOCKING

    #define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"

SOUP_SOCKET_FLAG_NONBLOCKING

### SOUP_SOCKET_FLAG_NODELAY

    #define SOUP_SOCKET_FLAG_NODELAY     "nodelay"

SOUP_SOCKET_FLAG_NODELAY

### SOUP_SOCKET_FLAG_REUSEADDR

    #define SOUP_SOCKET_FLAG_REUSEADDR   "reuseaddr"

SOUP_SOCKET_FLAG_REUSEADDR

### SOUP_SOCKET_IS_SERVER

    #define SOUP_SOCKET_IS_SERVER        "is-server"

SOUP_SOCKET_IS_SERVER

### SOUP_SOCKET_SSL_CREDENTIALS

    #define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"

SOUP_SOCKET_SSL_CREDENTIALS

### 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_new

### 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_connect

### 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_listen

### 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_ssl

### 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_disconnect

### 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`.

soup_socket_is_connected

### 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 :

SoupSocketCallback

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

SoupSocketListenerCallback

### 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_async

### 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_client_new_sync

### 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_server_new

### 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_local_address

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

soup_socket_get_remote_address

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

SoupSocketIOStatus

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

### 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_read_until

### 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_write