res_ari.c File Reference

HTTP binding for the Stasis API. More...

#include "asterisk.h"
#include "ari/internal.h"
#include "ari/ari_websockets.h"
#include "asterisk/ari.h"
#include "asterisk/astobj2.h"
#include "asterisk/module.h"
#include "asterisk/paths.h"
#include "asterisk/stasis_app.h"
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>

Include dependency graph for res_ari.c:

Go to the source code of this file.

Macros
#define	ACA_HEADERS   "Access-Control-Allow-Headers"
#define	ACA_METHODS   "Access-Control-Allow-Methods"
#define	ACR_HEADERS   "Access-Control-Request-Headers"
#define	ACR_METHOD   "Access-Control-Request-Method"

Functions
static void	__reg_module (void)
static void	__unreg_module (void)
static void	add_allow_header (struct stasis_rest_handlers *handler, struct ast_ari_response *response)
int	ast_ari_add_handler (struct stasis_rest_handlers *handler)
static int	ast_ari_callback (struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers)
	Callback for the root URI. More...
void	ast_ari_get_docs (const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response)
enum ast_ari_invoke_result	ast_ari_invoke (struct ast_tcptls_session_instance *ser, enum ast_ari_invoke_source source, const struct ast_http_uri *urih, 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_module *	AST_MODULE_SELF_SYM (void)
static struct ast_ari_conf_user *	authenticate_api_key (const char *api_key)
	Authenticate a ?api_key=userid:password More...
static struct ast_ari_conf_user *	authenticate_user (struct ast_variable *get_params, struct ast_variable *headers)
	Authenticate an HTTP request. More...
static struct stasis_rest_handlers *	get_root_handler (void)
static void	handle_options (struct stasis_rest_handlers *handler, struct ast_variable *headers, struct ast_ari_response *response)
	Handle OPTIONS request, mainly for CORS preflight requests. More...
static int	is_enabled (void)
	Helper function to check if module is enabled. More...
static int	load_module (void)
static int	origin_allowed (const char *origin)
static void	process_cors_request (struct ast_variable *headers, struct ast_ari_response *response)
	Handle CORS headers for simple requests. More...
static int	reload_module (void)
static void	remove_trailing_slash (const char *uri, struct ast_ari_response *response)
static struct stasis_rest_handlers *	root_handler_create (void)
static int	unload_module (void)

Variables
static struct ast_module_info	__mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk RESTful Interface" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .reload = reload_module, .requires = "http,res_stasis,res_http_websocket", .load_pri = AST_MODPRI_APP_DEPEND, }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct ast_http_uri	http_uri
static struct ast_json *	oom_json
static struct stasis_rest_handlers *	root_handler
static ast_mutex_t	root_handler_lock

Detailed Description

HTTP binding for the Stasis API.

Author

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

The API itself is documented using Swagger, a lightweight mechanism for documenting RESTful API's using JSON. This allows us to use swagger-ui to provide executable documentation for the API, generate client bindings in different languages, and generate a lot of the boilerplate code for implementing the RESTful bindings. The API docs live in the rest-api/ directory.

The RESTful bindings are generated from the Swagger API docs using a set of Mustache templates. The code generator is written in Python, and uses the Python implementation pystache. Pystache has no dependencies, and be installed easily using pip. Code generation code lives in rest-api-templates/.

The generated code reduces a lot of boilerplate when it comes to handling HTTP requests. It also helps us have greater consistency in the REST API.

The structure of the generated code is:

• res/ari/resource_{resource}.h
  • For each operation in the resource, a generated argument structure (holding the parsed arguments from the request) and function declarations (to implement in res/ari/resource_{resource}.c)
• res_ari_{resource}.c
  • A set of stasis_rest_callback functions, which glue the two together. They parse out path variables and request parameters to populate a specific *_args which is passed to the specific request handler (in res/ari/resource_{resource}.c)
  • A tree of stasis_rest_handlers for routing requests to its stasis_rest_callback

The basic flow of an HTTP request is:

• ast_ari_callback()
  1. Initial request validation
  2. Routes as either a doc request (ast_ari_get_docs) or API request (ast_ari_invoke)
     • ast_ari_invoke()
       1. Further request validation
       2. Routes the request through the tree of generated stasis_rest_handlers.
       3. Dispatch to the generated callback
          • ast_ari_*_cb
            1. Populate *_args struct with path and get params
            2. Invoke the request handler
  3. Validates and sends response

Definition in file res_ari.c.

Macro Definition Documentation

ACA_HEADERS

#define ACA_HEADERS   "Access-Control-Allow-Headers"

Definition at line 413 of file res_ari.c.

ACA_METHODS

#define ACA_METHODS   "Access-Control-Allow-Methods"

Definition at line 412 of file res_ari.c.

ACR_HEADERS

#define ACR_HEADERS   "Access-Control-Request-Headers"

Definition at line 411 of file res_ari.c.

ACR_METHOD

#define ACR_METHOD   "Access-Control-Request-Method"

Definition at line 410 of file res_ari.c.

Function Documentation

__reg_module()

static void __reg_module ( void  )

static

Definition at line 1326 of file res_ari.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 1326 of file res_ari.c.

add_allow_header()

static void add_allow_header ( struct stasis_rest_handlers *  handler, struct ast_ari_response *  response  )

static

Definition at line 375 of file res_ari.c.

{
    enum ast_http_method m;
    ast_str_append(&response->headers, 0,
               "Allow: OPTIONS");
    for (m = 0; m < AST_HTTP_MAX_METHOD; ++m) {
        if (handler->callbacks[m] != NULL) {
            ast_str_append(&response->headers, 0,
                       ",%s", ast_get_http_method(m));
        }
    }
    ast_str_append(&response->headers, 0, "\r\n");
}

References ast_get_http_method(), AST_HTTP_MAX_METHOD, ast_str_append(), handler(), ast_ari_response::headers, and NULL.

Referenced by ast_ari_invoke(), and handle_options().

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 239 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_callback()

static int ast_ari_callback ( struct ast_tcptls_session_instance *  ser, const struct ast_http_uri *  urih, const char *  uri, enum ast_http_method  method, struct ast_variable *  get_params, struct ast_variable *  headers  )

static

Callback for the root URI.

Definition at line 1036 of file res_ari.c.

{
    RAII_VAR(struct ast_str *, response_body, ast_str_create(256), ast_free);
    struct ast_ari_response response = { .fd = -1, 0 };
    RAII_VAR(struct ast_variable *, post_vars, NULL, ast_variables_destroy);
    struct ast_variable *var;
    const char *app_name = NULL;
    RAII_VAR(struct ast_json *, body, ast_json_null(), ast_json_unref);
    int debug_app = 0;
    enum ast_ari_invoke_result result;
    SCOPE_ENTER(2, "%s: Request: %s %s\n", ast_sockaddr_stringify(&ser->remote_address),
        ast_get_http_method(method), uri);
 
    if (!response_body) {
        ast_http_request_close_on_completion(ser);
        ast_http_error(ser, 500, "Server Error", "Out of memory");
        SCOPE_EXIT_RTN_VALUE(0, "Out of memory\n");
    }
 
    response.headers = ast_str_create(40);
    if (!response.headers) {
        ast_http_request_close_on_completion(ser);
        ast_http_error(ser, 500, "Server Error", "Out of memory");
        SCOPE_EXIT_RTN_VALUE(0, "Out of memory\n");
    }
 
    process_cors_request(headers, &response);
 
    /* Process form data from a POST. It could be mixed with query
     * parameters, which seems a bit odd. But it's allowed, so that's okay
     * with us.
     */
    post_vars = ast_http_get_post_vars(ser, headers);
    if (!post_vars) {
        ast_trace(-1, "No post_vars\n");
        switch (errno) {
        case EFBIG:
            ast_ari_response_error(&response, 413,
                "Request Entity Too Large",
                "Request body too large");
            goto request_failed;
        case ENOMEM:
            ast_http_request_close_on_completion(ser);
            ast_ari_response_error(&response, 500,
                "Internal Server Error",
                "Out of memory");
            goto request_failed;
        case EIO:
            ast_ari_response_error(&response, 400,
                "Bad Request", "Error parsing request body");
            goto request_failed;
        }
 
        /* Look for a JSON request entity only if there were no post_vars.
         * If there were post_vars, then the request body would already have
         * been consumed and can not be read again.
         */
        ast_trace(-1, "Checking body for vars\n");
        body = ast_http_get_json(ser, headers);
        if (!body) {
            switch (errno) {
            case EFBIG:
                ast_ari_response_error(&response, 413, "Request Entity Too Large", "Request body too large");
                goto request_failed;
            case ENOMEM:
                ast_ari_response_error(&response, 500, "Internal Server Error", "Error processing request");
                goto request_failed;
            case EIO:
                ast_ari_response_error(&response, 400, "Bad Request", "Error parsing request body");
                goto request_failed;
            }
        }
    }
    if (get_params == NULL) {
        ast_trace(-1, "No get_params, using post_vars if any\n");
        get_params = post_vars;
    } else if (get_params && post_vars) {
        /* Has both post_vars and get_params */
        struct ast_variable *last_var = post_vars;
        ast_trace(-1, "Has get_params and post_vars.  Merging\n");
        while (last_var->next) {
            last_var = last_var->next;
        }
        /* The duped get_params will get freed when post_vars gets
         * ast_variables_destroyed.
         */
        last_var->next = ast_variables_dup(get_params);
        get_params = post_vars;
    }
 
    /* At this point, get_params will contain post_vars (if any) */
    app_name = ast_variable_find_in_list(get_params, "app");
    if (!app_name) {
        struct ast_json *app = ast_json_object_get(body, "app");
 
        app_name = (app ? ast_json_string_get(app) : NULL);
    }
    ast_trace(-1, "app_name: %s\n", app_name);
 
    /* stasis_app_get_debug_by_name returns an "||" of the app's debug flag
     * and the global debug flag.
     */
    debug_app = stasis_app_get_debug_by_name(app_name);
    if (debug_app) {
        struct ast_str *buf = ast_str_create(512);
        char *str = ast_json_dump_string_format(body, ast_ari_json_format());
 
        if (!buf || (body && !str)) {
            ast_http_request_close_on_completion(ser);
            ast_ari_response_error(&response, 500, "Server Error", "Out of memory");
            ast_json_free(str);
            ast_free(buf);
            goto request_failed;
        }
 
        ast_str_append(&buf, 0, "<--- ARI request received from: %s --->\n",
            ast_sockaddr_stringify(&ser->remote_address));
        ast_str_append(&buf, 0, "%s %s\n", ast_get_http_method(method), uri);
        for (var = headers; var; var = var->next) {
            ast_str_append(&buf, 0, "%s: %s\n", var->name, var->value);
        }
        for (var = get_params; var; var = var->next) {
            ast_str_append(&buf, 0, "%s: %s\n", var->name, var->value);
        }
        ast_verbose("%sbody:\n%s\n\n", ast_str_buffer(buf), S_OR(str, ""));
        ast_json_free(str);
        ast_free(buf);
    }
 
    result = SCOPE_CALL_WITH_RESULT(-1, enum ast_ari_invoke_result,
        ast_ari_invoke, ser, ARI_INVOKE_SOURCE_REST,
        urih, uri, method, get_params, headers, body, &response);
    if (result == ARI_INVOKE_RESULT_ERROR_CLOSE) {
        ast_http_request_close_on_completion(ser);
    }
 
    if (response.no_response) {
        /* The handler indicates no further response is necessary.
         * Probably because it already handled it */
        ast_free(response.headers);
        SCOPE_EXIT_RTN_VALUE(0, "No response needed\n");
    }
 
request_failed:
 
    /* If you explicitly want to have no content, set message to
     * ast_json_null().
     */
    ast_assert(response.message != NULL);
    ast_assert(response.response_code > 0);
 
    /* response.message could be NULL, in which case the empty response_body
     * is correct
     */
    if (response.message && !ast_json_is_null(response.message)) {
        ast_str_append(&response.headers, 0,
                   "Content-type: application/json\r\n");
        if (ast_json_dump_str_format(response.message, &response_body,
            ast_ari_json_format()) != 0) {
            /* Error encoding response */
            response.response_code = 500;
            response.response_text = "Internal Server Error";
            ast_str_set(&response_body, 0, "%s", "");
            ast_str_set(&response.headers, 0, "%s", "");
        }
    }
 
    if (debug_app) {
        ast_verbose("<--- Sending ARI response to %s --->\n%d %s\n%s%s\n\n",
            ast_sockaddr_stringify(&ser->remote_address), response.response_code,
            response.response_text, ast_str_buffer(response.headers),
            ast_str_buffer(response_body));
    }
 
    ast_http_send(ser, method, response.response_code,
              response.response_text, response.headers, response_body,
              response.fd != -1 ? response.fd : 0, 0);
    /* ast_http_send takes ownership, so we don't have to free them */
    response_body = NULL;
 
    ast_json_unref(response.message);
    if (response.fd >= 0) {
        close(response.fd);
    }
    SCOPE_EXIT_RTN_VALUE(0, "Done.  response: %d : %s\n", response.response_code,
        response.response_text);
}

References app, app_name(), ARI_INVOKE_RESULT_ERROR_CLOSE, ARI_INVOKE_SOURCE_REST, ast_ari_invoke(), ast_ari_json_format(), ast_ari_response_error(), ast_assert, ast_free, ast_get_http_method(), ast_http_error(), ast_http_get_json(), ast_http_get_post_vars(), ast_http_request_close_on_completion(), ast_http_send(), ast_json_dump_str_format(), ast_json_dump_string_format(), ast_json_free(), ast_json_is_null(), ast_json_null(), ast_json_object_get(), ast_json_string_get(), ast_json_unref(), ast_sockaddr_stringify(), ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_set(), ast_trace, ast_variable_find_in_list(), ast_variables_destroy(), ast_variables_dup(), ast_verbose(), buf, errno, ast_ari_response::fd, ast_ari_response::headers, ast_ari_response::message, method, ast_variable::next, ast_ari_response::no_response, NULL, process_cors_request(), RAII_VAR, ast_tcptls_session_instance::remote_address, ast_ari_response::response_code, ast_ari_response::response_text, result, S_OR, SCOPE_CALL_WITH_RESULT, SCOPE_ENTER, SCOPE_EXIT_RTN_VALUE, stasis_app_get_debug_by_name(), str, and var.

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 833 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_invoke(), and AST_TEST_DEFINE().

ast_ari_invoke()

enum ast_ari_invoke_result ast_ari_invoke	(	struct ast_tcptls_session_instance *	ser,
		enum ast_ari_invoke_source	source,
		const struct ast_http_uri *	urih,
		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 635 of file res_ari.c.

{
    RAII_VAR(struct stasis_rest_handlers *, root, NULL, ao2_cleanup);
    struct stasis_rest_handlers *handler = NULL;
    struct stasis_rest_handlers *wildcard_handler = NULL;
    RAII_VAR(struct ast_variable *, path_vars, NULL, ast_variables_destroy);
    RAII_VAR(struct ast_ari_conf_user *, user, NULL, ao2_cleanup);
    RAII_VAR(struct ast_ari_conf *, conf, ast_ari_config_get(), ao2_cleanup);
 
    char *path = ast_strdupa(uri);
    char *path_segment = NULL;
    stasis_rest_callback callback;
    SCOPE_ENTER(3, "Request: %s %s, path:%s\n", ast_get_http_method(method), uri, path);
 
 
    if (!conf || !conf->general) {
        if (ser && source == ARI_INVOKE_SOURCE_REST) {
            ast_http_request_close_on_completion(ser);
        }
        ast_ari_response_error(response, 500, "Server Error", "URI handler config missing");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CLOSE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    }
 
    user = authenticate_user(get_params, headers);
 
    if (!user && source == ARI_INVOKE_SOURCE_REST) {
        /* Per RFC 2617, section 1.2: The 401 (Unauthorized) response
         * message is used by an origin server to challenge the
         * authorization of a user agent. This response MUST include a
         * WWW-Authenticate header field containing at least one
         * challenge applicable to the requested resource.
         */
        ast_ari_response_error(response, 401, "Unauthorized", "Authentication required");
 
        /* Section 1.2:
         *   realm       = "realm" "=" realm-value
         *   realm-value = quoted-string
         * Section 2:
         *   challenge   = "Basic" realm
         */
        ast_str_append(&response->headers, 0,
            "WWW-Authenticate: Basic realm=\"%s\"\r\n",
            conf->general->auth_realm);
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    } else if (!ast_fully_booted) {
        ast_ari_response_error(response, 503, "Service Unavailable", "Asterisk not booted");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CLOSE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    } else if (user && user->read_only && method != AST_HTTP_GET && method != AST_HTTP_OPTIONS) {
        ast_ari_response_error(response, 403, "Forbidden", "Write access denied");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    } else if (ast_ends_with(uri, "/")) {
        remove_trailing_slash(uri, response);
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    } else if (ast_begins_with(uri, "api-docs/")) {
        /* Serving up API docs */
        if (method != AST_HTTP_GET) {
            ast_ari_response_error(response, 405, "Method Not Allowed", "Unsupported method");
        } else {
            if (urih) {
                /* Skip the api-docs prefix */
                ast_ari_get_docs(strchr(uri, '/') + 1, urih->prefix, headers, response);
            } else {
                /*
                 * If we were invoked without a urih, we're probably
                 * being called from the websocket so just use the
                 * default prefix.  It's filled in by ast_http_uri_link().
                 */
                ast_ari_get_docs(strchr(uri, '/') + 1, http_uri.prefix, headers, response);
            }
        }
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    }
 
    root = handler = get_root_handler();
    ast_assert(root != NULL);
 
    while ((path_segment = strsep(&path, "/")) && (strlen(path_segment) > 0)) {
        struct stasis_rest_handlers *found_handler = NULL;
        int i;
        SCOPE_ENTER(4, "Finding handler for path segment %s\n", path_segment);
 
        ast_uri_decode(path_segment, ast_uri_http_legacy);
 
        for (i = 0; found_handler == NULL && i < handler->num_children; ++i) {
            struct stasis_rest_handlers *child = handler->children[i];
            SCOPE_ENTER(5, "Checking handler path segment %s\n", child->path_segment);
 
            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_trace(-1, "        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_trace(-1, "        Checking %s %s:  Explicit match with %s\n", handler->path_segment, child->path_segment, path_segment);
            } else {
                ast_trace(-1, "        Checking %s %s:  Didn't match %s\n", handler->path_segment, child->path_segment, path_segment);
            }
            SCOPE_EXIT("Done checking %s\n", child->path_segment);
        }
 
        if (!found_handler && wildcard_handler) {
            ast_trace(-1, "  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_ari_response_error(
                response, 404, "Not Found",
                "Resource not found");
            SCOPE_EXIT_EXPR(break, "Handler not found for %s\n", path_segment);
        } else {
            handler = found_handler;
        }
        SCOPE_EXIT("Done checking %s\n", path_segment);
    }
 
    if (handler == NULL || response->response_code == 404) {
        /* resource not found */
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s %s\n",
            response->response_code, response->response_text, uri);
    }
 
    ast_assert(handler != NULL);
    if (method == AST_HTTP_OPTIONS) {
        handle_options(handler, headers, response);
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Was options\n");
    }
 
    if (method < 0 || method >= AST_HTTP_MAX_METHOD) {
        add_allow_header(handler, response);
        ast_ari_response_error(
            response, 405, "Method Not Allowed",
            "Invalid method");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    }
 
    if (handler->is_websocket && method == AST_HTTP_GET) {
        if (source == ARI_INVOKE_SOURCE_WEBSOCKET) {
            ast_ari_response_error(
                response, 400, "Bad request",
                "Can't upgrade to websocket from a websocket");
            SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
                response->response_code, response->response_text);
        }
        /* WebSocket! */
        ast_trace(-1, "Handling websocket %s\n", uri);
        ari_handle_websocket(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;
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Upgrade to websocket\n");
    }
 
    callback = handler->callbacks[method];
    if (callback == NULL) {
        add_allow_header(handler, response);
        ast_ari_response_error(
            response, 405, "Method Not Allowed",
            "Invalid method");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    }
 
    ast_trace(-1, "Running callback: %s\n", uri);
    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");
        SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_ERROR_CONTINUE, "Response: %d : %s\n",
            response->response_code, response->response_text);
    }
    SCOPE_EXIT_RTN_VALUE(ARI_INVOKE_RESULT_SUCCESS, "Response: %d : %s\n",
        response->response_code, response->response_text);
}

