WebSockets: libsoup Reference Manual

## WebSockets WebSockets — The WebSocket Protocol |

## Functions

void | soup_websocket_client_prepare_handshake ()
void | soup_websocket_client_prepare_handshake_with_extensions ()
gboolean | soup_websocket_client_verify_handshake ()
gboolean | soup_websocket_client_verify_handshake_with_extensions ()
gboolean | soup_websocket_server_check_handshake ()
gboolean | soup_websocket_server_check_handshake_with_extensions ()
gboolean | soup_websocket_server_process_handshake ()
gboolean | soup_websocket_server_process_handshake_with_extensions ()
SoupWebsocketConnection * | soup_websocket_connection_new ()
SoupWebsocketConnection * | soup_websocket_connection_new_with_extensions ()
GIOStream * | soup_websocket_connection_get_io_stream ()
SoupWebsocketConnectionType | soup_websocket_connection_get_connection_type ()
SoupURI * | 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 ()
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 ()
gboolean | soup_websocket_extension_configure ()
char * | soup_websocket_extension_get_request_params ()
char * | soup_websocket_extension_get_response_params ()
GBytes * | soup_websocket_extension_process_outgoing_message ()
GBytes * | soup_websocket_extension_process_incoming_message ()

## 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
SoupURI * | 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
| SoupWebsocketExtensionManager
| SoupWebsocketExtension
struct | SoupWebsocketExtensionDeflate
enum | SoupWebsocketError
#define | SOUP_WEBSOCKET_ERROR

## Object Hierarchy

        GObject
        ├── SoupWebsocketConnection
        ├── SoupWebsocketExtension
        │   ╰── SoupWebsocketExtensionDeflate
        ╰── SoupWebsocketExtensionManager

## Implemented Interfaces

SoupWebsocketExtensionManager implements SoupSessionFeature.

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

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

Use `soup_websocket_client_prepare_handshake_with_extensions()` if you want to include "Sec-WebSocket-Extensions" header in the request.

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. | [allow-none]
protocols | list of protocols to offer. | [allow-none][array zero-terminated=1]

Since: 2.50

### soup_websocket_client_prepare_handshake_with_extensions ()

    void
    soup_websocket_client_prepare_handshake_with_extensions
                                   (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]

Since: 2.68

