websocket_client.h File Reference

#include "asterisk/http_websocket.h"
#include "asterisk/sorcery.h"

Include dependency graph for websocket_client.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

Macros
#define	AST_WS_CLIENT_FIELD_USER_START   24

Enumerations
enum	ast_ws_client_fields {   AST_WS_CLIENT_FIELD_NONE = 0 , AST_WS_CLIENT_FIELD_URI = (1 << 0) , AST_WS_CLIENT_FIELD_PROTOCOLS = (1 << 1) , AST_WS_CLIENT_FIELD_USERNAME = (1 << 3) ,   AST_WS_CLIENT_FIELD_PASSWORD = (1 << 4) , AST_WS_CLIENT_FIELD_TLS_ENABLED = (1 << 7) , AST_WS_CLIENT_FIELD_CA_LIST_FILE = (1 << 8) , AST_WS_CLIENT_FIELD_CA_LIST_PATH = (1 << 9) ,   AST_WS_CLIENT_FIELD_CERT_FILE = (1 << 10) , AST_WS_CLIENT_FIELD_PRIV_KEY_FILE = (1 << 11) , AST_WS_CLIENT_FIELD_CONNECTION_TYPE = (1 << 13) , AST_WS_CLIENT_FIELD_RECONNECT_INTERVAL = (1 << 14) ,   AST_WS_CLIENT_FIELD_RECONNECT_ATTEMPTS = (1 << 15) , AST_WS_CLIENT_FIELD_CONNECTION_TIMEOUT = (1 << 16) , AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT = (1 << 17) , AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME = (1 << 18) ,   AST_WS_CLIENT_NEEDS_RECONNECT }

Functions
struct ast_websocket *	ast_websocket_client_connect (struct ast_websocket_client *wc, void *lock_obj, const char *display_name, enum ast_websocket_result *result)
	Connect to a websocket server using the configured authentication, retry and TLS options. More...
enum ast_ws_client_fields	ast_websocket_client_get_field_diff (struct ast_websocket_client *old_wc, struct ast_websocket_client *new_wc)
	Detect changes between two websocket client configurations. More...
int	ast_websocket_client_observer_add (const struct ast_sorcery_observer *callbacks)
	Add sorcery observers for websocket client events. More...
void	ast_websocket_client_observer_remove (const struct ast_sorcery_observer *callbacks)
	Remove sorcery observers for websocket client events. More...
int	ast_websocket_client_reload (void)
	Force res_websocket_client to reload its configuration. More...
struct ao2_container *	ast_websocket_client_retrieve_all (void)
	Retrieve a container of all websocket client objects. More...
struct ast_websocket_client *	ast_websocket_client_retrieve_by_id (const char *id)
	Retrieve a websocket client object by ID. More...

Macro Definition Documentation

AST_WS_CLIENT_FIELD_USER_START

#define AST_WS_CLIENT_FIELD_USER_START   24

Definition at line 54 of file websocket_client.h.

Enumeration Type Documentation

ast_ws_client_fields

enum ast_ws_client_fields

Enumerator
AST_WS_CLIENT_FIELD_NONE
AST_WS_CLIENT_FIELD_URI
AST_WS_CLIENT_FIELD_PROTOCOLS
AST_WS_CLIENT_FIELD_USERNAME
AST_WS_CLIENT_FIELD_PASSWORD
AST_WS_CLIENT_FIELD_TLS_ENABLED
AST_WS_CLIENT_FIELD_CA_LIST_FILE
AST_WS_CLIENT_FIELD_CA_LIST_PATH
AST_WS_CLIENT_FIELD_CERT_FILE
AST_WS_CLIENT_FIELD_PRIV_KEY_FILE
AST_WS_CLIENT_FIELD_CONNECTION_TYPE
AST_WS_CLIENT_FIELD_RECONNECT_INTERVAL
AST_WS_CLIENT_FIELD_RECONNECT_ATTEMPTS
AST_WS_CLIENT_FIELD_CONNECTION_TIMEOUT
AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT
AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME
AST_WS_CLIENT_NEEDS_RECONNECT

