internal.h File Reference

Internal API's for res_ari. More...

#include "asterisk/http.h"
#include "asterisk/json.h"
#include "asterisk/md5.h"
#include "asterisk/sorcery.h"
#include "asterisk/stringfields.h"
#include "asterisk/websocket_client.h"
#include "ari_websockets.h"

Include dependency graph for internal.h:

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

Go to the source code of this file.

Data Structures
struct	ari_conf_general
	Global configuration options for ARI. More...
struct	ari_conf_outbound_websocket
struct	ari_conf_user
	Per-user configuration options. More...

Functions
int	ari_cli_register (void)
	Register CLI commands for ARI. More...
void	ari_cli_unregister (void)
	Unregister CLI commands for ARI. More...
void	ari_conf_destroy (void)
	Destroy the ARI configuration. More...
struct ari_conf_general *	ari_conf_get_general (void)
struct ari_conf_outbound_websocket *	ari_conf_get_owc (const char *id)
struct ari_conf_outbound_websocket *	ari_conf_get_owc_for_app (const char *app_name, unsigned int ws_type)
	Get the outbound websocket configuration for a Stasis app. More...
struct ao2_container *	ari_conf_get_owcs (void)
struct ari_conf_user *	ari_conf_get_user (const char *username)
struct ao2_container *	ari_conf_get_users (void)
int	ari_conf_load (enum ari_conf_load_flags flags)
	(Re)load the ARI configuration More...
enum	ari_conf_load_flags {   ARI_CONF_INIT = (1 << 0) , ARI_CONF_RELOAD = (1 << 1) , ARI_CONF_LOAD_GENERAL = (1 << 2) , ARI_CONF_LOAD_USER = (1 << 3) ,   ARI_CONF_LOAD_OWC = (1 << 4) , ARI_CONF_LOAD_ALL }
enum ari_conf_owc_fields	ari_conf_owc_detect_changes (struct ari_conf_outbound_websocket *old_owc, struct ari_conf_outbound_websocket *new_owc)
	Detect changes between two outbound websocket configurations. More...
enum	ari_conf_owc_fields {   ARI_OWC_FIELD_NONE = 0 , ARI_OWC_FIELD_WEBSOCKET_CONNECTION_ID = (1 << AST_WS_CLIENT_FIELD_USER_START) , ARI_OWC_FIELD_APPS = (1 << (AST_WS_CLIENT_FIELD_USER_START + 1)) , ARI_OWC_FIELD_LOCAL_ARI_USER = (1 << (AST_WS_CLIENT_FIELD_USER_START + 2)) ,   ARI_OWC_FIELD_LOCAL_ARI_PASSWORD = (1 << (AST_WS_CLIENT_FIELD_USER_START + 3)) , ARI_OWC_FIELD_SUBSCRIBE_ALL = (1 << (AST_WS_CLIENT_FIELD_USER_START + 4)) , ARI_OWC_NEEDS_RECONNECT , ARI_OWC_NEEDS_REREGISTER = ARI_OWC_FIELD_APPS | ARI_OWC_FIELD_SUBSCRIBE_ALL }
enum ari_conf_owc_fields	ari_conf_owc_get_invalid_fields (const char *id)
struct ari_conf_user *	ari_conf_validate_user (const char *username, const char *password)
	Validated a user's credentials. More...
int	ari_sorcery_observer_add (const char *object_type, const struct ast_sorcery_observer *callbacks)
int	ari_sorcery_observer_remove (const char *object_type, const struct ast_sorcery_observer *callbacks)
enum	ari_user_password_format { ARI_PASSWORD_FORMAT_PLAIN , ARI_PASSWORD_FORMAT_CRYPT }
	Password format. More...
const char *	ari_websocket_type_to_str (enum ast_websocket_type type)

Detailed Description

Internal API's for res_ari.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Definition in file internal.h.

Enumeration Type Documentation

ari_conf_load_flags

enum ari_conf_load_flags

Enumerator
ARI_CONF_INIT	Initialize sorcery
ARI_CONF_RELOAD	Reload sorcery
ARI_CONF_LOAD_GENERAL	Load general config
ARI_CONF_LOAD_USER	Load user config
ARI_CONF_LOAD_OWC	Load outbound websocket config
ARI_CONF_LOAD_ALL

