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.

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.

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.

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.

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.

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.

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

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.

The message is queued to be sent and will be sent when the main loop is run.

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.

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_ERROR

#define SOUP_WEBSOCKET_ERROR (soup_websocket_error_get_quark ())

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

Since: 2.50

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

enum SoupWebsocketError

WebSocket-related errors.

Since: 2.50

The “connection-type” property

  “connection-type”          SoupWebsocketConnectionType

The type of connection (client/server).

Flags: Read / Write / Construct Only

Default value: SOUP_WEBSOCKET_CONNECTION_UNKNOWN

Since: 2.50

The “io-stream” property

  “io-stream”                GIOStream *

The underlying IO stream the WebSocket is communicating over.

The input and output streams must be pollable streams.

Flags: Read / Write / Construct Only

Since: 2.50

The “origin” property

  “origin”                   gchar *

The client's Origin.

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.50

The “protocol” property

  “protocol”                 gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.50

The “state” property

  “state”                    SoupWebsocketState

The current state of the WebSocket.

Flags: Read

Default value: SOUP_WEBSOCKET_STATE_OPEN

Since: 2.50

The “uri” property

  “uri”                      SoupURI *

The URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

Flags: Read / Write / Construct Only

Since: 2.50

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