Asterisk - The Open Source Telephony Project
21.4.1
|
Support for WebSocket connections within the Asterisk HTTP server and client WebSocket connections to a server. More...
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_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. More... | |
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. More... | |
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 } |
WebSocket operation codes. More... | |
enum | ast_websocket_result { 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 } |
Result code for a websocket client. | |
Functions | |
static void | __dtor__ast_websocket_add_protocol (void) |
static void | __dtor__ast_websocket_add_protocol2 (void) |
static void | __dtor__ast_websocket_client_accept_protocol (void) |
static void | __dtor__ast_websocket_client_create (void) |
static void | __dtor__ast_websocket_client_create_with_options (void) |
static void | __dtor__ast_websocket_close (void) |
static void | __dtor__ast_websocket_fd (void) |
static void | __dtor__ast_websocket_is_secure (void) |
static void | __dtor__ast_websocket_local_address (void) |
static void | __dtor__ast_websocket_read (void) |
static void | __dtor__ast_websocket_read_string (void) |
static void | __dtor__ast_websocket_reconstruct_disable (void) |
static void | __dtor__ast_websocket_reconstruct_enable (void) |
static void | __dtor__ast_websocket_ref (void) |
static void | __dtor__ast_websocket_remote_address (void) |
static void | __dtor__ast_websocket_remove_protocol (void) |
static void | __dtor__ast_websocket_server_add_protocol (void) |
static void | __dtor__ast_websocket_server_add_protocol2 (void) |
static void | __dtor__ast_websocket_server_create (void) |
static void | __dtor__ast_websocket_server_remove_protocol (void) |
static void | __dtor__ast_websocket_session_id (void) |
static void | __dtor__ast_websocket_set_nonblock (void) |
static void | __dtor__ast_websocket_set_timeout (void) |
static void | __dtor__ast_websocket_sub_protocol_alloc (void) |
static void | __dtor__ast_websocket_unref (void) |
static void | __dtor__ast_websocket_uri_cb (void) |
static void | __dtor__ast_websocket_wait_for_input (void) |
static void | __dtor__ast_websocket_write (void) |
static void | __dtor__ast_websocket_write_string (void) |
static void | __init__ast_websocket_add_protocol (void) |
static void | __init__ast_websocket_add_protocol2 (void) |
static void | __init__ast_websocket_client_accept_protocol (void) |
static void | __init__ast_websocket_client_create (void) |
static void | __init__ast_websocket_client_create_with_options (void) |
static void | __init__ast_websocket_close (void) |
static void | __init__ast_websocket_fd (void) |
static void | __init__ast_websocket_is_secure (void) |
static void | __init__ast_websocket_local_address (void) |
static void | __init__ast_websocket_read (void) |
static void | __init__ast_websocket_read_string (void) |
static void | __init__ast_websocket_reconstruct_disable (void) |
static void | __init__ast_websocket_reconstruct_enable (void) |
static void | __init__ast_websocket_ref (void) |
static void | __init__ast_websocket_remote_address (void) |
static void | __init__ast_websocket_remove_protocol (void) |
static void | __init__ast_websocket_server_add_protocol (void) |
static void | __init__ast_websocket_server_add_protocol2 (void) |
static void | __init__ast_websocket_server_create (void) |
static void | __init__ast_websocket_server_remove_protocol (void) |
static void | __init__ast_websocket_session_id (void) |
static void | __init__ast_websocket_set_nonblock (void) |
static void | __init__ast_websocket_set_timeout (void) |
static void | __init__ast_websocket_sub_protocol_alloc (void) |
static void | __init__ast_websocket_unref (void) |
static void | __init__ast_websocket_uri_cb (void) |
static void | __init__ast_websocket_wait_for_input (void) |
static void | __init__ast_websocket_write (void) |
static void | __init__ast_websocket_write_string (void) |
static int | __stub__ast_websocket_add_protocol (const char *name, ast_websocket_callback callback) |
Add a sub-protocol handler to the default /ws server. More... | |
static int | __stub__ast_websocket_add_protocol2 (struct ast_websocket_protocol *protocol) |
Add a sub-protocol handler to the default /ws server. More... | |
static const char * | __stub__ast_websocket_client_accept_protocol (struct ast_websocket *ws) |
Retrieve the server accepted sub-protocol on the client. More... | |
static struct ast_websocket * | __stub__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. More... | |
static struct ast_websocket * | __stub__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. More... | |
static int | __stub__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. More... | |
static int | __stub__ast_websocket_fd (struct ast_websocket *session) |
Get the file descriptor for a WebSocket session. More... | |
static int | __stub__ast_websocket_is_secure (struct ast_websocket *session) |
Get whether the WebSocket session is using a secure transport or not. More... | |
static struct ast_sockaddr * | __stub__ast_websocket_local_address (struct ast_websocket *session) |
Get the local address for a WebSocket connection session. More... | |
static int | __stub__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. More... | |
static int | __stub__ast_websocket_read_string (struct ast_websocket *ws, char **buf) |
Read a WebSocket frame containing string data. More... | |
static void | __stub__ast_websocket_reconstruct_disable (struct ast_websocket *session) |
Disable multi-frame reconstruction. More... | |
static void | __stub__ast_websocket_reconstruct_enable (struct ast_websocket *session, size_t bytes) |
Enable multi-frame reconstruction up to a certain number of bytes. More... | |
static void | __stub__ast_websocket_ref (struct ast_websocket *session) |
Increase the reference count for a WebSocket session. More... | |
static struct ast_sockaddr * | __stub__ast_websocket_remote_address (struct ast_websocket *session) |
Get the remote address for a WebSocket connected session. More... | |
static int | __stub__ast_websocket_remove_protocol (const char *name, ast_websocket_callback callback) |
Remove a sub-protocol handler from the default /ws server. More... | |
static int | __stub__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. More... | |
static int | __stub__ast_websocket_server_add_protocol2 (struct ast_websocket_server *server, struct ast_websocket_protocol *protocol) |
Add a sub-protocol handler to the given server. More... | |
static struct ast_websocket_server * | __stub__ast_websocket_server_create (void) |
Creates a ast_websocket_server. More... | |
static int | __stub__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. More... | |
static const char * | __stub__ast_websocket_session_id (struct ast_websocket *session) |
Get the session ID for a WebSocket session. More... | |
static int | __stub__ast_websocket_set_nonblock (struct ast_websocket *session) |
Set the socket of a WebSocket session to be non-blocking. More... | |
static int | __stub__ast_websocket_set_timeout (struct ast_websocket *session, int timeout) |
Set the timeout on a non-blocking WebSocket session. More... | |
static struct ast_websocket_protocol * | __stub__ast_websocket_sub_protocol_alloc (const char *name) |
Allocate a websocket sub-protocol instance. More... | |
static void | __stub__ast_websocket_unref (struct ast_websocket *session) |
Decrease the reference count for a WebSocket session. More... | |
static int | __stub__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. More... | |
static int | __stub__ast_websocket_wait_for_input (struct ast_websocket *session, int timeout) |
Wait for the WebSocket session to be ready to be read. More... | |
static int | __stub__ast_websocket_write (struct ast_websocket *session, enum ast_websocket_opcode opcode, char *payload, uint64_t payload_size) |
Construct and transmit a WebSocket frame. More... | |
static int | __stub__ast_websocket_write_string (struct ast_websocket *ws, const char *buf) |
Construct and transmit a WebSocket frame containing string data. More... | |
static | typeof (__stub__ast_websocket_server_create)*ast_websocket_server_create |
static | typeof (__stub__ast_websocket_uri_cb)*ast_websocket_uri_cb |
static | typeof (__stub__ast_websocket_sub_protocol_alloc)*ast_websocket_sub_protocol_alloc |
static | typeof (__stub__ast_websocket_add_protocol)*ast_websocket_add_protocol |
static | typeof (__stub__ast_websocket_add_protocol2)*ast_websocket_add_protocol2 |
static | typeof (__stub__ast_websocket_remove_protocol)*ast_websocket_remove_protocol |
static | typeof (__stub__ast_websocket_server_add_protocol)*ast_websocket_server_add_protocol |
static | typeof (__stub__ast_websocket_server_add_protocol2)*ast_websocket_server_add_protocol2 |
static | typeof (__stub__ast_websocket_server_remove_protocol)*ast_websocket_server_remove_protocol |
static | typeof (__stub__ast_websocket_read)*ast_websocket_read |
static | typeof (__stub__ast_websocket_read_string)*ast_websocket_read_string |
static | typeof (__stub__ast_websocket_write)*ast_websocket_write |
static | typeof (__stub__ast_websocket_write_string)*ast_websocket_write_string |
static | typeof (__stub__ast_websocket_close)*ast_websocket_close |
static | typeof (__stub__ast_websocket_reconstruct_enable)*ast_websocket_reconstruct_enable |
static | typeof (__stub__ast_websocket_reconstruct_disable)*ast_websocket_reconstruct_disable |
static | typeof (__stub__ast_websocket_ref)*ast_websocket_ref |
static | typeof (__stub__ast_websocket_unref)*ast_websocket_unref |
static | typeof (__stub__ast_websocket_fd)*ast_websocket_fd |
static | typeof (__stub__ast_websocket_wait_for_input)*ast_websocket_wait_for_input |
static | typeof (__stub__ast_websocket_remote_address)*ast_websocket_remote_address |
static | typeof (__stub__ast_websocket_local_address)*ast_websocket_local_address |
static | typeof (__stub__ast_websocket_is_secure)*ast_websocket_is_secure |
static | typeof (__stub__ast_websocket_set_nonblock)*ast_websocket_set_nonblock |
static | typeof (__stub__ast_websocket_session_id)*ast_websocket_session_id |
static | typeof (__stub__ast_websocket_client_create)*ast_websocket_client_create |
static | typeof (__stub__ast_websocket_client_create_with_options)*ast_websocket_client_create_with_options |
static | typeof (__stub__ast_websocket_client_accept_protocol)*ast_websocket_client_accept_protocol |
static | typeof (__stub__ast_websocket_set_timeout)*ast_websocket_set_timeout |
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
Definition in file http_websocket.h.
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.
session | A WebSocket session structure |
parameters | Parameters extracted from the request URI |
headers | Headers included in the request |
Definition at line 101 of file http_websocket.h.
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.
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. |
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. |
Definition at line 88 of file http_websocket.h.
enum ast_websocket_opcode |
WebSocket operation codes.
Definition at line 51 of file http_websocket.h.
|
static |
Add a sub-protocol handler to the default /ws server.
name | Name of the sub-protocol to register |
callback | Callback called when a new connection requesting the sub-protocol is established |
0 | success |
-1 | if sub-protocol handler could not be registered |
Definition at line 164 of file http_websocket.h.
|
static |
Add a sub-protocol handler to the default /ws server.
protocol | The sub-protocol to register. Note that this must be allocated using /ref ast_websocket_sub_protocol_alloc. |
protocol
on success.0 | success |
-1 | if sub-protocol handler could not be registered |
Definition at line 179 of file http_websocket.h.
|
static |
Retrieve the server accepted sub-protocol on the client.
ws | the websocket client |
Definition at line 500 of file http_websocket.h.
|
static |
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.
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.
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 |
NULL | if object could not be created or connected |
Definition at line 441 of file http_websocket.h.
|
static |
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.
options | Websocket client options |
result | result code set on client failure |
NULL | if object could not be created or connected |
Definition at line 490 of file http_websocket.h.
|
static |
Close a WebSocket session by sending a message with the CLOSE opcode and an optional code.
session | Pointer to the WebSocket session |
reason | Reason code for closing the session as defined in the RFC |
0 | if successfully written |
-1 | if error occurred |
Definition at line 299 of file http_websocket.h.
|
static |
Get the file descriptor for a WebSocket session.
Definition at line 341 of file http_websocket.h.
|
static |
Get whether the WebSocket session is using a secure transport or not.
0 | if unsecure |
1 | if secure |
Definition at line 379 of file http_websocket.h.
|
static |
Get the local address for a WebSocket connection session.
Definition at line 371 of file http_websocket.h.
|
static |
Read a WebSocket frame and handle it.
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 |
-1 | on error |
0 | on success |
Definition at line 248 of file http_websocket.h.
|
static |
Read a WebSocket frame containing string data.
ws | pointer to the websocket |
buf | string buffer to populate with data read from socket |
-1 | on error |
Definition at line 264 of file http_websocket.h.
|
static |
Disable multi-frame reconstruction.
session | Pointer to the WebSocket session |
Definition at line 318 of file http_websocket.h.
|
static |
Enable multi-frame reconstruction up to a certain number of bytes.
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 308 of file http_websocket.h.
|
static |
Increase the reference count for a WebSocket session.
session | Pointer to the WebSocket session |
Definition at line 325 of file http_websocket.h.
|
static |
Get the remote address for a WebSocket connected session.
Definition at line 362 of file http_websocket.h.
|
static |
Remove a sub-protocol handler from the default /ws server.
name | Name of the sub-protocol to unregister |
callback | Session Established callback that was previously registered with the sub-protocol |
0 | success |
-1 | if sub-protocol was not found or if callback did not match |
Definition at line 190 of file http_websocket.h.
|
static |
Add a sub-protocol handler to the given server.
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 |
0 | success |
-1 | if sub-protocol handler could not be registered |
Definition at line 203 of file http_websocket.h.
|
static |
Add a sub-protocol handler to the given server.
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. |
protocol
on success.0 | success |
-1 | if sub-protocol handler could not be registered |
Definition at line 219 of file http_websocket.h.
|
static |
Creates a ast_websocket_server.
NULL | on error |
Definition at line 136 of file http_websocket.h.
|
static |
Remove a sub-protocol handler from the given server.
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 |
0 | success |
-1 | if sub-protocol was not found or if callback did not match |
Definition at line 232 of file http_websocket.h.
|
static |
Get the session ID for a WebSocket session.
Definition at line 394 of file http_websocket.h.
|
static |
Set the socket of a WebSocket session to be non-blocking.
0 | on success |
-1 | on failure |
Definition at line 387 of file http_websocket.h.
|
static |
Set the timeout on a non-blocking WebSocket session.
0 | on success |
-1 | on failure |
Definition at line 511 of file http_websocket.h.
|
static |
Allocate a websocket sub-protocol instance.
NULL | on error |
Definition at line 153 of file http_websocket.h.
|
static |
Decrease the reference count for a WebSocket session.
session | Pointer to the WebSocket session |
Definition at line 332 of file http_websocket.h.
|
static |
Callback suitable for use with a ast_http_uri.
Set the data field of the ast_http_uri to ast_websocket_server.
Definition at line 144 of file http_websocket.h.
|
static |
Wait for the WebSocket session to be ready to be read.
session | Pointer to the WebSocket session |
timeout | the number of milliseconds to wait |
-1 | if error occurred |
0 | if the timeout expired |
1 | if the WebSocket session is ready for reading |
Definition at line 355 of file http_websocket.h.
|
static |
Construct and transmit a WebSocket frame.
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) |
0 | if successfully written |
-1 | if error occurred |
Definition at line 277 of file http_websocket.h.
|
static |
Construct and transmit a WebSocket frame containing string data.
ws | pointer to the websocket |
buf | string data to write to socket |
0 | if successfully written |
-1 | if error occurred |
Definition at line 289 of file http_websocket.h.