SoupSocket

## SoupSocket SoupSocket — A network socket |

## Synopsis

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

    void                (*SoupSocketCallback)               (SoupSocket *sock,
                                                             guint status,
                                                             gpointer user_data);
    void                soup_socket_connect_async           (SoupSocket *sock,
                                                             GCancellable *cancellable,
                                                             SoupSocketCallback callback,
                                                             gpointer user_data);
    guint               soup_socket_connect_sync            (SoupSocket *sock,
                                                             GCancellable *cancellable);

    gboolean            soup_socket_listen                  (SoupSocket *sock);

    gboolean            soup_socket_start_ssl               (SoupSocket *sock,
                                                             GCancellable *cancellable);
    gboolean            soup_socket_start_proxy_ssl         (SoupSocket *sock,
                                                             const char *ssl_host,
                                                             GCancellable *cancellable);
    gboolean            soup_socket_is_ssl                  (SoupSocket *sock);

    void                soup_socket_disconnect              (SoupSocket *sock);
    gboolean            soup_socket_is_connected            (SoupSocket *sock);

    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,
                                                             GCancellable *cancellable,
                                                             GError **error);
    SoupSocketIOStatus  soup_socket_read_until              (SoupSocket *sock,
                                                             gpointer buffer,
                                                             gsize len,
                                                             gconstpointer boundary,
                                                             gsize boundary_len,
                                                             gsize *nread,
                                                             gboolean *got_boundary,
                                                             GCancellable *cancellable,
                                                             GError **error);
    SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                             gconstpointer buffer,
                                                             gsize len,
                                                             gsize *nwrote,
                                                             GCancellable *cancellable,
                                                             GError **error);

    #define             SOUP_SSL_ERROR
    enum                SoupSSLError;

    #define             SOUP_SOCKET_LOCAL_ADDRESS
    #define             SOUP_SOCKET_REMOTE_ADDRESS
    #define             SOUP_SOCKET_FLAG_NONBLOCKING
    #define             SOUP_SOCKET_IS_SERVER
    #define             SOUP_SOCKET_SSL_CREDENTIALS
    #define             SOUP_SOCKET_ASYNC_CONTEXT
    #define             SOUP_SOCKET_TIMEOUT

## Object Hierarchy

      GObject
       +----SoupSocket

## Properties

      "async-context"            gpointer              : Read / Write / Construct Only
      "is-server"                gboolean              : Read
      "local-address"            SoupAddress           : Read / Write / Construct Only
      "non-blocking"             gboolean              : Read / Write
      "remote-address"           SoupAddress           : Read / Write / Construct Only
      "ssl-creds"                gpointer              : Read / Write
      "timeout"                  guint                 : Read / Write

## Signals

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

## Description

SoupSocket is libsoup's TCP socket type. While it is primarily intended for internal use, SoupSockets are exposed in the API in various places, and some of their methods (eg, `soup_socket_get_remote_address()`) may be useful to applications.

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

### SoupSocketCallback ()

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

The callback function passed to `soup_socket_connect_async()`.

`sock` : | the SoupSocket
`status` : | an HTTP status code indicating success or failure
`user_data` : | the data passed to `soup_socket_connect_async()`

### soup_socket_connect_async ()

    void                soup_socket_connect_async           (SoupSocket *sock,
                                                             GCancellable *cancellable,
                                                             SoupSocketCallback callback,
                                                             gpointer user_data);

Begins asynchronously connecting to `sock`'s remote address. The socket will call `callback` when it succeeds or fails (but not before returning from this function).

If `cancellable` is non-`NULL`, it can be used to cancel the connection. `callback` will still be invoked in this case, with a status of `SOUP_STATUS_CANCELLED`.

`sock` : | a client SoupSocket (which must not already be connected)
`cancellable` : | a GCancellable, or `NULL`
`callback` : | callback to call after connecting
`user_data` : | data to pass to `callback`

### soup_socket_connect_sync ()

    guint               soup_socket_connect_sync            (SoupSocket *sock,
                                                             GCancellable *cancellable);

Attempt to synchronously connect `sock` to its remote address.

If `cancellable` is non-`NULL`, it can be used to cancel the connection, in which case `soup_socket_connect_sync()` will return `SOUP_STATUS_CANCELLED`.