References add_allow_header(), ao2_cleanup, ari_handle_websocket(), ARI_INVOKE_RESULT_ERROR_CLOSE, ARI_INVOKE_RESULT_ERROR_CONTINUE, ARI_INVOKE_RESULT_SUCCESS, ARI_INVOKE_SOURCE_REST, ARI_INVOKE_SOURCE_WEBSOCKET, ast_ari_config_get(), ast_ari_get_docs(), ast_ari_response_error(), ast_assert, ast_begins_with(), ast_ends_with(), ast_fully_booted, ast_get_http_method(), AST_HTTP_GET, AST_HTTP_MAX_METHOD, AST_HTTP_OPTIONS, ast_http_request_close_on_completion(), ast_log, ast_str_append(), ast_strdupa, ast_trace, ast_uri_decode(), ast_uri_http_legacy, ast_variable_new, ast_variables_destroy(), authenticate_user(), callback(), conf::general, get_root_handler(), handle_options(), handler(), ast_ari_response::headers, http_uri, 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, ast_http_uri::prefix, RAII_VAR, remove_trailing_slash(), ast_ari_response::response_code, ast_ari_response::response_text, SCOPE_ENTER, SCOPE_EXIT, SCOPE_EXIT_EXPR, SCOPE_EXIT_RTN_VALUE, and strsep().