Definition at line 25 of file websocket_client.h.

                          {
    AST_WS_CLIENT_FIELD_NONE =                   0,
    AST_WS_CLIENT_FIELD_URI =                    (1 << 0),
    AST_WS_CLIENT_FIELD_PROTOCOLS =              (1 << 1),
    AST_WS_CLIENT_FIELD_USERNAME =               (1 << 3),
    AST_WS_CLIENT_FIELD_PASSWORD =               (1 << 4),
    AST_WS_CLIENT_FIELD_TLS_ENABLED =            (1 << 7),
    AST_WS_CLIENT_FIELD_CA_LIST_FILE =           (1 << 8),
    AST_WS_CLIENT_FIELD_CA_LIST_PATH =           (1 << 9),
    AST_WS_CLIENT_FIELD_CERT_FILE =              (1 << 10),
    AST_WS_CLIENT_FIELD_PRIV_KEY_FILE =          (1 << 11),
    AST_WS_CLIENT_FIELD_CONNECTION_TYPE =        (1 << 13),
    AST_WS_CLIENT_FIELD_RECONNECT_INTERVAL =     (1 << 14),
    AST_WS_CLIENT_FIELD_RECONNECT_ATTEMPTS =     (1 << 15),
    AST_WS_CLIENT_FIELD_CONNECTION_TIMEOUT =     (1 << 16),
    AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT =     (1 << 17),
    AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME = (1 << 18),
    AST_WS_CLIENT_NEEDS_RECONNECT = AST_WS_CLIENT_FIELD_URI | AST_WS_CLIENT_FIELD_PROTOCOLS
        | AST_WS_CLIENT_FIELD_CONNECTION_TYPE
        | AST_WS_CLIENT_FIELD_USERNAME | AST_WS_CLIENT_FIELD_PASSWORD
        | AST_WS_CLIENT_FIELD_TLS_ENABLED | AST_WS_CLIENT_FIELD_CA_LIST_FILE
        | AST_WS_CLIENT_FIELD_CA_LIST_PATH | AST_WS_CLIENT_FIELD_CERT_FILE
        | AST_WS_CLIENT_FIELD_PRIV_KEY_FILE | AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT
        | AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME,
};

Function Documentation

ast_websocket_client_connect()

struct ast_websocket * ast_websocket_client_connect	(	struct ast_websocket_client *	wc,
		void *	lock_obj,
		const char *	display_name,
		enum ast_websocket_result *	result
	)

Connect to a websocket server using the configured authentication, retry and TLS options.

Parameters

wc	A pointer to the ast_websocket_structure
lock_obj	A pointer to an ao2 object to lock while the connection is being attempted or NULL if no locking is needed.
display_name	An id string to use for logging messages. If NULL or empty the connection's ID will be used.
result	A pointer to an enum ast_websocket_result to store the result of the connection attempt.

Returns

A pointer to the ast_websocket structure on success, or NULL on failure.

Definition at line 240 of file res_websocket_client.c.