`sock` : | a client SoupSocket (which must not already be connected)
`cancellable` : | a GCancellable, or `NULL`
Returns : | a success or failure code.

### soup_socket_listen ()

    gboolean            soup_socket_listen                  (SoupSocket *sock);

Makes `sock` start listening on its local address. When connections come in, `sock` will emit `new_connection`.

`sock` : | a server SoupSocket (which must not already be connected or listening)
Returns : | whether or not `sock` is now listening.

### soup_socket_start_ssl ()

    gboolean            soup_socket_start_ssl               (SoupSocket *sock,
                                                             GCancellable *cancellable);

Starts using SSL on `socket`.

`sock` : | the socket
`cancellable` : | a GCancellable
Returns : | success or failure

### soup_socket_start_proxy_ssl ()

    gboolean            soup_socket_start_proxy_ssl         (SoupSocket *sock,
                                                             const char *ssl_host,
                                                             GCancellable *cancellable);

Starts using SSL on `socket`, expecting to find a host named `ssl_host`.

`sock` : | the socket
`ssl_host` : | hostname of the SSL server
`cancellable` : | a GCancellable
Returns : | success or failure

### soup_socket_is_ssl ()

    gboolean            soup_socket_is_ssl                  (SoupSocket *sock);

Tests if `sock` is set up to do SSL. Note that this simply means that the `SOUP_SOCKET_SSL_CREDENTIALS` property has been set; it does not mean that `soup_socket_start_ssl()` has been called.

`sock` : | a SoupSocket
Returns : | `TRUE` if `sock` has SSL credentials set

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

### 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,
                                                             GCancellable *cancellable,
                                                             GError **error);

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`
`cancellable` : | a GCancellable, or `NULL`
`error` : | error pointer
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, in which case `error` will also be set).

### 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,
                                                             GCancellable *cancellable,
                                                             GError **error);

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
`cancellable` : | a GCancellable, or `NULL`
`error` : | error pointer
Returns : | as for `soup_socket_read()`

### soup_socket_write ()

    SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                             gconstpointer buffer,
                                                             gsize len,
                                                             gsize *nwrote,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to write `len` bytes from `buffer` to `sock`. If some data is successfully written, the resturn status will be `SOUP_SOCKET_OK`, 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
`cancellable` : | a GCancellable, or `NULL`
`error` : | error pointer
Returns : | a SoupSocketIOStatus, as described above (or `SOUP_SOCKET_EOF` or `SOUP_SOCKET_ERROR`. `error` will be set if the return value is `SOUP_SOCKET_ERROR`.)

### SOUP_SSL_ERROR

    #define SOUP_SSL_ERROR soup_ssl_error_quark()

### enum SoupSSLError

    typedef enum {
    	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ,
    	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE,
    	SOUP_SSL_ERROR_CERTIFICATE,
    } SoupSSLError;

### SOUP_SOCKET_LOCAL_ADDRESS

    #define SOUP_SOCKET_LOCAL_ADDRESS    "local-address"

### SOUP_SOCKET_REMOTE_ADDRESS

    #define SOUP_SOCKET_REMOTE_ADDRESS   "remote-address"

### SOUP_SOCKET_FLAG_NONBLOCKING

    #define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"

### SOUP_SOCKET_IS_SERVER

    #define SOUP_SOCKET_IS_SERVER        "is-server"

### SOUP_SOCKET_SSL_CREDENTIALS

    #define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"

### SOUP_SOCKET_ASYNC_CONTEXT

    #define SOUP_SOCKET_ASYNC_CONTEXT    "async-context"

### SOUP_SOCKET_TIMEOUT

    #define SOUP_SOCKET_TIMEOUT	     "timeout"

## 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 `"is-server"` property

      "is-server"                gboolean              : Read

Whether or not the socket is a server socket.

Default value: FALSE

### The `"local-address"` property

      "local-address"            SoupAddress           : Read / Write / Construct Only

Address of local end of socket.

### The `"non-blocking"` property

      "non-blocking"             gboolean              : Read / Write

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

Default value: TRUE

### The `"remote-address"` property

      "remote-address"           SoupAddress           : Read / Write / Construct Only

Address of remote end of socket.

### 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 `"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()`) receives a new connection.

You must ref the `new` if you want to keep it; otherwise it will be destroyed after the signal is emitted.

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