extension_state.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2026, Sangoma Technologies Corporation
 *
 * Joshua Colp <jcolp@sangoma.com>
 *
 * See https://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.
 */
 
/*** MODULEINFO
    <support_level>core</support_level>
 ***/
 
#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/module.h"
#include "asterisk/extension_state.h"
#include "asterisk/pbx.h"
#include "asterisk/stasis.h"
#include "asterisk/stasis_message_router.h"
#include "asterisk/astobj2.h"
#include "asterisk/cli.h"
#include "pbx_private.h"
 
/*** DOCUMENTATION
    <manager name="ExtensionStateList" language="en_US">
        <since>
            <version>13.0.0</version>
        </since>
        <synopsis>
            List the current known extension states.
        </synopsis>
        <syntax>
            <xi:include xpointer="xpointer(/docs/manager[@name='Login']/syntax/parameter[@name='ActionID'])" />
        </syntax>
        <description>
            <para>This will list out all known extension states in a
            sequence of <replaceable>ExtensionStatus</replaceable> events.
            When finished, a <replaceable>ExtensionStateListComplete</replaceable> event
            will be emitted.</para>
        </description>
        <see-also>
            <ref type="manager">ExtensionState</ref>
            <ref type="function">HINT</ref>
            <ref type="function">EXTENSION_STATE</ref>
        </see-also>
        <responses>
            <list-elements>
                <xi:include xpointer="xpointer(/docs/managerEvent[@name='ExtensionStatus'])" />
            </list-elements>
            <managerEvent name="ExtensionStateListComplete" language="en_US">
                <managerEventInstance class="EVENT_FLAG_COMMAND">
                    <since>
                        <version>13.0.0</version>
                    </since>
                    <synopsis>
                        Indicates the end of the list the current known extension states.
                    </synopsis>
                    <syntax>
                        <parameter name="EventList">
                            <para>Conveys the status of the event list.</para>
                        </parameter>
                        <parameter name="ListItems">
                            <para>Conveys the number of statuses reported.</para>
                        </parameter>
                    </syntax>
                </managerEventInstance>
            </managerEvent>
        </responses>
    </manager>
 ***/
 
#define HINTDEVICE_DATA_LENGTH 16
AST_THREADSTORAGE(hintdevice_data);
 
/*! \brief Device state source feeding an extension state */
struct extension_state_device_source {
    /*! \brief The current state of the device - this is immutable */
    struct ast_extension_state_device_state_info *info;
    /*! \brief Synchronous subscription to the device state topic */
    struct stasis_subscription *device_state_subscription;
    /*! \brief The current version for this source */
    unsigned int version;
};
 
AST_VECTOR(device_state_sources_vector, struct extension_state_device_source *);
 
/*! \brief Extension state information */
struct extension_state {
    /*! \brief The current device snapshot for the extension */
    struct ast_extension_state_device_snapshot *device_snapshot;
    /*! \brief The current presence snapshot for the extension */
    struct ast_extension_state_presence_snapshot *presence_snapshot;
    /*! \brief The extension state topic for this extension */
    struct stasis_topic *extension_state_topic;
    /*! \brief Forwarder from per-extension topic to all topic */
    struct stasis_forward *extension_state_forwarder;
    /*! \brief Device state sources feeding the hint topic, and their forwarding */
    struct device_state_sources_vector device_state_sources;
    /*! \brief The string representation of all presence state sources feeding this extension state */
    char *presence_sources_string;
    /*! \brief The dialplan hint that last configured this extension state */
    struct ast_exten *hint_extension;
    /*! \brief The dialplan context */
    char dialplan_context[AST_MAX_CONTEXT];
    /*! \brief The dialplan extension */
    char dialplan_extension[AST_MAX_EXTENSION];
    /*! \brief The combined extension this state is for (extension@context) */
    char extension[0];
};
 
/*! \brief Number of buckets for extension states */
#ifdef LOW_MEMORY
#define EXTENSION_STATE_BUCKETS 17
#else
#define EXTENSION_STATE_BUCKETS 563
#endif
 
static const struct cfextension_states {
    int extension_state;
    const char * const text;
} extension_state_mappings[] = {
    { AST_EXTENSION_NOT_INUSE,                     "Idle" },
    { AST_EXTENSION_INUSE,                         "InUse" },
    { AST_EXTENSION_BUSY,                          "Busy" },
    { AST_EXTENSION_UNAVAILABLE,                   "Unavailable" },
    { AST_EXTENSION_RINGING,                       "Ringing" },
    { AST_EXTENSION_INUSE | AST_EXTENSION_RINGING, "InUse&Ringing" },
    { AST_EXTENSION_ONHOLD,                        "Hold" },
    { AST_EXTENSION_INUSE | AST_EXTENSION_ONHOLD,  "InUse&Hold" }
};
 
/*! \brief The global container of extension states */
static struct ao2_container *extension_states;
 
/*! \brief Topic which receives all extension state updates */
static struct stasis_topic *extension_state_topic_all;
 
/*! \brief Single presence state subscription, for all extension states */
static struct stasis_subscription *presence_state_sub;
 
/*! \brief Sort function for extension states */
AO2_STRING_FIELD_SORT_FN(extension_state, extension)
 
/*! \brief Compare function for extension states */
AO2_STRING_FIELD_CMP_FN(extension_state, extension)
 
/*! \brief Message type for extension state updates */
STASIS_MESSAGE_TYPE_DEFN(ast_extension_state_update_message_type);
 
/*!
 * \internal
 * \brief Destroy an extension state update message
 * \param obj The extension state update message to destroy
 */
static void extension_state_update_message_destroy(void *obj)
{
    struct ast_extension_state_update_message *update_message = obj;
 
    ao2_cleanup(update_message->old_device_snapshot);
    ao2_cleanup(update_message->new_device_snapshot);
    ao2_cleanup(update_message->old_presence_snapshot);
    ao2_cleanup(update_message->new_presence_snapshot);
}
 
/*!
 * \internal
 * \brief Create an extension state update message
 *
 * \param context The context of the extension
 * \param extension The extension
 * \param old_device_snapshot The old device state snapshot
 * \param new_device_snapshot The new device state snapshot
 * \param old_presence_snapshot The old presence state snapshot
 * \param new_presence_snapshot The new presence state snapshot
 * \retval An allocated extension state update message, or NULL on failure
 *
 * This function creates an extension state update message for the specified context, extension,
 * old device state snapshot, new device state snapshot, old presence state snapshot, and new presence state snapshot.
 */
static struct ast_extension_state_update_message *extension_state_update_message_create(const char *context,
    const char *extension, struct ast_extension_state_device_snapshot *old_device_snapshot,
    struct ast_extension_state_device_snapshot *new_device_snapshot, struct ast_extension_state_presence_snapshot *old_presence_snapshot,
    struct ast_extension_state_presence_snapshot *new_presence_snapshot)
{
    size_t context_len = strlen(context) + 1;
    size_t extension_len = strlen(extension) + 1;
    struct ast_extension_state_update_message *update_message;
 
    update_message = ao2_alloc_options(sizeof(*update_message) + context_len + extension_len,
        extension_state_update_message_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!update_message) {
        return NULL;
    }
 
    ast_copy_string(update_message->extension, extension, extension_len); /* Safe */
    update_message->context = update_message->extension + extension_len;
    ast_copy_string(update_message->context, context, context_len); /* Safe */
 
    update_message->old_device_snapshot = ao2_bump(old_device_snapshot);
    update_message->new_device_snapshot = ao2_bump(new_device_snapshot);
    update_message->old_presence_snapshot = ao2_bump(old_presence_snapshot);
    update_message->new_presence_snapshot = ao2_bump(new_presence_snapshot);
 