Referenced by ari_websocket_process_request(), 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 1015 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 ari_ws_session_write(), and ast_ari_callback().

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 234 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 262 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 351 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 358 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_transfer_progress_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_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(), parse_app_args(), 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 365 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 319 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_transfer_progress(), ast_ari_channels_transfer_progress_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_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(), parse_app_args(), 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 344 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_transfer_progress(), 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 336 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_MODULE_SELF_SYM()

struct ast_module * AST_MODULE_SELF_SYM

(

void

)

Definition at line 1326 of file res_ari.c.

authenticate_api_key()

static struct ast_ari_conf_user * authenticate_api_key ( const char *  api_key )

static

Authenticate a ?api_key=userid:password

Parameters

api_key

API key query parameter

Returns

User object for the authenticated user.

Return values

NULL	if authentication failed.

Definition at line 558 of file res_ari.c.

{
    RAII_VAR(char *, copy, NULL, ast_free);
    char *username;
    char *password;
 
    password = copy = ast_strdup(api_key);
    if (!copy) {
        return NULL;
    }
 
    username = strsep(&password, ":");
    if (!password) {
        ast_log(LOG_WARNING, "Invalid api_key\n");
        return NULL;
    }
 
    return ast_ari_config_validate_user(username, password);
}

References ast_ari_config_validate_user(), ast_free, ast_log, ast_strdup, copy(), LOG_WARNING, NULL, ast_ari_conf_user::password, RAII_VAR, strsep(), and ast_ari_conf_user::username.

