http_websocket.h File Reference

Support for WebSocket connections within the Asterisk HTTP server and client WebSocket connections to a server. More...

#include "asterisk/http.h"
#include "asterisk/optional_api.h"
#include <errno.h>

Include dependency graph for http_websocket.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_websocket_client_options
	Options used for a websocket client. More...
struct	ast_websocket_protocol
	A websocket protocol implementation. More...

Macros
#define	AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT   100
	Default websocket write timeout, in ms.
#define	AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT_STR   "100"
	Default websocket write timeout, in ms (as a string)
#define	AST_WEBSOCKET_MAX_RX_PAYLOAD_SIZE   65535
	Size of the pre-determined buffer for WebSocket frames.
#define	AST_WEBSOCKET_PROTOCOL_VERSION   1
	Protocol version. This prevents dynamically loadable modules from registering if this struct is changed.

Typedefs
typedef void(*	ast_websocket_callback) (struct ast_websocket *session, struct ast_variable *parameters, struct ast_variable *headers)
	Callback for when a new connection for a sub-protocol is established.
typedef int(*	ast_websocket_pre_callback) (struct ast_tcptls_session_instance *ser, struct ast_variable *parameters, struct ast_variable *headers, const char *session_id)
	Callback from the HTTP request attempting to establish a websocket connection.

Enumerations
enum	ast_websocket_opcode {   AST_WEBSOCKET_OPCODE_TEXT = 0x1 , AST_WEBSOCKET_OPCODE_BINARY = 0x2 , AST_WEBSOCKET_OPCODE_PING = 0x9 , AST_WEBSOCKET_OPCODE_PONG = 0xA ,   AST_WEBSOCKET_OPCODE_CLOSE = 0x8 , AST_WEBSOCKET_OPCODE_CONTINUATION = 0x0 , AST_WEBSOCKET_OPCODE_UNKNOWN = 0xf }
	WebSocket operation codes. More...
enum	ast_websocket_result {   WS_OK = 0 , WS_ALLOCATE_ERROR , WS_KEY_ERROR , WS_URI_PARSE_ERROR ,   WS_URI_RESOLVE_ERROR , WS_BAD_STATUS , WS_INVALID_RESPONSE , WS_BAD_REQUEST ,   WS_URL_NOT_FOUND , WS_HEADER_MISMATCH , WS_HEADER_MISSING , WS_NOT_SUPPORTED ,   WS_WRITE_ERROR , WS_CLIENT_START_ERROR , WS_UNAUTHORIZED , WS_TLS_ERROR }
	Result code for a websocket client. More...
enum	ast_websocket_status_code {   AST_WEBSOCKET_STATUS_NORMAL = 1000 , AST_WEBSOCKET_STATUS_GOING_AWAY = 1001 , AST_WEBSOCKET_STATUS_PROTOCOL_ERROR = 1002 , AST_WEBSOCKET_STATUS_UNSUPPORTED_DATA = 1003 ,   AST_WEBSOCKET_STATUS_RESERVED_1004 = 1004 , AST_WEBSOCKET_STATUS_RESERVED_1005 = 1005 , AST_WEBSOCKET_STATUS_RESERVED_1006 = 1006 , AST_WEBSOCKET_STATUS_INVALID_FRAME = 1007 ,   AST_WEBSOCKET_STATUS_POLICY_VIOLATION = 1008 , AST_WEBSOCKET_STATUS_TOO_BIG = 1009 , AST_WEBSOCKET_STATUS_MANDATORY_EXT = 1010 , AST_WEBSOCKET_STATUS_INTERNAL_ERROR = 1011 ,   AST_WEBSOCKET_STATUS_RESERVED_1012 = 1012 , AST_WEBSOCKET_STATUS_RESERVED_1013 = 1013 , AST_WEBSOCKET_STATUS_BAD_GATEWAY = 1014 , AST_WEBSOCKET_STATUS_RESERVED_1015 = 1015 }
	Websocket Status Codes from RFC-6455. More...
enum	ast_websocket_type {   AST_WS_TYPE_CLIENT_PERSISTENT = (1 << 0) , AST_WS_TYPE_CLIENT_PER_CALL_CONFIG = (1 << 1) , AST_WS_TYPE_CLIENT_PER_CALL = (1 << 2) , AST_WS_TYPE_CLIENT = (1 << 3) ,   AST_WS_TYPE_INBOUND = (1 << 4) , AST_WS_TYPE_SERVER = (1 << 5) , AST_WS_TYPE_ANY = (0xFFFFFFFF) }
	WebSocket connection/configuration types. More...

Functions
int AST_OPTIONAL_API_NAME()	ast_websocket_add_protocol (const char *name, ast_websocket_callback callback)
	Add a sub-protocol handler to the default /ws server.
int AST_OPTIONAL_API_NAME()	ast_websocket_add_protocol2 (struct ast_websocket_protocol *protocol)
	Add a sub-protocol handler to the default /ws server.
const char *AST_OPTIONAL_API_NAME()	ast_websocket_client_accept_protocol (struct ast_websocket *ws)
	Retrieve the server accepted sub-protocol on the client.
struct ast_websocket *AST_OPTIONAL_API_NAME()	ast_websocket_client_create (const char *uri, const char *protocols, struct ast_tls_config *tls_cfg, enum ast_websocket_result *result)
	Create, and connect, a websocket client.
struct ast_websocket *AST_OPTIONAL_API_NAME()	ast_websocket_client_create_with_options (struct ast_websocket_client_options *options, enum ast_websocket_result *result)
	Create, and connect, a websocket client using given options.
int AST_OPTIONAL_API_NAME()	ast_websocket_close (struct ast_websocket *session, uint16_t reason)
	Close a WebSocket session by sending a message with the CLOSE opcode and an optional code.
int AST_OPTIONAL_API_NAME()	ast_websocket_fd (struct ast_websocket *session)
	Get the file descriptor for a WebSocket session.
int AST_OPTIONAL_API_NAME()	ast_websocket_is_secure (struct ast_websocket *session)
	Get whether the WebSocket session is using a secure transport or not.
struct ast_sockaddr *AST_OPTIONAL_API_NAME()	ast_websocket_local_address (struct ast_websocket *session)
	Get the local address for a WebSocket connection session.
int AST_OPTIONAL_API_NAME()	ast_websocket_read (struct ast_websocket *session, char **payload, uint64_t *payload_len, enum ast_websocket_opcode *opcode, int *fragmented)
	Read a WebSocket frame and handle it.
int AST_OPTIONAL_API_NAME()	ast_websocket_read_string (struct ast_websocket *ws, char **buf)
	Read a WebSocket frame containing string data.
void AST_OPTIONAL_API_NAME()	ast_websocket_reconstruct_disable (struct ast_websocket *session)
	Disable multi-frame reconstruction.
void AST_OPTIONAL_API_NAME()	ast_websocket_reconstruct_enable (struct ast_websocket *session, size_t bytes)
	Enable multi-frame reconstruction up to a certain number of bytes.
void AST_OPTIONAL_API_NAME()	ast_websocket_ref (struct ast_websocket *session)
	Increase the reference count for a WebSocket session.
struct ast_sockaddr *AST_OPTIONAL_API_NAME()	ast_websocket_remote_address (struct ast_websocket *session)
	Get the remote address for a WebSocket connected session.
int AST_OPTIONAL_API_NAME()	ast_websocket_remove_protocol (const char *name, ast_websocket_callback callback)
	Remove a sub-protocol handler from the default /ws server.
const char *AST_OPTIONAL_API_NAME()	ast_websocket_result_to_str (enum ast_websocket_result result)
	Convert a websocket result code to a string.
int AST_OPTIONAL_API_NAME()	ast_websocket_server_add_protocol (struct ast_websocket_server *server, const char *name, ast_websocket_callback callback)
	Add a sub-protocol handler to the given server.
int AST_OPTIONAL_API_NAME()	ast_websocket_server_add_protocol2 (struct ast_websocket_server *server, struct ast_websocket_protocol *protocol)
	Add a sub-protocol handler to the given server.
struct ast_websocket_server *AST_OPTIONAL_API_NAME()	ast_websocket_server_create (void)
	Creates a ast_websocket_server.
int AST_OPTIONAL_API_NAME()	ast_websocket_server_remove_protocol (struct ast_websocket_server *server, const char *name, ast_websocket_callback callback)
	Remove a sub-protocol handler from the given server.
const char *AST_OPTIONAL_API_NAME()	ast_websocket_session_id (struct ast_websocket *session)
	Get the session ID for a WebSocket session.
int AST_OPTIONAL_API_NAME()	ast_websocket_set_nonblock (struct ast_websocket *session)
	Set the socket of a WebSocket session to be non-blocking.
int AST_OPTIONAL_API_NAME()	ast_websocket_set_timeout (struct ast_websocket *session, int timeout)
	Set the timeout on a non-blocking WebSocket session.
