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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Since: 2.50

soup_websocket_connection_get_origin ()

const char *
soup_websocket_connection_get_origin (SoupWebsocketConnection *self);

Get the origin of the WebSocket.

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.

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.

Since: 2.68

soup_websocket_connection_get_state ()

SoupWebsocketState
soup_websocket_connection_get_state (SoupWebsocketConnection *self);

Get the current state of the WebSocket.

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.

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.

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.

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.

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.

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.

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

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.

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.

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 .

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 .

Since: 2.68

SoupWebsocketConnection

typedef struct _SoupWebsocketConnection SoupWebsocketConnection;

A class representing a WebSocket connection.

Since: 2.50

enum SoupWebsocketConnectionType

The type of a SoupWebsocketConnection.

Since: 2.50

enum SoupWebsocketState

The state of the WebSocket connection.

Since: 2.50

enum SoupWebsocketDataType

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

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

Since: 2.50

SoupWebsocketExtensionManager

typedef struct _SoupWebsocketExtensionManager SoupWebsocketExtensionManager;

SoupWebsocketExtension

typedef struct _SoupWebsocketExtension SoupWebsocketExtension;

struct SoupWebsocketExtensionDeflate

struct SoupWebsocketExtensionDeflate;

enum SoupWebsocketError

WebSocket-related errors.

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

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”                   gchar *

The client's Origin.

Owner: SoupWebsocketConnection

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.

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

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.

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.

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.

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.

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.

Flags: Run First

Since: 2.60