ari.h File Reference

Asterisk RESTful API hooks. More...

#include "asterisk/http.h"
#include "asterisk/json.h"

Include dependency graph for ari.h:

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

Go to the source code of this file.

Data Structures
struct	ast_ari_response
struct	stasis_rest_handlers
	Handler for a single RESTful path segment. More...

Typedefs
typedef void(*	stasis_rest_callback) (struct ast_tcptls_session_instance *ser, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
	Callback type for RESTful method handlers. More...

Functions
int	ast_ari_add_handler (struct stasis_rest_handlers *handler)
void	ast_ari_get_docs (const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response)
void	ast_ari_invoke (struct ast_tcptls_session_instance *ser, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
enum ast_json_encoding_format	ast_ari_json_format (void)
	Configured encoding format for JSON output. More...
struct ast_json *	ast_ari_oom_json (void)
	The stock message to return when out of memory. More...
int	ast_ari_remove_handler (struct stasis_rest_handlers *handler)
void	ast_ari_response_accepted (struct ast_ari_response *response)
	Fill in a Accepted (202) ast_ari_response. More...
void	ast_ari_response_alloc_failed (struct ast_ari_response *response)
	Fill in response with a 500 message for allocation failures. More...
void	ast_ari_response_created (struct ast_ari_response *response, const char *url, struct ast_json *message)
	Fill in a Created (201) ast_ari_response. More...
void	ast_ari_response_error (struct ast_ari_response *response, int response_code, const char *response_text, const char *message_fmt,...)
	Fill in an error ast_ari_response. More...
void	ast_ari_response_no_content (struct ast_ari_response *response)
	Fill in a No Content (204) ast_ari_response. More...
void	ast_ari_response_ok (struct ast_ari_response *response, struct ast_json *message)
	Fill in an OK (200) ast_ari_response. More...
struct ast_ari_websocket_session *	ast_ari_websocket_session_create (struct ast_websocket *ws_session, int(*validator)(struct ast_json *))
	Create an ARI WebSocket session. More...
struct ast_sockaddr *	ast_ari_websocket_session_get_remote_addr (struct ast_ari_websocket_session *session)
	Get the remote address from an ARI WebSocket. More...
const char *	ast_ari_websocket_session_id (const struct ast_ari_websocket_session *session)
	Get the Session ID for an ARI WebSocket. More...
struct ast_json *	ast_ari_websocket_session_read (struct ast_ari_websocket_session *session)
	Read a message from an ARI WebSocket. More...
int	ast_ari_websocket_session_write (struct ast_ari_websocket_session *session, struct ast_json *message)
	Send a message to an ARI WebSocket. More...

Detailed Description

Asterisk RESTful API hooks.

This header file is used mostly as glue code between generated declarations and res_ari.c.

Author

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

Definition in file ari.h.

Typedef Documentation

stasis_rest_callback

typedef void(* stasis_rest_callback) (struct ast_tcptls_session_instance *ser, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)

Callback type for RESTful method handlers.

Parameters

	ser	TCP/TLS session object
	get_params	GET parameters from the HTTP request.
	path_vars	Path variables from any wildcard path segments.
	headers	HTTP headers from the HTTP requiest.
	body
[out]	response	The RESTful response.

Definition at line 60 of file ari.h.

Function Documentation

ast_ari_add_handler()

int ast_ari_add_handler

(

struct stasis_rest_handlers *

handler

)

Add a resource for REST handling.

Parameters

handler

Handler to add.

Return values

0	on success.
non-zero	on failure.

Definition at line 179 of file res_ari.c.

{
    RAII_VAR(struct stasis_rest_handlers *, new_handler, NULL, ao2_cleanup);
    size_t old_size, new_size;
 
    SCOPED_MUTEX(lock, &root_handler_lock);
 
    old_size = sizeof(*new_handler) + root_handler->num_children * sizeof(handler);
    new_size = old_size + sizeof(handler);
 
    new_handler = ao2_alloc(new_size, NULL);
    if (!new_handler) {
        return -1;
    }
    memcpy(new_handler, root_handler, old_size);
    new_handler->children[new_handler->num_children++] = handler;
 
    ao2_cleanup(root_handler);
    ao2_ref(new_handler, +1);
    root_handler = new_handler;
    return 0;
}

References ao2_alloc, ao2_cleanup, ao2_ref, handler(), lock, NULL, stasis_rest_handlers::num_children, RAII_VAR, root_handler, root_handler_lock, and SCOPED_MUTEX.

Referenced by load_module(), and setup_invocation_test().

ast_ari_get_docs()

void ast_ari_get_docs	(	const char *	uri,
		const char *	prefix,
		struct ast_variable *	headers,
		struct ast_ari_response *	response
	)

Definition at line 598 of file res_ari.c.

{
    RAII_VAR(struct ast_str *, absolute_path_builder, NULL, ast_free);
    RAII_VAR(char *, absolute_api_dirname, NULL, ast_std_free);
    RAII_VAR(char *, absolute_filename, NULL, ast_std_free);
    struct ast_json *obj = NULL;
    struct ast_variable *host = NULL;
    struct ast_json_error error = {};
    struct stat file_stat;
 
    ast_debug(3, "%s(%s)\n", __func__, uri);
 
    absolute_path_builder = ast_str_create(80);
    if (absolute_path_builder == NULL) {
        ast_ari_response_alloc_failed(response);
        return;
    }
 
    /* absolute path to the rest-api directory */
    ast_str_append(&absolute_path_builder, 0, "%s", ast_config_AST_DATA_DIR);
    ast_str_append(&absolute_path_builder, 0, "/rest-api/");
    absolute_api_dirname = realpath(ast_str_buffer(absolute_path_builder), NULL);
    if (absolute_api_dirname == NULL) {
        ast_log(LOG_ERROR, "Error determining real directory for rest-api\n");
        ast_ari_response_error(
            response, 500, "Internal Server Error",
            "Cannot find rest-api directory");
        return;
    }
 
    /* absolute path to the requested file */
    ast_str_append(&absolute_path_builder, 0, "%s", uri);
    absolute_filename = realpath(ast_str_buffer(absolute_path_builder), NULL);
    if (absolute_filename == NULL) {
        switch (errno) {
        case ENAMETOOLONG:
        case ENOENT:
        case ENOTDIR:
            ast_ari_response_error(
                response, 404, "Not Found",
                "Resource not found");
            break;
        case EACCES:
            ast_ari_response_error(
                response, 403, "Forbidden",
                "Permission denied");
            break;
        default:
            ast_log(LOG_ERROR,
                "Error determining real path for uri '%s': %s\n",
                uri, strerror(errno));
            ast_ari_response_error(
                response, 500, "Internal Server Error",
                "Cannot find file");
            break;
        }
        return;
    }
 
    if (!ast_begins_with(absolute_filename, absolute_api_dirname)) {
        /* HACKERZ! */
        ast_log(LOG_ERROR,
            "Invalid attempt to access '%s' (not in %s)\n",
            absolute_filename, absolute_api_dirname);
        ast_ari_response_error(
            response, 404, "Not Found",
            "Resource not found");
        return;
    }
 
    if (stat(absolute_filename, &file_stat) == 0) {
        if (!(file_stat.st_mode & S_IFREG)) {
            /* Not a file */
            ast_ari_response_error(
                response, 403, "Forbidden",
                "Invalid access");
            return;
        }
    } else {
        /* Does not exist */
        ast_ari_response_error(
            response, 404, "Not Found",
            "Resource not found");
        return;
    }
 
    /* Load resource object from file */
    obj = ast_json_load_new_file(absolute_filename, &error);
    if (obj == NULL) {
        ast_log(LOG_ERROR, "Error parsing resource file: %s:%d(%d) %s\n",
            error.source, error.line, error.column, error.text);
        ast_ari_response_error(
            response, 500, "Internal Server Error",
            "Yikes! Cannot parse resource");
        return;
    }
 
    /* Update the basePath properly */
    if (ast_json_object_get(obj, "basePath") != NULL) {
        for (host = headers; host; host = host->next) {
            if (strcasecmp(host->name, "Host") == 0) {
                break;
            }
        }
        if (host != NULL) {
            if (prefix != NULL && strlen(prefix) > 0) {
                ast_json_object_set(
                    obj, "basePath",
                    ast_json_stringf("http://%s%s/ari", host->value,prefix));
            } else {
                ast_json_object_set(
                    obj, "basePath",
                    ast_json_stringf("http://%s/ari", host->value));
            }
        } else {
            /* Without the host, we don't have the basePath */
            ast_json_object_del(obj, "basePath");
        }
    }
 
    ast_ari_response_ok(response, obj);
}

References ast_ari_response_alloc_failed(), ast_ari_response_error(), ast_ari_response_ok(), ast_begins_with(), ast_config_AST_DATA_DIR, ast_debug, ast_free, ast_json_load_new_file(), ast_json_object_del(), ast_json_object_get(), ast_json_object_set(), ast_json_stringf(), ast_log, ast_std_free(), ast_str_append(), ast_str_buffer(), ast_str_create, errno, error(), LOG_ERROR, ast_variable::name, ast_variable::next, NULL, prefix, RAII_VAR, and ast_variable::value.

Referenced by ast_ari_callback(), and AST_TEST_DEFINE().

ast_ari_invoke()

void ast_ari_invoke	(	struct ast_tcptls_session_instance *	ser,
		const char *	uri,
		enum ast_http_method	method,
		struct ast_variable *	get_params,
		struct ast_variable *	headers,
		struct ast_json *	body,
		struct ast_ari_response *	response
	)

Definition at line 491 of file res_ari.c.

{
    RAII_VAR(struct stasis_rest_handlers *, root, NULL, ao2_cleanup);
    struct stasis_rest_handlers *handler;
    struct stasis_rest_handlers *wildcard_handler = NULL;
    RAII_VAR(struct ast_variable *, path_vars, NULL, ast_variables_destroy);
    char *path = ast_strdupa(uri);
    char *path_segment;
    stasis_rest_callback callback;
 
    root = handler = get_root_handler();
    ast_assert(root != NULL);
 
    ast_debug(3, "Finding handler for %s\n", path);
 
    while ((path_segment = strsep(&path, "/")) && (strlen(path_segment) > 0)) {
        struct stasis_rest_handlers *found_handler = NULL;
        int i;
 
        ast_uri_decode(path_segment, ast_uri_http_legacy);
        ast_debug(3, "  Finding handler for %s\n", path_segment);
 
        for (i = 0; found_handler == NULL && i < handler->num_children; ++i) {
            struct stasis_rest_handlers *child = handler->children[i];
 
            if (child->is_wildcard) {
                /* Record the path variable */
                struct ast_variable *path_var = ast_variable_new(child->path_segment, path_segment, __FILE__);
                path_var->next = path_vars;
                path_vars = path_var;
                wildcard_handler = child;
                ast_debug(3, "        Checking %s %s:  Matched wildcard.\n", handler->path_segment, child->path_segment);
 
            } else if (strcmp(child->path_segment, path_segment) == 0) {
                found_handler = child;
                ast_debug(3, "        Checking %s %s:  Explicit match with %s\n", handler->path_segment, child->path_segment, path_segment);
            } else {
                ast_debug(3, "        Checking %s %s:  Didn't match %s\n", handler->path_segment, child->path_segment, path_segment);
            }
        }
 
        if (!found_handler && wildcard_handler) {
            ast_debug(3, "  No explicit handler found for %s.  Using wildcard %s.\n",
                path_segment, wildcard_handler->path_segment);
            found_handler = wildcard_handler;
            wildcard_handler = NULL;
        }
 
        if (found_handler == NULL) {
            /* resource not found */
            ast_debug(3, "  Handler not found for %s\n", path_segment);
            ast_ari_response_error(
                response, 404, "Not Found",
                "Resource not found");
            return;
        } else {
            handler = found_handler;
        }
    }
 
    ast_assert(handler != NULL);
    if (method == AST_HTTP_OPTIONS) {
        handle_options(handler, headers, response);
        return;
    }
 
    if (method < 0 || method >= AST_HTTP_MAX_METHOD) {
        add_allow_header(handler, response);
        ast_ari_response_error(
            response, 405, "Method Not Allowed",
            "Invalid method");
        return;
    }
 
    if (handler->ws_server && method == AST_HTTP_GET) {
        /* WebSocket! */
        ari_handle_websocket(handler->ws_server, ser, uri, method,
            get_params, headers);
        /* Since the WebSocket code handles the connection, we shouldn't
         * do anything else; setting no_response */
        response->no_response = 1;
        return;
    }
 
    callback = handler->callbacks[method];
    if (callback == NULL) {
        add_allow_header(handler, response);
        ast_ari_response_error(
            response, 405, "Method Not Allowed",
            "Invalid method");
        return;
    }
 
    callback(ser, get_params, path_vars, headers, body, response);
    if (response->message == NULL && response->response_code == 0) {
        /* Really should not happen */
        ast_log(LOG_ERROR, "ARI %s %s not implemented\n",
            ast_get_http_method(method), uri);
        ast_ari_response_error(
            response, 501, "Not Implemented",
            "Method not implemented");
    }
}

References add_allow_header(), ao2_cleanup, ari_handle_websocket(), ast_ari_response_error(), ast_assert, ast_debug, ast_get_http_method(), AST_HTTP_GET, AST_HTTP_MAX_METHOD, AST_HTTP_OPTIONS, ast_log, ast_strdupa, ast_uri_decode(), ast_uri_http_legacy, ast_variable_new, ast_variables_destroy(), get_root_handler(), handle_options(), handler(), stasis_rest_handlers::is_wildcard, LOG_ERROR, ast_ari_response::message, method, ast_variable::next, ast_ari_response::no_response, NULL, stasis_rest_handlers::path_segment, RAII_VAR, ast_ari_response::response_code, and strsep().

Referenced by ast_ari_callback(), and AST_TEST_DEFINE().

ast_ari_json_format()

enum ast_json_encoding_format ast_ari_json_format

(

void

)

Configured encoding format for JSON output.

Returns

JSON output encoding (compact, pretty, etc.)

Definition at line 806 of file res_ari.c.

{
    RAII_VAR(struct ast_ari_conf *, cfg, NULL, ao2_cleanup);
    cfg = ast_ari_config_get();
    return cfg->general->format;
}

References ao2_cleanup, ast_ari_config_get(), NULL, and RAII_VAR.

Referenced by ast_ari_callback(), ast_ari_websocket_session_write(), and stasis_app_message_handler().

ast_ari_oom_json()

struct ast_json * ast_ari_oom_json

(

void

)

The stock message to return when out of memory.

The refcount is NOT bumped on this object, so ast_json_ref() if you want to keep the reference.

Returns

JSON message specifying an out-of-memory error.

Definition at line 174 of file res_ari.c.

{
    return oom_json;
}

References oom_json.

ast_ari_remove_handler()

int ast_ari_remove_handler

(

struct stasis_rest_handlers *

handler

)

Remove a resource for REST handling.

Parameters

handler

Handler to add.

Return values

0	on success.
non-zero	on failure.

Definition at line 202 of file res_ari.c.

{
    struct stasis_rest_handlers *new_handler;
    size_t size;
    size_t i;
    size_t j;
 
    ast_assert(root_handler != NULL);
 
    ast_mutex_lock(&root_handler_lock);
    size = sizeof(*new_handler) + root_handler->num_children * sizeof(handler);
 
    new_handler = ao2_alloc(size, NULL);
    if (!new_handler) {
        ast_mutex_unlock(&root_handler_lock);
        return -1;
    }
 
    /* Create replacement root_handler less the handler to remove. */
    memcpy(new_handler, root_handler, sizeof(*new_handler));
    for (i = 0, j = 0; i < root_handler->num_children; ++i) {
        if (root_handler->children[i] == handler) {
            continue;
        }
        new_handler->children[j++] = root_handler->children[i];
    }
    new_handler->num_children = j;
 
    /* Replace the old root_handler with the new. */
    ao2_cleanup(root_handler);
    root_handler = new_handler;
 
    ast_mutex_unlock(&root_handler_lock);
    return 0;
}

References ao2_alloc, ao2_cleanup, ast_assert, ast_mutex_lock, ast_mutex_unlock, stasis_rest_handlers::children, handler(), NULL, stasis_rest_handlers::num_children, root_handler, and root_handler_lock.

Referenced by tear_down_invocation_test(), and unload_module().

ast_ari_response_accepted()

void ast_ari_response_accepted

(

struct ast_ari_response *

response

)

Fill in a Accepted (202) ast_ari_response.

Definition at line 291 of file res_ari.c.

{
    response->message = ast_json_null();
    response->response_code = 202;
    response->response_text = "Accepted";
}

References ast_json_null(), ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ast_ari_asterisk_reload_module().

ast_ari_response_alloc_failed()

void ast_ari_response_alloc_failed

(

struct ast_ari_response *

response

)

Fill in response with a 500 message for allocation failures.

Parameters

response

Response to fill in.

Definition at line 298 of file res_ari.c.

{
    response->message = ast_json_ref(oom_json);
    response->response_code = 500;
    response->response_text = "Internal Server Error";
}

References ast_json_ref(), ast_ari_response::message, oom_json, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_bridges_play_helper(), ari_bridges_play_new(), ari_channels_handle_originate_with_id(), ast_ari_applications_subscribe_cb(), ast_ari_applications_unsubscribe_cb(), ast_ari_asterisk_add_log_cb(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_global_var_cb(), ast_ari_asterisk_get_info(), ast_ari_asterisk_get_info_cb(), ast_ari_asterisk_get_module(), ast_ari_asterisk_list_modules(), ast_ari_asterisk_set_global_var_cb(), ast_ari_asterisk_update_object(), ast_ari_bridges_add_channel(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_create_cb(), ast_ari_bridges_create_with_id_cb(), ast_ari_bridges_list(), ast_ari_bridges_play_cb(), ast_ari_bridges_play_with_id_cb(), ast_ari_bridges_record(), ast_ari_bridges_record_cb(), ast_ari_bridges_remove_channel_cb(), ast_ari_bridges_start_moh(), ast_ari_bridges_start_moh_cb(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_continue_in_dialplan_cb(), ast_ari_channels_create(), ast_ari_channels_dial(), ast_ari_channels_dial_cb(), ast_ari_channels_get_channel_var(), ast_ari_channels_get_channel_var_cb(), ast_ari_channels_hangup_cb(), ast_ari_channels_list(), ast_ari_channels_move_cb(), ast_ari_channels_mute_cb(), ast_ari_channels_play_cb(), ast_ari_channels_play_with_id_cb(), ast_ari_channels_record_cb(), ast_ari_channels_redirect_cb(), ast_ari_channels_send_dtmf_cb(), ast_ari_channels_set_channel_var_cb(), ast_ari_channels_snoop_channel_cb(), ast_ari_channels_snoop_channel_with_id_cb(), ast_ari_channels_start_moh_cb(), ast_ari_channels_unmute_cb(), ast_ari_device_states_update_cb(), ast_ari_endpoints_get(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_ari_events_user_event_cb(), ast_ari_get_docs(), ast_ari_mailboxes_update_cb(), ast_ari_playbacks_control_cb(), ast_ari_recordings_copy_stored_cb(), ast_ari_recordings_list_stored(), ast_ari_sounds_list_cb(), control_list_create(), handle_options(), json_to_ast_variables(), return_sorcery_object(), send_message(), and send_refer().

ast_ari_response_created()

void ast_ari_response_created	(	struct ast_ari_response *	response,
		const char *	url,
		struct ast_json *	message
	)

Fill in a Created (201) ast_ari_response.

Parameters

response	Response to fill in.
url	URL to the created resource.
message	JSON response. This reference is stolen, so just ast_json_ref if you need to keep a reference to it.

Definition at line 305 of file res_ari.c.

{
    RAII_VAR(struct stasis_rest_handlers *, root, get_root_handler(), ao2_cleanup);
    response->message = message;
    response->response_code = 201;
    response->response_text = "Created";
    ast_str_append(&response->headers, 0, "Location: /%s%s\r\n", root->path_segment, url);
}

References ao2_cleanup, ast_str_append(), get_root_handler(), ast_ari_response::headers, ast_ari_response::message, RAII_VAR, ast_ari_response::response_code, ast_ari_response::response_text, and url.

Referenced by ari_bridges_play_found(), ari_bridges_play_new(), ari_channels_handle_play(), ast_ari_bridges_record(), and ast_ari_channels_record().

ast_ari_response_error()

void ast_ari_response_error	(	struct ast_ari_response *	response,
		int	response_code,
		const char *	response_text,
		const char *	message_fmt,
			...
	)

Fill in an error ast_ari_response.

Parameters

response	Response to fill in.
response_code	HTTP response code.
response_text	Text corresponding to the HTTP response code.
message_fmt	Error message format string.

Definition at line 259 of file res_ari.c.

{
    RAII_VAR(struct ast_json *, message, NULL, ast_json_unref);
    va_list ap;
 
    va_start(ap, message_fmt);
    message = ast_json_vstringf(message_fmt, ap);
    va_end(ap);
    response->message = ast_json_pack("{s: o}",
                      "message", ast_json_ref(message));
    response->response_code = response_code;
    response->response_text = response_text;
}

References ast_json_pack(), ast_json_ref(), ast_json_unref(), ast_json_vstringf(), ast_ari_response::message, NULL, RAII_VAR, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_bridges_play_helper(), ari_bridges_play_new(), ari_channels_handle_originate_with_id(), ari_channels_handle_play(), ari_channels_handle_snoop_channel(), ast_ari_applications_filter(), ast_ari_applications_filter_cb(), ast_ari_applications_get(), ast_ari_applications_get_cb(), ast_ari_applications_list(), ast_ari_applications_list_cb(), ast_ari_applications_subscribe(), ast_ari_applications_subscribe_cb(), ast_ari_applications_unsubscribe(), ast_ari_applications_unsubscribe_cb(), ast_ari_asterisk_add_log(), ast_ari_asterisk_add_log_cb(), ast_ari_asterisk_delete_log(), ast_ari_asterisk_delete_log_cb(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_delete_object_cb(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_global_var_cb(), ast_ari_asterisk_get_info_cb(), ast_ari_asterisk_get_module(), ast_ari_asterisk_get_module_cb(), ast_ari_asterisk_get_object(), ast_ari_asterisk_get_object_cb(), ast_ari_asterisk_list_log_channels(), ast_ari_asterisk_list_log_channels_cb(), ast_ari_asterisk_list_modules_cb(), ast_ari_asterisk_load_module(), ast_ari_asterisk_load_module_cb(), ast_ari_asterisk_ping_cb(), ast_ari_asterisk_reload_module(), ast_ari_asterisk_reload_module_cb(), ast_ari_asterisk_rotate_log(), ast_ari_asterisk_rotate_log_cb(), ast_ari_asterisk_set_global_var(), ast_ari_asterisk_set_global_var_cb(), ast_ari_asterisk_unload_module(), ast_ari_asterisk_unload_module_cb(), ast_ari_asterisk_update_object(), ast_ari_asterisk_update_object_cb(), ast_ari_bridges_add_channel_cb(), ast_ari_bridges_clear_video_source_cb(), ast_ari_bridges_create(), ast_ari_bridges_create_cb(), ast_ari_bridges_create_with_id(), ast_ari_bridges_create_with_id_cb(), ast_ari_bridges_destroy_cb(), ast_ari_bridges_get(), ast_ari_bridges_get_cb(), ast_ari_bridges_list_cb(), ast_ari_bridges_play_cb(), ast_ari_bridges_play_with_id_cb(), ast_ari_bridges_record(), ast_ari_bridges_record_cb(), ast_ari_bridges_remove_channel(), ast_ari_bridges_remove_channel_cb(), ast_ari_bridges_set_video_source(), ast_ari_bridges_set_video_source_cb(), ast_ari_bridges_start_moh_cb(), ast_ari_bridges_stop_moh(), ast_ari_bridges_stop_moh_cb(), ast_ari_callback(), ast_ari_channels_answer(), ast_ari_channels_answer_cb(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_continue_in_dialplan_cb(), ast_ari_channels_create(), ast_ari_channels_create_cb(), ast_ari_channels_dial(), ast_ari_channels_dial_cb(), ast_ari_channels_external_media(), ast_ari_channels_external_media_cb(), ast_ari_channels_get(), ast_ari_channels_get_cb(), ast_ari_channels_get_channel_var(), ast_ari_channels_get_channel_var_cb(), ast_ari_channels_hangup(), ast_ari_channels_hangup_cb(), ast_ari_channels_hold_cb(), ast_ari_channels_list_cb(), ast_ari_channels_move(), ast_ari_channels_move_cb(), ast_ari_channels_mute(), ast_ari_channels_mute_cb(), ast_ari_channels_originate_cb(), ast_ari_channels_originate_with_id_cb(), ast_ari_channels_play_cb(), ast_ari_channels_play_with_id_cb(), ast_ari_channels_record(), ast_ari_channels_record_cb(), ast_ari_channels_redirect(), ast_ari_channels_redirect_cb(), ast_ari_channels_ring_cb(), ast_ari_channels_ring_stop_cb(), ast_ari_channels_rtpstatistics(), ast_ari_channels_rtpstatistics_cb(), ast_ari_channels_send_dtmf(), ast_ari_channels_send_dtmf_cb(), ast_ari_channels_set_channel_var(), ast_ari_channels_set_channel_var_cb(), ast_ari_channels_snoop_channel_cb(), ast_ari_channels_snoop_channel_with_id_cb(), ast_ari_channels_start_moh_cb(), ast_ari_channels_start_silence_cb(), ast_ari_channels_stop_moh_cb(), ast_ari_channels_stop_silence_cb(), ast_ari_channels_unhold_cb(), ast_ari_channels_unmute(), ast_ari_channels_unmute_cb(), ast_ari_device_states_delete(), ast_ari_device_states_delete_cb(), ast_ari_device_states_get(), ast_ari_device_states_get_cb(), ast_ari_device_states_list(), ast_ari_device_states_list_cb(), ast_ari_device_states_update(), ast_ari_device_states_update_cb(), ast_ari_endpoints_get(), ast_ari_endpoints_get_cb(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_endpoints_list_by_tech_cb(), ast_ari_endpoints_list_cb(), ast_ari_endpoints_refer_cb(), ast_ari_endpoints_refer_to_endpoint(), ast_ari_endpoints_refer_to_endpoint_cb(), ast_ari_endpoints_send_message_cb(), ast_ari_endpoints_send_message_to_endpoint(), ast_ari_endpoints_send_message_to_endpoint_cb(), ast_ari_events_event_websocket_ws_attempted_cb(), ast_ari_events_event_websocket_ws_established_cb(), ast_ari_events_user_event(), ast_ari_events_user_event_cb(), ast_ari_get_docs(), ast_ari_invoke(), ast_ari_mailboxes_delete(), ast_ari_mailboxes_delete_cb(), ast_ari_mailboxes_get(), ast_ari_mailboxes_get_cb(), ast_ari_mailboxes_list(), ast_ari_mailboxes_list_cb(), ast_ari_mailboxes_update(), ast_ari_mailboxes_update_cb(), ast_ari_playbacks_control(), ast_ari_playbacks_control_cb(), ast_ari_playbacks_get(), ast_ari_playbacks_get_cb(), ast_ari_playbacks_stop(), ast_ari_playbacks_stop_cb(), ast_ari_recordings_cancel_cb(), ast_ari_recordings_copy_stored(), ast_ari_recordings_copy_stored_cb(), ast_ari_recordings_delete_stored(), ast_ari_recordings_delete_stored_cb(), ast_ari_recordings_get_live(), ast_ari_recordings_get_live_cb(), ast_ari_recordings_get_stored(), ast_ari_recordings_get_stored_cb(), ast_ari_recordings_get_stored_file(), ast_ari_recordings_get_stored_file_cb(), ast_ari_recordings_list_stored_cb(), ast_ari_recordings_mute_cb(), ast_ari_recordings_pause_cb(), ast_ari_recordings_stop_cb(), ast_ari_recordings_unmute_cb(), ast_ari_recordings_unpause_cb(), ast_ari_sounds_get(), ast_ari_sounds_get_cb(), ast_ari_sounds_list(), ast_ari_sounds_list_cb(), channel_state_invalid(), check_add_remove_channel(), control_list_create(), control_recording(), external_media_audiosocket_tcp(), find_bridge(), find_channel_control(), find_control(), json_to_ast_variables(), remove_trailing_slash(), send_message(), and send_refer().

ast_ari_response_no_content()

void ast_ari_response_no_content

(

struct ast_ari_response *

response

)

Fill in a No Content (204) ast_ari_response.

Definition at line 284 of file res_ari.c.

{
    response->message = ast_json_null();
    response->response_code = 204;
    response->response_text = "No Content";
}

References ast_json_null(), ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ast_ari_asterisk_add_log(), ast_ari_asterisk_delete_log(), ast_ari_asterisk_delete_object(), ast_ari_asterisk_load_module(), ast_ari_asterisk_reload_module(), ast_ari_asterisk_rotate_log(), ast_ari_asterisk_set_global_var(), ast_ari_asterisk_unload_module(), ast_ari_bridges_add_channel(), ast_ari_bridges_clear_video_source(), ast_ari_bridges_destroy(), ast_ari_bridges_remove_channel(), ast_ari_bridges_set_video_source(), ast_ari_bridges_start_moh(), ast_ari_bridges_stop_moh(), ast_ari_channels_answer(), ast_ari_channels_continue_in_dialplan(), ast_ari_channels_dial(), ast_ari_channels_hangup(), ast_ari_channels_hold(), ast_ari_channels_move(), ast_ari_channels_mute(), ast_ari_channels_redirect(), ast_ari_channels_ring(), ast_ari_channels_ring_stop(), ast_ari_channels_send_dtmf(), ast_ari_channels_set_channel_var(), ast_ari_channels_start_moh(), ast_ari_channels_start_silence(), ast_ari_channels_stop_moh(), ast_ari_channels_stop_silence(), ast_ari_channels_unhold(), ast_ari_channels_unmute(), ast_ari_device_states_delete(), ast_ari_device_states_update(), ast_ari_events_user_event(), ast_ari_mailboxes_delete(), ast_ari_mailboxes_update(), ast_ari_playbacks_control(), ast_ari_playbacks_stop(), ast_ari_recordings_delete_stored(), control_recording(), and handle_options().

ast_ari_response_ok()

void ast_ari_response_ok	(	struct ast_ari_response *	response,
		struct ast_json *	message
	)

Fill in an OK (200) ast_ari_response.

Parameters

response	Response to fill in.
message	JSON response. This reference is stolen, so just ast_json_ref if you need to keep a reference to it.

Definition at line 276 of file res_ari.c.

{
    response->message = message;
    response->response_code = 200;
    response->response_text = "OK";
}

References ast_ari_response::message, ast_ari_response::response_code, and ast_ari_response::response_text.

Referenced by ari_channels_handle_originate_with_id(), ari_channels_handle_snoop_channel(), ast_ari_applications_filter(), ast_ari_applications_get(), ast_ari_applications_list(), ast_ari_applications_subscribe(), ast_ari_applications_unsubscribe(), ast_ari_asterisk_get_global_var(), ast_ari_asterisk_get_info(), ast_ari_asterisk_get_module(), ast_ari_asterisk_list_log_channels(), ast_ari_asterisk_list_modules(), ast_ari_asterisk_ping(), ast_ari_bridges_create(), ast_ari_bridges_create_with_id(), ast_ari_bridges_get(), ast_ari_bridges_list(), ast_ari_channels_create(), ast_ari_channels_get(), ast_ari_channels_get_channel_var(), ast_ari_channels_list(), ast_ari_channels_rtpstatistics(), ast_ari_device_states_get(), ast_ari_device_states_list(), ast_ari_endpoints_get(), ast_ari_endpoints_list(), ast_ari_endpoints_list_by_tech(), ast_ari_get_docs(), ast_ari_mailboxes_get(), ast_ari_mailboxes_list(), ast_ari_playbacks_get(), ast_ari_recordings_copy_stored(), ast_ari_recordings_get_live(), ast_ari_recordings_get_stored(), ast_ari_recordings_get_stored_file(), ast_ari_recordings_list_stored(), ast_ari_sounds_get(), ast_ari_sounds_list(), and return_sorcery_object().

ast_ari_websocket_session_create()

struct ast_ari_websocket_session * ast_ari_websocket_session_create	(	struct ast_websocket *	ws_session,
		int(*)(struct ast_json *)	validator
	)

Create an ARI WebSocket session.

If NULL is given for the validator function, no validation will be performed.

Parameters

ws_session	Underlying WebSocket session.
validator	Function to validate outgoing messages.

Returns

New ARI WebSocket session.

Return values

NULL

on error.

Definition at line 54 of file ari_websockets.c.

{
    RAII_VAR(struct ast_ari_websocket_session *, session, NULL, ao2_cleanup);
    RAII_VAR(struct ast_ari_conf *, config, ast_ari_config_get(), ao2_cleanup);
 
    if (ws_session == NULL) {
        return NULL;
    }
 
    if (config == NULL || config->general == NULL) {
        return NULL;
    }
 
    if (validator == NULL) {
        validator = null_validator;
    }
 
    if (ast_websocket_set_nonblock(ws_session) != 0) {
        ast_log(LOG_ERROR,
            "ARI web socket failed to set nonblock; closing: %s\n",
            strerror(errno));
        return NULL;
    }
 
    if (ast_websocket_set_timeout(ws_session, config->general->write_timeout)) {
        ast_log(LOG_WARNING, "Failed to set write timeout %d on ARI web socket\n",
            config->general->write_timeout);
    }
 
    session = ao2_alloc(sizeof(*session), websocket_session_dtor);
    if (!session) {
        return NULL;
    }
 
    ao2_ref(ws_session, +1);
    session->ws_session = ws_session;
    session->validator = validator;
 
    ao2_ref(session, +1);
    return session;
}

References ao2_alloc, ao2_cleanup, ao2_ref, ast_ari_config_get(), ast_log, ast_websocket_set_nonblock(), ast_websocket_set_timeout(), config, errno, LOG_ERROR, LOG_WARNING, NULL, null_validator(), RAII_VAR, session, ast_ari_websocket_session::validator, websocket_session_dtor(), and ast_ari_websocket_session::ws_session.

Referenced by ast_ari_events_event_websocket_ws_established_cb().

ast_ari_websocket_session_get_remote_addr()

struct ast_sockaddr * ast_ari_websocket_session_get_remote_addr

(

struct ast_ari_websocket_session *

session

)

Get the remote address from an ARI WebSocket.

Parameters

session

Session to write to.

Returns

ast_sockaddr (does not have to be freed)

Definition at line 185 of file ari_websockets.c.

{
    return ast_websocket_remote_address(session->ws_session);
}

References ast_websocket_remote_address(), and session.

Referenced by ast_ari_websocket_session_write(), and stasis_app_message_handler().

ast_ari_websocket_session_id()

const char * ast_ari_websocket_session_id

(

const struct ast_ari_websocket_session *

session

)

Get the Session ID for an ARI WebSocket.

Parameters

session

Session to query.

Returns

Session ID.

Return values

NULL

on error.

Definition at line 203 of file ari_websockets.c.

{
    return ast_websocket_session_id(session->ws_session);
}

References ast_websocket_session_id(), and session.

Referenced by ast_ari_websocket_events_event_websocket_established().

ast_ari_websocket_session_read()

struct ast_json * ast_ari_websocket_session_read

(

struct ast_ari_websocket_session *

session

)

Read a message from an ARI WebSocket.

Parameters

session

Session to read from.

Returns

Message received.

Return values

NULL	if WebSocket could not be read.

Definition at line 97 of file ari_websockets.c.

{
    RAII_VAR(struct ast_json *, message, NULL, ast_json_unref);
 
    if (ast_websocket_fd(session->ws_session) < 0) {
        return NULL;
    }
 
    while (!message) {
        int res;
        char *payload;
        uint64_t payload_len;
        enum ast_websocket_opcode opcode;
        int fragmented;
 
        res = ast_wait_for_input(
            ast_websocket_fd(session->ws_session), -1);
 
        if (res <= 0) {
            ast_log(LOG_WARNING, "WebSocket poll error: %s\n",
                strerror(errno));
            return NULL;
        }
 
        res = ast_websocket_read(session->ws_session, &payload,
            &payload_len, &opcode, &fragmented);
 
        if (res != 0) {
            ast_log(LOG_WARNING, "WebSocket read error: %s\n",
                strerror(errno));
            return NULL;
        }
 
        switch (opcode) {
        case AST_WEBSOCKET_OPCODE_CLOSE:
            ast_debug(1, "WebSocket closed\n");
            return NULL;
        case AST_WEBSOCKET_OPCODE_TEXT:
            message = ast_json_load_buf(payload, payload_len, NULL);
            if (message == NULL) {
                ast_log(LOG_WARNING,
                    "WebSocket input failed to parse\n");
            }
 
            break;
        default:
            /* Ignore all other message types */
            break;
        }
    }
 
    return ast_json_ref(message);
}

References ast_debug, ast_json_load_buf(), ast_json_ref(), ast_json_unref(), ast_log, ast_wait_for_input(), ast_websocket_fd(), AST_WEBSOCKET_OPCODE_CLOSE, AST_WEBSOCKET_OPCODE_TEXT, ast_websocket_read(), errno, LOG_WARNING, NULL, RAII_VAR, and session.

Referenced by ast_ari_websocket_events_event_websocket_established().

ast_ari_websocket_session_write()

int ast_ari_websocket_session_write	(	struct ast_ari_websocket_session *	session,
		struct ast_json *	message
	)

Send a message to an ARI WebSocket.

Parameters

session	Session to write to.
message	Message to send.

Return values

0	on success.
Non-zero	on error.

Definition at line 158 of file ari_websockets.c.

{
    RAII_VAR(char *, str, NULL, ast_json_free);
 
#ifdef AST_DEVMODE
    if (!session->validator(message)) {
        ast_log(LOG_ERROR, "Outgoing message failed validation\n");
        return ast_websocket_write_string(session->ws_session, VALIDATION_FAILED);
    }
#endif
 
    str = ast_json_dump_string_format(message, ast_ari_json_format());
 
    if (str == NULL) {
        ast_log(LOG_ERROR, "Failed to encode JSON object\n");
        return -1;
    }
 
    if (ast_websocket_write_string(session->ws_session, str)) {
        ast_log(LOG_NOTICE, "Problem occurred during websocket write to %s, websocket closed\n",
            ast_sockaddr_stringify(ast_ari_websocket_session_get_remote_addr(session)));
        return -1;
    }
    return 0;
}

References ast_ari_json_format(), ast_ari_websocket_session_get_remote_addr(), ast_json_dump_string_format(), ast_json_free(), ast_log, ast_sockaddr_stringify(), ast_websocket_write_string(), LOG_ERROR, LOG_NOTICE, NULL, RAII_VAR, session, str, and VALIDATION_FAILED.

Referenced by event_session_update_websocket(), and stasis_app_message_handler().