Definition at line 145 of file internal.h.

                         {
    ARI_CONF_INIT =              (1 << 0), /*!< Initialize sorcery */
    ARI_CONF_RELOAD =            (1 << 1), /*!< Reload sorcery */
    ARI_CONF_LOAD_GENERAL = (1 << 2), /*!< Load general config */
    ARI_CONF_LOAD_USER =    (1 << 3), /*!< Load user config */
    ARI_CONF_LOAD_OWC =     (1 << 4), /*!< Load outbound websocket config */
    ARI_CONF_LOAD_ALL =     (         /*!< Load all configs */
        ARI_CONF_LOAD_GENERAL
        | ARI_CONF_LOAD_USER
        | ARI_CONF_LOAD_OWC),
};

ari_conf_owc_fields

enum ari_conf_owc_fields

Enumerator
ARI_OWC_FIELD_NONE
ARI_OWC_FIELD_WEBSOCKET_CONNECTION_ID
ARI_OWC_FIELD_APPS
ARI_OWC_FIELD_LOCAL_ARI_USER
ARI_OWC_FIELD_LOCAL_ARI_PASSWORD
ARI_OWC_FIELD_SUBSCRIBE_ALL
ARI_OWC_NEEDS_RECONNECT
ARI_OWC_NEEDS_REREGISTER

Definition at line 96 of file internal.h.

                         {
    ARI_OWC_FIELD_NONE =                    0,
    ARI_OWC_FIELD_WEBSOCKET_CONNECTION_ID = (1 << AST_WS_CLIENT_FIELD_USER_START),
    ARI_OWC_FIELD_APPS =                    (1 << (AST_WS_CLIENT_FIELD_USER_START + 1)),
    ARI_OWC_FIELD_LOCAL_ARI_USER =          (1 << (AST_WS_CLIENT_FIELD_USER_START + 2)),
    ARI_OWC_FIELD_LOCAL_ARI_PASSWORD =      (1 << (AST_WS_CLIENT_FIELD_USER_START + 3)),
    ARI_OWC_FIELD_SUBSCRIBE_ALL =           (1 << (AST_WS_CLIENT_FIELD_USER_START + 4)),
    ARI_OWC_NEEDS_RECONNECT = AST_WS_CLIENT_NEEDS_RECONNECT
    | ARI_OWC_FIELD_WEBSOCKET_CONNECTION_ID | ARI_OWC_FIELD_LOCAL_ARI_USER
    | ARI_OWC_FIELD_LOCAL_ARI_PASSWORD,
    ARI_OWC_NEEDS_REREGISTER = ARI_OWC_FIELD_APPS | ARI_OWC_FIELD_SUBSCRIBE_ALL,
};

ari_user_password_format

enum ari_user_password_format

Password format.

Enumerator
ARI_PASSWORD_FORMAT_PLAIN	Plaintext password.
ARI_PASSWORD_FORMAT_CRYPT	crypt(3) password

Definition at line 76 of file internal.h.

                              {
    /*! \brief Plaintext password */
    ARI_PASSWORD_FORMAT_PLAIN,
    /*! crypt(3) password */
    ARI_PASSWORD_FORMAT_CRYPT,
};

Function Documentation

ari_cli_register()

int ari_cli_register

(

void

)

Register CLI commands for ARI.

Returns

0 on success.

Non-zero on error.

Definition at line 699 of file res/ari/cli.c.

                           {
    return ast_cli_register_multiple(cli_ari, ARRAY_LEN(cli_ari));
}

References ARRAY_LEN, ast_cli_register_multiple, and cli_ari.

Referenced by load_module().

ari_cli_unregister()

void ari_cli_unregister

(

void

)

Unregister CLI commands for ARI.

Definition at line 703 of file res/ari/cli.c.

                              {
    ast_cli_unregister_multiple(cli_ari, ARRAY_LEN(cli_ari));
}

References ARRAY_LEN, ast_cli_unregister_multiple(), and cli_ari.

Referenced by unload_module().

ari_conf_destroy()

void ari_conf_destroy

(

void

)