    return update_message;
}
 
/*!
 * \internal
 * \brief Destroy an extension state device source
 * \param source The extension state device source to destroy
 *
 * This function destroys an extension state device source by unsubscribing from the device state
 * topic and cleaning up the associated resources.
 */
static void extension_state_device_source_destroy(struct extension_state_device_source *source)
{
    if (source->device_state_subscription) {
        stasis_unsubscribe(source->device_state_subscription);
    }
    ao2_cleanup(source->info);
    ast_free(source);
}
 
/*!
 * \internal
 * \brief Allocate an extension device state info object
 *
 * \param device The device name
 * \param state The device state
 * \retval An allocated extension device state info object, or NULL on failure
 *
 * This function allocates an extension device state info object with the specified device name and state.
 */
static struct ast_extension_state_device_state_info *extension_state_device_state_info_alloc(const char *device,
    enum ast_device_state state)
{
    struct ast_extension_state_device_state_info *info;
 
    info = ao2_alloc_options(sizeof(*info) + strlen(device) + 1, NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!info) {
        return NULL;
    }
 
    info->state = state;
    strcpy(info->device, device); /* Safe */
 
    return info;
}
 
/*!
 * \internal
 * \brief Destroy an extension state device snapshot
 *
 * \param obj The extension state device snapshot to destroy
 *
 * This function destroys an extension state device snapshot by cleaning up
 * the causing device and additional devices.
 */
static void extension_state_device_snapshot_destroy(void *obj)
{
    struct ast_extension_state_device_snapshot *device_snapshot = obj;
 
    ao2_cleanup(device_snapshot->causing_device);
    AST_VECTOR_CALLBACK_VOID(&device_snapshot->additional_devices, ao2_cleanup);
    AST_VECTOR_FREE(&device_snapshot->additional_devices);
}
 
/*!
 * \internal
 * \brief Create an extension state device snapshot
 *
 * \param device_state The device state
 * \param device_state_sources The device state sources
 * \param causing_device The causing device
 * \retval An allocated extension state device snapshot, or NULL on failure
 *
 * This function creates an extension state device snapshot with the device state,
 * device state sources, and causing device.
 */
static struct ast_extension_state_device_snapshot *extension_state_device_snapshot_create(
    enum ast_extension_states device_state, struct device_state_sources_vector *device_state_sources,
    struct ast_extension_state_device_state_info *causing_device)
{
    struct ast_extension_state_device_snapshot *device_snapshot;
    int i;
 
    device_snapshot = ao2_alloc_options(sizeof(*device_snapshot),
        extension_state_device_snapshot_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!device_snapshot) {
        return NULL;
    }
 
    device_snapshot->state = device_state;
    device_snapshot->causing_device = ao2_bump(causing_device);
    if (AST_VECTOR_INIT(&device_snapshot->additional_devices, AST_VECTOR_SIZE(device_state_sources))) {
        ao2_ref(device_snapshot, -1);
        return NULL;
    }
 
    for (i = 0; i < AST_VECTOR_SIZE(device_state_sources); i++) {
        struct extension_state_device_source *source = AST_VECTOR_GET(device_state_sources, i);
 
        if (causing_device && source->info == causing_device) {
            continue;
        }
 
        AST_VECTOR_APPEND(&device_snapshot->additional_devices, ao2_bump(source->info));
    }
 
    return device_snapshot;
}
 
/*!
 * \internal
 * \brief Callback for device state changes
 *
 * \param userdata The extension state to update
 * \param sub The subscription
 * \param msg The device state message
 *
 * This function is called when a device state changes and updates the extension state
 * accordingly by aggregating the device states and publishing the new state.
 */
static void extension_state_device_state_cb(void *userdata, struct stasis_subscription *sub,
        struct stasis_message *msg)
{
    struct extension_state *state = userdata;
    struct ast_device_state_message *device_state;
    struct ast_devstate_aggregate agg;
    struct ast_extension_state_device_state_info *extension_device_state_info;
    int i;
    unsigned int updated = 0;
    enum ast_extension_states new_device_state;
 
    if (stasis_message_type(msg) != ast_device_state_message_type()) {
        return;
    }
 
    device_state = stasis_message_data(msg);
 
    /* We only care about the aggregate state */
    if (device_state->eid) {
        return;
    }
 
    ast_devstate_aggregate_init(&agg);
 
    /*
     * Alrighty, the reason that we store an extension_device_state_info is to reduce the memory allocation that
     * has to occur every time we get a device state update and have to construct a new message. If the extension
     * state contains only a single device source we have to do this anyway, but if there's multiple then if we
     * didn't store the result we'd be creating new ones every message to put in the additional_devices vector.
     */
    extension_device_state_info = extension_state_device_state_info_alloc(device_state->device, device_state->state);
    if (!extension_device_state_info) {
        return;
    }
 
    ao2_lock(state);
 
    for (i = 0; i < AST_VECTOR_SIZE(&state->device_state_sources); i++) {
        struct extension_state_device_source *source = AST_VECTOR_GET(&state->device_state_sources, i);
 
        if (!strcmp(source->info->device, device_state->device)) {
            ao2_replace(source->info, extension_device_state_info);
            updated = 1;
        }
 
        ast_devstate_aggregate_add(&agg, source->info->state);
    }
 
    /* We don't really care about the device state info contents now, so we can drop the reference */
    ao2_ref(extension_device_state_info, -1);
 
    /*
     * It's possible for a device state update to come in for a device which is no longer feeding this
     * extension state if it has been updated, so only actually care about the new device state if a
     * source has actually been updated.
     */
    if (!updated) {
        ao2_unlock(state);
        return;
    }
 
    /*
     * We actually update things and raise a message if the state is different, or if the state is ringing
     * as that can actually just be an update that someone else is ringing the same extension.
     */
    new_device_state = ast_devstate_to_extenstate(ast_devstate_aggregate_result(&agg));
    if ((state->device_snapshot->state != new_device_state) || (new_device_state & AST_EXTENSION_RINGING)) {
        struct ast_extension_state_device_snapshot *device_snapshot;
        struct ast_extension_state_update_message *update_message;
        struct stasis_message *message;
 
        /* Now above you probably noticed I dropped the reference for extension_device_state_info but now I'm
         * passing it in here. Don't panic - a reference exists on the device state source still and since we
         * have the state locked it can't go away.
         */
        device_snapshot = extension_state_device_snapshot_create(new_device_state, &state->device_state_sources,
            extension_device_state_info);
        if (!device_snapshot) {
            ao2_unlock(state);
            return;
        }
 
        update_message = extension_state_update_message_create(state->dialplan_context, state->dialplan_extension,
            state->device_snapshot, device_snapshot, state->presence_snapshot, state->presence_snapshot);
 
        /* Even if we can't publish an update message we still ensure the local cached snapshot is up to date */
        ao2_replace(state->device_snapshot, device_snapshot);
        ao2_ref(device_snapshot, -1);
 
        if (!update_message) {
            ao2_unlock(state);
            return;
        }
 
        /* Inform any subscribers of the change to the device snapshot */
        message = stasis_message_create(ast_extension_state_update_message_type(), update_message);
        if (message) {
            stasis_publish(state->extension_state_topic, message);
            ao2_ref(message, -1);
        }
 
        ao2_ref(update_message, -1);
    }
 
    ao2_unlock(state);
}
 
