SoupWebsocketExtension

SoupWebsocketExtension — a WebSocket extension

Functions

Types and Values

Object Hierarchy

    GObject
    ├── SoupWebsocketExtension
       ╰── SoupWebsocketExtensionDeflate
    ╰── SoupWebsocketExtensionManager

Implemented Interfaces

SoupWebsocketExtensionManager implements SoupSessionFeature.

Includes

#include <libsoup/soup.h>

Description

SoupWebsocketExtension is the base class for WebSocket extension objects.

Functions

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]


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]


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]


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]

Types and Values

SoupWebsocketExtension

typedef struct _SoupWebsocketExtension SoupWebsocketExtension;

Class for impelementing websocket extensions.


struct SoupWebsocketExtensionClass

struct SoupWebsocketExtensionClass {
	GObjectClass parent_class;

	const char  *name;

	gboolean (* configure)                (SoupWebsocketExtension     *extension,
					       SoupWebsocketConnectionType connection_type,
					       GHashTable                 *params,
					       GError                    **error);

	char    *(* get_request_params)       (SoupWebsocketExtension     *extension);

	char    *(* get_response_params)      (SoupWebsocketExtension     *extension);

	GBytes  *(* process_outgoing_message) (SoupWebsocketExtension     *extension,
					       guint8                     *header,
					       GBytes                     *payload,
					       GError                    **error);

	GBytes  *(* process_incoming_message) (SoupWebsocketExtension     *extension,
					       guint8                     *header,
					       GBytes                     *payload,
                                               GError                    **error);
};

The class structure for the SoupWebsocketExtension.

Members

const char *name;

the name of the extension

 

configure ()

called to configure the extension with the given parameters

 

get_request_params ()

called by the client to build the request header. It should include the parameters string starting with ';'

 

get_response_params ()

called by the server to build the response header. It should include the parameters string starting with ';'

 

process_outgoing_message ()

called to process the payload data of a message before it's sent. Reserved bits of the header should be changed.

 

process_incoming_message ()

called to process the payload data of a message after it's received. Reserved bits of the header should be cleared.

 

SoupWebsocketExtensionDeflate

typedef struct _SoupWebsocketExtensionDeflate SoupWebsocketExtensionDeflate;

A SoupWebsocketExtensionDeflate is a SoupWebsocketExtension implementing permessage-deflate (RFC 7692).

This extension is used by default in a SoupSession when SoupWebsocketExtensionManager feature is present, and always used by SoupServer.


SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE

#define SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE (soup_websocket_extension_deflate_get_type ())

A GType corresponding to permessage-deflate WebSocket extension.


SoupWebsocketExtensionManager

typedef struct _SoupWebsocketExtensionManager SoupWebsocketExtensionManager;

SoupWebsocketExtensionManager is the SoupSessionFeature that handles WebSockets extensions for a SoupSession.

A SoupWebsocketExtensionManager is added to the session by default, and normally you don't need to worry about it at all. However, if you want to disable WebSocket extensions, you can remove the feature from the session with soup_session_remove_feature_by_type(), or disable it on individual requests with soup_message_disable_feature().


SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER

#define SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER (soup_websocket_extension_manager_get_type ())

The GType of SoupWebsocketExtensionManager; you can use this with soup_session_remove_feature_by_type() or soup_message_disable_feature().

See Also

SoupSession, SoupWebsocketExtensionManager