SoupWebsocketExtension: libsoup Reference Manual

## SoupWebsocketExtension SoupWebsocketExtension — a WebSocket extension |

## Functions

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

## Types and Values

| SoupWebsocketExtension
struct | SoupWebsocketExtensionClass
| SoupWebsocketExtensionDeflate
#define | SOUP_TYPE_WEBSOCKET_EXTENSION_DEFLATE
| SoupWebsocketExtensionManager
#define | SOUP_TYPE_WEBSOCKET_EXTENSION_MANAGER

## 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