{
    int reconnect_counter = wc->reconnect_attempts;
 
    if (ast_strlen_zero(display_name)) {
        display_name = ast_sorcery_object_get_id(wc);
    }
 
    while (1) {
        struct ast_websocket *astws = NULL;
        struct ast_websocket_client_options options = {
            .uri = wc->uri,
            .protocols = wc->protocols,
            .username = wc->username,
            .password = wc->password,
            .timeout = wc->connect_timeout,
            .suppress_connection_msgs = 1,
            .tls_cfg = NULL,
        };
 
        if (lock_obj) {
            ao2_lock(lock_obj);
        }
 
        if (wc->tls_enabled) {
            /*
             * tls_cfg and its contents are freed automatically
             * by res_http_websocket when the connection ends.
             * We create it even if tls is not enabled to we can
             * suppress connection error messages and print our own.
             */
            options.tls_cfg = ast_calloc(1, sizeof(*options.tls_cfg));
            if (!options.tls_cfg) {
                if (lock_obj) {
                    ao2_unlock(lock_obj);
                }
                return NULL;
            }
            /* TLS options */
            options.tls_cfg->enabled = wc->tls_enabled;
            options.tls_cfg->cafile = ast_strdup(wc->ca_list_file);
            options.tls_cfg->capath = ast_strdup(wc->ca_list_path);
            options.tls_cfg->certfile = ast_strdup(wc->cert_file);
            options.tls_cfg->pvtfile = ast_strdup(wc->priv_key_file);
            ast_set2_flag(&options.tls_cfg->flags, !wc->verify_server_cert, AST_SSL_DONT_VERIFY_SERVER);
            ast_set2_flag(&options.tls_cfg->flags, !wc->verify_server_hostname, AST_SSL_IGNORE_COMMON_NAME);
        }
 
        astws = ast_websocket_client_create_with_options(&options, result);
        if (astws && *result == WS_OK) {
            if (lock_obj) {
                ao2_unlock(lock_obj);
            }
            return astws;
        }
 
        reconnect_counter--;
        if (reconnect_counter <= 0) {
            if (wc->connection_type == AST_WS_TYPE_CLIENT_PERSISTENT) {
                ast_log(LOG_WARNING,
                    "%s: Websocket connection to %s failed after %d tries: %s%s%s%s.  Retrying in %d ms.\n",
                    display_name,
                    wc->uri,
                    wc->reconnect_attempts,
                    ast_websocket_result_to_str(*result),
                    errno ? " (" : "",
                    errno ? strerror(errno) : "",
                    errno ? ")" : "",
                    wc->reconnect_interval
                );
            } else {
                ast_log(LOG_WARNING,
                    "%s: Websocket connection to %s failed after %d tries: %s%s%s%s.  Hanging up after exhausting retries.\n",
                    display_name,
                    wc->uri,
                    wc->reconnect_attempts,
                    ast_websocket_result_to_str(*result),
                    errno ? " (" : "",
                    errno ? strerror(errno) : "",
                    errno ? ")" : ""
                );
            }
            break;
        }
 
        if (lock_obj) {
            ao2_lock(lock_obj);
        }
        usleep(wc->reconnect_interval * 1000);
    }
 
    return NULL;
}

References ao2_lock, ao2_unlock, ast_calloc, ast_log, ast_set2_flag, ast_sorcery_object_get_id(), AST_SSL_DONT_VERIFY_SERVER, AST_SSL_IGNORE_COMMON_NAME, ast_strdup, ast_strlen_zero(), ast_websocket_client_create_with_options(), ast_websocket_result_to_str(), AST_WS_TYPE_CLIENT_PERSISTENT, ast_websocket_client::ca_list_file, ast_websocket_client::ca_list_path, ast_websocket_client::cert_file, ast_websocket_client::connect_timeout, ast_websocket_client::connection_type, errno, LOG_WARNING, NULL, options, ast_websocket_client::password, ast_websocket_client::priv_key_file, ast_websocket_client::protocols, ast_websocket_client::reconnect_attempts, ast_websocket_client::reconnect_interval, result, ast_websocket_client::tls_enabled, ast_websocket_client::uri, ast_websocket_client::username, ast_websocket_client::verify_server_cert, ast_websocket_client::verify_server_hostname, and WS_OK.

Referenced by outbound_session_handler_thread().

ast_websocket_client_get_field_diff()

enum ast_ws_client_fields ast_websocket_client_get_field_diff	(	struct ast_websocket_client *	old_wc,
		struct ast_websocket_client *	new_wc
	)

Detect changes between two websocket client configurations.

Parameters

old_ow	The old websocket configuration.
new_ow	The new websocket configuration.

Returns

A bitmask of changed fields.

Definition at line 451 of file res_websocket_client.c.