const char *AST_OPTIONAL_API_NAME()	ast_websocket_status_to_str (enum ast_websocket_status_code code)
	Convert a websocket status code to a string.
struct ast_websocket_protocol *AST_OPTIONAL_API_NAME()	ast_websocket_sub_protocol_alloc (const char *name)
	Allocate a websocket sub-protocol instance.
const char *	ast_websocket_type_to_str (enum ast_websocket_type type)
void AST_OPTIONAL_API_NAME()	ast_websocket_unref (struct ast_websocket *session)
	Decrease the reference count for a WebSocket session.
int AST_OPTIONAL_API_NAME()	ast_websocket_uri_cb (struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_vars, struct ast_variable *headers)
	Callback suitable for use with a ast_http_uri.
int AST_OPTIONAL_API_NAME()	ast_websocket_wait_for_input (struct ast_websocket *session, int timeout)
	Wait for the WebSocket session to be ready to be read.
int AST_OPTIONAL_API_NAME()	ast_websocket_write (struct ast_websocket *session, enum ast_websocket_opcode opcode, char *payload, uint64_t payload_size)
	Construct and transmit a WebSocket frame.
int AST_OPTIONAL_API_NAME()	ast_websocket_write_string (struct ast_websocket *ws, const char *buf)
	Construct and transmit a WebSocket frame containing string data.

Detailed Description

Support for WebSocket connections within the Asterisk HTTP server and client WebSocket connections to a server.

Supported WebSocket versions in server implementation: Version 7 defined in specification http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-07 Version 8 defined in specification http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 Version 13 defined in specification http://tools.ietf.org/html/rfc6455 Supported WebSocket versions in client implementation: Version 13 defined in specification http://tools.ietf.org/html/rfc6455

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file http_websocket.h.

Macro Definition Documentation

AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT

#define AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT   100

Default websocket write timeout, in ms.

Definition at line 28 of file http_websocket.h.

AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT_STR

#define AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT_STR   "100"

Default websocket write timeout, in ms (as a string)

Definition at line 31 of file http_websocket.h.

AST_WEBSOCKET_MAX_RX_PAYLOAD_SIZE

#define AST_WEBSOCKET_MAX_RX_PAYLOAD_SIZE   65535

Size of the pre-determined buffer for WebSocket frames.

Definition at line 106 of file http_websocket.h.

AST_WEBSOCKET_PROTOCOL_VERSION

#define AST_WEBSOCKET_PROTOCOL_VERSION   1

Protocol version. This prevents dynamically loadable modules from registering if this struct is changed.

Definition at line 169 of file http_websocket.h.

Typedef Documentation

ast_websocket_callback

typedef void(* ast_websocket_callback) (struct ast_websocket *session, struct ast_variable *parameters, struct ast_variable *headers)

Callback for when a new connection for a sub-protocol is established.

Parameters

session	A WebSocket session structure
parameters	Parameters extracted from the request URI
headers	Headers included in the request

Note

Once called the ownership of the session is transferred to the sub-protocol handler. It is responsible for closing and cleaning up.

Definition at line 150 of file http_websocket.h.

ast_websocket_pre_callback

typedef int(* ast_websocket_pre_callback) (struct ast_tcptls_session_instance *ser, struct ast_variable *parameters, struct ast_variable *headers, const char *session_id)

Callback from the HTTP request attempting to establish a websocket connection.

This callback occurs when an HTTP request is made to establish a websocket connection. Implementers of ast_websocket_protocol can use this to deny a request, or to set up application specific data before invocation of ast_websocket_callback.

Parameters

ser	The TCP/TLS session
parameters	Parameters extracted from the request URI
headers	Headers included in the request
session_id	The id of the current session.

Return values

0	The session should be accepted
-1	The session should be rejected. Note that the caller must send an error response using ast_http_error.

Since

13.5.0

Definition at line 137 of file http_websocket.h.

Enumeration Type Documentation

ast_websocket_opcode

enum ast_websocket_opcode

WebSocket operation codes.

Enumerator
AST_WEBSOCKET_OPCODE_TEXT	Text frame
AST_WEBSOCKET_OPCODE_BINARY	Binary frame
AST_WEBSOCKET_OPCODE_PING	Request that the other side respond with a pong
AST_WEBSOCKET_OPCODE_PONG	Response to a ping
AST_WEBSOCKET_OPCODE_CLOSE	Connection is being closed
AST_WEBSOCKET_OPCODE_CONTINUATION	Continuation of a previous frame
AST_WEBSOCKET_OPCODE_UNKNOWN	Error

Definition at line 71 of file http_websocket.h.

                          {
    AST_WEBSOCKET_OPCODE_TEXT = 0x1,         /*!< Text frame */
    AST_WEBSOCKET_OPCODE_BINARY = 0x2,       /*!< Binary frame */
    AST_WEBSOCKET_OPCODE_PING = 0x9,         /*!< Request that the other side respond with a pong */
    AST_WEBSOCKET_OPCODE_PONG = 0xA,         /*!< Response to a ping */
    AST_WEBSOCKET_OPCODE_CLOSE = 0x8,        /*!< Connection is being closed */
    AST_WEBSOCKET_OPCODE_CONTINUATION = 0x0, /*!< Continuation of a previous frame */
    AST_WEBSOCKET_OPCODE_UNKNOWN = 0xf,      /*!< Error */
};

ast_websocket_result

enum ast_websocket_result

Result code for a websocket client.

Enumerator
WS_OK
WS_ALLOCATE_ERROR
WS_KEY_ERROR
WS_URI_PARSE_ERROR
WS_URI_RESOLVE_ERROR
WS_BAD_STATUS
WS_INVALID_RESPONSE
WS_BAD_REQUEST
WS_URL_NOT_FOUND
WS_HEADER_MISMATCH
WS_HEADER_MISSING
WS_NOT_SUPPORTED
WS_WRITE_ERROR
WS_CLIENT_START_ERROR
WS_UNAUTHORIZED
WS_TLS_ERROR

Definition at line 448 of file http_websocket.h.

                          {
    WS_OK = 0,
    WS_ALLOCATE_ERROR,
    WS_KEY_ERROR,
    WS_URI_PARSE_ERROR,
    WS_URI_RESOLVE_ERROR,
    WS_BAD_STATUS,
    WS_INVALID_RESPONSE,
    WS_BAD_REQUEST,
    WS_URL_NOT_FOUND,
    WS_HEADER_MISMATCH,
    WS_HEADER_MISSING,
    WS_NOT_SUPPORTED,
    WS_WRITE_ERROR,
    WS_CLIENT_START_ERROR,
    WS_UNAUTHORIZED,
    WS_TLS_ERROR,
};

ast_websocket_status_code

enum ast_websocket_status_code

Websocket Status Codes from RFC-6455.

Enumerator
AST_WEBSOCKET_STATUS_NORMAL
AST_WEBSOCKET_STATUS_GOING_AWAY
AST_WEBSOCKET_STATUS_PROTOCOL_ERROR
AST_WEBSOCKET_STATUS_UNSUPPORTED_DATA
AST_WEBSOCKET_STATUS_RESERVED_1004
AST_WEBSOCKET_STATUS_RESERVED_1005
AST_WEBSOCKET_STATUS_RESERVED_1006
AST_WEBSOCKET_STATUS_INVALID_FRAME
AST_WEBSOCKET_STATUS_POLICY_VIOLATION
AST_WEBSOCKET_STATUS_TOO_BIG
AST_WEBSOCKET_STATUS_MANDATORY_EXT
AST_WEBSOCKET_STATUS_INTERNAL_ERROR
AST_WEBSOCKET_STATUS_RESERVED_1012
AST_WEBSOCKET_STATUS_RESERVED_1013
AST_WEBSOCKET_STATUS_BAD_GATEWAY
AST_WEBSOCKET_STATUS_RESERVED_1015

Definition at line 82 of file http_websocket.h.

                               {
    AST_WEBSOCKET_STATUS_NORMAL = 1000,
    AST_WEBSOCKET_STATUS_GOING_AWAY = 1001,
    AST_WEBSOCKET_STATUS_PROTOCOL_ERROR = 1002,
    AST_WEBSOCKET_STATUS_UNSUPPORTED_DATA = 1003,
    AST_WEBSOCKET_STATUS_RESERVED_1004 = 1004,
    AST_WEBSOCKET_STATUS_RESERVED_1005 = 1005,
    AST_WEBSOCKET_STATUS_RESERVED_1006 = 1006,
    AST_WEBSOCKET_STATUS_INVALID_FRAME = 1007,
    AST_WEBSOCKET_STATUS_POLICY_VIOLATION = 1008,
    AST_WEBSOCKET_STATUS_TOO_BIG = 1009,
    AST_WEBSOCKET_STATUS_MANDATORY_EXT = 1010,
    AST_WEBSOCKET_STATUS_INTERNAL_ERROR = 1011,
    AST_WEBSOCKET_STATUS_RESERVED_1012 = 1012,
    AST_WEBSOCKET_STATUS_RESERVED_1013 = 1013,
    AST_WEBSOCKET_STATUS_BAD_GATEWAY = 1014,
    AST_WEBSOCKET_STATUS_RESERVED_1015 = 1015,
};

