SoupWebsocket

SoupWebsocket — The WebSocket Protocol

Functions

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

Types and Values

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.

[allow-none]

protocol

the subprotocol in use.

[allow-none]

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.

[allow-none]

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