{
    enum ast_ws_client_fields changed = AST_WS_CLIENT_FIELD_NONE;
    const char *new_id = ast_sorcery_object_get_id(new_wc);
    RAII_VAR(struct ast_variable *, changes, NULL, ast_variables_destroy);
    struct ast_variable *v = NULL;
    int res = 0;
    int changes_found = 0;
 
    ast_debug(2, "%s: Detecting changes\n", new_id);
 
    res = ast_sorcery_diff(sorcery, old_wc, new_wc, &changes);
    if (res != 0) {
        ast_log(LOG_WARNING, "%s: Failed to create changeset\n", new_id);
        return AST_WS_CLIENT_FIELD_NONE;
    }
 
    for (v = changes; v; v = v->next) {
        changes_found = 1;
        ast_debug(2, "%s: %s changed to %s\n", new_id, v->name, v->value);
        if (ast_strings_equal(v->name, "connection_type")) {
            changed |= AST_WS_CLIENT_FIELD_CONNECTION_TYPE;
        } else if (ast_strings_equal(v->name, "uri")) {
            changed |= AST_WS_CLIENT_FIELD_URI;
        } else if (ast_strings_equal(v->name, "protocols")) {
            changed |= AST_WS_CLIENT_FIELD_PROTOCOLS;
        } else if (ast_strings_equal(v->name, "username")) {
            changed |= AST_WS_CLIENT_FIELD_USERNAME;
        } else if (ast_strings_equal(v->name, "password")) {
            changed |= AST_WS_CLIENT_FIELD_PASSWORD;
        } else if (ast_strings_equal(v->name, "tls_enabled")) {
            changed |= AST_WS_CLIENT_FIELD_TLS_ENABLED;
        } else if (ast_strings_equal(v->name, "ca_list_file")) {
            changed |= AST_WS_CLIENT_FIELD_CA_LIST_FILE;
        } else if (ast_strings_equal(v->name, "ca_list_path")) {
            changed |= AST_WS_CLIENT_FIELD_CA_LIST_PATH;
        } else if (ast_strings_equal(v->name, "cert_file")) {
            changed |= AST_WS_CLIENT_FIELD_CERT_FILE;
        } else if (ast_strings_equal(v->name, "priv_key_file")) {
            changed |= AST_WS_CLIENT_FIELD_PRIV_KEY_FILE;
        } else if (ast_strings_equal(v->name, "reconnect_interval")) {
            changed |= AST_WS_CLIENT_FIELD_RECONNECT_INTERVAL;
        } else if (ast_strings_equal(v->name, "reconnect_attempts")) {
            changed |= AST_WS_CLIENT_FIELD_RECONNECT_ATTEMPTS;
        } else if (ast_strings_equal(v->name, "connection_timeout")) {
            changed |= AST_WS_CLIENT_FIELD_CONNECTION_TIMEOUT;
        } else if (ast_strings_equal(v->name, "verify_server_cert")) {
            changed |= AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT;
        } else if (ast_strings_equal(v->name, "verify_server_hostname")) {
            changed |= AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME;
        } else {
            ast_debug(2, "%s: Unknown change %s\n", new_id, v->name);
        }
    }
 
    if (!changes_found) {
        ast_debug(2, "%s: No changes found %p %p\n", new_id,
            old_wc,new_wc);
    }
    return changed;
 
}

References ast_debug, ast_log, ast_sorcery_diff(), ast_sorcery_object_get_id(), ast_strings_equal(), ast_variables_destroy(), AST_WS_CLIENT_FIELD_CA_LIST_FILE, AST_WS_CLIENT_FIELD_CA_LIST_PATH, AST_WS_CLIENT_FIELD_CERT_FILE, AST_WS_CLIENT_FIELD_CONNECTION_TIMEOUT, AST_WS_CLIENT_FIELD_CONNECTION_TYPE, AST_WS_CLIENT_FIELD_NONE, AST_WS_CLIENT_FIELD_PASSWORD, AST_WS_CLIENT_FIELD_PRIV_KEY_FILE, AST_WS_CLIENT_FIELD_PROTOCOLS, AST_WS_CLIENT_FIELD_RECONNECT_ATTEMPTS, AST_WS_CLIENT_FIELD_RECONNECT_INTERVAL, AST_WS_CLIENT_FIELD_TLS_ENABLED, AST_WS_CLIENT_FIELD_URI, AST_WS_CLIENT_FIELD_USERNAME, AST_WS_CLIENT_FIELD_VERIFY_SERVER_CERT, AST_WS_CLIENT_FIELD_VERIFY_SERVER_HOSTNAME, LOG_WARNING, ast_variable::name, ast_variable::next, NULL, RAII_VAR, sorcery, and ast_variable::value.

