## SoupWebsocket

SoupWebsocket — The WebSocket Protocol

## Functions

void | soup_websocket_client_prepare_handshake ()
gboolean | soup_websocket_client_verify_handshake ()
gboolean | soup_websocket_server_check_handshake ()
gboolean | soup_websocket_server_process_handshake ()
SoupWebsocketConnection * | soup_websocket_connection_new ()
GIOStream * | soup_websocket_connection_get_io_stream ()
SoupWebsocketConnectionType | soup_websocket_connection_get_connection_type ()
GUri * | soup_websocket_connection_get_uri ()
const char * | soup_websocket_connection_get_origin ()
const char * | soup_websocket_connection_get_protocol ()
GList * | soup_websocket_connection_get_extensions ()
guint64 | soup_websocket_connection_get_max_incoming_payload_size ()
void | soup_websocket_connection_set_max_incoming_payload_size ()
guint | soup_websocket_connection_get_keepalive_interval ()
void | soup_websocket_connection_set_keepalive_interval ()
SoupWebsocketState | soup_websocket_connection_get_state ()
void | soup_websocket_connection_send_text ()
void | soup_websocket_connection_send_binary ()
void | soup_websocket_connection_send_message ()
void | soup_websocket_connection_close ()
gushort | soup_websocket_connection_get_close_code ()
const char * | soup_websocket_connection_get_close_data ()

## Properties

SoupWebsocketConnectionType | connection-type | Read / Write / Construct Only
gpointer | extensions | Read / Write / Construct Only
GIOStream * | io-stream | Read / Write / Construct Only
guint | keepalive-interval | Read / Write / Construct
guint64 | max-incoming-payload-size | Read / Write / Construct
char * | origin | Read / Write / Construct Only
char * | protocol | Read / Write / Construct Only
SoupWebsocketState | state | Read
GUri * | uri | Read / Write / Construct Only

## Signals

void | closed | Run First
void | closing | Run Last
void | error | Run First
void | message | Run First
void | pong | Run First

## Types and Values

| SoupWebsocketConnection
enum | SoupWebsocketConnectionType
enum | SoupWebsocketState
enum | SoupWebsocketDataType
enum | SoupWebsocketCloseCode
enum | SoupWebsocketError
#define | SOUP_WEBSOCKET_ERROR

## Object Hierarchy

        GObject
        ╰── SoupWebsocketConnection

## Includes

    #include <libsoup/soup.h>

## Description

SoupWebsocketConnection provides support for the WebSocket protocol.

To connect to a WebSocket server, create a SoupSession and call `soup_session_websocket_connect_async()`. To accept WebSocket connections, create a SoupServer and add a handler to it with `soup_server_add_websocket_handler()`.

(Lower-level support is available via `soup_websocket_client_prepare_handshake()` and `soup_websocket_client_verify_handshake()`, for handling the client side of the WebSocket handshake, and `soup_websocket_server_process_handshake()` for handling the server side.)

SoupWebsocketConnection handles the details of WebSocket communication. You can use `soup_websocket_connection_send_text()` and `soup_websocket_connection_send_binary()` to send data, and the “message” signal to receive data. (SoupWebsocketConnection currently only supports asynchronous I/O.)

## Functions

### soup_websocket_client_prepare_handshake ()

    void
    soup_websocket_client_prepare_handshake
                                   (SoupMessage *msg,
                                    const char *origin,
                                    char **protocols,
                                    GPtrArray *supported_extensions);

Adds the necessary headers to `msg` to request a WebSocket handshake including supported WebSocket extensions. The message body and non-WebSocket-related headers are not modified.

This is a low-level function; if you use `soup_session_websocket_connect_async()` to create a WebSocket connection, it will call this for you.

#### Parameters

msg | a SoupMessage |
origin | the "Origin" header to set. | [nullable]
protocols | list of protocols to offer. | [nullable][array zero-terminated=1]
supported_extensions | list of supported extension types. | [nullable][element-type GObject.TypeClass]

### soup_websocket_client_verify_handshake ()

    gboolean
    soup_websocket_client_verify_handshake
                                   (SoupMessage *msg,
                                    GPtrArray *supported_extensions,
                                    GList **accepted_extensions,
                                    GError **error);

