mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-02 10:22:46 +00:00
e1b959ccbb
In working with res_stasis, I discovered a significant limitation to
the current structure of stasis_caching_topics: you cannot subscribe
to cache updates for a single channel/bridge/endpoint/etc.
To address this, this patch splits the cache away from the
stasis_caching_topic, making it a first class object. The stasis_cache
object is shared amongst individual stasis_caching_topics that are
created per channel/endpoint/etc. These are still forwarded to global
whatever_all_cached topics, so their use from most of the code does
not change.
In making these changes, I noticed that we frequently used a similar
pattern for bridges, endpoints and channels:
single_topic ----------------> all_topic
^
|
single_topic_cached ----+----> all_topic_cached
|
+----> cache
This pattern was extracted as the 'Stasis Caching Pattern', defined in
stasis_caching_pattern.h. This avoids a lot of duplicate code between
the different domain objects.
Since the cache is now disassociated from its upstream caching topics,
this also necessitated a change to how the 'guaranteed' flag worked
for retrieving from a cache. The code for handling the caching
guarantee was extracted into a 'stasis_topic_wait' function, which
works for any stasis_topic.
(closes issue ASTERISK-22002)
Review: https://reviewboard.asterisk.org/r/2672/
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@395954 65c4cc65-6c06-0410-ace0-fbb531ad65f3
229 lines
6.3 KiB
C
229 lines
6.3 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2013, Digium, Inc.
|
|
*
|
|
* David M. Lee, II <dlee@digium.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.
|
|
*/
|
|
|
|
#ifndef _ASTERISK_STASIS_ENDPOINTS_H
|
|
#define _ASTERISK_STASIS_ENDPOINTS_H
|
|
|
|
/*! \file
|
|
*
|
|
* \brief Endpoint abstractions.
|
|
*
|
|
* \author David M. Lee, II <dlee@digium.com>
|
|
* \since 12
|
|
*/
|
|
|
|
#include "asterisk/endpoints.h"
|
|
#include "asterisk/json.h"
|
|
#include "asterisk/stasis.h"
|
|
#include "asterisk/stasis_cache_pattern.h"
|
|
#include "asterisk/stringfields.h"
|
|
|
|
/*! \addtogroup StasisTopicsAndMessages
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* \brief A snapshot of an endpoint's state.
|
|
*
|
|
* The id for an endpoint is tech/resource. The duplication is needed because
|
|
* there are several cases where any of the three values would be needed, and
|
|
* constantly splitting or reassembling would be a pain.
|
|
*
|
|
* \since 12
|
|
*/
|
|
struct ast_endpoint_snapshot {
|
|
AST_DECLARE_STRING_FIELDS(
|
|
AST_STRING_FIELD(id); /*!< unique id for this endpoint. */
|
|
AST_STRING_FIELD(tech); /*!< Channel technology */
|
|
AST_STRING_FIELD(resource); /*!< Tech-unique name */
|
|
);
|
|
|
|
/*! Endpoint state */
|
|
enum ast_endpoint_state state;
|
|
/*!
|
|
* Maximum number of channels this endpoint supports. If the upper limit
|
|
* for an endpoint is unknown, this field is set to -1.
|
|
*/
|
|
int max_channels;
|
|
/*! Number of channels currently active on this endpoint */
|
|
int num_channels;
|
|
/*! Channel ids */
|
|
char *channel_ids[];
|
|
};
|
|
|
|
/*!
|
|
* \brief Blob of data associated with an endpoint.
|
|
*
|
|
* The blob is actually a JSON object of structured data. It has a "type" field
|
|
* which contains the type string describing this blob.
|
|
*
|
|
* \since 12
|
|
*/
|
|
struct ast_endpoint_blob {
|
|
struct ast_endpoint_snapshot *snapshot;
|
|
struct ast_json *blob;
|
|
};
|
|
|
|
/*!
|
|
* \since 12
|
|
* \brief Creates a \ref ast_endpoint_blob message.
|
|
*
|
|
* The given \a blob should be treated as immutable and not modified after it is
|
|
* put into the message.
|
|
*
|
|
* \param endpoint Endpoint blob is associated with.
|
|
* \param type Message type for this blob.
|
|
* \param blob JSON object representing the data, or \c NULL for no data. If
|
|
* \c NULL, ast_json_null() is put into the object.
|
|
*
|
|
* \return \ref ast_endpoint_blob message.
|
|
* \return \c NULL on error
|
|
*/
|
|
struct stasis_message *ast_endpoint_blob_create(struct ast_endpoint *endpoint,
|
|
struct stasis_message_type *type, struct ast_json *blob);
|
|
|
|
/*!
|
|
* \since 12
|
|
* \brief Creates and publishes a \ref ast_endpoint_blob message.
|
|
*
|
|
* The given \a blob should be treated as immutable and not modified after it is
|
|
* put into the message.
|
|
*
|
|
* \param endpoint Endpoint blob is associated with.
|
|
* \param type Message type for this blob.
|
|
* \param blob JSON object representing the data, or \c NULL for no data. If
|
|
* \c NULL, ast_json_null() is put into the object.
|
|
*/
|
|
void ast_endpoint_blob_publish(struct ast_endpoint *endpoint, struct stasis_message_type *type,
|
|
struct ast_json *blob);
|
|
|
|
/*!
|
|
* \brief Message type for endpoint state changes.
|
|
* \since 12
|
|
*/
|
|
struct stasis_message_type *ast_endpoint_state_type(void);
|
|
|
|
/*!
|
|
* \brief Message type for \ref ast_endpoint_snapshot.
|
|
* \since 12
|
|
*/
|
|
struct stasis_message_type *ast_endpoint_snapshot_type(void);
|
|
|
|
/*!
|
|
* \brief Create a snapshot of an endpoint
|
|
* \param endpoint Endpoint to snap a shot of.
|
|
* \return Snapshot of the endpoint.
|
|
* \return \c NULL on error.
|
|
* \since 12
|
|
*/
|
|
struct ast_endpoint_snapshot *ast_endpoint_snapshot_create(
|
|
struct ast_endpoint *endpoint);
|
|
|
|
/*!
|
|
* \brief Returns the topic for a specific endpoint.
|
|
*
|
|
* \param endpoint The endpoint.
|
|
* \return The topic for the given endpoint.
|
|
* \return ast_endpoint_topic_all() if endpoint is \c NULL.
|
|
* \since 12
|
|
*/
|
|
struct stasis_topic *ast_endpoint_topic(struct ast_endpoint *endpoint);
|
|
|
|
/*!
|
|
* \brief Returns the topic for a specific endpoint.
|
|
*
|
|
* \ref ast_endpoint_snapshot messages are replaced with
|
|
* \ref stasis_cache_update
|
|
*
|
|
* \param endpoint The endpoint.
|
|
* \return The topic for the given endpoint.
|
|
* \return ast_endpoint_topic_all() if endpoint is \c NULL.
|
|
* \since 12
|
|
*/
|
|
struct stasis_topic *ast_endpoint_topic_cached(struct ast_endpoint *endpoint);
|
|
|
|
/*!
|
|
* \internal
|
|
* \brief Cache and global topics for endpoints.
|
|
*
|
|
* This is public simply to be used by endpoints.c. Please use the accessor
|
|
* functions (ast_endpoint_topic_all(), ast_endpoint_topic_all_cached(),
|
|
* ast_endpoint_cache(), etc.) instead of calling this directly.
|
|
*
|
|
* \since 12
|
|
*/
|
|
struct stasis_cp_all *ast_endpoint_cache_all(void);
|
|
|
|
/*!
|
|
* \brief Topic for all endpoint releated messages.
|
|
* \since 12
|
|
*/
|
|
struct stasis_topic *ast_endpoint_topic_all(void);
|
|
|
|
/*!
|
|
* \brief Cached topic for all endpoint related messages.
|
|
* \since 12
|
|
*/
|
|
struct stasis_topic *ast_endpoint_topic_all_cached(void);
|
|
|
|
/*!
|
|
* \brief Backend cache for ast_endpoint_topic_all_cached().
|
|
* \return Cache of \ref ast_endpoint_snapshot.
|
|
* \since 12
|
|
*/
|
|
struct stasis_cache *ast_endpoint_cache(void);
|
|
|
|
/*!
|
|
* \brief Retrieve the most recent snapshot for the endpoint with the given
|
|
* name.
|
|
*
|
|
* \param tech Name of the endpoint's technology.
|
|
* \param resource Resource name of the endpoint.
|
|
* \param guaranteed Whether to require all pending messages to have been processed or not.
|
|
* \return Snapshot of the endpoint with the given name.
|
|
* \return \c NULL if endpoint is not found, or on error.
|
|
* \since 12
|
|
*/
|
|
struct ast_endpoint_snapshot *ast_endpoint_latest_snapshot(const char *tech,
|
|
const char *resource,
|
|
unsigned int guaranteed
|
|
);
|
|
|
|
/*! @} */
|
|
|
|
/*!
|
|
* \brief Build a JSON object from a \ref ast_endpoint_snapshot.
|
|
*
|
|
* \param snapshot Endpoint snapshot.
|
|
* \return JSON object representing endpoint snapshot.
|
|
* \return \c NULL on error
|
|
*/
|
|
struct ast_json *ast_endpoint_snapshot_to_json(
|
|
const struct ast_endpoint_snapshot *snapshot);
|
|
|
|
/*!
|
|
* \brief Initialization function for endpoint stasis support.
|
|
*
|
|
* \return 0 on success.
|
|
* \return non-zero on error.
|
|
* \since 12
|
|
*/
|
|
int ast_endpoint_stasis_init(void);
|
|
|
|
#endif /* _ASTERISK_STASIS_ENDPOINTS_H */
|