ast_websocket_type

enum ast_websocket_type

WebSocket connection/configuration types.

These may look like they overlap or are redundant, but they're shared by other modules like ari and chan_websocket and it didn't make sense to force them to define their own types.

Enumerator
AST_WS_TYPE_CLIENT_PERSISTENT
AST_WS_TYPE_CLIENT_PER_CALL_CONFIG
AST_WS_TYPE_CLIENT_PER_CALL
AST_WS_TYPE_CLIENT
AST_WS_TYPE_INBOUND
AST_WS_TYPE_SERVER
AST_WS_TYPE_ANY

Definition at line 57 of file http_websocket.h.

                        {
    AST_WS_TYPE_CLIENT_PERSISTENT = (1 << 0),
    AST_WS_TYPE_CLIENT_PER_CALL_CONFIG = (1 << 1),
    AST_WS_TYPE_CLIENT_PER_CALL = (1 << 2),
    AST_WS_TYPE_CLIENT = (1 << 3),
    AST_WS_TYPE_INBOUND = (1 << 4),
    AST_WS_TYPE_SERVER = (1 << 5),
    AST_WS_TYPE_ANY = (0xFFFFFFFF),
};

Function Documentation

ast_websocket_add_protocol()

int AST_OPTIONAL_API_NAME() ast_websocket_add_protocol	(	const char *	name,
		ast_websocket_callback	callback
	)

Add a sub-protocol handler to the default /ws server.

Parameters

name	Name of the sub-protocol to register
callback	Callback called when a new connection requesting the sub-protocol is established

Return values

0	success
-1	if sub-protocol handler could not be registered

Definition at line 1242 of file res_http_websocket.c.

{
    return websocket_add_protocol_internal(name, callback);
}

References callback(), name, and websocket_add_protocol_internal().

Referenced by AST_TEST_DEFINE(), and load_module().

ast_websocket_add_protocol2()

int AST_OPTIONAL_API_NAME() ast_websocket_add_protocol2

(

struct ast_websocket_protocol *

protocol

)

Add a sub-protocol handler to the default /ws server.

Parameters

protocol

The sub-protocol to register. Note that this must be allocated using /ref ast_websocket_sub_protocol_alloc.

Note

This method is reference stealing. It will steal the reference to protocol on success.

Return values

0	success
-1	if sub-protocol handler could not be registered

Since

13.5.0

Definition at line 1247 of file res_http_websocket.c.

{
    struct ast_websocket_server *ws_server = websocketuri.data;
 
    if (!ws_server) {
        return -1;
    }
 
    if (ast_websocket_server_add_protocol2(ws_server, protocol)) {
        return -1;
    }
 
    return 0;
}

References ast_websocket_server_add_protocol2(), ast_http_uri::data, and websocketuri.

ast_websocket_client_accept_protocol()

const char *AST_OPTIONAL_API_NAME() ast_websocket_client_accept_protocol

(

struct ast_websocket *

ws

)

Retrieve the server accepted sub-protocol on the client.

Parameters

ws	the websocket client

Returns

the accepted client sub-protocol.

Since

13

Definition at line 1563 of file res_http_websocket.c.

{
    return ws->client->accept_protocol;
}

References websocket_client::accept_protocol, and ast_websocket::client.

Referenced by AST_TEST_DEFINE().

ast_websocket_client_create()

struct ast_websocket *AST_OPTIONAL_API_NAME() ast_websocket_client_create	(	const char *	uri,
		const char *	protocols,
		struct ast_tls_config *	tls_cfg,
		enum ast_websocket_result *	result
	)

Create, and connect, a websocket client.

If the client websocket successfully connects, then the accepted protocol can be checked via a call to ast_websocket_client_accept_protocol.

Note

While connecting this will block until a response is received from the remote host.

Expected uri form:

ws[s]://<address>[:port][/<path>] 

The address (can be a host name) and port are parsed out and used to connect to the remote server. If multiple IPs are returned during address resolution then the first one is chosen.

Parameters

uri	uri to connect to
protocols	a comma separated string of supported protocols
tls_cfg	secure websocket credentials
result	result code set on client failure

Returns

a client websocket.

Return values

NULL	if object could not be created or connected

Since

13

Warning

The returned websocket must be closed with ast_websocket_close and its reference count decremented with ast_websocket_unref when it's no longer needed.

Definition at line 1914 of file res_http_websocket.c.

{
    struct ast_websocket_client_options options = {
        .uri = uri,
        .protocols = protocols,
        .timeout = -1,
        .tls_cfg = tls_cfg,
    };
 
    return ast_websocket_client_create_with_options(&options, result);
}

References ast_websocket_client_create_with_options(), options, ast_websocket_client_options::protocols, result, ast_websocket_client_options::tls_cfg, and ast_websocket_client_options::uri.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), and AST_TEST_DEFINE().

ast_websocket_client_create_with_options()

struct ast_websocket *AST_OPTIONAL_API_NAME() ast_websocket_client_create_with_options	(	struct ast_websocket_client_options *	options,
		enum ast_websocket_result *	result
	)

Create, and connect, a websocket client using given options.

If the client websocket successfully connects, then the accepted protocol can be checked via a call to ast_websocket_client_accept_protocol.

Note

While connecting this will block until a response is received from the remote host, or the connection timeout is reached

Parameters

options	Websocket client options
result	result code set on client failure

Returns

a client websocket.

Return values

NULL	if object could not be created or connected

Warning

The returned websocket must be closed with ast_websocket_close and its reference count decremented with ast_websocket_unref when it's no longer needed.

Definition at line 2006 of file res_http_websocket.c.

{
    struct ast_websocket *ws = NULL;
    SCOPE_ENTER(2, "%s: Creating client\n", options->uri);
 
    ws = websocket_client_create(options, result);
    if (!ws) {
        SCOPE_EXIT_LOG_RTN_VALUE(NULL, LOG_ERROR, "%s: Failed to create: %s\n", options->uri, ast_websocket_result_to_str(*result));
    }
 
    ast_trace(-1, "%s: Connecting\n", ws->client->options->uri);
 
    if ((*result = websocket_client_connect(ws, options)) != WS_OK) {
        ao2_ref(ws, -1);
        SCOPE_EXIT_RTN_VALUE(NULL, "%s: Failed to connect: %s\n", options->uri, ast_websocket_result_to_str(*result));
    }
    ast_trace(-1, "%s: Connected\n", ws->client->options->uri);
 
    if (ws->client->options->tcp_keepalives) {
        int sockfd = ast_iostream_get_fd(ws->stream);
        int enabled = 1;
 
        setsockopt(sockfd, SOL_SOCKET, SO_KEEPALIVE, &enabled, sizeof(enabled));
        setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPIDLE, &options->tcp_keepalive_time, sizeof(options->tcp_keepalive_time));
        setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPINTVL, &options->tcp_keepalive_interval, sizeof(&options->tcp_keepalive_interval));
        setsockopt(sockfd, IPPROTO_TCP, TCP_KEEPCNT, &options->tcp_keepalive_probes, sizeof(&options->tcp_keepalive_probes));
        ast_trace(-1, "%s: Enabled TCP keepalives\n", ws->client->options->uri);
    }
 
    if (ws->client->options->pingpongs) {
        ws->client->ping_sched_timer = ast_sched_add(ping_scheduler, ws->client->options->pingpong_interval * 1000,
            ping_scheduler_callback, ao2_bump(ws));
        if (ws->client->ping_sched_timer < 0) {
            ast_log(LOG_WARNING, "%s: Unable to schedule PING/PONG keepalives\n", ws->client->options->uri);
            ao2_ref(ws, -1);
        } else {
            ast_trace(-1, "%s: Enabled PING/PONG keepalives\n", ws->client->options->uri);
        }
    }
    SCOPE_EXIT_RTN_VALUE(ws, "%s: Client created and connected %p %p\n", options->uri, ws, ws->client);
}

References ao2_bump, ao2_ref, ast_iostream_get_fd(), ast_log, ast_sched_add(), ast_trace, ast_websocket_result_to_str(), ast_websocket::client, enabled, LOG_ERROR, LOG_WARNING, NULL, websocket_client::options, options, websocket_client::ping_sched_timer, ping_scheduler, ping_scheduler_callback(), ast_websocket_client_options::pingpong_interval, ast_websocket_client_options::pingpongs, result, SCOPE_ENTER, SCOPE_EXIT_LOG_RTN_VALUE, SCOPE_EXIT_RTN_VALUE, ast_websocket::stream, ast_websocket_client_options::tcp_keepalives, ast_websocket_client_options::uri, websocket_client_connect(), websocket_client_create(), and WS_OK.

