refer.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2023, Commend International
 *
 * Maximilian Fridrich <m.fridrich@commend.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */
 
/*! \file
 *
 * \brief Out-of-call refer support
 *
 * \author Maximilian Fridrich <m.fridrich@commend.com>
 */
 
/*** MODULEINFO
    <support_level>core</support_level>
 ***/
 
#include "asterisk.h"
 
#include "asterisk/_private.h"
 
#include "asterisk/module.h"
#include "asterisk/datastore.h"
#include "asterisk/pbx.h"
#include "asterisk/manager.h"
#include "asterisk/strings.h"
#include "asterisk/astobj2.h"
#include "asterisk/vector.h"
#include "asterisk/app.h"
#include "asterisk/taskprocessor.h"
#include "asterisk/refer.h"
 
struct refer_data {
    /* Stored in stuff[] at struct end */
    char *name;
    /* Stored separately */
    char *value;
    /* Holds name */
    char stuff[0];
};
 
/*!
 * \brief A refer.
 */
struct ast_refer {
    AST_DECLARE_STRING_FIELDS(
        /*! Where the refer is going */
        AST_STRING_FIELD(to);
        /*! Where we "say" the refer came from */
        AST_STRING_FIELD(from);
        /*! Where to refer to */
        AST_STRING_FIELD(refer_to);
        /*! An endpoint associated with this refer */
        AST_STRING_FIELD(endpoint);
        /*! The technology of the endpoint associated with this refer */
        AST_STRING_FIELD(tech);
    );
    /* Whether to refer to Asterisk itself, if refer_to is an Asterisk endpoint. */
    int to_self;
    /*! Technology/dialplan specific variables associated with the refer */
    struct ao2_container *vars;
};
 
/*! \brief Lock for \c refer_techs vector */
static ast_rwlock_t refer_techs_lock;
 
/*! \brief Vector of refer technologies */
AST_VECTOR(, const struct ast_refer_tech *) refer_techs;
 
static int refer_data_cmp_fn(void *obj, void *arg, int flags)
{
    const struct refer_data *object_left = obj;
    const struct refer_data *object_right = arg;
    const char *right_key = arg;
    int cmp;
 
    switch (flags & OBJ_SEARCH_MASK) {
    case OBJ_SEARCH_OBJECT:
        right_key = object_right->name;
    case OBJ_SEARCH_KEY:
        cmp = strcasecmp(object_left->name, right_key);
        break;
    case OBJ_SEARCH_PARTIAL_KEY:
        cmp = strncasecmp(object_left->name, right_key, strlen(right_key));
        break;
    default:
        cmp = 0;
        break;
    }
    if (cmp) {
        return 0;
    }
    return CMP_MATCH;
}
 
static void refer_data_destructor(void *obj)
{
    struct refer_data *data = obj;
    ast_free(data->value);
}
 
static void refer_destructor(void *obj)
{
    struct ast_refer *refer = obj;
 
    ast_string_field_free_memory(refer);
    ao2_cleanup(refer->vars);
}
 
struct ast_refer *ast_refer_alloc(void)
{
    struct ast_refer *refer;
 
    if (!(refer = ao2_alloc_options(sizeof(*refer), refer_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK))) {
        return NULL;
    }
 
    if (ast_string_field_init(refer, 128)) {
        ao2_ref(refer, -1);
        return NULL;
    }
 
    refer->vars = ao2_container_alloc_list(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
        NULL, refer_data_cmp_fn);
    if (!refer->vars) {
        ao2_ref(refer, -1);
        return NULL;
    }
    refer->to_self = 0;
 
    return refer;
}
 
struct ast_refer *ast_refer_ref(struct ast_refer *refer)
{
    ao2_ref(refer, 1);
    return refer;
}
 
struct ast_refer *ast_refer_destroy(struct ast_refer *refer)
{
    ao2_ref(refer, -1);
    return NULL;
}
 
int ast_refer_set_to(struct ast_refer *refer, const char *fmt, ...)
{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, to, fmt, ap);
    va_end(ap);
 
    return 0;
}
 
int ast_refer_set_from(struct ast_refer *refer, const char *fmt, ...)
{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, from, fmt, ap);
    va_end(ap);
 
    return 0;
}
 
int ast_refer_set_refer_to(struct ast_refer *refer, const char *fmt, ...)
{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, refer_to, fmt, ap);
    va_end(ap);
 
    return 0;
}
 
int ast_refer_set_to_self(struct ast_refer *refer, int val)
{
    refer->to_self = val;
    return 0;
}
 
