Web Sockets package object

This package implements the Websocket protocol as described in the RFC 6455. It allow to define callbacks on specifics events and also implements a broadcaster service to make easier distribute message among different active connections.

Initialization

In order to make use of websocket package, two simple steps are required: the first one is to include the package header file on top of your code, then perform an explicit package inside duda_main() function.

Example:

/* Include package header */
#include "packages/websocket/websocket.h"

int duda_main()
{
    ...
    duda_load_package(websocket, "websocket");
    ...
    /*
     * In case you want to use the websocket broadcast feature you must enable the
     * broadcaster service:
     */
    websocket->broadcaster();

    ...
    return 0;
}

Once the package is loaded, you can use any methods from your callbacks in the following way:

websocket->method(...)

set_callback
write

broadcast()

It sends a message in broadcast mode to all active connections registered under a specific channel. This method is intended to be used inside a websocket callback. If you look for a method to broadcast all connection from a worker please review the method broadcast_all().

Prototype

int broadcast(ws_request_t *wr, unsigned char *data, uint64_t len, int msg_type, int channel);

Parameters

wr: the websocket request context struct
data: the data to be send
msg_type: define the message type, it can be WS_OPCODE_TEXT or WS_OPCODE_BINARY.
channel: specify the channel number, use -1 for all.

Return: This method always returns 0.

broadcast_all()

It sends a message in broadcast mode to all active connections registered under a specific channel number. This method is intended to be used from a worker.

Prototype

int broadcast_all(unsigned char *data, uint64_t len, int msg_type, int channel);

Parameters

data: the data to be send
msg_type: define the message type, it can be WS_OPCODE_TEXT or WS_OPCODE_BINARY.
channel: specify a specific channel number, use -1 for all.

Return: This method always returns 0.

broadcaster()

Initialize the websocket broadcaster service and interfaces. This method must be invoked inside duda_main().

Prototype

int broadcaster();

Parameters None

Return: On success it returns 0, on error this method perform an explicit exit.

handshake()

It perform the websocket handshake and connection upgrade. This must be used inside a normal HTTP callback function. It will take care of the handshake details and response data.

Prototype

int handshake(duda_request_t *dr, int channel);

Parameters

dr: the request context information hold by a duda_request_t type
channel: specify the channel number where the connection will be associated. Use -1 to specify all channels.

Return: Upon successful completion it returns 0, on error returns -1.

set_callback()

It set a specific callback function against on a received event.

Prototype

int set_callback(int type, void (*callback) (duda_request_t *, struct ws_request *));

Parameters

type: it specifies one of the following event types: WS_ON_MESSAGE, WS_ON_ERROR, WS_ON_CLOSE or WS_ON_TIMEOUT.
callback: the callback function

Return: It returns zero when the callback is set, otherwise -1 on errir

write()

It writes a message frame to a specified websocket connection.

Prototype

int write(struct ws_request *wr, unsigned int code, unsigned char *data, uint64_t len);

Parameters

wr: the target websocket connection
code: the message code, can be one of: WS_OPCODE_CONTINUE, WS_OPCODE_TEXT, WS_OPCODE_BINARY, WS_OPCODE_CLOSE, WS_OPCODE_PING or WS_OPCODE_PONG.
data: the data to be send
len: the length of the data to be send

Return: Upon successful completion it returns 0, on error returns -1.