Referenced by ast_websocket_client_connect(), ast_websocket_client_create(), and websocket_connect().

ast_websocket_close()

int AST_OPTIONAL_API_NAME() ast_websocket_close	(	struct ast_websocket *	session,
		uint16_t	reason
	)

Close a WebSocket session by sending a message with the CLOSE opcode and an optional code.

Parameters

session	Pointer to the WebSocket session
reason	Reason code for closing the session as defined in the RFC

Return values

0	if successfully written
-1	if error occurred

Close a WebSocket session by sending a message with the CLOSE opcode and an optional code.

Definition at line 553 of file res_http_websocket.c.

{
    if (session->closed_by == WS_NOT_CLOSED) {
        session->closed_by = WS_CLOSED_BY_US;
    }
 
    return websocket_close(session, reason, 0);
}

References session, websocket_close(), WS_CLOSED_BY_US, and WS_NOT_CLOSED.

Referenced by ast_websocket_read(), incoming_ws_established_cb(), outbound_session_apply_config(), outbound_session_handler_thread(), outbound_session_pc_close_thread(), outbound_sessions_load(), session_destroy_fn(), session_shutdown_cb(), webchan_hangup(), websocket_disconnect(), websocket_established_cb(), and ws_shutdown().

ast_websocket_fd()

int AST_OPTIONAL_API_NAME() ast_websocket_fd

(

struct ast_websocket *

session

)

Get the file descriptor for a WebSocket session.

Returns

file descriptor

Note

You must not directly read from or write to this file descriptor. It should only be used for polling.

Definition at line 662 of file res_http_websocket.c.

{
    return session->closing ? -1 : ast_iostream_get_fd(session->stream);
}

References ast_iostream_get_fd(), and session.

Referenced by session_read(), speech_test_server_cb(), websocket_echo_callback(), websocket_handoff_to_channel(), websocket_read(), and ws_shutdown().

ast_websocket_is_secure()

int AST_OPTIONAL_API_NAME() ast_websocket_is_secure

(

struct ast_websocket *

session

)

Get whether the WebSocket session is using a secure transport or not.

Return values

0	if unsecure
1	if secure

Definition at line 682 of file res_http_websocket.c.

{
    return session->secure;
}

References session.

Referenced by transport_create().

ast_websocket_local_address()

struct ast_sockaddr *AST_OPTIONAL_API_NAME() ast_websocket_local_address

(

struct ast_websocket *

session

)

Get the local address for a WebSocket connection session.

Returns

Local address

Since

13.19.0

Definition at line 677 of file res_http_websocket.c.

{
    return &session->local_address;
}

References session.

Referenced by transport_create().

ast_websocket_read()

int AST_OPTIONAL_API_NAME() ast_websocket_read	(	struct ast_websocket *	session,
		char **	payload,
		uint64_t *	payload_len,
		enum ast_websocket_opcode *	opcode,
		int *	fragmented
	)

Read a WebSocket frame and handle it.

Parameters

session	Pointer to the WebSocket session
payload	Pointer to a char* which will be populated with a pointer to the payload if present
payload_len	Pointer to a uint64_t which will be populated with the length of the payload if present
opcode	Pointer to an enum which will be populated with the opcode of the frame
fragmented	Pointer to an int which is set to 1 if payload is fragmented and 0 if not

Return values

-1	on error
0	on success

Note

Once an AST_WEBSOCKET_OPCODE_CLOSE opcode is received the socket will be closed

Definition at line 803 of file res_http_websocket.c.

{
    int fin = 0;
    int mask_present = 0;
    char *mask = NULL, *new_payload = NULL;
    size_t options_len = 0, frame_size = 0;
    SCOPE_ENTER(4, "%s: Reading\n", WS_SESSION_REMOTE(session));
 
    *payload = NULL;
    *payload_len = 0;
    *fragmented = 0;
 
    if (ws_safe_read(session, &session->buf[0], MIN_WS_HDR_SZ, opcode)) {
        SCOPE_EXIT_RTN_VALUE(-1, "%s: Initial ws_safe_read failed\n", WS_SESSION_REMOTE(session));
    }
    frame_size += MIN_WS_HDR_SZ;
 
    /* ok, now we have the first 2 bytes, so we know some flags, opcode and payload length (or whether payload length extension will be required) */
    *opcode = session->buf[0] & 0xf;
    *payload_len = session->buf[1] & 0x7f;
    if (*opcode == AST_WEBSOCKET_OPCODE_TEXT || *opcode == AST_WEBSOCKET_OPCODE_BINARY || *opcode == AST_WEBSOCKET_OPCODE_CONTINUATION ||
        *opcode == AST_WEBSOCKET_OPCODE_PING || *opcode == AST_WEBSOCKET_OPCODE_PONG  || *opcode == AST_WEBSOCKET_OPCODE_CLOSE) {
        fin = (session->buf[0] >> 7) & 1;
        mask_present = (session->buf[1] >> 7) & 1;
 
        /* Based on the mask flag and payload length, determine how much more we need to read before start parsing the rest of the header */
        options_len += mask_present ? 4 : 0;
        options_len += (*payload_len == 126) ? 2 : (*payload_len == 127) ? 8 : 0;
        if (options_len) {
            /* read the rest of the header options */
            if (ws_safe_read(session, &session->buf[frame_size], options_len, opcode)) {
                SCOPE_EXIT_RTN_VALUE(-1, "%s: ws_safe_read of options failed\n", WS_SESSION_REMOTE(session));
            }
            frame_size += options_len;
        }
 
        if (*payload_len == 126) {
            /* Grab the 2-byte payload length  */
            *payload_len = ntohs(get_unaligned_uint16(&session->buf[2]));
            mask = &session->buf[4];
        } else if (*payload_len == 127) {
            /* Grab the 8-byte payload length  */
            *payload_len = ntohll(get_unaligned_uint64(&session->buf[2]));
            mask = &session->buf[10];
        } else {
            /* Just set the mask after the small 2-byte header */
            mask = &session->buf[2];
        }
 
        /* Now read the rest of the payload */
        *payload = &session->buf[frame_size]; /* payload will start here, at the end of the options, if any */
        frame_size = frame_size + (*payload_len); /* final frame size is header + optional headers + payload data */
        if (frame_size > AST_WEBSOCKET_MAX_RX_PAYLOAD_SIZE) {
            /* The frame won't fit :-( */
            ast_websocket_close(session, 1009);
            SCOPE_EXIT_LOG_RTN_VALUE(-1, LOG_WARNING, "%s: Cannot fit huge websocket frame of %zu bytes\n",
                WS_SESSION_REMOTE(session), frame_size);
        }
 
        if (*payload_len) {
            if (ws_safe_read(session, *payload, *payload_len, opcode)) {
                SCOPE_EXIT_RTN_VALUE(-1, "%s: ws_safe_read of payload failed\n", WS_SESSION_REMOTE(session));
            }
        }
 
        /* If a mask is present unmask the payload */
        if (mask_present) {
            unsigned int pos;
            for (pos = 0; pos < *payload_len; pos++) {
                (*payload)[pos] ^= mask[pos % 4];
            }
        }
 
        /* Per the RFC for PING we need to send back an opcode with the application data as received */
        if (*opcode == AST_WEBSOCKET_OPCODE_PING) {
            if (ast_websocket_write(session, AST_WEBSOCKET_OPCODE_PONG, *payload, *payload_len)) {
                ast_websocket_close(session, 1009);
            }
            *payload_len = 0;
            SCOPE_EXIT_RTN_VALUE(0, "%s: PING received.  Sent PONG\n", WS_SESSION_REMOTE(session));
        }
 
        if (websocket_handled_pong_or_close(session, *payload, *payload_len, *opcode)) {
            SCOPE_EXIT_RTN_VALUE(0, "%s: Handled PONG or CLOSE\n", WS_SESSION_REMOTE(session));
        }
 
        /* Below this point we are handling TEXT, BINARY or CONTINUATION opcodes */
        if (*payload_len) {
            if (!(new_payload = ast_realloc(session->payload, (session->payload_len + *payload_len)))) {
                *payload_len = 0;
                ast_websocket_close(session, 1009);
                SCOPE_EXIT_LOG_RTN_VALUE(-1, LOG_WARNING, "%s: Failed allocation: %p, %zu, %"PRIu64"\n",
                    WS_SESSION_REMOTE(session), session->payload, session->payload_len, *payload_len);
            }
 
            session->payload = new_payload;
            memcpy((session->payload + session->payload_len), (*payload), (*payload_len));
            session->payload_len += *payload_len;
        } else if (!session->payload_len && session->payload) {
            ast_free(session->payload);
            session->payload = NULL;
        }
 
        if (!fin && session->reconstruct && (session->payload_len < session->reconstruct)) {
            /* If this is not a final message we need to defer returning it until later */
            if (*opcode != AST_WEBSOCKET_OPCODE_CONTINUATION) {
                session->opcode = *opcode;
            }
            *opcode = AST_WEBSOCKET_OPCODE_CONTINUATION;
            *payload_len = 0;
            *payload = NULL;
        } else {
            if (*opcode == AST_WEBSOCKET_OPCODE_CONTINUATION) {
                if (!fin) {
                    /* If this was not actually the final message tell the user it is fragmented so they can deal with it accordingly */
                    *fragmented = 1;
                } else {
                    /* Final frame in multi-frame so push up the actual opcode */
                    *opcode = session->opcode;
                }
            }
            *payload_len = session->payload_len;
            *payload = session->payload;
            session->payload_len = 0;
        }
    } else {
        ast_log(LOG_WARNING, "WebSocket unknown opcode %u\n", *opcode);
        /* We received an opcode that we don't understand, the RFC states that 1003 is for a type of data that can't be accepted... opcodes
         * fit that, I think. */
        ast_websocket_close(session, 1003);
    }
 
    SCOPE_EXIT_RTN_VALUE(0, "%s: Read complete.  Opcode: %s  Length: %"PRIu64"\n",
        WS_SESSION_REMOTE(session), websocket_opcode2str(*opcode), *payload_len);
}

