stasis_endpoints.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2013, Digium, Inc.
 *
 * David M. Lee, II <[email protected]>
 *
 * 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 <[email protected]>
 * \since 12
 */

#include "asterisk/endpoints.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 endpoint contact state changes.
 * \since 13.5
 */
struct stasis_message_type *ast_endpoint_contact_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.
 * \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
);

/*! @} */

/*!
 * \brief Build a JSON object from a \ref ast_endpoint_snapshot.
 *
 * \param snapshot Endpoint snapshot.
 * \param sanitize The message sanitizer to use on the 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,
   const struct stasis_message_sanitizer *sanitize);

/*!
 * \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 */