Destroy the ARI configuration.

Definition at line 794 of file res/ari/config.c.

{
    ast_websocket_client_observer_remove(&ws_client_observer_callbacks);
 
    ast_sorcery_unref(sorcery);
    sorcery = NULL;
    ao2_cleanup(owc_states);
}

References ao2_cleanup, ast_sorcery_unref, ast_websocket_client_observer_remove(), NULL, owc_states, sorcery, and ws_client_observer_callbacks.

Referenced by unload_module().

ari_conf_get_general()

struct ari_conf_general * ari_conf_get_general

(

void

)

Definition at line 482 of file res/ari/config.c.

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

References ast_sorcery_retrieve_by_id(), NULL, and sorcery.

Referenced by ari_show(), ast_ari_invoke(), ast_ari_json_format(), is_enabled(), origin_allowed(), and session_update().

ari_conf_get_owc()

struct ari_conf_outbound_websocket * ari_conf_get_owc

(

const char *

id

)

Definition at line 313 of file res/ari/config.c.

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

References ast_sorcery_retrieve_by_id(), NULL, and sorcery.

Referenced by ari_show_owc(), ari_start_owc(), outbound_sessions_load(), and outbound_websocket_state_cleanup().

ari_conf_get_owc_for_app()

struct ari_conf_outbound_websocket * ari_conf_get_owc_for_app	(	const char *	app_name,
		unsigned int	ws_type
	)

Get the outbound websocket configuration for a Stasis app.

Parameters

app_name	The application name to search for.
ws_type	An OR'd list of ari_websocket_types or ARI_WS_TYPE_ANY.

Return values

ARI	outbound websocket configuration object.
NULL	if not found.

Definition at line 322 of file res/ari/config.c.

{
    struct ari_conf_outbound_websocket *owc = NULL;
    struct ao2_container *owcs = NULL;
    struct ao2_iterator i;
 
    if (ast_strlen_zero(app_name)) {
        return NULL;
    }
 
    ast_debug(3, "Checking outbound websockets for app '%s'\n", app_name);
 
    owcs = ari_conf_get_owcs();
    if (!owcs || ao2_container_count(owcs) == 0) {
        ast_debug(3, "No outbound websockets found\n");
        return NULL;
    }
 
    i = ao2_iterator_init(owcs, 0);
    while ((owc = ao2_iterator_next(&i))) {
        const char *id = ast_sorcery_object_get_id(owc);
 
        ast_debug(3, "%s: Checking outbound websocket apps '%s' for app '%s'\n",
            id, owc->apps, app_name);
        if (owc->websocket_client->connection_type & ws_type
            && ast_in_delimited_string(app_name, owc->apps, ',')) {
            ast_debug(3, "%s: Found correct websocket type for apps '%s' for app '%s'\n",
                id, owc->apps, app_name);
            break;
        }
        ao2_cleanup(owc);
    }
    ao2_iterator_destroy(&i);
    ao2_cleanup(owcs);
    if (!owc) {
        ast_debug(3, "No outbound websocket found for app '%s'\n", app_name);
    }
 
    return owc;
}

References ao2_cleanup, ao2_container_count(), ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, app_name(), ari_conf_outbound_websocket::apps, ari_conf_get_owcs(), ast_debug, ast_in_delimited_string(), ast_sorcery_object_get_id(), ast_strlen_zero(), ast_websocket_client::connection_type, NULL, and ari_conf_outbound_websocket::websocket_client.

Referenced by ast_ari_create_per_call_websocket().

ari_conf_get_owcs()

struct ao2_container * ari_conf_get_owcs

(

void

)

Definition at line 303 of file res/ari/config.c.