Referenced by ari_conf_owc_detect_changes().

ast_websocket_client_observer_add()

int ast_websocket_client_observer_add

(

const struct ast_sorcery_observer *

callbacks

)

Add sorcery observers for websocket client events.

Parameters

callbacks

The observer callbacks to add.

Returns

0 on success, -1 on failure.

Definition at line 516 of file res_websocket_client.c.

{
    if (!sorcery || !callbacks) {
        return -1;
    }
 
    if (ast_sorcery_observer_add(sorcery, "websocket_client", callbacks)) {
        ast_log(LOG_ERROR, "Failed to register websocket client observers\n");
        return -1;
    }
 
    return 0;
}

References ast_log, ast_sorcery_observer_add(), callbacks, LOG_ERROR, and sorcery.

Referenced by ari_conf_init().

ast_websocket_client_observer_remove()

void ast_websocket_client_observer_remove

(

const struct ast_sorcery_observer *

callbacks

)

Remove sorcery observers for websocket client events.

Parameters

callbacks

The observer callbacks to remove.

Definition at line 530 of file res_websocket_client.c.

{
    if (!sorcery || !callbacks) {
        return;
    }
 
    ast_sorcery_observer_remove(sorcery, "websocket_client", callbacks);
}

References ast_sorcery_observer_remove(), callbacks, and sorcery.

Referenced by ari_conf_destroy().

ast_websocket_client_reload()

int ast_websocket_client_reload

(

void

)

Force res_websocket_client to reload its configuration.

Returns

0 on success, -1 on failure.

Definition at line 590 of file res_websocket_client.c.

{
    ast_debug(2, "Reloading Websocket Client Configuration\n");
    if (sorcery) {
        ast_sorcery_reload(sorcery);
    }
 
    return 0;
}

References ast_debug, ast_sorcery_reload(), and sorcery.

Referenced by ari_conf_load().

ast_websocket_client_retrieve_all()

struct ao2_container * ast_websocket_client_retrieve_all

(

void

)

Retrieve a container of all websocket client objects.

Returns

The container. It may be empty but must always be cleaned up by the caller.

Definition at line 432 of file res_websocket_client.c.

{
    if (!sorcery) {
        return NULL;
    }
 
    return ast_sorcery_retrieve_by_fields(sorcery, "websocket_client",
        AST_RETRIEVE_FLAG_MULTIPLE | AST_RETRIEVE_FLAG_ALL, NULL);
}

References AST_RETRIEVE_FLAG_ALL, AST_RETRIEVE_FLAG_MULTIPLE, ast_sorcery_retrieve_by_fields(), NULL, and sorcery.

ast_websocket_client_retrieve_by_id()

struct ast_websocket_client * ast_websocket_client_retrieve_by_id

(

const char *

id

)

Retrieve a websocket client object by ID.

Parameters

id	The ID of the websocket client object.

Returns

The websocket client ao2 object or NULL if not found. The reference must be cleaned up by the caller.

Definition at line 442 of file res_websocket_client.c.

{
    if (!sorcery) {
        return NULL;
    }
 
    return ast_sorcery_retrieve_by_id(sorcery, "websocket_client", id);
}

References ast_sorcery_retrieve_by_id(), NULL, and sorcery.

Referenced by outbound_websocket_websocket_client_id_from_str().