## 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_FLAG_CLOEXEC
    #define             SOUP_SOCKET_TIMEOUT
    #define             SOUP_SOCKET_IS_SERVER
    #define             SOUP_SOCKET_SSL_CREDENTIALS
    #define             SOUP_SOCKET_ASYNC_CONTEXT

## Object Hierarchy

      GObject
       +----SoupSocket

## Properties

      "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

## Signals

      "connect-result"                                 : Run First
      "disconnected"                                   : Run Last
      "new-connection"                                 : Run First
      "readable"                                       : Run Last
      "writable"                                       : Run Last

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

Uses the default GMainContext. If you need to use an alternate context, use `soup_socket_new()` and `soup_socket_connect()` directly.

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

Uses the default GMainContext. If you need to use an alternate context, use `soup_socket_new()` and `soup_socket_listen()` directly.

`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_FLAG_CLOEXEC

    #define SOUP_SOCKET_FLAG_CLOEXEC     "cloexec"

An alias for the "cloexec" property.

### SOUP_SOCKET_TIMEOUT

    #define SOUP_SOCKET_TIMEOUT	     "timeout"

An alias for the "timeout" 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.

### SOUP_SOCKET_ASYNC_CONTEXT

    #define SOUP_SOCKET_ASYNC_CONTEXT    "async-context"

An alias for the "async-context" property.

## Property Details

### The "`async-context`" property

      "async-context"            gpointer              : Read / Write / Construct Only

The GMainContext to dispatch this socket's async I/O in.

### The "`cloexec`" property

      "cloexec"                  gboolean              : Read / Write

Whether or not the socket will be closed automatically on exec().

Default value: FALSE

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

### The "`timeout`" property

      "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

## Signal Details

### The "connect-result" signal

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

`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)      : Run Last

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)      : Run First

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)      : Run Last

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)      : Run Last

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.