/*!
 * \internal
 * \brief Allocate a device source for an extension state
 *
 * \param state The extension state to allocate the device source for
 * \param device The device to allocate the source for
 * \retval An allocated device source, or NULL on failure
 *
 * This function allocates a device source for an extension state by creating a device state source
 * and setting up the necessary subscriptions and references.
 */
static struct extension_state_device_source *extension_state_device_source_alloc(struct extension_state *state, const char *device)
{
    struct extension_state_device_source *source;
    struct stasis_topic *topic;
 
    /*
     * Ensure that we have a direct device state topic for the device, note this is returned without a reference but
     * is guaranteed to exist regardless.
     */
    topic = ast_device_state_topic(device);
    if (!topic) {
        return NULL;
    }
 
    /*
     * The device state source is only used within the extension state and is never
     * passed around so the overhead of an ao2 object with reference counting is unnecessary.
     */
    source = ast_calloc(1, sizeof(*source));
    if (!source) {
        return NULL;
    }
 
    source->info = extension_state_device_state_info_alloc(device, ast_device_state(device));
    if (!source->info) {
        extension_state_device_source_destroy(source);
        return NULL;
    }
 
    /*
     * We do a synchronous subscription to the device state topic, as our callback is extremely
     * short lived and the added overhead of queueing to a taskprocessor for another thread to handle
     * it is just not worth it.
     */
    source->device_state_subscription = stasis_subscribe_synchronous(topic, extension_state_device_state_cb, state);
    if (!source->device_state_subscription) {
        extension_state_device_source_destroy(source);
        return NULL;
    }
 
    stasis_subscription_accept_message_type(source->device_state_subscription, ast_device_state_message_type());
    stasis_subscription_set_filter(source->device_state_subscription, STASIS_SUBSCRIPTION_FILTER_SELECTIVE);
 
    return source;
}
 
/*!
 * \internal
 * \brief Destroy an extension state presence snapshot
 *
 * \param obj The extension state presence snapshot to destroy
 *
 * This function destroys an extension state presence snapshot by cleaning up
 * the presence snapshot.
 */
static void extension_state_presence_snapshot_destroy(void *obj)
{
    struct ast_extension_state_presence_snapshot *presence_snapshot = obj;
 
    ast_free(presence_snapshot->presence_subtype);
    ast_free(presence_snapshot->presence_message);
}
 
/*!
 * \internal
 * \brief Create an extension state presence snapshot
 *
 * \param presence_state The presence state
 * \param presence_subtype The presence subtype (can be NULL)
 * \param presence_message The presence message (can be NULL)
 * \retval An allocated extension state presence snapshot, or NULL on failure
 *
 * This function creates an extension state presence snapshot for the specified presence state,
 * presence subtype, and presence message.
 */
static struct ast_extension_state_presence_snapshot *extension_state_presence_snapshot_create(enum ast_presence_state presence_state,
    const char *presence_subtype, const char *presence_message)
{
    struct ast_extension_state_presence_snapshot *presence_snapshot;
 
    presence_snapshot = ao2_alloc_options(sizeof(*presence_snapshot), extension_state_presence_snapshot_destroy,
        AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!presence_snapshot) {
        return NULL;
    }
 
    /* To ensure that we don't give a partial snapshot we fail creation if any allocation fails */
    presence_snapshot->presence_state = presence_state;
    if (presence_subtype) {
        presence_snapshot->presence_subtype = ast_strdup(presence_subtype);
        if (!presence_snapshot->presence_subtype) {
            ao2_ref(presence_snapshot, -1);
            return NULL;
        }
    }
    if (presence_message) {
        presence_snapshot->presence_message = ast_strdup(presence_message);
        if (!presence_snapshot->presence_message) {
            ao2_ref(presence_snapshot, -1);
            return NULL;
        }
    }
 
    return presence_snapshot;
}
 
/*!
 * \brief device source non-matching version comparator for AST_VECTOR_REMOVE_CMP_UNORDERED()
 *
 * \param elem Element to compare against
 * \param value Value to compare with the vector element.
 *
 * \return 0 if element does not match.
 * \return Non-zero if element matches.
 */
#define DEVICE_SOURCE_ELEM_VERSION_CMP(elem, value) ((elem)->version != (value))
 
/*!
 * \internal
 * \brief Update the sources of an extension state
 *
 * \param state The extension state to update
 * \param exten The extension to update
 * \retval 0 on success, -1 on failure
 *
 * This function updates the sources of an extension state by parsing the app part
 * of the extension and updating the device and presence state sources.
 */
static int extension_state_update_sources(struct extension_state *state, struct ast_exten *exten)
{
    struct ast_str *str = ast_str_thread_get(&hintdevice_data, HINTDEVICE_DATA_LENGTH);
    char *devices, *device, *presence_state_sources;
    struct ast_devstate_aggregate agg;
    enum ast_extension_states new_device_state;
    unsigned int version;
    struct ast_extension_state_device_snapshot *device_snapshot = NULL;
    struct ast_extension_state_presence_snapshot *presence_snapshot = NULL;
 
    ast_str_set(&str, 0, "%s", ast_get_extension_app(exten));
    devices = ast_str_buffer(str);
 
    ao2_lock(state);
 
    /*
     * The format of the app part of a hint is "[device[&device]],[presence[&presence]]" so
     * we can just find the first occurrence of ',' in order to get to the presence sources.
     */
    presence_state_sources = strchr(devices, ',');
    if (presence_state_sources) {
        *presence_state_sources++ = '\0';
    }
 
    ast_devstate_aggregate_init(&agg);
 
    version = ast_random();
 
    /* Devices are separated by '&' */
    while ((device = strsep(&devices, "&"))) {
        struct extension_state_device_source *source = NULL;
        int i;
 
        /* Skip any device names that are empty, as we can do nothing */
        if (ast_strlen_zero(device)) {
            continue;
        }
 
        for (i = 0; i < AST_VECTOR_SIZE(&state->device_state_sources); i++) {
            struct extension_state_device_source *existing_source = AST_VECTOR_GET(&state->device_state_sources, i);
 
            if (!strcmp(existing_source->info->device, device)) {
                source = existing_source;
                break;
            }
        }
        if (!source) {
            source = extension_state_device_source_alloc(state, device);
            if (!source) {
                ao2_unlock(state);
                return -1;
            }
            AST_VECTOR_APPEND(&state->device_state_sources, source);
        }
 
        ast_devstate_aggregate_add(&agg, source->info->state);
        source->version = version;
    }
 
    /* Do a pass and remove all old device sources */
    AST_VECTOR_REMOVE_ALL_CMP_UNORDERED(&state->device_state_sources, version,
        DEVICE_SOURCE_ELEM_VERSION_CMP, extension_state_device_source_destroy);
 
    /* If device state sources exist it is what produces the device state, otherwise we use the default */
    if (AST_VECTOR_SIZE(&state->device_state_sources)) {
        new_device_state = ast_devstate_to_extenstate(ast_devstate_aggregate_result(&agg));
    } else {
        new_device_state = AST_EXTENSION_UNAVAILABLE;
    }
 
    /* If the device state has changed, create a new snapshot */
    if (state->device_snapshot->state != new_device_state) {
        device_snapshot = extension_state_device_snapshot_create(new_device_state, &state->device_state_sources, NULL);
    }
    if (!device_snapshot) {
        /* If there's no new device snapshot we use the old one */
        device_snapshot = state->device_snapshot;
    }
 
    /* If the presence state has changed, create a new snapshot */
    if (strcmp(S_OR(state->presence_sources_string, ""), S_OR(presence_state_sources, ""))) {
        enum ast_presence_state presence_state = AST_PRESENCE_NOT_SET;
        char *presence_subtype = NULL, *presence_message = NULL;
 
        ast_free(state->presence_sources_string);
 
        if (!ast_strlen_zero(presence_state_sources)) {
            state->presence_sources_string = ast_strdup(presence_state_sources);
            /* Presence state is also separated by & but only the presence state API can handle it and aggregate */
            presence_state = ast_presence_state(presence_state_sources, &presence_subtype,
                &presence_message);
        } else {
            state->presence_sources_string = NULL;
        }
 
        presence_snapshot = extension_state_presence_snapshot_create(presence_state, presence_subtype, presence_message);
 
        ast_free(presence_subtype);
        ast_free(presence_message);
    }
    if (!presence_snapshot) {
        /* If there's no new presence snapshot we use the old one */
        presence_snapshot = state->presence_snapshot;
    }
 
    /* If any snapshots have changed create an update message containing them */
    if (state->device_snapshot != device_snapshot || state->presence_snapshot != presence_snapshot) {
        struct ast_extension_state_update_message *update_message;
 
        update_message = extension_state_update_message_create(state->dialplan_context, state->dialplan_extension, state->device_snapshot,
            device_snapshot, state->presence_snapshot, presence_snapshot);
        if (update_message) {
            struct stasis_message *message = stasis_message_create(ast_extension_state_update_message_type(), update_message);
 
            if (message) {
                stasis_publish(state->extension_state_topic, message);
                ao2_ref(message, -1);
            }
 
            ao2_ref(update_message, -1);
        }
 
        /* If applicable, update the snapshots on the state to their new version */
        if (state->device_snapshot != device_snapshot) {
            ao2_replace(state->device_snapshot, device_snapshot);
            ao2_ref(device_snapshot, -1);
        }
        if (state->presence_snapshot != presence_snapshot) {
            ao2_replace(state->presence_snapshot, presence_snapshot);
            ao2_ref(presence_snapshot, -1);
        }
    }
 
    ao2_unlock(state);
 
    return 0;
}
 