References ast_free, ast_log, ast_realloc, ast_websocket_close(), AST_WEBSOCKET_MAX_RX_PAYLOAD_SIZE, AST_WEBSOCKET_OPCODE_BINARY, AST_WEBSOCKET_OPCODE_CLOSE, AST_WEBSOCKET_OPCODE_CONTINUATION, AST_WEBSOCKET_OPCODE_PING, AST_WEBSOCKET_OPCODE_PONG, AST_WEBSOCKET_OPCODE_TEXT, ast_websocket_write(), frame_size, get_unaligned_uint16(), get_unaligned_uint64(), LOG_WARNING, MIN_WS_HDR_SZ, ntohll(), NULL, ast_websocket::opcode, ast_websocket::payload, ast_websocket::payload_len, SCOPE_ENTER, SCOPE_EXIT_LOG_RTN_VALUE, SCOPE_EXIT_RTN_VALUE, session, websocket_handled_pong_or_close(), websocket_opcode2str(), ws_safe_read(), and WS_SESSION_REMOTE.

Referenced by ast_websocket_read_string(), read_from_ws_and_queue(), session_read(), speech_test_server_cb(), websocket_cb(), websocket_echo_callback(), and websocket_read().

ast_websocket_read_string()

int AST_OPTIONAL_API_NAME() ast_websocket_read_string	(	struct ast_websocket *	ws,
		char **	buf
	)

Read a WebSocket frame containing string data.

Note

The caller is responsible for freeing the output "buf".

Parameters

ws	pointer to the websocket
buf	string buffer to populate with data read from socket

Return values

-1

on error

Returns

number of bytes read on success

Note

Once an AST_WEBSOCKET_OPCODE_CLOSE opcode is received the socket will be closed

Definition at line 2049 of file res_http_websocket.c.

{
    char *payload;
    uint64_t payload_len;
    enum ast_websocket_opcode opcode;
    int fragmented = 1;
 
    while (fragmented) {
        if (ast_websocket_read(ws, &payload, &payload_len,
                       &opcode, &fragmented)) {
            ast_log(LOG_ERROR, "Client WebSocket string read - "
                "error reading string data\n");
            return -1;
        }
 
        if (opcode == AST_WEBSOCKET_OPCODE_PING) {
            /* Try read again, we have sent pong already */
            fragmented = 1;
            continue;
        }
 
        if (opcode == AST_WEBSOCKET_OPCODE_CONTINUATION) {
            continue;
        }
 
        if (opcode == AST_WEBSOCKET_OPCODE_CLOSE) {
            return -1;
        }
 
        if (opcode != AST_WEBSOCKET_OPCODE_TEXT) {
            ast_log(LOG_ERROR, "Client WebSocket string read - "
                "non string data received\n");
            return -1;
        }
    }
 
    if (!(*buf = ast_strndup(payload, payload_len))) {
        return -1;
    }
 
    return payload_len + 1;
}

References ast_log, ast_strndup, AST_WEBSOCKET_OPCODE_CLOSE, AST_WEBSOCKET_OPCODE_CONTINUATION, AST_WEBSOCKET_OPCODE_PING, AST_WEBSOCKET_OPCODE_TEXT, ast_websocket_read(), buf, LOG_ERROR, ast_websocket::opcode, ast_websocket::payload, and ast_websocket::payload_len.

Referenced by AST_TEST_DEFINE().

ast_websocket_reconstruct_disable()

void AST_OPTIONAL_API_NAME() ast_websocket_reconstruct_disable

(

struct ast_websocket *

session

)

Disable multi-frame reconstruction.

Parameters

session

Pointer to the WebSocket session

Note

If reconstruction is disabled each message that is part of a multi-frame message will be sent up to the user when ast_websocket_read is called.

Definition at line 638 of file res_http_websocket.c.

{
    session->reconstruct = 0;
}

References session.

ast_websocket_reconstruct_enable()

void AST_OPTIONAL_API_NAME() ast_websocket_reconstruct_enable	(	struct ast_websocket *	session,
		size_t	bytes
	)

Enable multi-frame reconstruction up to a certain number of bytes.

Parameters

session	Pointer to the WebSocket session
bytes	If a reconstructed payload exceeds the specified number of bytes the payload will be returned and upon reception of the next multi-frame a new reconstructed payload will begin.

Definition at line 633 of file res_http_websocket.c.

{
    session->reconstruct = MIN(bytes, MAXIMUM_RECONSTRUCTION_CEILING);
}

References MAXIMUM_RECONSTRUCTION_CEILING, MIN, and session.

Referenced by websocket_handoff_to_channel().

ast_websocket_ref()

void AST_OPTIONAL_API_NAME() ast_websocket_ref

(

struct ast_websocket *

session

)

Increase the reference count for a WebSocket session.

Parameters

session

Pointer to the WebSocket session

Definition at line 643 of file res_http_websocket.c.

{
    char *id = ast_strdupa(WS_SESSION_REMOTE(session));
    int refcount = session ? ao2_ref(session, 0) : 0;
    SCOPE_ENTER(2, "%s: Reffing.  Refcount: %d\n", id, refcount);
    ao2_ref(session, +1);
    SCOPE_EXIT("%s: Reffed.  Refcount: %d\n", id, session ? refcount - 1 : 0);
}

References ao2_ref, ast_strdupa, SCOPE_ENTER, SCOPE_EXIT, session, and WS_SESSION_REMOTE.

Referenced by session_update(), and transport_create().

ast_websocket_remote_address()

struct ast_sockaddr *AST_OPTIONAL_API_NAME() ast_websocket_remote_address

(

struct ast_websocket *

session

)

Get the remote address for a WebSocket connected session.

Returns

Remote address

Definition at line 672 of file res_http_websocket.c.

{
    return &session->remote_address;
}

References session.

Referenced by ari_websocket_send_event(), session_update(), session_write(), transport_create(), transport_read(), websocket_established_cb(), and websocket_handoff_to_channel().

ast_websocket_remove_protocol()

int AST_OPTIONAL_API_NAME() ast_websocket_remove_protocol	(	const char *	name,
		ast_websocket_callback	callback
	)

Remove a sub-protocol handler from the default /ws server.

Parameters

name	Name of the sub-protocol to unregister
callback	Session Established callback that was previously registered with the sub-protocol

Return values

0	success
-1	if sub-protocol was not found or if callback did not match

Definition at line 1271 of file res_http_websocket.c.

{
    return websocket_remove_protocol_internal(name, callback);
}

References callback(), name, and websocket_remove_protocol_internal().

Referenced by AST_TEST_DEFINE(), and unload_module().

ast_websocket_result_to_str()

const char *AST_OPTIONAL_API_NAME() ast_websocket_result_to_str

(

enum ast_websocket_result

result

)

Convert a websocket result code to a string.

Parameters

result

The result code to convert

Returns

A string representation of the result code

Definition at line 2129 of file res_http_websocket.c.

{
    if (!ARRAY_IN_BOUNDS(result, websocket_result_string_map)) {
        return "unknown";
    }
    return websocket_result_string_map[result];
}

References ARRAY_IN_BOUNDS, result, and websocket_result_string_map.

Referenced by ast_websocket_client_connect(), ast_websocket_client_create_with_options(), webchan_call(), websocket_client_handshake(), websocket_client_handshake_get_response(), and websocket_proxy_handshake().

ast_websocket_server_add_protocol()

int AST_OPTIONAL_API_NAME() ast_websocket_server_add_protocol	(	struct ast_websocket_server *	server,
		const char *	name,
		ast_websocket_callback	callback
	)