Looks at the response status code and headers in `msg` and determines if they contain a valid WebSocket handshake response (given the handshake request in `msg` 's request headers).

If `supported_extensions` is non-`NULL`, extensions included in the response "Sec-WebSocket-Extensions" are verified too. Accepted extensions are returned in `accepted_extensions` parameter if non-`NULL`.

This is a low-level function; if you use `soup_session_websocket_connect_async()` to create a WebSocket connection, it will call this for you.

#### Parameters

msg | SoupMessage containing both client and server sides of a WebSocket handshake |
supported_extensions | list of supported extension types. | [nullable][element-type GObject.TypeClass]
accepted_extensions | a GList of SoupWebsocketExtension objects. | [out][optional][element-type SoupWebsocketExtension]
error | return location for a GError |

#### Returns

`TRUE` if `msg` contains a completed valid WebSocket handshake, `FALSE` and an error if not.

### soup_websocket_server_check_handshake ()

    gboolean
    soup_websocket_server_check_handshake (SoupServerMessage *msg,
                                           const char *origin,
                                           char **protocols,
                                           GPtrArray *supported_extensions,
                                           GError **error);

Examines the method and request headers in `msg` and determines whether `msg` contains a valid handshake request.

If `origin` is non-`NULL`, then only requests containing a matching "Origin" header will be accepted. If `protocols` is non-`NULL`, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If `supported_extensions` is non-`NULL`, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted.

Normally `soup_websocket_server_process_handshake()` will take care of this for you, and if you use `soup_server_add_websocket_handler()` to handle accepting WebSocket connections, it will call that for you. However, this function may be useful if you need to perform more complicated validation; eg, accepting multiple different Origins, or handling different protocols depending on the path.

#### Parameters

msg | SoupServerMessage containing the client side of a WebSocket handshake |
origin | expected Origin header. | [nullable]
protocols | allowed WebSocket protocols. | [nullable][array zero-terminated=1]
supported_extensions | list of supported extension types. | [nullable][element-type GObject.TypeClass]
error | return location for a GError |

#### Returns

`TRUE` if `msg` contained a valid WebSocket handshake, `FALSE` and an error if not.

### soup_websocket_server_process_handshake ()

    gboolean
    soup_websocket_server_process_handshake
                                   (SoupServerMessage *msg,
                                    const char *expected_origin,
                                    char **protocols,
                                    GPtrArray *supported_extensions,
                                    GList **accepted_extensions);

Examines the method and request headers in `msg` and (assuming `msg` contains a valid handshake request), fills in the handshake response.

If `expected_origin` is non-`NULL`, then only requests containing a matching "Origin" header will be accepted. If `protocols` is non-`NULL`, then only requests containing a compatible "Sec-WebSocket-Protocols" header will be accepted. If `supported_extensions` is non-`NULL`, then only requests containing valid supported extensions in "Sec-WebSocket-Extensions" header will be accepted. The accepted extensions will be returned in `accepted_extensions` parameter if non-`NULL`.

This is a low-level function; if you use `soup_server_add_websocket_handler()` to handle accepting WebSocket connections, it will call this for you.

#### Parameters

msg | SoupServerMessage containing the client side of a WebSocket handshake |
expected_origin | expected Origin header. | [nullable]
protocols | allowed WebSocket protocols. | [nullable][array zero-terminated=1]
supported_extensions | list of supported extension types. | [nullable][element-type GObject.TypeClass]
accepted_extensions | a GList of SoupWebsocketExtension objects. | [out][optional][element-type SoupWebsocketExtension]

#### Returns

`TRUE` if `msg` contained a valid WebSocket handshake request and was updated to contain a handshake response. `FALSE` if not.

### soup_websocket_connection_new ()

    SoupWebsocketConnection *
    soup_websocket_connection_new (GIOStream *stream,
                                   GUri *uri,
                                   SoupWebsocketConnectionType type,
                                   const char *origin,
                                   const char *protocol,
                                   GList *extensions);

Creates a SoupWebsocketConnection on `stream` with the given active `extensions` . This should be called after completing the handshake to begin using the WebSocket protocol.

#### Parameters

stream | a GIOStream connected to the WebSocket server |
uri | the URI of the connection |
type | the type of connection (client/side) |
origin | the Origin of the client. | [nullable]
protocol | the subprotocol in use. | [nullable]
extensions | a GList of SoupWebsocketExtension objects. | [element-type SoupWebsocketExtension][transfer full]

#### Returns

a new SoupWebsocketConnection

### soup_websocket_connection_get_io_stream ()

    GIOStream *
    soup_websocket_connection_get_io_stream
                                   (SoupWebsocketConnection *self);

Get the I/O stream the WebSocket is communicating over.

#### Parameters

self | the WebSocket |

#### Returns

the WebSocket's I/O stream.

[transfer none]

### soup_websocket_connection_get_connection_type ()

    SoupWebsocketConnectionType
    soup_websocket_connection_get_connection_type
                                   (SoupWebsocketConnection *self);

Get the connection type (client/server) of the connection.

#### Parameters

self | the WebSocket |

#### Returns

the connection type

### soup_websocket_connection_get_uri ()

    GUri *
    soup_websocket_connection_get_uri (SoupWebsocketConnection *self);

Get the URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

#### Parameters

self | the WebSocket |

#### Returns

the URI.

[transfer none]

### soup_websocket_connection_get_origin ()

    const char *
    soup_websocket_connection_get_origin (SoupWebsocketConnection *self);

Get the origin of the WebSocket.

#### Parameters

self | the WebSocket |

#### Returns

the origin, or `NULL`.

[nullable]

### soup_websocket_connection_get_protocol ()

    const char *
    soup_websocket_connection_get_protocol
                                   (SoupWebsocketConnection *self);

Get the protocol chosen via negotiation with the peer.

#### Parameters

self | the WebSocket |

#### Returns

the chosen protocol, or `NULL`.

[nullable]

### soup_websocket_connection_get_extensions ()

    GList *
    soup_websocket_connection_get_extensions
                                   (SoupWebsocketConnection *self);

Get the extensions chosen via negotiation with the peer.

#### Parameters

self | the WebSocket |

#### Returns

a GList of SoupWebsocketExtension objects.

[element-type SoupWebsocketExtension][transfer none]

### soup_websocket_connection_get_max_incoming_payload_size ()

    guint64
    soup_websocket_connection_get_max_incoming_payload_size
                                   (SoupWebsocketConnection *self);

Gets the maximum payload size allowed for incoming packets.

#### Parameters

self | the WebSocket |

#### Returns

the maximum payload size.

### soup_websocket_connection_set_max_incoming_payload_size ()

    void
    soup_websocket_connection_set_max_incoming_payload_size
                                   (SoupWebsocketConnection *self,
                                    guint64 max_incoming_payload_size);

Sets the maximum payload size allowed for incoming packets. It does not limit the outgoing packet size.

#### Parameters

self | the WebSocket |
max_incoming_payload_size | the maximum payload size |

### soup_websocket_connection_get_keepalive_interval ()

    guint
    soup_websocket_connection_get_keepalive_interval
                                   (SoupWebsocketConnection *self);

Gets the keepalive interval in seconds or 0 if disabled.

#### Parameters

self | the WebSocket |

#### Returns

the keepalive interval.

### soup_websocket_connection_set_keepalive_interval ()

    void
    soup_websocket_connection_set_keepalive_interval
                                   (SoupWebsocketConnection *self,
                                    guint interval);

Sets the interval in seconds on when to send a ping message which will serve as a keepalive message. If set to 0 the keepalive message is disabled.

#### Parameters

self | the WebSocket |
interval | the interval to send a ping message or 0 to disable it |

### soup_websocket_connection_get_state ()

    SoupWebsocketState
    soup_websocket_connection_get_state (SoupWebsocketConnection *self);

Get the current state of the WebSocket.

#### Parameters

self | the WebSocket |

#### Returns

the state

### soup_websocket_connection_send_text ()

    void
    soup_websocket_connection_send_text (SoupWebsocketConnection *self,
                                         const char *text);

Send a `NULL`-terminated text (UTF-8) message to the peer. If you need to send text messages containing `NULL` characters use `soup_websocket_connection_send_message()` instead.

The message is queued to be sent and will be sent when the main loop is run.

#### Parameters

self | the WebSocket |
text | the message contents |

### soup_websocket_connection_send_binary ()

    void
    soup_websocket_connection_send_binary (SoupWebsocketConnection *self,
                                           gconstpointer data,
                                           gsize length);

Send a binary message to the peer. If `length` is 0, `data` may be `NULL`.

The message is queued to be sent and will be sent when the main loop is run.

#### Parameters

self | the WebSocket |
data | the message contents. | [array length=length][element-type guint8][nullable]
length | the length of `data` |

### soup_websocket_connection_send_message ()

    void
    soup_websocket_connection_send_message
                                   (SoupWebsocketConnection *self,
                                    SoupWebsocketDataType type,
                                    GBytes *message);

Send a message of the given `type` to the peer. Note that this method, allows to send text messages containing `NULL` characters.

The message is queued to be sent and will be sent when the main loop is run.

#### Parameters

self | the WebSocket |
type | the type of message contents |
message | the message data as GBytes |

### soup_websocket_connection_close ()

    void
    soup_websocket_connection_close (SoupWebsocketConnection *self,
                                     gushort code,
                                     const char *data);

Close the connection in an orderly fashion.

Note that until the “closed” signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.

The `code` and `data` are sent to the peer along with the close request. If `code` is `SOUP_WEBSOCKET_CLOSE_NO_STATUS` a close message with no body (without code and data) is sent. Note that the `data` must be UTF-8 valid.

#### Parameters

self | the WebSocket |
code | close code |
data | close data. | [nullable]

### soup_websocket_connection_get_close_code ()

    gushort
    soup_websocket_connection_get_close_code
                                   (SoupWebsocketConnection *self);

Get the close code received from the WebSocket peer.

This only becomes valid once the WebSocket is in the `SOUP_WEBSOCKET_STATE_CLOSED` state. The value will often be in the SoupWebsocketCloseCode enumeration, but may also be an application defined close code.

#### Parameters

self | the WebSocket |

#### Returns

the close code or zero.

### soup_websocket_connection_get_close_data ()

    const char *
    soup_websocket_connection_get_close_data
                                   (SoupWebsocketConnection *self);

Get the close data received from the WebSocket peer.

This only becomes valid once the WebSocket is in the `SOUP_WEBSOCKET_STATE_CLOSED` state. The data may be freed once the main loop is run, so copy it if you need to keep it around.

#### Parameters

self | the WebSocket |

#### Returns

the close data or `NULL`

## Types and Values

### SoupWebsocketConnection

    typedef struct _SoupWebsocketConnection SoupWebsocketConnection;

A class representing a WebSocket connection.

### enum SoupWebsocketConnectionType

The type of a SoupWebsocketConnection.

#### Members

SOUP_WEBSOCKET_CONNECTION_UNKNOWN | unknown/invalid connection |
SOUP_WEBSOCKET_CONNECTION_CLIENT | a client-side connection |
SOUP_WEBSOCKET_CONNECTION_SERVER | a server-side connection |

### enum SoupWebsocketState

The state of the WebSocket connection.

#### Members

SOUP_WEBSOCKET_STATE_OPEN | the connection is ready to send messages |
SOUP_WEBSOCKET_STATE_CLOSING | the connection is in the process of closing down; messages may be received, but not sent |
SOUP_WEBSOCKET_STATE_CLOSED | the connection is completely closed down |

### enum SoupWebsocketDataType

The type of data contained in a “message” signal.

#### Members

SOUP_WEBSOCKET_DATA_TEXT | UTF-8 text |
SOUP_WEBSOCKET_DATA_BINARY | binary data |

### enum SoupWebsocketCloseCode

Pre-defined close codes that can be passed to `soup_websocket_connection_close()` or received from `soup_websocket_connection_get_close_code()`. (However, other codes are also allowed.)

#### Members

SOUP_WEBSOCKET_CLOSE_NORMAL | a normal, non-error close |
SOUP_WEBSOCKET_CLOSE_GOING_AWAY | the client/server is going away |
SOUP_WEBSOCKET_CLOSE_PROTOCOL_ERROR | a protocol error occurred |
SOUP_WEBSOCKET_CLOSE_UNSUPPORTED_DATA | the endpoint received data of a type that it does not support. |
SOUP_WEBSOCKET_CLOSE_NO_STATUS | reserved value indicating that no close code was present; must not be sent. |
SOUP_WEBSOCKET_CLOSE_ABNORMAL | reserved value indicating that the connection was closed abnormally; must not be sent. |
SOUP_WEBSOCKET_CLOSE_BAD_DATA | the endpoint received data that was invalid (eg, non-UTF-8 data in a text message). |
SOUP_WEBSOCKET_CLOSE_POLICY_VIOLATION | generic error code indicating some sort of policy violation. |
SOUP_WEBSOCKET_CLOSE_TOO_BIG | the endpoint received a message that is too big to process. |
SOUP_WEBSOCKET_CLOSE_NO_EXTENSION | the client is closing the connection because the server failed to negotiate a required extension. |
SOUP_WEBSOCKET_CLOSE_SERVER_ERROR | the server is closing the connection because it was unable to fulfill the request. |
SOUP_WEBSOCKET_CLOSE_TLS_HANDSHAKE | reserved value indicating that the TLS handshake failed; must not be sent. |

### enum SoupWebsocketError

WebSocket-related errors.

#### Members

SOUP_WEBSOCKET_ERROR_FAILED | a generic error |
SOUP_WEBSOCKET_ERROR_NOT_WEBSOCKET | attempted to handshake with a server that does not appear to understand WebSockets. |
SOUP_WEBSOCKET_ERROR_BAD_HANDSHAKE | the WebSocket handshake failed because some detail was invalid (eg, incorrect accept key). |
SOUP_WEBSOCKET_ERROR_BAD_ORIGIN | the WebSocket handshake failed because the "Origin" header was not an allowed value. |

### SOUP_WEBSOCKET_ERROR

    #define SOUP_WEBSOCKET_ERROR (soup_websocket_error_quark ())

A GError domain for WebSocket-related errors. Used with SoupWebsocketError.

## Property Details

### The `“connection-type”` property

      “connection-type”          SoupWebsocketConnectionType

The type of connection (client/server).

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

Default value: SOUP_WEBSOCKET_CONNECTION_UNKNOWN

### The `“extensions”` property

      “extensions”               gpointer

List of SoupWebsocketExtension objects that are active in the connection.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

### The `“io-stream”` property

      “io-stream”                GIOStream *

The underlying IO stream the WebSocket is communicating over.

The input and output streams must be pollable streams.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

### The `“keepalive-interval”` property

      “keepalive-interval”       guint

Interval in seconds on when to send a ping message which will serve as a keepalive message. If set to 0 the keepalive message is disabled.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct

Default value: 0

### The `“max-incoming-payload-size”` property

      “max-incoming-payload-size” guint64

The maximum payload size for incoming packets the protocol expects or 0 to not limit it.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct

Default value: 131072

### The `“origin”` property

      “origin”                   char *

The client's Origin.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

Default value: NULL

### The `“protocol”` property

      “protocol”                 char *

The chosen protocol, or `NULL` if a protocol was not agreed upon.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

Default value: NULL

### The `“state”` property

      “state”                    SoupWebsocketState

The current state of the WebSocket.

Owner: SoupWebsocketConnection

Flags: Read

Default value: SOUP_WEBSOCKET_STATE_OPEN

### The `“uri”` property

      “uri”                      GUri *

The URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

## Signal Details

### The `“closed”` signal

    void
    user_function (SoupWebsocketConnection *self,
                   gpointer                 user_data)

Emitted when the connection has completely closed, either due to an orderly close from the peer, one initiated via `soup_websocket_connection_close()` or a fatal error condition that caused a close.

This signal will be emitted once.

#### Parameters

self | the WebSocket |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“closing”` signal

    void
    user_function (SoupWebsocketConnection *self,
                   gpointer                 user_data)

This signal will be emitted during an orderly close.

#### Parameters

self | the WebSocket |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“error”` signal

    void
    user_function (SoupWebsocketConnection *self,
                   GError                  *error,
                   gpointer                 user_data)

Emitted when an error occurred on the WebSocket. This may be fired multiple times. Fatal errors will be followed by the “closed” signal being emitted.

#### Parameters

self | the WebSocket |
error | the error that occured |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“message”` signal

    void
    user_function (SoupWebsocketConnection *self,
                   int                      type,
                   GBytes                  *message,
                   gpointer                 user_data)

Emitted when we receive a message from the peer.

As a convenience, the `message` data will always be NUL-terminated, but the NUL byte will not be included in the length count.

#### Parameters

self | the WebSocket |
type | the type of message contents |
message | the message data |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“pong”` signal

    void
    user_function (SoupWebsocketConnection *self,
                   GBytes                  *message,
                   gpointer                 user_data)

Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.

As a convenience, the `message` data will always be NUL-terminated, but the NUL byte will not be included in the length count.

#### Parameters

self | the WebSocket |
message | the application data (if any) |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

soup_session_websocket_connect_async(), `soup_server_add_websocket_handler()`