{
    if (!sorcery) {
        return NULL;
    }
 
    return ast_sorcery_retrieve_by_fields(sorcery, "outbound_websocket",
        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.

Referenced by ari_conf_get_owc_for_app(), ari_show_owc(), ari_show_owcs(), ari_start_owc(), outbound_sessions_load(), outbound_websocket_validate_cb(), and outbound_websockets_validate().

ari_conf_get_user()

struct ari_conf_user * ari_conf_get_user

(

const char *

username

)

Definition at line 583 of file res/ari/config.c.

{
    if (!sorcery) {
        return NULL;
    }
 
    return ast_sorcery_retrieve_by_id(sorcery, "user", username);
}

References ast_sorcery_retrieve_by_id(), NULL, and sorcery.

Referenced by ari_show_user().

ari_conf_get_users()

struct ao2_container * ari_conf_get_users

(

void

)

Definition at line 573 of file res/ari/config.c.

{
    if (!sorcery) {
        return NULL;
    }
 
    return ast_sorcery_retrieve_by_fields(sorcery, "user",
        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.

Referenced by ari_show_user(), and ari_show_users().

ari_conf_load()

int ari_conf_load

(

enum ari_conf_load_flags

flags

)

(Re)load the ARI configuration

Definition at line 750 of file res/ari/config.c.

{
    void (*loader)(const struct ast_sorcery *sorcery, const char *type);
    const char *msg_prefix;
 
    if (flags & ARI_CONF_RELOAD) {
        loader = ast_sorcery_reload_object;
        msg_prefix= "Reloading";
        ast_websocket_client_reload();
    } else {
        loader = ast_sorcery_load_object;
        msg_prefix= "Loading";
    }
 
    if (flags & ARI_CONF_INIT) {
        if (ari_conf_init() != 0) {
            ast_log(LOG_ERROR, "Failed to initialize ARI configuration\n");
            return -1;
        }
    }
 
    if (!sorcery) {
        ast_log(LOG_ERROR, "ARI configuration not initialized\n");
        return -1;
    }
 
    if (flags & ARI_CONF_LOAD_GENERAL) {
        ast_debug(2, "%s ARI '%s' configuration\n", msg_prefix, "general");
        loader(sorcery, "general");
    }
 
    if (flags & ARI_CONF_LOAD_USER) {
        ast_debug(2, "%s ARI '%s' configuration\n", msg_prefix, "user");
        loader(sorcery, "user");
    }
 
    if (flags & ARI_CONF_LOAD_OWC) {
        ast_debug(2, "%s ARI '%s' configuration\n", msg_prefix, "outbound_websocket");
        loader(sorcery, "outbound_websocket");
    }
 
    return 0;
}

References ari_conf_init(), ARI_CONF_INIT, ARI_CONF_LOAD_GENERAL, ARI_CONF_LOAD_OWC, ARI_CONF_LOAD_USER, ARI_CONF_RELOAD, ast_debug, ast_log, ast_sorcery_load_object(), ast_sorcery_reload_object(), ast_websocket_client_reload(), LOG_ERROR, sorcery, and type.

Referenced by load_module(), and reload_module().

ari_conf_owc_detect_changes()

enum ari_conf_owc_fields ari_conf_owc_detect_changes	(	struct ari_conf_outbound_websocket *	old_owc,
		struct ari_conf_outbound_websocket *	new_owc
	)

Detect changes between two outbound websocket configurations.

Parameters

old_owc	The old outbound websocket configuration.
new_owc	The new outbound websocket configuration.

Returns

A bitmask of changed fields.

Definition at line 382 of file res/ari/config.c.

{
    enum ari_conf_owc_fields changed = ARI_OWC_FIELD_NONE;
    const char *new_id = ast_sorcery_object_get_id(new_owc);
    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_owc, new_owc, &changes);
    if (res != 0) {
        ast_log(LOG_WARNING, "%s: Failed to create changeset\n", new_id);
        return ARI_OWC_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, "apps")) {
            changed |= ARI_OWC_FIELD_APPS;
        } else if (ast_strings_equal(v->name, "subscribe_all")) {
            changed |= ARI_OWC_FIELD_SUBSCRIBE_ALL;
        } else if (ast_strings_equal(v->name, "local_ari_user")) {
            changed |= ARI_OWC_FIELD_LOCAL_ARI_USER;
        } else if (ast_strings_equal(v->name, "local_ari_password")) {
            changed |= ARI_OWC_FIELD_LOCAL_ARI_PASSWORD;
        } 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_owc->websocket_client,new_owc->websocket_client);
    }
 
    changed |= ast_websocket_client_get_field_diff(
        old_owc->websocket_client, new_owc->websocket_client);
 
    return changed;
 
}

