## SoupSocket

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_NODELAY

    #define SOUP_SOCKET_FLAG_NODELAY     "nodelay"

### SOUP_SOCKET_FLAG_REUSEADDR

    #define SOUP_SOCKET_FLAG_REUSEADDR   "reuseaddr"

### SOUP_SOCKET_IS_SERVER

    #define SOUP_SOCKET_IS_SERVER        "is-server"

### SOUP_SOCKET_SSL_CREDENTIALS

    #define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"

### soup_socket_new ()

    SoupSocket* soup_socket_new                 (const char *optname1,
                                                 ...);

`optname1` : | name of first property to set (or `NULL`)
`...` : | value of `optname1`, followed by additional property/value pairs
Returns : | a new (disconnected) 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_disconnect ()

    void        soup_socket_disconnect          (SoupSocket *sock);

`sock` : |

### soup_socket_is_connected ()

    gboolean    soup_socket_is_connected        (SoupSocket *sock);

`sock` : |
Returns : |

### SoupSocketCallback ()

    void        (*SoupSocketCallback)           (SoupSocket *sock,
                                                 guint status,
                                                 gpointer user_data);

`sock` : |
`status` : |
`user_data` : |

### SoupSocketListenerCallback ()

    void        (*SoupSocketListenerCallback)   (SoupSocket *listener,
                                                 SoupSocket *sock,
                                                 gpointer user_data);

`listener` : |
`sock` : |
`user_data` : |

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

`sock` : |
Returns : |

### soup_socket_get_remote_address ()

    SoupAddress* soup_socket_get_remote_address (SoupSocket *sock);

`sock` : |
Returns : |

### enum SoupSocketIOStatus

    typedef enum {
    	SOUP_SOCKET_OK,
    	SOUP_SOCKET_WOULD_BLOCK,
    	SOUP_SOCKET_EOF,
    	SOUP_SOCKET_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_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`).