/*!
 * \internal
 * \brief Destroy an extension state
 *
 * \param obj The extension state to destroy
 *
 * This function destroys an extension state by cleaning up its resources.
 */
static void extension_state_destroy(void *obj)
{
    struct extension_state *state = obj;
 
    ao2_cleanup(state->device_snapshot);
    ao2_cleanup(state->presence_snapshot);
    ao2_cleanup(state->extension_state_topic);
 
    ast_free(state->presence_sources_string);
}
 
/*! \brief Stasis message type for extension state remove messages */
STASIS_MESSAGE_TYPE_DEFN(ast_extension_state_remove_message_type);
 
/*!
 * \internal
 * \brief Create an extension state remove message
 *
 * \param context The context of the extension
 * \param extension The extension to remove
 * \retval A stasis message for the remove event, or NULL on failure
 *
 * This function creates an extension state remove message for the specified context and extension.
 */
static struct stasis_message *extension_state_remove_message_create(const char *context, const char *extension)
{
    size_t context_len = strlen(context) + 1;
    size_t extension_len = strlen(extension) + 1;
    struct ast_extension_state_remove_message *remove_message;
    struct stasis_message *message;
 
    remove_message = ao2_alloc_options(sizeof(*remove_message) + context_len + extension_len, NULL,
        AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!remove_message) {
        return NULL;
    }
 
    ast_copy_string(remove_message->extension, extension, extension_len); /* Safe */
    remove_message->context = remove_message->extension + extension_len;
    ast_copy_string(remove_message->context, context, context_len); /* Safe */
 
    message = stasis_message_create(ast_extension_state_remove_message_type(), remove_message);
    ao2_ref(remove_message, -1);
 
    return message;
}
 
/*!
 * \internal
 * \brief Shut down an extension state
 *
 * \param state The extension state to shut down
 *
 * This function shuts down an extension state by publishing a remove message to its topic
 * and cleaning up its resources.
 */
static void extension_state_shutdown(struct extension_state *state)
{
    struct stasis_message *remove_message;
 
    /*
     * Shutting down an extension state requires us to publish to its topic so all subscribers
     * know that it is going away. However, if the topic failed to be created then we have nothing
     * to publish to and can just return.
     */
    if (!state->extension_state_topic) {
        return;
    }
 
    /* Inform all subscribers that this extension state is being removed */
    remove_message = extension_state_remove_message_create(state->dialplan_context,
        state->dialplan_extension);
    if (remove_message) {
        stasis_publish(state->extension_state_topic, remove_message);
        ao2_ref(remove_message, -1);
    }
 
    AST_VECTOR_CALLBACK_VOID(&state->device_state_sources, extension_state_device_source_destroy);
    AST_VECTOR_FREE(&state->device_state_sources);
 
    stasis_forward_cancel(state->extension_state_forwarder);
}
 
/*!
 * \internal
 * \brief Callback for presence state messages
 *
 * \param unused Unused parameter
 * \param sub The stasis subscription
 * \param msg The stasis message
 *
 * This callback is invoked when a presence state message is received. It updates
 * the presence state of all extension states that are interested in the presence
 * state provider and publishes an extension state update message if it has changed.
 */
static void extension_state_presence_state_cb(void *unused, struct stasis_subscription *sub,
        struct stasis_message *msg)
{
    struct ast_presence_state_message *presence_state;
    struct ao2_iterator iter;
    struct extension_state *state;
 
    if (stasis_message_type(msg) != ast_presence_state_message_type()) {
        return;
    }
 
    presence_state = stasis_message_data(msg);
 
    ao2_lock(extension_states);
    iter = ao2_iterator_init(extension_states, 0);
    for (; (state = ao2_iterator_next(&iter)); ao2_ref(state, -1)) {
        enum ast_presence_state presence_state_new;
        char *presence_subtype, *presence_message;
        struct ast_extension_state_presence_snapshot *presence_snapshot;
        struct ast_extension_state_update_message *update_message;
 
        ao2_lock(state);
 
        /*
         * We determine if this update is relevant to this extension state by seeing if the presence sources string
         * even remotely contains the provider for this update. Worst case it's a substring and the calculated presence
         * state is the same as before in which case we ignore it.
         */
        if (!state->presence_sources_string || !strcasestr(state->presence_sources_string, presence_state->provider)) {
            ao2_unlock(state);
            continue;
        }
 
        /*
         * Aggregation of presence state is done by requesting the current presence state with passing in a complete
         * list of providers. This means that a presence state change message is just a notification to us to go and
         * retrieve the new presence state. We don't just take it from the message itself. Since presence state is not
         * as common as device state this is not a problem despite being inefficient in comparison to the device state
         * implementation.
         */
        presence_state_new = ast_presence_state(state->presence_sources_string, &presence_subtype, &presence_message);
        if (presence_state_new == AST_PRESENCE_INVALID) {
            /* For the invalid case we just ignore this update */
            ao2_unlock(state);
            continue;
        }
 
        if ((state->presence_snapshot->presence_state == presence_state_new) &&
            ((!presence_subtype && !state->presence_snapshot->presence_subtype) ||
                (presence_subtype && state->presence_snapshot->presence_subtype &&
                    !strcmp(presence_subtype, state->presence_snapshot->presence_subtype))) &&
            ((!presence_message && !state->presence_snapshot->presence_message) ||
                (presence_message && state->presence_snapshot->presence_message &&
                    !strcmp(presence_message, state->presence_snapshot->presence_message)))) {
            /* No change in presence state, so ignore this update */
            ao2_unlock(state);
            ast_free(presence_subtype);
            ast_free(presence_message);
            continue;
        }
 
        presence_snapshot = extension_state_presence_snapshot_create(presence_state_new, presence_subtype, presence_message);
        if (!presence_snapshot) {
            ao2_unlock(state);
            ast_free(presence_subtype);
            ast_free(presence_message);
            continue;
        }
 
        update_message = extension_state_update_message_create(state->dialplan_context,
            state->dialplan_extension, state->device_snapshot, state->device_snapshot, state->presence_snapshot, presence_snapshot);
        ao2_replace(state->presence_snapshot, presence_snapshot);
        ao2_ref(presence_snapshot, -1);
        if (update_message) {
            struct stasis_message *message = stasis_message_create(ast_extension_state_update_message_type(), update_message);
 
            if (message) {
                stasis_publish(state->extension_state_topic, message);
                ao2_ref(message, -1);
            }
 
            ao2_ref(update_message, -1);
        }
 
        ao2_unlock(state);
 
        ast_free(presence_subtype);
        ast_free(presence_message);
    }
    ao2_iterator_destroy(&iter);
    ao2_unlock(extension_states);
}
 