Referenced by authenticate_user().

authenticate_user()

static struct ast_ari_conf_user * authenticate_user ( struct ast_variable *  get_params, struct ast_variable *  headers  )

static

Authenticate an HTTP request.

Parameters

get_params	GET parameters of the request.
headers	HTTP headers.

Returns

User object for the authenticated user.

Return values

NULL	if authentication failed.

Definition at line 586 of file res_ari.c.

{
    RAII_VAR(struct ast_http_auth *, http_auth, NULL, ao2_cleanup);
    struct ast_variable *v;
 
    /* HTTP Basic authentication */
    http_auth = ast_http_get_auth(headers);
    if (http_auth) {
        return ast_ari_config_validate_user(http_auth->userid,
            http_auth->password);
    }
 
    /* ?api_key authentication */
    for (v = get_params; v; v = v->next) {
        if (strcasecmp("api_key", v->name) == 0) {
            return authenticate_api_key(v->value);
        }
    }
 
    return NULL;
}

References ao2_cleanup, ast_ari_config_validate_user(), ast_http_get_auth(), authenticate_api_key(), ast_variable::name, ast_variable::next, NULL, RAII_VAR, and ast_variable::value.

Referenced by ast_ari_invoke().

get_root_handler()

static struct stasis_rest_handlers * get_root_handler ( void  )

