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

Types and Values

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