References ARI_OWC_FIELD_APPS, ARI_OWC_FIELD_LOCAL_ARI_PASSWORD, ARI_OWC_FIELD_LOCAL_ARI_USER, ARI_OWC_FIELD_NONE, ARI_OWC_FIELD_SUBSCRIBE_ALL, ast_debug, ast_log, ast_sorcery_diff(), ast_sorcery_object_get_id(), ast_strings_equal(), ast_variables_destroy(), ast_websocket_client_get_field_diff(), LOG_WARNING, ast_variable::name, ast_variable::next, NULL, RAII_VAR, sorcery, ast_variable::value, and ari_conf_outbound_websocket::websocket_client.

Referenced by outbound_session_apply_config().

ari_conf_owc_get_invalid_fields()

enum ari_conf_owc_fields ari_conf_owc_get_invalid_fields

(

const char *

id

)

Definition at line 163 of file res/ari/config.c.

{
    RAII_VAR(struct outbound_websocket_state *, state, NULL, ao2_cleanup);
 
    state = ao2_find(owc_states, id, OBJ_SEARCH_KEY);
    return state ? state->invalid_fields : ARI_OWC_FIELD_NONE;
}

References ao2_cleanup, ao2_find, ARI_OWC_FIELD_NONE, NULL, OBJ_SEARCH_KEY, owc_states, and RAII_VAR.

Referenced by ari_show_owc(), ast_ari_create_per_call_websocket(), outbound_session_create(), and show_owc_cb().

ari_conf_validate_user()

struct ari_conf_user * ari_conf_validate_user	(	const char *	username,
		const char *	password
	)

Validated a user's credentials.

Parameters

username	Name of the user.
password	User's password.

Returns

User object.

Return values

NULL	if username or password is invalid.

Definition at line 596 of file res/ari/config.c.

{
    struct ari_conf_user *user = NULL;
    int is_valid = 0;
 
    if (ast_strlen_zero(username) || ast_strlen_zero(password)) {
        return NULL;
    }
 
    user = ast_sorcery_retrieve_by_id(sorcery, "user", username);
    if (!user) {
        return NULL;
    }
 
    switch (user->password_format) {
    case ARI_PASSWORD_FORMAT_PLAIN:
        is_valid = strcmp(password, user->password) == 0;
        break;
    case ARI_PASSWORD_FORMAT_CRYPT:
        is_valid = ast_crypt_validate(password, user->password);
        break;
    }
 
    if (!is_valid) {
        ao2_cleanup(user);
        user = NULL;
    }
 
    return user;
}

References ao2_cleanup, ARI_PASSWORD_FORMAT_CRYPT, ARI_PASSWORD_FORMAT_PLAIN, ast_crypt_validate(), ast_sorcery_retrieve_by_id(), ast_strlen_zero(), NULL, ari_conf_user::password, sorcery, and user.

Referenced by authenticate_api_key(), and authenticate_user().

ari_sorcery_observer_add()

int ari_sorcery_observer_add	(	const char *	object_type,
		const struct ast_sorcery_observer *	callbacks
	)

Definition at line 628 of file res/ari/config.c.

{
    if (!sorcery) {
        return -1;
    }
    return ast_sorcery_observer_add(sorcery, object_type, callbacks);
}

References ast_sorcery_observer_add(), callbacks, and sorcery.

Referenced by ari_websocket_load_module().

ari_sorcery_observer_remove()

int ari_sorcery_observer_remove	(	const char *	object_type,
		const struct ast_sorcery_observer *	callbacks
	)

Definition at line 637 of file res/ari/config.c.

{
    if (!sorcery) {
        return -1;
    }
    ast_sorcery_observer_remove(sorcery, object_type, callbacks);
    return 0;
}

References ast_sorcery_observer_remove(), callbacks, and sorcery.

Referenced by ari_websocket_unload_module().

ari_websocket_type_to_str()

const char * ari_websocket_type_to_str

(

enum ast_websocket_type

type

)

Definition at line 364 of file res/ari/config.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_INBOUND:
        return "inbound";
    case AST_WS_TYPE_ANY:
        return "any";
    default:
        return "unknown";
    }
}