static

Definition at line 298 of file res_ari.c.

{
    SCOPED_MUTEX(lock, &root_handler_lock);
    ao2_ref(root_handler, +1);
    return root_handler;
}

References ao2_ref, lock, root_handler, root_handler_lock, and SCOPED_MUTEX.

Referenced by ast_ari_invoke(), and ast_ari_response_created().

handle_options()

static void handle_options ( struct stasis_rest_handlers *  handler, struct ast_variable *  headers, struct ast_ari_response *  response  )

static

Handle OPTIONS request, mainly for CORS preflight requests.

Some browsers will send this prior to non-simple methods (i.e. DELETE). See http://www.w3.org/TR/cors/ for the spec. Especially section 6.2.

Definition at line 421 of file res_ari.c.

{
    struct ast_variable *header;
    char const *acr_method = NULL;
    char const *acr_headers = NULL;
    char const *origin = NULL;
 
    RAII_VAR(struct ast_str *, allow, NULL, ast_free);
    enum ast_http_method m;
    int allowed = 0;
 
    /* Regular OPTIONS response */
    add_allow_header(handler, response);
    ast_ari_response_no_content(response);
 
    /* Parse CORS headers */
    for (header = headers; header != NULL; header = header->next) {
        if (strcmp(ACR_METHOD, header->name) == 0) {
            acr_method = header->value;
        } else if (strcmp(ACR_HEADERS, header->name) == 0) {
            acr_headers = header->value;
        } else if (strcmp("Origin", header->name) == 0) {
            origin = header->value;
        }
    }
 
    /* CORS 6.2, #1 - "If the Origin header is not present terminate this
     * set of steps."
     */
    if (origin == NULL) {
        return;
    }
 
    /* CORS 6.2, #2 - "If the value of the Origin header is not a
     * case-sensitive match for any of the values in list of origins do not
     * set any additional headers and terminate this set of steps.
     *
     * Always matching is acceptable since the list of origins can be
     * unbounded.
     *
     * The Origin header can only contain a single origin as the user agent
     * will not follow redirects."
     */
    if (!origin_allowed(origin)) {
        ast_log(LOG_NOTICE, "Origin header '%s' does not match an allowed origin.\n", origin);
        return;
    }
 
    /* CORS 6.2, #3 - "If there is no Access-Control-Request-Method header
     * or if parsing failed, do not set any additional headers and terminate
     * this set of steps."
     */
    if (acr_method == NULL) {
        return;
    }
 
    /* CORS 6.2, #4 - "If there are no Access-Control-Request-Headers
     * headers let header field-names be the empty list."
     */
    if (acr_headers == NULL) {
        acr_headers = "";
    }
 
    /* CORS 6.2, #5 - "If method is not a case-sensitive match for any of
     * the values in list of methods do not set any additional headers and
     * terminate this set of steps."
     */
    allow = ast_str_create(20);
 
    if (!allow) {
        ast_ari_response_alloc_failed(response);
        return;
    }
 
    /* Go ahead and build the ACA_METHODS header at the same time */
    for (m = 0; m < AST_HTTP_MAX_METHOD; ++m) {
        if (handler->callbacks[m] != NULL) {
            char const *m_str = ast_get_http_method(m);
            if (strcmp(m_str, acr_method) == 0) {
                allowed = 1;
            }
            ast_str_append(&allow, 0, ",%s", m_str);
        }
    }
 
    if (!allowed) {
        return;
    }
 
    /* CORS 6.2 #6 - "If any of the header field-names is not a ASCII
     * case-insensitive match for any of the values in list of headers do
     * not set any additional headers and terminate this set of steps.
     *
     * Note: Always matching is acceptable since the list of headers can be
     * unbounded."
     */
 
    /* CORS 6.2 #7 - "If the resource supports credentials add a single
     * Access-Control-Allow-Origin header, with the value of the Origin
     * header as value, and add a single Access-Control-Allow-Credentials
     * header with the case-sensitive string "true" as value."
     *
     * Added by process_cors_request() earlier in the request.
     */
 
    /* CORS 6.2 #8 - "Optionally add a single Access-Control-Max-Age
     * header..."
     */
 
    /* CORS 6.2 #9 - "Add one or more Access-Control-Allow-Methods headers
     * consisting of (a subset of) the list of methods."
     */
    ast_str_append(&response->headers, 0, "%s: OPTIONS%s\r\n",
               ACA_METHODS, ast_str_buffer(allow));
 
 
    /* CORS 6.2, #10 - "Add one or more Access-Control-Allow-Headers headers
     * consisting of (a subset of) the list of headers.
     *
     * Since the list of headers can be unbounded simply returning headers
     * can be enough."
     */
    if (!ast_strlen_zero(acr_headers)) {
        ast_str_append(&response->headers, 0, "%s: %s\r\n",
                   ACA_HEADERS, acr_headers);
    }
}