Add a sub-protocol handler to the given server.

Parameters

server	The server to add the sub-protocol to
name	Name of the sub-protocol to register
callback	Callback called when a new connection requesting the sub-protocol is established

Return values

0	success
-1	if sub-protocol handler could not be registered

Since

12

Definition at line 295 of file res_http_websocket.c.

{
    struct ast_websocket_protocol *protocol;
 
    if (!server->protocols) {
        return -1;
    }
 
    protocol = ast_websocket_sub_protocol_alloc(name);
    if (!protocol) {
        return -1;
    }
    protocol->session_established = callback;
 
    if (ast_websocket_server_add_protocol2(server, protocol)) {
        ao2_ref(protocol, -1);
        return -1;
    }
 
    return 0;
}

References ao2_ref, ast_websocket_server_add_protocol2(), ast_websocket_sub_protocol_alloc(), callback(), name, ast_websocket_server::protocols, and ast_websocket_protocol::session_established.

Referenced by websocket_add_protocol_internal().

ast_websocket_server_add_protocol2()

int AST_OPTIONAL_API_NAME() ast_websocket_server_add_protocol2	(	struct ast_websocket_server *	server,
		struct ast_websocket_protocol *	protocol
	)

Add a sub-protocol handler to the given server.

Parameters

server	The server to add the sub-protocol to.
protocol	The sub-protocol to register. Note that this must be allocated using /ref ast_websocket_sub_protocol_alloc.

Note

This method is reference stealing. It will steal the reference to protocol on success.

Return values

0	success
-1	if sub-protocol handler could not be registered

Since

13.5.0

Definition at line 317 of file res_http_websocket.c.

{
    struct ast_websocket_protocol *existing;
 
    if (!server->protocols) {
        return -1;
    }
 
    if (protocol->version != AST_WEBSOCKET_PROTOCOL_VERSION) {
        ast_log(LOG_WARNING, "WebSocket could not register sub-protocol '%s': "
            "expected version '%u', got version '%u'\n",
            protocol->name, AST_WEBSOCKET_PROTOCOL_VERSION, protocol->version);
        return -1;
    }
 
    ao2_lock(server->protocols);
 
    /* Ensure a second protocol handler is not registered for the same protocol */
    existing = ao2_find(server->protocols, protocol->name, OBJ_KEY | OBJ_NOLOCK);
    if (existing) {
        ao2_ref(existing, -1);
        ao2_unlock(server->protocols);
        return -1;
    }
 
    ao2_link_flags(server->protocols, protocol, OBJ_NOLOCK);
    ao2_unlock(server->protocols);
 
    ast_debug(1, "WebSocket registered sub-protocol '%s'\n", protocol->name);
    ao2_ref(protocol, -1);
 
    return 0;
}

References ao2_find, ao2_link_flags, ao2_lock, ao2_ref, ao2_unlock, ast_debug, ast_log, AST_WEBSOCKET_PROTOCOL_VERSION, LOG_WARNING, OBJ_KEY, OBJ_NOLOCK, and ast_websocket_server::protocols.

Referenced by ari_websocket_load_module(), ast_websocket_add_protocol2(), ast_websocket_server_add_protocol(), and load_module().

ast_websocket_server_create()

struct ast_websocket_server *AST_OPTIONAL_API_NAME() ast_websocket_server_create

(

void

)

Creates a ast_websocket_server.

Returns

New ast_websocket_server instance

Return values

NULL

on error

Since

12

Definition at line 250 of file res_http_websocket.c.

{
    return websocket_server_create_impl();
}

References websocket_server_create_impl().

Referenced by ari_websocket_load_module(), and load_module().

ast_websocket_server_remove_protocol()

int AST_OPTIONAL_API_NAME() ast_websocket_server_remove_protocol	(	struct ast_websocket_server *	server,
		const char *	name,
		ast_websocket_callback	callback
	)

Remove a sub-protocol handler from the given server.

Parameters

server	The server to unregister the sub-protocol from
name	Name of the sub-protocol to unregister
callback	Callback that was previously registered with the sub-protocol

Return values

0	success
-1	if sub-protocol was not found or if callback did not match

Since

12

Definition at line 351 of file res_http_websocket.c.

{
    struct ast_websocket_protocol *protocol;
 
    if (!(protocol = ao2_find(server->protocols, name, OBJ_KEY))) {
        return -1;
    }
 
    if (protocol->session_established != callback) {
        ao2_ref(protocol, -1);
        return -1;
    }
 
    ao2_unlink(server->protocols, protocol);
    ao2_ref(protocol, -1);
 
    ast_debug(1, "WebSocket unregistered sub-protocol '%s'\n", name);
 
    return 0;
}

References ao2_find, ao2_ref, ao2_unlink, ast_debug, callback(), name, OBJ_KEY, ast_websocket_server::protocols, and ast_websocket_protocol::session_established.

Referenced by websocket_remove_protocol_internal().

ast_websocket_session_id()

const char *AST_OPTIONAL_API_NAME() ast_websocket_session_id

(

struct ast_websocket *

session

)

Get the session ID for a WebSocket session.

Returns

session id

Definition at line 701 of file res_http_websocket.c.

{
    return session->session_id;
}

References session.

Referenced by websocket_established_cb().

ast_websocket_set_nonblock()

int AST_OPTIONAL_API_NAME() ast_websocket_set_nonblock

(

struct ast_websocket *

session

)

Set the socket of a WebSocket session to be non-blocking.

Return values

0	on success
-1	on failure

Definition at line 687 of file res_http_websocket.c.

{
    ast_iostream_nonblock(session->stream);
    ast_iostream_set_exclusive_input(session->stream, 0);
    return 0;
}

References ast_iostream_nonblock(), ast_iostream_set_exclusive_input(), and session.

Referenced by session_update(), and websocket_cb().

ast_websocket_set_timeout()

int AST_OPTIONAL_API_NAME() ast_websocket_set_timeout	(	struct ast_websocket *	session,
		int	timeout
	)

Set the timeout on a non-blocking WebSocket session.

Since

11.11.0

12.4.0

Return values

0	on success
-1	on failure

Definition at line 694 of file res_http_websocket.c.

{
    session->timeout = timeout;
 
    return 0;
}

References session, and ast_websocket::timeout.

Referenced by session_update(), and websocket_cb().

ast_websocket_status_to_str()

const char *AST_OPTIONAL_API_NAME() ast_websocket_status_to_str

(

enum ast_websocket_status_code

code

)

Convert a websocket status code to a string.

Parameters

code	The code to convert

Returns

A string representation of the code

Definition at line 2162 of file res_http_websocket.c.

{
    int i;
 
    for (i = 0; i < ARRAY_LEN(websocket_status_map); i++) {
        if (websocket_status_map[i].code == code)
            return websocket_status_map[i].desc;
    }
 
    return "Unknown";
}

References ARRAY_LEN, status_map::code, status_map::desc, and websocket_status_map.

Referenced by _websocket_request_hangup(), websocket_close(), and websocket_handled_pong_or_close().

ast_websocket_sub_protocol_alloc()

struct ast_websocket_protocol *AST_OPTIONAL_API_NAME() ast_websocket_sub_protocol_alloc

(

const char *

name

)

Allocate a websocket sub-protocol instance.

Returns

An instance of ast_websocket_protocol on success

Return values

NULL

on error

Since

13.5.0

Definition at line 276 of file res_http_websocket.c.

{
    struct ast_websocket_protocol *protocol;
 
    protocol = ao2_alloc(sizeof(*protocol), protocol_destroy_fn);
    if (!protocol) {
        return NULL;
    }
 
    protocol->name = ast_strdup(name);
    if (!protocol->name) {
        ao2_ref(protocol, -1);
        return NULL;
    }
    protocol->version = AST_WEBSOCKET_PROTOCOL_VERSION;
 
    return protocol;
}

References ao2_alloc, ao2_ref, ast_strdup, AST_WEBSOCKET_PROTOCOL_VERSION, name, ast_websocket_protocol::name, NULL, protocol_destroy_fn(), and ast_websocket_protocol::version.

Referenced by ari_websocket_load_module(), ast_websocket_server_add_protocol(), and load_module().

ast_websocket_type_to_str()

const char * ast_websocket_type_to_str

(

enum ast_websocket_type

type

)

Definition at line 167 of file res_http_websocket.c.

{
    switch (type) {
    case AST_WS_TYPE_CLIENT_PERSISTENT:
        return "persistent";
    case AST_WS_TYPE_CLIENT_PER_CALL:
        return "per_call";
    case AST_WS_TYPE_CLIENT_PER_CALL_CONFIG:
        return "per_call_config";
    case AST_WS_TYPE_CLIENT:
        return "client";
    case AST_WS_TYPE_INBOUND:
        return "inbound";
    case AST_WS_TYPE_SERVER:
        return "server";
    case AST_WS_TYPE_ANY:
        return "any";
    default:
        return "unknown";
    }
}

