SoupSocket

## SoupSocket SoupSocket — A network socket |

## Synopsis

    #include <libsoup/soup.h>

                        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
      "ssl-strict"               gboolean              : Read / Write / Construct Only
      "timeout"                  guint                 : Read / Write
      "trusted-certificate"      gboolean              : Read / Write / Construct Only

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

### SoupSocket

    typedef struct _SoupSocket 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 (which may be less than `len`).

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. "readable" is only emitted after `soup_socket_read()` returns `SOUP_SOCKET_WOULD_BLOCK`, and it is only emitted once. See the documentation for "non-blocking".)

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

`soup_socket_read_until()` will almost always return fewer than `len` bytes: if the boundary is found, then it will only return the bytes up until the end of the boundary, and if the boundary is not found, then it will leave the last `(boundary_len - 1)` bytes in its internal buffer, in case they form the start of the boundary string. Thus, `len` normally needs to be at least 1 byte longer than `boundary_len` if you want to make any progress at all.

`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 return status will be `SOUP_SOCKET_OK`, and *`nwrote` will contain the number of bytes actually written (which may be less than `len`).

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 `soup_socket_write()` returns `SOUP_SOCKET_WOULD_BLOCK`, and it is only emitted once. See the documentation for "non-blocking".)

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

A GError domain representing an SSL error. Used with SoupSSLError.

### enum SoupSSLError

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

SSL-related I/O errors.

`SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ` | Internal error. Never exposed outside of libsoup.
`SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE` | Internal error. Never exposed outside of libsoup.
`SOUP_SSL_ERROR_CERTIFICATE` | Indicates an error validating an SSL certificate
`SOUP_SSL_ERROR_HANDSHAKE_FAILED` |

### SOUP_SOCKET_LOCAL_ADDRESS

    #define SOUP_SOCKET_LOCAL_ADDRESS       "local-address"

Alias for the "local-address" property. (Address of local end of socket.)

### SOUP_SOCKET_REMOTE_ADDRESS

    #define SOUP_SOCKET_REMOTE_ADDRESS      "remote-address"

Alias for the "remote-address" property. (Address of remote end of socket.)

### SOUP_SOCKET_FLAG_NONBLOCKING

    #define SOUP_SOCKET_FLAG_NONBLOCKING    "non-blocking"

Alias for the "non-blocking" property. (Whether or not the socket uses non-blocking I/O.)

### SOUP_SOCKET_IS_SERVER

    #define SOUP_SOCKET_IS_SERVER           "is-server"

Alias for the "is-server" property. (Whether or not the socket is a server socket.)

### SOUP_SOCKET_SSL_CREDENTIALS

    #define SOUP_SOCKET_SSL_CREDENTIALS     "ssl-creds"

Alias for the "ssl-credentials" property. (SSL credential information.)

### SOUP_SOCKET_ASYNC_CONTEXT

    #define SOUP_SOCKET_ASYNC_CONTEXT       "async-context"

Alias for the "async-context" property. (The socket's GMainContext.)

### SOUP_SOCKET_TIMEOUT

    #define SOUP_SOCKET_TIMEOUT             "timeout"

Alias for the "timeout" property. (The timeout in seconds for blocking socket I/O operations.)

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

SoupSocket's I/O methods are designed around the idea of using a single codepath for both synchronous and asynchronous I/O. If you want to read off a SoupSocket, the "correct" way to do it is to call `soup_socket_read()` or `soup_socket_read_until()` repeatedly until you have read everything you want. If it returns `SOUP_SOCKET_WOULD_BLOCK` at any point, stop reading and wait for it to emit the "readable" signal. Then go back to the reading-as-much-as-you-can loop. Likewise, for writing to a SoupSocket, you should call `soup_socket_write()` either until you have written everything, or it returns `SOUP_SOCKET_WOULD_BLOCK` (in which case you wait for "writable" and then go back into the loop).

Code written this way will work correctly with both blocking and non-blocking sockets; blocking sockets will simply never return `SOUP_SOCKET_WOULD_BLOCK`, and so the code that handles that case just won't get used for them.

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 `"ssl-strict"` property

      "ssl-strict"               gboolean              : Read / Write / Construct Only

Whether certificate errors should be considered a connection error.

Default value: TRUE

### The `"timeout"` property

      "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

### The `"trusted-certificate"` property

      "trusted-certificate"      gboolean              : Read / Write / Construct Only

Whether the server certificate is trusted, if this is an SSL socket.

Default value: FALSE

## 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()`, `soup_socket_read_until()` and "non-blocking".

`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()` and "non-blocking".

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