References ACA_HEADERS, ACA_METHODS, ACR_HEADERS, ACR_METHOD, add_allow_header(), ast_ari_response_alloc_failed(), ast_ari_response_no_content(), ast_free, ast_get_http_method(), AST_HTTP_MAX_METHOD, ast_log, ast_str_append(), ast_str_buffer(), ast_str_create, ast_strlen_zero(), handler(), ast_ari_response::headers, LOG_NOTICE, header::name, header::next, NULL, origin_allowed(), RAII_VAR, and header::value.

Referenced by ast_ari_invoke().

is_enabled()

static int is_enabled ( void  )

static

Helper function to check if module is enabled.

Definition at line 203 of file res_ari.c.

{
    RAII_VAR(struct ast_ari_conf *, cfg, ast_ari_config_get(), ao2_cleanup);
    return cfg && cfg->general && cfg->general->enabled;
}

References ao2_cleanup, ast_ari_config_get(), and RAII_VAR.

Referenced by ast_cel_set_config(), load_module(), reload_module(), and unload_module().

load_module()

static int load_module ( void  )

static

Definition at line 1252 of file res_ari.c.

{
    ast_mutex_init(&root_handler_lock);
 
    /* root_handler may have been built during a declined load */
    if (!root_handler) {
        root_handler = root_handler_create();
    }
    if (!root_handler) {
        return AST_MODULE_LOAD_DECLINE;
    }
 
    /* oom_json may have been built during a declined load */
    if (!oom_json) {
        oom_json = ast_json_pack(
            "{s: s}", "error", "Allocation failed");
    }
    if (!oom_json) {
        /* Ironic */
        unload_module();
        return AST_MODULE_LOAD_DECLINE;
    }
 
    if (ast_ari_config_init() != 0) {
        unload_module();
        return AST_MODULE_LOAD_DECLINE;
    }
 
    if (ari_websocket_load_module() != AST_MODULE_LOAD_SUCCESS) {
        unload_module();
        return AST_MODULE_LOAD_DECLINE;
    }
 
    if (is_enabled()) {
        ast_debug(3, "ARI enabled\n");
        ast_http_uri_link(&http_uri);
    } else {
        ast_debug(3, "ARI disabled\n");
    }
 
    if (ast_ari_cli_register() != 0) {
        unload_module();
        return AST_MODULE_LOAD_DECLINE;
    }
 
    return AST_MODULE_LOAD_SUCCESS;
}