int ast_refer_set_tech(struct ast_refer *refer, const char *fmt, ...)
{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, tech, fmt, ap);
    va_end(ap);
 
    return 0;
}
 
int ast_refer_set_endpoint(struct ast_refer *refer, const char *fmt, ...)
{
    va_list ap;
 
    va_start(ap, fmt);
    ast_string_field_build_va(refer, endpoint, fmt, ap);
    va_end(ap);
 
    return 0;
}
 
const char *ast_refer_get_refer_to(const struct ast_refer *refer)
{
    return refer->refer_to;
}
 
const char *ast_refer_get_from(const struct ast_refer *refer)
{
    return refer->from;
}
 
const char *ast_refer_get_to(const struct ast_refer *refer)
{
    return refer->to;
}
 
int ast_refer_get_to_self(const struct ast_refer *refer)
{
    return refer->to_self;
}
 
const char *ast_refer_get_tech(const struct ast_refer *refer)
{
    return refer->tech;
}
 
const char *ast_refer_get_endpoint(const struct ast_refer *refer)
{
    return refer->endpoint;
}
 
static struct refer_data *refer_data_new(const char *name)
{
    struct refer_data *data;
    int name_len = strlen(name) + 1;
 
    if ((data = ao2_alloc_options(name_len + sizeof(*data), refer_data_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK))) {
        data->name = data->stuff;
        strcpy(data->name, name);
    }
 
    return data;
}
 
static struct refer_data *refer_data_find(struct ao2_container *vars, const char *name)
{
    return ao2_find(vars, name, OBJ_SEARCH_KEY);
}
 
char *ast_refer_get_var_and_unlink(struct ast_refer *refer, const char *name)
{
    struct refer_data *data;
    char *val = NULL;
 
    if (!(data = ao2_find(refer->vars, name, OBJ_SEARCH_KEY | OBJ_UNLINK))) {
        return NULL;
    }
 
    val = ast_strdup(data->value);
    ao2_ref(data, -1);
 
    return val;
}
 
static int refer_set_var_full(struct ast_refer *refer, const char *name, const char *value)
{
    struct refer_data *data;
 
    if (!(data = refer_data_find(refer->vars, name))) {
        if (ast_strlen_zero(value)) {
            return 0;
        }
        if (!(data = refer_data_new(name))) {
            return -1;
        };
        data->value = ast_strdup(value);
 
        ao2_link(refer->vars, data);
    } else {
        if (ast_strlen_zero(value)) {
            ao2_unlink(refer->vars, data);
        } else {
            ast_free(data->value);
            data->value = ast_strdup(value);
        }
    }
 
    ao2_ref(data, -1);
 
    return 0;
}
 
int ast_refer_set_var_outbound(struct ast_refer *refer, const char *name, const char *value)
{
    return refer_set_var_full(refer, name, value);
}
 
const char *ast_refer_get_var(struct ast_refer *refer, const char *name)
{
    struct refer_data *data;
    const char *val = NULL;
 
    if (!(data = refer_data_find(refer->vars, name))) {
        return NULL;
    }
 
    val = data->value;
    ao2_ref(data, -1);
 
    return val;
}
 
struct ast_refer_var_iterator {
    struct ao2_iterator iter;
    struct refer_data *current_used;
};
 
struct ast_refer_var_iterator *ast_refer_var_iterator_init(const struct ast_refer *refer)
{
    struct ast_refer_var_iterator *iter;
 
    iter = ast_calloc(1, sizeof(*iter));
    if (!iter) {
        return NULL;
    }
 
    iter->iter = ao2_iterator_init(refer->vars, 0);
 
    return iter;
}
 
int ast_refer_var_iterator_next(struct ast_refer_var_iterator *iter, const char **name, const char **value)
{
    struct refer_data *data;
 
    if (!iter) {
        return 0;
    }
 
    data = ao2_iterator_next(&iter->iter);
    if (!data) {
        return 0;
    }
 
    *name = data->name;
    *value = data->value;
 
    iter->current_used = data;
 
    return 1;
}
 
void ast_refer_var_unref_current(struct ast_refer_var_iterator *iter)
{
    ao2_cleanup(iter->current_used);
    iter->current_used = NULL;
}
 
void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter)
{
    if (iter) {
        ao2_iterator_destroy(&iter->iter);
        ast_refer_var_unref_current(iter);
        ast_free(iter);
    }
}
 
