WebSockets: libsoup Reference Manual

## WebSockets WebSockets — 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 ()
SoupURI * | soup_websocket_connection_get_uri ()
const char * | soup_websocket_connection_get_origin ()
const char * | soup_websocket_connection_get_protocol ()
SoupWebsocketState | soup_websocket_connection_get_state ()
void | soup_websocket_connection_send_text ()
void | soup_websocket_connection_send_binary ()
void | soup_websocket_connection_close ()
gushort | soup_websocket_connection_get_close_code ()
const char * | soup_websocket_connection_get_close_data ()
#define | SOUP_WEBSOCKET_ERROR

## Properties

SoupWebsocketConnectionType | connection-type | Read / Write / Construct Only
GIOStream * | io-stream | Read / Write / Construct Only
gchar * | origin | Read / Write / Construct Only
gchar * | 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

## Types and Values

| SoupWebsocketConnection
enum | SoupWebsocketConnectionType
enum | SoupWebsocketState
enum | SoupWebsocketDataType
enum | SoupWebsocketCloseCode
enum | SoupWebsocketError

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

Adds the necessary headers to `msg` to request a WebSocket handshake. 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. | [allow-none]
protocols | list of protocols to offer. | [allow-none][array zero-terminated=1]

Since: 2.50

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

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

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

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_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_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_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 text (UTF-8) message to the peer.

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.

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]
length | the length of `data` |

Since: 2.50

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

    #define SOUP_WEBSOCKET_ERROR (soup_websocket_error_get_quark ())

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

Since: 2.50

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

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

## Property Details

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

      “connection-type”          SoupWebsocketConnectionType

The type of connection (client/server).

Flags: Read / Write / Construct Only

Default value: SOUP_WEBSOCKET_CONNECTION_UNKNOWN

Since: 2.50

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

Flags: Read / Write / Construct Only

Since: 2.50

### The `“origin”` property

      “origin”                   gchar *

The client's Origin.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.50

### The `“protocol”` property

      “protocol”                 gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.50

### The `“state”` property

      “state”                    SoupWebsocketState

The current state of the WebSocket.

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.

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,
                   gint                     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

## See Also

soup_session_websocket_connect_async(), `soup_server_add_websocket_handler()`