References AST_WS_TYPE_ANY, AST_WS_TYPE_CLIENT, AST_WS_TYPE_CLIENT_PER_CALL, AST_WS_TYPE_CLIENT_PER_CALL_CONFIG, AST_WS_TYPE_CLIENT_PERSISTENT, AST_WS_TYPE_INBOUND, AST_WS_TYPE_SERVER, and type.

Referenced by session_cleanup().

ast_websocket_unref()

void AST_OPTIONAL_API_NAME() ast_websocket_unref

(

struct ast_websocket *

session

)

Decrease the reference count for a WebSocket session.

Parameters

session

Pointer to the WebSocket session

Definition at line 652 of file res_http_websocket.c.

{
    char *id = ast_strdupa(WS_SESSION_REMOTE(session));
    int refcount = session ? ao2_ref(session, 0) : 0;
    SCOPE_ENTER(2, "%s: Unreffing.  Refcount: %d\n", id, refcount);
 
    ao2_cleanup(session);
    SCOPE_EXIT("%s: Unreffed.  Refcount: %d\n", id, session ? refcount - 1 : 0);
}

References ao2_cleanup, ao2_ref, ast_strdupa, SCOPE_ENTER, SCOPE_EXIT, session, and WS_SESSION_REMOTE.

Referenced by incoming_ws_established_cb(), outbound_session_handler_thread(), session_dtor(), speech_test_server_cb(), transport_dtor(), webchan_hangup(), websocket_cb(), websocket_destroy(), websocket_destructor(), websocket_echo_callback(), and websocket_established_cb().

ast_websocket_uri_cb()

int AST_OPTIONAL_API_NAME() ast_websocket_uri_cb	(	struct ast_tcptls_session_instance *	ser,
		const struct ast_http_uri *	urih,
		const char *	uri,
		enum ast_http_method	method,
		struct ast_variable *	get_vars,
		struct ast_variable *	headers
	)

Callback suitable for use with a ast_http_uri.

Set the data field of the ast_http_uri to ast_websocket_server.

Since

12

Definition at line 980 of file res_http_websocket.c.

{
    struct ast_variable *v;
    const char *upgrade = NULL, *key = NULL, *key1 = NULL, *key2 = NULL, *protos = NULL;
    char *requested_protocols = NULL, *protocol = NULL;
    int version = 0, flags = 1;
    struct ast_websocket_protocol *protocol_handler = NULL;
    struct ast_websocket *session;
    struct ast_websocket_server *server;
 
    SCOPED_MODULE_USE(ast_module_info->self);
 
    /* Upgrade requests are only permitted on GET methods */
    if (method != AST_HTTP_GET) {
        ast_http_error(ser, 501, "Not Implemented", "Attempt to use unimplemented / unsupported method");
        return 0;
    }
 
    server = urih->data;
 
    /* Get the minimum headers required to satisfy our needs */
    for (v = headers; v; v = v->next) {
        if (!strcasecmp(v->name, "Upgrade")) {
            upgrade = v->value;
        } else if (!strcasecmp(v->name, "Sec-WebSocket-Key")) {
            key = v->value;
        } else if (!strcasecmp(v->name, "Sec-WebSocket-Key1")) {
            key1 = v->value;
        } else if (!strcasecmp(v->name, "Sec-WebSocket-Key2")) {
            key2 = v->value;
        } else if (!strcasecmp(v->name, "Sec-WebSocket-Protocol")) {
            protos = v->value;
        } else if (!strcasecmp(v->name, "Sec-WebSocket-Version")) {
            if (sscanf(v->value, "%30d", &version) != 1) {
                version = 0;
            }
        }
    }
 
    /* If this is not a websocket upgrade abort */
    if (!upgrade || strcasecmp(upgrade, "websocket")) {
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - did not request WebSocket\n",
            ast_sockaddr_stringify(&ser->remote_address));
        ast_http_error(ser, 426, "Upgrade Required", NULL);
        return 0;
    } else if (ast_strlen_zero(protos)) {
        /* If there's only a single protocol registered, and the
         * client doesn't specify what protocol it's using, go ahead
         * and accept the connection */
        protocol_handler = one_protocol(server);
        if (!protocol_handler) {
            /* Multiple registered subprotocols; client must specify */
            ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - no protocols requested\n",
                ast_sockaddr_stringify(&ser->remote_address));
            websocket_bad_request(ser);
            return 0;
        }
    } else if (key1 && key2) {
        /* Specification defined in http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76 and
         * http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00 -- not currently supported*/
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - unsupported version '00/76' chosen\n",
            ast_sockaddr_stringify(&ser->remote_address));
        websocket_bad_request(ser);
        return 0;
    }
 
    if (!protocol_handler && protos) {
        requested_protocols = ast_strdupa(protos);
        /* Iterate through the requested protocols trying to find one that we have a handler for */
        while (!protocol_handler && (protocol = strsep(&requested_protocols, ","))) {
            protocol_handler = ao2_find(server->protocols, ast_strip(protocol), OBJ_KEY);
        }
    }
 
    /* If no protocol handler exists bump this back to the requester */
    if (!protocol_handler) {
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - no protocols out of '%s' supported\n",
            ast_sockaddr_stringify(&ser->remote_address), protos);
        websocket_bad_request(ser);
        return 0;
    }
 
    /* Determine how to respond depending on the version */
    if (version == 7 || version == 8 || version == 13) {
        char base64[64];
 
        if (!key || strlen(key) + strlen(WEBSOCKET_GUID) + 1 > 8192) { /* no stack overflows please */
            websocket_bad_request(ser);
            ao2_ref(protocol_handler, -1);
            return 0;
        }
 
        if (ast_http_body_discard(ser)) {
            websocket_bad_request(ser);
            ao2_ref(protocol_handler, -1);
            return 0;
        }
 
        if (!(session = ao2_alloc(sizeof(*session) + AST_UUID_STR_LEN + 1, session_destroy_fn))) {
            ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted\n",
                ast_sockaddr_stringify(&ser->remote_address));
            websocket_bad_request(ser);
            ao2_ref(protocol_handler, -1);
            return 0;
        }
        session->timeout = AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT;
 
        /* Generate the session id */
        if (!ast_uuid_generate_str(session->session_id, sizeof(session->session_id))) {
            ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - failed to generate a session id\n",
                ast_sockaddr_stringify(&ser->remote_address));
            ast_http_error(ser, 500, "Internal Server Error", "Allocation failed");
            ao2_ref(protocol_handler, -1);
            return 0;
        }
 
        if (protocol_handler->session_attempted
            && protocol_handler->session_attempted(ser, get_vars, headers, session->session_id)) {
            ast_debug(3, "WebSocket connection from '%s' rejected by protocol handler '%s'\n",
                ast_sockaddr_stringify(&ser->remote_address), protocol_handler->name);
            websocket_bad_request(ser);
            ao2_ref(protocol_handler, -1);
            return 0;
        }
 
        /* RFC 6455, Section 4.1:
         *
         * 6. If the response includes a |Sec-WebSocket-Protocol| header
         *    field and this header field indicates the use of a
         *    subprotocol that was not present in the client's handshake
         *    (the server has indicated a subprotocol not requested by
         *    the client), the client MUST _Fail the WebSocket
         *    Connection_.
         */
        if (protocol) {
            ast_iostream_printf(ser->stream,
                "HTTP/1.1 101 Switching Protocols\r\n"
                "Upgrade: %s\r\n"
                "Connection: Upgrade\r\n"
                "Sec-WebSocket-Accept: %s\r\n"
                "Sec-WebSocket-Protocol: %s\r\n\r\n",
                upgrade,
                websocket_combine_key(key, base64, sizeof(base64)),
                protocol);
        } else {
            ast_iostream_printf(ser->stream,
                "HTTP/1.1 101 Switching Protocols\r\n"
                "Upgrade: %s\r\n"
                "Connection: Upgrade\r\n"
                "Sec-WebSocket-Accept: %s\r\n\r\n",
                upgrade,
                websocket_combine_key(key, base64, sizeof(base64)));
        }
    } else {
 
        /* Specification defined in http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75 or completely unknown */
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - unsupported version '%d' chosen\n",
            ast_sockaddr_stringify(&ser->remote_address), version ? version : 75);
        websocket_bad_request(ser);
        ao2_ref(protocol_handler, -1);
        return 0;
    }
 
    /* Enable keepalive on all sessions so the underlying user does not have to */
    if (setsockopt(ast_iostream_get_fd(ser->stream), SOL_SOCKET, SO_KEEPALIVE, &flags, sizeof(flags))) {
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - failed to enable keepalive\n",
            ast_sockaddr_stringify(&ser->remote_address));
        websocket_bad_request(ser);
        ao2_ref(session, -1);
        ao2_ref(protocol_handler, -1);
        return 0;
    }
 
    /* Get our local address for the connected socket */
    if (ast_getsockname(ast_iostream_get_fd(ser->stream), &session->local_address)) {
        ast_log(LOG_WARNING, "WebSocket connection from '%s' could not be accepted - failed to get local address\n",
            ast_sockaddr_stringify(&ser->remote_address));
        websocket_bad_request(ser);
        ao2_ref(session, -1);
        ao2_ref(protocol_handler, -1);
        return 0;
    }
 
    ast_debug(3, "WebSocket connection from '%s' for protocol '%s' accepted using version '%d'\n", ast_sockaddr_stringify(&ser->remote_address), protocol ? : "", version);
 
    /* Populate the session with all the needed details */
    session->stream = ser->stream;
    ast_sockaddr_copy(&session->remote_address, &ser->remote_address);
    session->opcode = -1;
    session->reconstruct = DEFAULT_RECONSTRUCTION_CEILING;
    session->secure = ast_iostream_get_ssl(ser->stream) ? 1 : 0;
 
    /* Give up ownership of the socket and pass it to the protocol handler */
    ast_iostream_set_exclusive_input(session->stream, 0);
    protocol_handler->session_established(session, get_vars, headers);
    ao2_ref(protocol_handler, -1);
 
    /*
     * By dropping the stream from the session the connection
     * won't get closed when the HTTP server cleans up because we
     * passed the connection to the protocol handler.
     */
    ser->stream = NULL;
 
    return 0;
}