References ari_websocket_load_module(), ast_ari_cli_register(), ast_ari_config_init(), ast_debug, ast_http_uri_link(), ast_json_pack(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, ast_mutex_init, http_uri, is_enabled(), oom_json, root_handler, root_handler_create(), root_handler_lock, and unload_module().

origin_allowed()

static int origin_allowed ( const char *  origin )

static

Definition at line 390 of file res_ari.c.

{
    RAII_VAR(struct ast_ari_conf *, cfg, ast_ari_config_get(), ao2_cleanup);
 
    char *allowed = ast_strdupa(cfg->general->allowed_origins);
    char *current;
 
    while ((current = strsep(&allowed, ","))) {
        if (!strcmp(current, "*")) {
            return 1;
        }
 
        if (!strcmp(current, origin)) {
            return 1;
        }
    }
 
    return 0;
}

References ao2_cleanup, ast_ari_config_get(), ast_strdupa, current, RAII_VAR, and strsep().

Referenced by handle_options(), and process_cors_request().

process_cors_request()

static void process_cors_request ( struct ast_variable *  headers, struct ast_ari_response *  response  )

static

Handle CORS headers for simple requests.

See http://www.w3.org/TR/cors/ for the spec. Especially section 6.1.

Definition at line 962 of file res_ari.c.

{
    char const *origin = NULL;
    struct ast_variable *header;
 
    /* Parse CORS headers */
    for (header = headers; header != NULL; header = header->next) {
        if (strcmp("Origin", header->name) == 0) {
            origin = header->value;
        }
    }
 
    /* CORS 6.1, #1 - "If the Origin header is not present terminate this
     * set of steps."
     */
    if (origin == NULL) {
        return;
    }
 
    /* CORS 6.1, #2 - "If the value of the Origin header is not a
     * case-sensitive match for any of the values in list of origins, do not
     * set any additional headers and terminate this set of steps.
     *
     * Note: Always matching is acceptable since the list of origins can be
     * unbounded."
     */
    if (!origin_allowed(origin)) {
        ast_log(LOG_NOTICE, "Origin header '%s' does not match an allowed origin.\n", origin);
        return;
    }
 
    /* CORS 6.1, #3 - "If the resource supports credentials add a single
     * Access-Control-Allow-Origin header, with the value of the Origin
     * header as value, and add a single Access-Control-Allow-Credentials
     * header with the case-sensitive string "true" as value.
     *
     * Otherwise, add a single Access-Control-Allow-Origin header, with
     * either the value of the Origin header or the string "*" as value."
     */
    ast_str_append(&response->headers, 0,
               "Access-Control-Allow-Origin: %s\r\n", origin);
    ast_str_append(&response->headers, 0,
               "Access-Control-Allow-Credentials: true\r\n");
 
    /* CORS 6.1, #4 - "If the list of exposed headers is not empty add one
     * or more Access-Control-Expose-Headers headers, with as values the
     * header field names given in the list of exposed headers."
     *
     * No exposed headers; skipping
     */
}

References ast_log, ast_str_append(), ast_ari_response::headers, LOG_NOTICE, header::name, header::next, NULL, origin_allowed(), and header::value.

Referenced by ast_ari_callback().

reload_module()

static int reload_module ( void  )

static

Definition at line 1300 of file res_ari.c.

{
    char was_enabled = is_enabled();
 
    if (ast_ari_config_reload() != 0) {
        return AST_MODULE_LOAD_DECLINE;
    }
 
    if (was_enabled && !is_enabled()) {
        ast_debug(3, "Disabling ARI\n");
        ast_http_uri_unlink(&http_uri);
    } else if (!was_enabled && is_enabled()) {
        ast_debug(3, "Enabling ARI\n");
        ast_http_uri_link(&http_uri);
    }
 
    return AST_MODULE_LOAD_SUCCESS;
}

References ast_ari_config_reload(), ast_debug, ast_http_uri_link(), ast_http_uri_unlink(), AST_MODULE_LOAD_DECLINE, AST_MODULE_LOAD_SUCCESS, http_uri, and is_enabled().

remove_trailing_slash()

static void remove_trailing_slash ( const char *  uri, struct ast_ari_response *  response  )

static

Definition at line 609 of file res_ari.c.

{
    char *slashless = ast_strdupa(uri);
    slashless[strlen(slashless) - 1] = '\0';
 
    /* While it's tempting to redirect the client to the slashless URL,
     * that is problematic. A 302 Found is the most appropriate response,
     * but most clients issue a GET on the location you give them,
     * regardless of the method of the original request.
     *
     * While there are some ways around this, it gets into a lot of client
     * specific behavior and corner cases in the HTTP standard. There's also
     * very little practical benefit of redirecting; only GET and HEAD can
     * be redirected automagically; all other requests "MUST NOT
     * automatically redirect the request unless it can be confirmed by the
     * user, since this might change the conditions under which the request
     * was issued."
     *
     * Given all of that, a 404 with a nice message telling them what to do
     * is probably our best bet.
     */
    ast_ari_response_error(response, 404, "Not Found",
        "ARI URLs do not end with a slash. Try /ari/%s", slashless);
}

References ast_ari_response_error(), and ast_strdupa.

Referenced by ast_ari_invoke().

root_handler_create()

static struct stasis_rest_handlers * root_handler_create ( void  )

static

Definition at line 305 of file res_ari.c.

{
    RAII_VAR(struct stasis_rest_handlers *, handler, NULL, ao2_cleanup);
 
    handler = ao2_alloc(sizeof(*handler), NULL);
    if (!handler) {
        return NULL;
    }
    handler->path_segment = "ari";
 
    ao2_ref(handler, +1);
    return handler;
}

References ao2_alloc, ao2_cleanup, ao2_ref, handler(), NULL, and RAII_VAR.

Referenced by load_module().

unload_module()

static int unload_module ( void  )

static

Definition at line 1229 of file res_ari.c.

{
    ari_websocket_unload_module();
 
    ast_ari_cli_unregister();
 
    if (is_enabled()) {
        ast_debug(3, "Disabling ARI\n");
        ast_http_uri_unlink(&http_uri);
    }
 
    ast_ari_config_destroy();
 
    ao2_cleanup(root_handler);
    root_handler = NULL;
    ast_mutex_destroy(&root_handler_lock);
 
    ast_json_unref(oom_json);
    oom_json = NULL;
 
    return 0;
}

References ao2_cleanup, ari_websocket_unload_module(), ast_ari_cli_unregister(), ast_ari_config_destroy(), ast_debug, ast_http_uri_unlink(), ast_json_unref(), ast_mutex_destroy, http_uri, is_enabled(), NULL, oom_json, root_handler, and root_handler_lock.

Referenced by load_module().

Variable Documentation

__mod_info

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Asterisk RESTful Interface" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .reload = reload_module, .requires = "http,res_stasis,res_http_websocket", .load_pri = AST_MODPRI_APP_DEPEND, }

static

Definition at line 1326 of file res_ari.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 1326 of file res_ari.c.

http_uri

struct ast_http_uri http_uri

static

Definition at line 224 of file res_ari.c.

Referenced by ast_ari_invoke(), load_module(), reload_module(), and unload_module().

oom_json

struct ast_json* oom_json

static

Pre-defined message for allocation failures.

Definition at line 216 of file res_ari.c.

Referenced by ast_ari_oom_json(), ast_ari_response_alloc_failed(), load_module(), and unload_module().

root_handler

struct stasis_rest_handlers* root_handler

static

Handler for root RESTful resource.

Definition at line 213 of file res_ari.c.

Referenced by ast_ari_add_handler(), ast_ari_remove_handler(), get_root_handler(), load_module(), and unload_module().

root_handler_lock

ast_mutex_t root_handler_lock

static

Lock for root_handler

Definition at line 210 of file res_ari.c.

Referenced by ast_ari_add_handler(), ast_ari_remove_handler(), get_root_handler(), load_module(), and unload_module().