/*!
 * \internal \brief Find a \c ast_refer_tech by its technology name
 *
 * \param tech_name The name of the refer technology
 *
 * \note \c refer_techs should be locked via \c refer_techs_lock prior to
 *       calling this function
 *
 * \retval NULL if no \ref ast_refer_tech has been registered
 * \return \ref ast_refer_tech if registered
 */
static const struct ast_refer_tech *refer_find_by_tech_name(const char *tech_name)
{
    const struct ast_refer_tech *current;
    int i;
 
    for (i = 0; i < AST_VECTOR_SIZE(&refer_techs); i++) {
        current = AST_VECTOR_GET(&refer_techs, i);
        if (!strcmp(current->name, tech_name)) {
            return current;
        }
    }
 
    return NULL;
}
 
int ast_refer_send(struct ast_refer *refer)
{
    char *tech_name = NULL;
    const struct ast_refer_tech *refer_tech;
    int res = -1;
 
    if (ast_strlen_zero(refer->to)) {
        ao2_ref(refer, -1);
        return -1;
    }
 
    tech_name = ast_strdupa(refer->to);
    tech_name = strsep(&tech_name, ":");
 
    ast_rwlock_rdlock(&refer_techs_lock);
    refer_tech = refer_find_by_tech_name(tech_name);
 
    if (!refer_tech) {
        ast_log(LOG_ERROR, "Unknown refer tech: %s\n", tech_name);
        ast_rwlock_unlock(&refer_techs_lock);
        ao2_ref(refer, -1);
        return -1;
    }
 
    ao2_lock(refer);
    res = refer_tech->refer_send(refer);
    ao2_unlock(refer);
 
    ast_rwlock_unlock(&refer_techs_lock);
 
    ao2_ref(refer, -1);
 
    return res;
}
 
int ast_refer_tech_register(const struct ast_refer_tech *tech)
{
    const struct ast_refer_tech *match;
 
    ast_rwlock_wrlock(&refer_techs_lock);
 
    match = refer_find_by_tech_name(tech->name);
    if (match) {
        ast_log(LOG_ERROR, "Refer technology already registered for '%s'\n",
                tech->name);
        ast_rwlock_unlock(&refer_techs_lock);
        return -1;
    }
 
    if (AST_VECTOR_APPEND(&refer_techs, tech)) {
        ast_log(LOG_ERROR, "Failed to register refer technology for '%s'\n",
                tech->name);
        ast_rwlock_unlock(&refer_techs_lock);
        return -1;
    }
    ast_verb(5, "Refer technology '%s' registered.\n", tech->name);
 
    ast_rwlock_unlock(&refer_techs_lock);
 
    return 0;
}
 
/*!
 * \brief Comparison callback for \c ast_refer_tech vector removal
 *
 * \param vec_elem The element in the vector being compared
 * \param srch The element being looked up
 *
 * \retval non-zero The items are equal
 * \retval 0 The items are not equal
 */
static int refer_tech_cmp(const struct ast_refer_tech *vec_elem, const struct ast_refer_tech *srch)
{
    if (!vec_elem->name || !srch->name) {
        return (vec_elem->name == srch->name) ? 1 : 0;
    }
    return !strcmp(vec_elem->name, srch->name);
}
 
int ast_refer_tech_unregister(const struct ast_refer_tech *tech)
{
    int match;
 
    ast_rwlock_wrlock(&refer_techs_lock);
    match = AST_VECTOR_REMOVE_CMP_UNORDERED(&refer_techs, tech, refer_tech_cmp,
                                            AST_VECTOR_ELEM_CLEANUP_NOOP);
    ast_rwlock_unlock(&refer_techs_lock);
 
    if (match) {
        ast_log(LOG_ERROR, "No '%s' refer technology found.\n", tech->name);
        return -1;
    }
 
    ast_verb(5, "Refer technology '%s' unregistered.\n", tech->name);
 
    return 0;
}
 
/*!
 * \internal
 * \brief Clean up other resources on Asterisk shutdown
 */
static void refer_shutdown(void)
{
    AST_VECTOR_FREE(&refer_techs);
    ast_rwlock_destroy(&refer_techs_lock);
}
 
/*!
 * \internal
 * \brief Initialize stuff during Asterisk startup.
 *
 * Cleanup isn't a big deal in this function.  If we return non-zero,
 * Asterisk is going to exit.
 *
 * \retval 0 success
 * \retval non-zero failure
 */
int ast_refer_init(void)
{
    ast_rwlock_init(&refer_techs_lock);
    if (AST_VECTOR_INIT(&refer_techs, 8)) {
        return -1;
    }
    ast_register_cleanup(refer_shutdown);
    return 0;
}