### soup_websocket_client_verify_handshake ()

    gboolean
    soup_websocket_client_verify_handshake
                                   (SoupMessage *msg,
                                    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 the response contains the "Sec-WebSocket-Extensions" header, the handshake will be considered invalid. You need to use `soup_websocket_client_verify_handshake_with_extensions()` to handle responses with extensions.

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 |
error | return location for a GError |

#### Returns

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

Since: 2.50

### soup_websocket_client_verify_handshake_with_extensions ()

    gboolean
    soup_websocket_client_verify_handshake_with_extensions
                                   (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.

Since: 2.68

### soup_websocket_server_check_handshake ()

    gboolean
    soup_websocket_server_check_handshake (SoupMessage *msg,
                                           const char *origin,
                                           char **protocols,
                                           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.

Requests containing "Sec-WebSocket-Extensions" header will be accepted even if the header is not valid. To check a request with extensions you need to use `soup_websocket_server_check_handshake_with_extensions()` and provide the list of supported extension types.

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 | SoupMessage containing the client side of a WebSocket handshake |
origin | expected Origin header. | [allow-none]
protocols | allowed WebSocket protocols. | [allow-none][array zero-terminated=1]
error | return location for a GError |

#### Returns

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

Since: 2.50

### soup_websocket_server_check_handshake_with_extensions ()

    gboolean
    soup_websocket_server_check_handshake_with_extensions
                                   (SoupMessage *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_with_extensioins()` 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 | SoupMessage 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.

Since: 2.68

### soup_websocket_server_process_handshake ()

    gboolean
    soup_websocket_server_process_handshake
                                   (SoupMessage *msg,
                                    const char *expected_origin,
                                    char **protocols);

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.

Requests containing "Sec-WebSocket-Extensions" header will be accepted even if the header is not valid. To process a request with extensions you need to use `soup_websocket_server_process_handshake_with_extensions()` and provide the list of supported extension types.

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 | SoupMessage containing the client side of a WebSocket handshake |
expected_origin | expected Origin header. | [allow-none]
protocols | allowed WebSocket protocols. | [allow-none][array zero-terminated=1]

#### Returns

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

Since: 2.50

### soup_websocket_server_process_handshake_with_extensions ()

    gboolean
    soup_websocket_server_process_handshake_with_extensions
                                   (SoupMessage *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 | SoupMessage 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.

Since: 2.68

### soup_websocket_connection_new ()

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

Creates a SoupWebsocketConnection on `stream` . 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. | [allow-none]
protocol | the subprotocol in use. | [allow-none]

#### Returns

a new SoupWebsocketConnection

Since: 2.50

### soup_websocket_connection_new_with_extensions ()

    SoupWebsocketConnection *
    soup_websocket_connection_new_with_extensions
                                   (GIOStream *stream,
                                    SoupURI *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. | [allow-none]
protocol | the subprotocol in use. | [allow-none]
extensions | a GList of SoupWebsocketExtension objects. | [element-type SoupWebsocketExtension][transfer full]

#### Returns

a new SoupWebsocketConnection

Since: 2.68

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

Since: 2.50

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

Since: 2.50

### soup_websocket_connection_get_uri ()

    SoupURI *
    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]

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.68

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.68

### 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. | [allow-none]

Since: 2.50

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

Since: 2.50

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

Since: 2.50

### soup_websocket_extension_configure ()

    gboolean
    soup_websocket_extension_configure (SoupWebsocketExtension *extension,
                                        SoupWebsocketConnectionType connection_type,
                                        GHashTable *params,
                                        GError **error);

Configures `extension` with the given `params`

#### Parameters

extension | a SoupWebsocketExtension |
connection_type | either `SOUP_WEBSOCKET_CONNECTION_CLIENT` or `SOUP_WEBSOCKET_CONNECTION_SERVER` |
params | the parameters, or `NULL`. | [nullable]
error | return location for a GError |

#### Returns

`TRUE` if extension could be configured with the given parameters, or `FALSE` otherwise

### soup_websocket_extension_get_request_params ()

    char *
    soup_websocket_extension_get_request_params
                                   (SoupWebsocketExtension *extension);

Get the parameters strings to be included in the request header. If the extension doesn't include any parameter in the request, this function returns `NULL`.

#### Parameters

extension | a SoupWebsocketExtension |

#### Returns

a new allocated string with the parameters.

[nullable][transfer full]

Since: 2.68

### soup_websocket_extension_get_response_params ()

    char *
    soup_websocket_extension_get_response_params
                                   (SoupWebsocketExtension *extension);

Get the parameters strings to be included in the response header. If the extension doesn't include any parameter in the response, this function returns `NULL`.

#### Parameters

extension | a SoupWebsocketExtension |

#### Returns

a new allocated string with the parameters.

[nullable][transfer full]

Since: 2.68

### soup_websocket_extension_process_outgoing_message ()

    GBytes *
    soup_websocket_extension_process_outgoing_message
                                   (SoupWebsocketExtension *extension,
                                    guint8 *header,
                                    GBytes *payload,
                                    GError **error);

Process a message before it's sent. If the payload isn't changed the given `payload` is just returned, otherwise `g_bytes_unref()` is called on the given `payload` and a new GBytes is returned with the new data.

Extensions using reserved bits of the header will change them in `header` .

#### Parameters

extension | a SoupWebsocketExtension |
header | the message header. | [inout]
payload | the payload data. | [transfer full]
error | return location for a GError |

#### Returns

the message payload data, or `NULL` in case of error.

[transfer full]

Since: 2.68

### soup_websocket_extension_process_incoming_message ()

    GBytes *
    soup_websocket_extension_process_incoming_message
                                   (SoupWebsocketExtension *extension,
                                    guint8 *header,
                                    GBytes *payload,
                                    GError **error);

Process a message after it's received. If the payload isn't changed the given `payload` is just returned, otherwise `g_bytes_unref()` is called on the given `payload` and a new GBytes is returned with the new data.

Extensions using reserved bits of the header will reset them in `header` .

#### Parameters

extension | a SoupWebsocketExtension |
header | the message header. | [inout]
payload | the payload data. | [transfer full]
error | return location for a GError |

#### Returns

the message payload data, or `NULL` in case of error.

[transfer full]

Since: 2.68

## Types and Values

### SoupWebsocketConnection

    typedef struct _SoupWebsocketConnection SoupWebsocketConnection;

A class representing a WebSocket connection.

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

### SoupWebsocketExtensionManager

    typedef struct _SoupWebsocketExtensionManager SoupWebsocketExtensionManager;

### SoupWebsocketExtension

    typedef struct _SoupWebsocketExtension SoupWebsocketExtension;

### struct SoupWebsocketExtensionDeflate

    struct SoupWebsocketExtensionDeflate;

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

Since: 2.50

### SOUP_WEBSOCKET_ERROR

    #define SOUP_WEBSOCKET_ERROR (soup_websocket_error_get_quark ())

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

Since: 2.50

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

Since: 2.50

### The `“extensions”` property

      “extensions”               gpointer

List of SoupWebsocketExtension objects that are active in the connection.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

Since: 2.68

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

Since: 2.50

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

Since: 2.58

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

Since: 2.56

### The `“origin”` property

      “origin”                   char *

The client's Origin.

Owner: SoupWebsocketConnection

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.50

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

Since: 2.50

### The `“state”` property

      “state”                    SoupWebsocketState

The current state of the WebSocket.

Owner: SoupWebsocketConnection

Flags: Read

Default value: SOUP_WEBSOCKET_STATE_OPEN

Since: 2.50

### The `“uri”` property

      “uri”                      SoupURI *

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.50

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

Since: 2.60

## See Also

soup_session_websocket_connect_async(), `soup_server_add_websocket_handler()`