/*!
 * \internal
 *
 * \brief Allocate an extension state object
 * \param exten The extension
 * \param context The context
 * \retval A pointer to the allocated extension state, or NULL on failure
 *
 * This function allocates an extension state object with the specified extension and context.
 */
static struct extension_state *extension_state_alloc(struct ast_exten *exten, struct ast_context *context)
{
    char extension[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
    struct extension_state *state;
    char *extension_state_topic_name;
 
    snprintf(extension, sizeof(extension), "%s@%s", ast_get_extension_name(exten), ast_get_context_name(context));
 
    /*
     * Each individual extension state has its own lock to ensure that when updating it
     * we do not cause problems for either the existing topic ingesting updates
     * or any access to the extension state cached message.
     */
    state = ao2_alloc(sizeof(*state) + strlen(extension) + 1, extension_state_destroy);
    if (!state) {
        return NULL;
    }
 
    ast_copy_string(state->dialplan_context, ast_get_context_name(context), sizeof(state->dialplan_context));
    ast_copy_string(state->dialplan_extension, ast_get_extension_name(exten), sizeof(state->dialplan_extension));
    strcpy(state->extension, extension); /* Safe */
    AST_VECTOR_INIT(&state->device_state_sources, 0);
 
    /* These are the default if no sources are present */
    state->device_snapshot = extension_state_device_snapshot_create(AST_EXTENSION_UNAVAILABLE,
        &state->device_state_sources, NULL);
    state->presence_snapshot = extension_state_presence_snapshot_create(AST_PRESENCE_NOT_SET, NULL, NULL);
    if (!state->device_snapshot || !state->presence_snapshot) {
        ao2_ref(state, -1);
        return NULL;
    }
 
    /*
     * We don't actually access the contents of exten past guarantee of it being valid so we can safely
     * store a pointer to just do pointer comparison.
     */
    state->hint_extension = exten;
 
    /* Pattern match extensions don't have sources or a topic, so return early */
    if (extension[0] == '_') {
        return state;
    }
 
    /* We most likely have at least one device state source */
    if (AST_VECTOR_INIT(&state->device_state_sources, 1)) {
        ao2_ref(state, -1);
        return NULL;
    }
 
    if (ast_asprintf(&extension_state_topic_name, "extension_state:extension/%s", extension) < 0) {
        ao2_ref(state, -1);
        return NULL;
    }
 
    state->extension_state_topic = stasis_topic_create(extension_state_topic_name);
    ast_free(extension_state_topic_name);
    if (!state->extension_state_topic) {
        ao2_ref(state, -1);
        return NULL;
    }
 
    state->extension_state_forwarder = stasis_forward_all(state->extension_state_topic, extension_state_topic_all);
    if (!state->extension_state_forwarder) {
        ao2_ref(state, -1);
        return NULL;
    }
 
    return state;
}
 
/*!
 * \internal
 *
 * \brief Get an extension state object
 * \param chan The channel
 * \param context The context
 * \param extension The extension
 * \retval A pointer to the extension state, or NULL on failure
 *
 * This function gets an extension state object for the specified channel, context, and extension.
 * If the extension state does not exist due to being from a pattern match, it will be created.
 */
static struct extension_state *extension_state_get(struct ast_channel *chan, const char *context, const char *extension)
{
    struct extension_state *state;
    struct ast_exten *hint_exten;
    struct pbx_find_info q = { .stacklen = 0 };
    char location[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
 
    /* We optimistically search for the extension state using the provided context and extension */
    snprintf(location, sizeof(location), "%s@%s", extension, context);
    state = ao2_find(extension_states, location, OBJ_SEARCH_KEY);
    if (state) {
        return state;
    }
 
    /*
     * Pattern match extensions do exist within extension state for the purposes of listing them out,
     * but they can't resolve down to anything else
     */
    if (extension[0] == '_') {
        return NULL;
    }
 
    ast_wrlock_contexts();
 
    /*
     * We can't use the provided context and extension as-is because an include
     * could have resulted in the context being different than what was provided.
     * To handle this we query the dialplan to find where the hint actually is.
     * We also need to do this to determine if this is a pattern match or an explicit
     * extension.
     */
    hint_exten = pbx_find_extension(chan, NULL, &q, context, extension,
        PRIORITY_HINT, NULL, "", E_MATCH);
    if (!hint_exten) {
        /*
         * The extension must ALWAYS exist in the dialplan in some capacity. It is
         * either in the dialplan as an explicit extension or a pattern match.
         */
        ast_unlock_contexts();
        return NULL;
    }
 
    if (ast_get_extension_name(hint_exten)[0] == '_') {
        /*
         * If this resolved down to a pattern match that means this is the first request
         * for this explicit extension so we need to add it to the dialplan which will create
         * an extension state for it. It's possible for us to conflict with another thread but
         * in that case the ast_add_extension call will fail and be a no-op and we will return
         * the extension state the other thread created.
         */
        ast_add_extension(q.foundcontext, 0, extension, PRIORITY_HINT, ast_get_extension_label(hint_exten),
            ast_get_extension_matchcid(hint_exten) ? ast_get_extension_cidmatch(hint_exten) : NULL,
            ast_get_extension_app(hint_exten), ast_strdup(ast_get_extension_app_data(hint_exten)), ast_free_ptr,
            ast_get_extension_registrar(hint_exten));
    }
 
    /* The extension state should already exist at this point */
    snprintf(location, sizeof(location), "%s@%s", extension, q.foundcontext);
    ast_unlock_contexts();
 
    return ao2_find(extension_states, location, OBJ_SEARCH_KEY);
}
 
struct ast_channel *ast_extension_state_get_device_causing_channel(const char *device, enum ast_device_state device_state)
{
    enum ast_channel_state search_state = 0; /* prevent false uninit warning */
    char match[AST_CHANNEL_NAME];
    struct ast_channel_iterator *chan_iter;
    struct ast_channel *chan, *channel = NULL;
    struct timeval chantime = {0, }; /* prevent false uninit warning */
 
    switch (device_state) {
    case AST_DEVICE_RINGING:
    case AST_DEVICE_RINGINUSE:
        /* find ringing channel */
        search_state = AST_STATE_RINGING;
        break;
    case AST_DEVICE_BUSY:
        /* find busy channel */
        search_state = AST_STATE_BUSY;
        break;
    case AST_DEVICE_ONHOLD:
    case AST_DEVICE_INUSE:
        /* find up channel */
        search_state = AST_STATE_UP;
        break;
    case AST_DEVICE_UNKNOWN:
    case AST_DEVICE_NOT_INUSE:
    case AST_DEVICE_INVALID:
    case AST_DEVICE_UNAVAILABLE:
    case AST_DEVICE_TOTAL /* not a state */:
        /* no channels are of interest */
        return NULL;
    }
 