References ao2_alloc, ao2_find, ao2_ref, ast_debug, AST_DEFAULT_WEBSOCKET_WRITE_TIMEOUT, ast_getsockname(), ast_http_body_discard(), ast_http_error(), AST_HTTP_GET, ast_iostream_get_fd(), ast_iostream_get_ssl(), ast_iostream_printf(), ast_iostream_set_exclusive_input(), ast_log, ast_sockaddr_copy(), ast_sockaddr_stringify(), ast_strdupa, ast_strip(), ast_strlen_zero(), ast_uuid_generate_str(), AST_UUID_STR_LEN, base64, ast_http_uri::data, DEFAULT_RECONSTRUCTION_CEILING, LOG_WARNING, method, ast_variable::name, ast_websocket_protocol::name, ast_variable::next, NULL, OBJ_KEY, one_protocol(), ast_websocket_server::protocols, ast_tcptls_session_instance::remote_address, SCOPED_MODULE_USE, ast_module_info::self, session, ast_websocket_protocol::session_attempted, session_destroy_fn(), ast_websocket_protocol::session_established, ast_tcptls_session_instance::stream, strsep(), ast_variable::value, version, websocket_bad_request(), websocket_combine_key(), and WEBSOCKET_GUID.

Referenced by ari_handle_websocket(), and incoming_ws_http_callback().

ast_websocket_wait_for_input()

int AST_OPTIONAL_API_NAME() ast_websocket_wait_for_input	(	struct ast_websocket *	session,
		int	timeout
	)

Wait for the WebSocket session to be ready to be read.

Since

16.8.0

17.2.0

Parameters

session	Pointer to the WebSocket session
timeout	the number of milliseconds to wait

Return values

-1	if error occurred
0	if the timeout expired
1	if the WebSocket session is ready for reading

Definition at line 667 of file res_http_websocket.c.

{
    return session->closing ? -1 : ast_iostream_wait_for_input(session->stream, timeout);
}

References ast_iostream_wait_for_input(), session, and ast_websocket::timeout.

Referenced by speech_test_server_cb(), websocket_cb(), websocket_echo_callback(), and websocket_read().

ast_websocket_write()

int AST_OPTIONAL_API_NAME() ast_websocket_write	(	struct ast_websocket *	session,
		enum ast_websocket_opcode	opcode,
		char *	payload,
		uint64_t	payload_size
	)

Construct and transmit a WebSocket frame.

Parameters

session	Pointer to the WebSocket session
opcode	WebSocket operation code to place in the frame
payload	Optional pointer to a payload to add to the frame
payload_size	Length of the payload (0 if no payload)

Return values

0	if successfully written
-1	if error occurred

Construct and transmit a WebSocket frame.

Definition at line 563 of file res_http_websocket.c.

{
    size_t header_size = 2; /* The minimum size of a websocket frame is 2 bytes */
    char *frame;
    uint64_t length;
    uint64_t frame_size;
    SCOPE_ENTER(4, "%s: Opcode: %s Length: %"PRIu64"\n",
        WS_SESSION_REMOTE(session), websocket_opcode2str(opcode), payload_size);
 
    if (payload_size < 126) {
        length = payload_size;
    } else if (payload_size < (1 << 16)) {
        length = 126;
        /* We need an additional 2 bytes to store the extended length */
        header_size += 2;
    } else {
        length = 127;
        /* We need an additional 8 bytes to store the really really extended length */
        header_size += 8;
    }
 
    if (session->client) {
        /* Additional 4 bytes for the client masking key */
        header_size += 4;
    }
 
    frame_size = header_size + payload_size;
 
    frame = ast_alloca(frame_size + 1);
    memset(frame, 0, frame_size + 1);
 
    frame[0] = opcode | 0x80;
    frame[1] = length;
 
    /* Use the additional available bytes to store the length */
    if (length == 126) {
        put_unaligned_uint16(&frame[2], htons(payload_size));
    } else if (length == 127) {
        put_unaligned_uint64(&frame[2], htonll(payload_size));
    }
 
    memcpy(&frame[header_size], payload, payload_size);
 
    websocket_mask_payload(session, frame, &frame[header_size], payload_size);
 
    ao2_lock(session);
    if (session->closing) {
        ao2_unlock(session);
        SCOPE_EXIT_RTN_VALUE(-1, "%s: Websocket already closing\n", WS_SESSION_REMOTE(session));
    }
 
    ast_iostream_set_timeout_sequence(session->stream, ast_tvnow(), session->timeout);
    if (ast_iostream_write(session->stream, frame, frame_size) != frame_size) {
        ao2_unlock(session);
        /* 1011 - server terminating connection due to not being able to fulfill the request */
        ast_trace(-1, "%s: Closing WS with 1011 because we can't fulfill a write request\n",
            WS_SESSION_REMOTE(session));
        websocket_close(session, 1011, 1);
        SCOPE_EXIT_RTN_VALUE(-1, "%s: Closed WS with 1011 because we couldn't fulfill a write request\n",
            WS_SESSION_REMOTE(session));
    }
 
    ast_iostream_set_timeout_disable(session->stream);
    ao2_unlock(session);
 
    SCOPE_EXIT_RTN_VALUE(0, "%s: Wrote opcode: %s length: %"PRIu64"\n",
        WS_SESSION_REMOTE(session), websocket_opcode2str(opcode), payload_size);
}

References ao2_lock, ao2_unlock, ast_alloca, ast_iostream_set_timeout_disable(), ast_iostream_set_timeout_sequence(), ast_iostream_write(), ast_trace, ast_tvnow(), frame_size, htonll(), ast_websocket::opcode, ast_websocket::payload, put_unaligned_uint16(), put_unaligned_uint64(), SCOPE_ENTER, SCOPE_EXIT_RTN_VALUE, session, websocket_close(), websocket_mask_payload(), websocket_opcode2str(), and WS_SESSION_REMOTE.

Referenced by ast_websocket_read(), ast_websocket_write_string(), ping_scheduler_callback(), speech_test_server_cb(), webchan_write(), websocket_echo_callback(), websocket_write(), and ws_send_msg().

ast_websocket_write_string()

int AST_OPTIONAL_API_NAME() ast_websocket_write_string	(	struct ast_websocket *	ws,
		const char *	buf
	)

Construct and transmit a WebSocket frame containing string data.

Parameters

ws	pointer to the websocket
buf	string data to write to socket

Return values

0	if successfully written
-1	if error occurred

Definition at line 2093 of file res_http_websocket.c.

{
    uint64_t len = strlen(buf);
 
    ast_debug(3, "Writing websocket string of length %" PRIu64 "\n", len);
 
    /* We do not pass strlen(buf) to ast_websocket_write() directly because the
     * size_t returned by strlen() may not require the same storage size
     * as the uint64_t that ast_websocket_write() uses. This normally
     * would not cause a problem, but since ast_websocket_write() uses
     * the optional API, this function call goes through a series of macros
     * that may cause a 32-bit to 64-bit conversion to go awry.
     */
    return ast_websocket_write(ws, AST_WEBSOCKET_OPCODE_TEXT,
                   (char *)buf, len);
}

References ast_debug, AST_WEBSOCKET_OPCODE_TEXT, ast_websocket_write(), buf, and len().

Referenced by AST_TEST_DEFINE(), dequeue_frame(), session_write(), and speech_test_server_handle_request().