WebSockets

WebSockets — The WebSocket Protocol

Properties

SoupWebsocketConnectionType connection-type Read / Write / Construct Only
GIOStream * io-stream Read / Write / Construct Only
guint64 max-incoming-payload-size Read / Write / Construct
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

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

Flags: Read / Write / Construct

Default value: 131072

Since: 2.56


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