    /* iterate over all channels of the device */
    snprintf(match, sizeof(match), "%s-", device);
    chan_iter = ast_channel_iterator_by_name_new(match, strlen(match));
    for (; (chan = ast_channel_iterator_next(chan_iter)); ast_channel_unref(chan)) {
        ast_channel_lock(chan);
        /* this channel's state doesn't match */
        if (search_state != ast_channel_state(chan)) {
            ast_channel_unlock(chan);
            continue;
        }
        /* any non-ringing channel will fit */
        if (search_state != AST_STATE_RINGING) {
            ast_channel_unlock(chan);
            channel = chan;
            break;
        }
        /* but we need the oldest ringing channel of the device to match with undirected pickup */
        if (!channel) {
            chantime = ast_channel_creationtime(chan);
            ast_channel_ref(chan); /* must ref it! */
            channel = chan;
        } else if (ast_tvcmp(ast_channel_creationtime(chan), chantime) < 0) {
            chantime = ast_channel_creationtime(chan);
            ast_channel_unref(channel);
            ast_channel_ref(chan); /* must ref it! */
            channel = chan;
        }
        ast_channel_unlock(chan);
    }
    ast_channel_iterator_destroy(chan_iter);
 
    return channel;
}
 
enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devstate)
{
    switch (devstate) {
    case AST_DEVICE_ONHOLD:
        return AST_EXTENSION_ONHOLD;
    case AST_DEVICE_BUSY:
        return AST_EXTENSION_BUSY;
    case AST_DEVICE_UNKNOWN:
        return AST_EXTENSION_NOT_INUSE;
    case AST_DEVICE_UNAVAILABLE:
    case AST_DEVICE_INVALID:
        return AST_EXTENSION_UNAVAILABLE;
    case AST_DEVICE_RINGINUSE:
        return (AST_EXTENSION_INUSE | AST_EXTENSION_RINGING);
    case AST_DEVICE_RINGING:
        return AST_EXTENSION_RINGING;
    case AST_DEVICE_INUSE:
        return AST_EXTENSION_INUSE;
    case AST_DEVICE_NOT_INUSE:
        return AST_EXTENSION_NOT_INUSE;
    case AST_DEVICE_TOTAL: /* not a device state, included for completeness */
        break;
    }
 
    return AST_EXTENSION_NOT_INUSE;
}
 
const char *ast_extension_state2str(int extension_state)
{
    int i;
 
    for (i = 0; (i < ARRAY_LEN(extension_state_mappings)); i++) {
        if (extension_state_mappings[i].extension_state == extension_state)
            return extension_state_mappings[i].text;
    }
    return "Unknown";
}
 
/*!
 * \internal
 * \brief Handle the ExtensionStateList Manager action
 *
 * \param s The manager session
 * \param m The manager message
 * \retval 0 on success, -1 on failure
 *
 * This function handles the ExtensionStateList Manager action by returning a list of all extension states.
 */
static int action_extensionstatelist(struct mansession *s, const struct message *m)
{
    const char *action_id = astman_get_header(m, "ActionID");
 
    if (!ao2_container_count(extension_states)) {
        astman_send_error(s, m, "No dialplan hints are available");
        return 0;
    }
 
    astman_send_listack(s, m, "Extension Statuses will follow", "start");
 
    ao2_lock(extension_states);
    if (ao2_container_count(extension_states)) {
        struct ao2_iterator it_states;
        struct extension_state *state;
        int count = 0;
 
        it_states = ao2_iterator_init(extension_states, 0);
        for (; (state = ao2_iterator_next(&it_states)); ao2_ref(state, -1)) {
            if (state->extension[0] == '_') {
                continue;
            }
 
            ++count;
 
            astman_append(s, "Event: ExtensionStatus\r\n");
            if (!ast_strlen_zero(action_id)) {
                astman_append(s, "ActionID: %s\r\n", action_id);
            }
            ao2_lock(state);
            astman_append(s,
               "Exten: %s\r\n"
               "Context: %s\r\n"
               "Hint: %s\r\n"
               "Status: %d\r\n"
               "StatusText: %s\r\n\r\n",
               state->dialplan_extension,
               state->dialplan_context,
               state->hint_extension ? ast_get_extension_app(state->hint_extension) : "None",
               state->device_snapshot->state,
               ast_extension_state2str(state->device_snapshot->state));
            ao2_unlock(state);
        }
        ao2_iterator_destroy(&it_states);
        astman_send_list_complete_start(s, m, "ExtensionStateListComplete", count);
        astman_send_list_complete_end(s);
    } else {
        astman_send_error(s, m, "No dialplan hints are available");
    }
 
    ao2_unlock(extension_states);
 
    return 0;
}
 
void pbx_extension_state_hint_set(struct ast_exten *exten, struct ast_context *context)
{
    char extension[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
    struct extension_state *state;
 
    snprintf(extension, sizeof(extension), "%s@%s", ast_get_extension_name(exten), ast_get_context_name(context));
 
    ao2_lock(extension_states);
 
    state = ao2_find(extension_states, extension, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (!state) {
        state = extension_state_alloc(exten, context);
        if (!state) {
            ast_log(LOG_WARNING, "Could not create extension state for hint '%s', it will be unavailable\n",
                extension);
            ao2_unlock(extension_states);
            return;
        }
        ao2_link_flags(extension_states, state, OBJ_NOLOCK);
    }
 
    state->hint_extension = exten;
    if (extension[0] != '_') {
        extension_state_update_sources(state, exten);
    }
    ao2_ref(state, -1);
 
    ao2_unlock(extension_states);
}
 
void pbx_extension_state_hint_remove(struct ast_exten *exten, struct ast_context *context)
{
    char extension[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 2];
    struct extension_state *state;
 
    snprintf(extension, sizeof(extension), "%s@%s", ast_get_extension_name(exten), ast_get_context_name(context));
 
    ao2_lock(extension_states);
 
    state = ao2_find(extension_states, extension, OBJ_SEARCH_KEY | OBJ_NOLOCK);
 
    /* If this is not the latest hint extension that configured this extension state it can't remove it */
    if (!state || state->hint_extension != exten) {
        ao2_unlock(extension_states);
        ao2_cleanup(state);
        return;
    }
 
    extension_state_shutdown(state);
    ao2_unlink_flags(extension_states, state, OBJ_NOLOCK);
    ao2_ref(state, -1);
 
    ao2_unlock(extension_states);
}
 
struct stasis_topic *ast_extension_state_topic_all(void)
{
    return extension_state_topic_all;
}
 
struct stasis_topic *ast_extension_state_topic(const char *exten, const char *context)
{
    struct extension_state *state;
    struct stasis_topic *topic;
 
    state = extension_state_get(NULL, context, exten);
    if (!state) {
        return NULL;
    }
 
    ao2_lock(state);
    topic = ao2_bump(state->extension_state_topic);
    ao2_unlock(state);
    ao2_ref(state, -1);
 
    return topic;
}
 
/*!
 * \internal
 * \brief Refresh the device snapshot of an extension state if it contains invalid device states
 *
 * \param state The extension state to refresh
 *
 * \pre The extension state must be locked by the caller before calling this function.
 *
 * This function checks whether any of the cached device states of the extension state are invalid
 * and if so attempts to retrieve the latest device state. If a valid device state is retrieved then
 * the source is updated and an update message is published to any subscribers.
 */
static void extension_state_device_snapshot_refresh(struct extension_state *state)
{
    struct ast_devstate_aggregate agg;
    enum ast_extension_states new_device_state;
    int i;
    int invalid = 0;
 
    /* If no cached device state is invalid then there is nothing to refresh */
    for (i = 0; i < AST_VECTOR_SIZE(&state->device_state_sources); i++) {
        struct extension_state_device_source *source = AST_VECTOR_GET(&state->device_state_sources, i);
 
        if (source->info->state == AST_DEVICE_INVALID) {
            invalid = 1;
            break;
        }
    }
    if (!invalid) {
        return;
    }
 
    ast_devstate_aggregate_init(&agg);
 
    for (i = 0; i < AST_VECTOR_SIZE(&state->device_state_sources); i++) {
        struct extension_state_device_source *source = AST_VECTOR_GET(&state->device_state_sources, i);
 
        /*
         * An invalid state may be because the device state provider was not available when the
         * state was last queried, such as when the hint was created before the provider was
         * loaded. Since a caller is explicitly requesting the state we make another attempt to
         * retrieve it and if it has changed update it and notify any subscribers.
         */
        if (source->info->state == AST_DEVICE_INVALID) {
            enum ast_device_state device_state = ast_device_state(source->info->device);
 
            if (device_state != source->info->state) {
                struct ast_extension_state_device_state_info *info;
 
                info = extension_state_device_state_info_alloc(source->info->device, device_state);
                if (info) {
                    ao2_replace(source->info, info);
                    ao2_ref(info, -1);
                }
            }
        }
 
        ast_devstate_aggregate_add(&agg, source->info->state);
    }
 
    new_device_state = ast_devstate_to_extenstate(ast_devstate_aggregate_result(&agg));
    if (new_device_state != state->device_snapshot->state) {
        struct ast_extension_state_device_snapshot *device_snapshot;
        struct ast_extension_state_update_message *update_message;
 
        device_snapshot = extension_state_device_snapshot_create(new_device_state, &state->device_state_sources, NULL);
        if (!device_snapshot) {
            return;
        }
 
        update_message = extension_state_update_message_create(state->dialplan_context, state->dialplan_extension,
            state->device_snapshot, device_snapshot, state->presence_snapshot, state->presence_snapshot);
 
        /* Even if we can't publish an update message we still ensure the local cached snapshot is up to date */
        ao2_replace(state->device_snapshot, device_snapshot);
        ao2_ref(device_snapshot, -1);
 
        if (update_message) {
            struct stasis_message *message = stasis_message_create(ast_extension_state_update_message_type(), update_message);
 
            if (message) {
                stasis_publish(state->extension_state_topic, message);
                ao2_ref(message, -1);
            }
 
            ao2_ref(update_message, -1);
        }
    }
}
 
struct ast_extension_state_device_snapshot *ast_extension_state_get_latest_device_snapshot(struct ast_channel *chan,
    const char *exten, const char *context)
{
    struct extension_state *state;
    struct ast_extension_state_device_snapshot *device_snapshot;
 
    state = extension_state_get(chan, context, exten);
    if (!state) {
        return NULL;
    }
 
    ao2_lock(state);
    extension_state_device_snapshot_refresh(state);
    device_snapshot = ao2_bump(state->device_snapshot);
    ao2_unlock(state);
    ao2_ref(state, -1);
 
    return device_snapshot;
}
 
/*!
 * \internal
 * \brief Refresh the presence snapshot of an extension state if it is invalid
 *
 * \param state The extension state to refresh
 *
 * \pre The extension state must be locked by the caller before calling this function.
 *
 * This function checks whether the cached presence snapshot of the extension state is invalid
 * and if so attempts to retrieve the latest presence state. If a valid presence state is
 * retrieved then the snapshot is updated and an update message is published to any subscribers.
 */
static void extension_state_presence_snapshot_refresh(struct extension_state *state)
{
    enum ast_presence_state presence_state_new;
    char *presence_subtype;
    char *presence_message;
 
    /*
     * If the cached presence state is invalid it may be because the presence state provider
     * was unable to be reached when it was last queried, or because the resulting update was
     * ignored. Since a caller is explicitly requesting the presence state we make another
     * attempt to retrieve it and if it has changed update it and notify any subscribers.
     */
    if (state->presence_snapshot->presence_state != AST_PRESENCE_INVALID || !state->presence_sources_string) {
        return;
    }
 
    presence_state_new = ast_presence_state(state->presence_sources_string, &presence_subtype, &presence_message);
    if (presence_state_new != AST_PRESENCE_INVALID) {
        struct ast_extension_state_presence_snapshot *new_presence_snapshot;
 
        new_presence_snapshot = extension_state_presence_snapshot_create(presence_state_new, presence_subtype,
            presence_message);
        if (new_presence_snapshot) {
            struct ast_extension_state_update_message *update_message;
 
            update_message = extension_state_update_message_create(state->dialplan_context, state->dialplan_extension,
                state->device_snapshot, state->device_snapshot, state->presence_snapshot, new_presence_snapshot);
            ao2_replace(state->presence_snapshot, new_presence_snapshot);
            ao2_ref(new_presence_snapshot, -1);
 
            if (update_message) {
                struct stasis_message *message = stasis_message_create(ast_extension_state_update_message_type(), update_message);
 
                if (message) {
                    stasis_publish(state->extension_state_topic, message);
                    ao2_ref(message, -1);
                }
 
                ao2_ref(update_message, -1);
            }
        }
    }
 
    ast_free(presence_subtype);
    ast_free(presence_message);
}
 
struct ast_extension_state_presence_snapshot *ast_extension_state_get_latest_presence_snapshot(struct ast_channel *chan,
    const char *exten, const char *context)
{
    struct extension_state *state;
    struct ast_extension_state_presence_snapshot *presence_snapshot;
 
    state = extension_state_get(chan, context, exten);
    if (!state) {
        return NULL;
    }
 
    ao2_lock(state);
    extension_state_presence_snapshot_refresh(state);
    presence_snapshot = ao2_bump(state->presence_snapshot);
    ao2_unlock(state);
    ao2_ref(state, -1);
 
    return presence_snapshot;
}
 
/*!
 * \internal
 * \brief CLI command to show hints
 *
 * \param e The CLI entry
 * \param cmd The command
 * \param a The CLI arguments
 *
 * This function shows all registered hints in the CLI.
 */
static char *handle_show_hints(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
    struct extension_state *state;
    int num = 0;
    struct ao2_iterator i;
 
    switch (cmd) {
    case CLI_INIT:
        e->command = "core show hints";
        e->usage =
            "Usage: core show hints\n"
            "       List registered hints.\n"
            "       Hint details are shown in five columns. In order from left to right, they are:\n"
            "       1. Hint extension URI.\n"
            "       2. List of mapped device or presence state identifiers.\n"
            "       3. Current extension state. The aggregate of mapped device states.\n"
            "       4. Current presence state for the mapped presence state provider.\n"
            "       5. Watchers - number of subscriptions and other entities watching this hint.\n";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }
 
    if (ao2_container_count(extension_states) == 0) {
        ast_cli(a->fd, "There are no registered dialplan hints\n");
        return CLI_SUCCESS;
    }
    /* ... we have hints ... */
    ast_cli(a->fd, "\n    -= Registered Asterisk Dial Plan Hints =-\n");
 
    i = ao2_iterator_init(extension_states, 0);
    for (; (state = ao2_iterator_next(&i)); ao2_ref(state, -1)) {
        ao2_lock(state);
        extension_state_device_snapshot_refresh(state);
        extension_state_presence_snapshot_refresh(state);
        ast_cli(a->fd, "%-30.30s: %-60.60s  State:%-15.15s Presence:%-15.15s Watchers %2zd\n",
            state->extension,
            state->hint_extension ? ast_get_extension_app(state->hint_extension) : "None",
            ast_extension_state2str(state->device_snapshot->state),
            ast_presence_state2str(state->presence_snapshot->presence_state),
            state->extension_state_topic ? stasis_topic_subscribers(state->extension_state_topic) : 0);
        ao2_unlock(state);
 
        num++;
    }
    ao2_iterator_destroy(&i);
 
    ast_cli(a->fd, "----------------\n");
    ast_cli(a->fd, "- %d hints registered\n", num);
    return CLI_SUCCESS;
}
 
/*!
 * \internal
 * \brief Complete the core show hint CLI command
 *
 * \param line The command line
 * \param word The word being completed
 * \param pos The position in the command
 * \param state The completion state
 *
 * This function completes the core show hint CLI command.
 */
static char *complete_core_show_hint(const char *line, const char *word, int pos, int state)
{
    struct extension_state *extstate;
    char *ret = NULL;
    int which = 0;
    int wordlen;
    struct ao2_iterator i;
 
    if (pos != 3)
        return NULL;
 
    wordlen = strlen(word);
 
    /* walk through all hints */
    i = ao2_iterator_init(extension_states, 0);
    for (; (extstate = ao2_iterator_next(&i)); ao2_ref(extstate, -1)) {
        ao2_lock(extstate);
        if (!strncasecmp(word, extstate->dialplan_extension, wordlen) && ++which > state) {
            ret = ast_strdup(extstate->dialplan_extension);
            ao2_unlock(extstate);
            ao2_ref(extstate, -1);
            break;
        }
        ao2_unlock(extstate);
    }
    ao2_iterator_destroy(&i);
 
    return ret;
}
 
/*!
 * \internal
 * \brief CLI support for listing registered dial plan hint
 *
 * \param e The CLI entry
 * \param cmd The command
 * \param a The CLI arguments
 *
 * This function handles the core show hint CLI command.
 */
static char *handle_show_hint(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
    struct extension_state *extstate;
    int num = 0, extenlen;
    struct ao2_iterator i;
 
    switch (cmd) {
    case CLI_INIT:
        e->command = "core show hint";
        e->usage =
            "Usage: core show hint <exten>\n"
            "       List registered hint.\n"
            "       Hint details are shown in five columns. In order from left to right, they are:\n"
            "       1. Hint extension URI.\n"
            "       2. List of mapped device or presence state identifiers.\n"
            "       3. Current extension state. The aggregate of mapped device states.\n"
            "       4. Current presence state for the mapped presence state provider.\n"
            "       5. Watchers - number of subscriptions and other entities watching this hint.\n";
        return NULL;
    case CLI_GENERATE:
        return complete_core_show_hint(a->line, a->word, a->pos, a->n);
    }
 
    if (a->argc < 4)
        return CLI_SHOWUSAGE;
 
    if (ao2_container_count(extension_states) == 0) {
        ast_cli(a->fd, "There are no registered dialplan hints\n");
        return CLI_SUCCESS;
    }
 
    extenlen = strlen(a->argv[3]);
    i = ao2_iterator_init(extension_states, 0);
    for (; (extstate = ao2_iterator_next(&i)); ao2_ref(extstate, -1)) {
        ao2_lock(extstate);
        if (!strncasecmp(extstate->extension, a->argv[3], extenlen)) {
            extension_state_device_snapshot_refresh(extstate);
            extension_state_presence_snapshot_refresh(extstate);
            ast_cli(a->fd, "%-30.30s: %-60.60s  State:%-15.15s Presence:%-15.15s Watchers %2zd\n",
                extstate->extension,
                extstate->hint_extension ? ast_get_extension_app(extstate->hint_extension) : "None",
                ast_extension_state2str(extstate->device_snapshot->state),
                ast_presence_state2str(extstate->presence_snapshot->presence_state),
                extstate->extension_state_topic ? stasis_topic_subscribers(extstate->extension_state_topic) : 0);
            num++;
        }
        ao2_unlock(extstate);
    }
    ao2_iterator_destroy(&i);
    if (!num)
        ast_cli(a->fd, "No hints matching extension %s\n", a->argv[3]);
    else
        ast_cli(a->fd, "%d hint%s matching extension %s\n", num, (num!=1 ? "s":""), a->argv[3]);
    return CLI_SUCCESS;
}
 
static struct ast_cli_entry extension_state_cli[] = {
    AST_CLI_DEFINE(handle_show_hints, "Show dialplan hints"),
    AST_CLI_DEFINE(handle_show_hint, "Show dialplan hint"),
};
 
/*!
 * \internal
 * \brief Callback function to clean up an individual extension state.
 *
 * \param obj The extension state object
 * \param arg Additional argument (not used)
 * \param flags Flags for the callback
 * \return CMP_MATCH if the object was processed, 0 otherwise
 */
static int extension_state_cleanup_individual(void *obj, void *arg, int flags)
{
    struct extension_state *state = obj;
 
    extension_state_shutdown(state);
 
    return CMP_MATCH;
}
 
/*!
 * \internal
 * \brief Clean up the extension state subsystem, called at shutdown.
 */
static void extension_state_cleanup(void)
{
    ast_cli_unregister_multiple(extension_state_cli, ARRAY_LEN(extension_state_cli));
    ast_manager_unregister("ExtensionStateList");
    if (extension_states) {
        ao2_callback(extension_states, OBJ_NODATA | OBJ_MULTIPLE | OBJ_UNLINK, extension_state_cleanup_individual, NULL);
        ao2_ref(extension_states, -1);
    }
    presence_state_sub = stasis_unsubscribe_and_join(presence_state_sub);
    STASIS_MESSAGE_TYPE_CLEANUP(ast_extension_state_update_message_type);
    STASIS_MESSAGE_TYPE_CLEANUP(ast_extension_state_remove_message_type);
}
 
int ast_extension_state_init(void)
{
    if (STASIS_MESSAGE_TYPE_INIT(ast_extension_state_update_message_type) != 0) {
        return -1;
    }
 
    if (STASIS_MESSAGE_TYPE_INIT(ast_extension_state_remove_message_type) != 0) {
        return -1;
    }
 
    /* Initialize extension state subsystem */
    extension_states = ao2_container_alloc_rbtree(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
        extension_state_sort_fn, extension_state_cmp_fn);
    if (!extension_states) {
        ast_log(LOG_ERROR, "Failed to allocate new states container\n");
        return -1;
    }
 
    extension_state_topic_all = stasis_topic_create("extension_state:all");
    if (!extension_state_topic_all) {
        ast_log(LOG_ERROR, "Failed to create extension state topic\n");
        return -1;
    }
 
    presence_state_sub = stasis_subscribe(ast_presence_state_topic_all(), extension_state_presence_state_cb, NULL);
    if (!presence_state_sub) {
        ast_log(LOG_ERROR, "Failed to create subscription to receive presence state updates\n");
        return -1;
    }
    stasis_subscription_accept_message_type(presence_state_sub, ast_presence_state_message_type());
    stasis_subscription_set_filter(presence_state_sub, STASIS_SUBSCRIPTION_FILTER_SELECTIVE);
 
    ast_cli_register_multiple(extension_state_cli, ARRAY_LEN(extension_state_cli));
    ast_manager_register_xml_core("ExtensionStateList", EVENT_FLAG_CALL | EVENT_FLAG_REPORTING, action_extensionstatelist);
    ast_register_cleanup(extension_state_cleanup);
 
    return 0;
}