Asterisk - The Open Source Telephony Project GIT-master-2de1a68
stasis_endpoints.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 2013, Digium, Inc.
5 *
6 * David M. Lee, II <dlee@digium.com>
7 *
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
13 *
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
17 */
18
19#ifndef _ASTERISK_STASIS_ENDPOINTS_H
20#define _ASTERISK_STASIS_ENDPOINTS_H
21
22/*! \file
23 *
24 * \brief Endpoint abstractions.
25 *
26 * \author David M. Lee, II <dlee@digium.com>
27 * \since 12
28 */
29
30#include "asterisk/endpoints.h"
31#include "asterisk/stasis.h"
34
35/*! \addtogroup StasisTopicsAndMessages
36 * @{
37 */
38
39/*!
40 * \brief A snapshot of an endpoint's state.
41 *
42 * The id for an endpoint is tech/resource. The duplication is needed because
43 * there are several cases where any of the three values would be needed, and
44 * constantly splitting or reassembling would be a pain.
45 *
46 * \since 12
47 */
50 AST_STRING_FIELD(id); /*!< unique id for this endpoint. */
51 AST_STRING_FIELD(tech); /*!< Channel technology */
52 AST_STRING_FIELD(resource); /*!< Tech-unique name */
53 );
54
55 /*! Endpoint state */
57 /*!
58 * Maximum number of channels this endpoint supports. If the upper limit
59 * for an endpoint is unknown, this field is set to -1.
60 */
62 /*! Number of channels currently active on this endpoint */
64 /*! Channel ids */
65 char *channel_ids[];
66};
67
68/*!
69 * \brief Blob of data associated with an endpoint.
70 *
71 * The blob is actually a JSON object of structured data. It has a "type" field
72 * which contains the type string describing this blob.
73 *
74 * \since 12
75 */
78 struct ast_json *blob;
79};
80
81/*!
82 * \since 12
83 * \brief Creates a \ref ast_endpoint_blob message.
84 *
85 * The given \a blob should be treated as immutable and not modified after it is
86 * put into the message.
87 *
88 * \param endpoint Endpoint blob is associated with.
89 * \param type Message type for this blob.
90 * \param blob JSON object representing the data, or \c NULL for no data. If
91 * \c NULL, ast_json_null() is put into the object.
92 *
93 * \return \ref ast_endpoint_blob message.
94 * \retval NULL on error
95 */
97 struct stasis_message_type *type, struct ast_json *blob);
98
99/*!
100 * \since 12
101 * \brief Creates and publishes a \ref ast_endpoint_blob message.
102 *
103 * The given \a blob should be treated as immutable and not modified after it is
104 * put into the message.
105 *
106 * \param endpoint Endpoint blob is associated with.
107 * \param type Message type for this blob.
108 * \param blob JSON object representing the data, or \c NULL for no data. If
109 * \c NULL, ast_json_null() is put into the object.
110 */
112 struct ast_json *blob);
113
114/*!
115 * \brief Message type for endpoint state changes.
116 * \since 12
117 */
119
120/*!
121 * \brief Message type for endpoint contact state changes.
122 * \since 13.5
123 */
125
126/*!
127 * \brief Message type for \ref ast_endpoint_snapshot.
128 * \since 12
129 */
131
132/*!
133 * \brief Create a snapshot of an endpoint
134 * \param endpoint Endpoint to snap a shot of.
135 * \return Snapshot of the endpoint.
136 * \retval NULL on error.
137 * \since 12
138 */
140 struct ast_endpoint *endpoint);
141
142/*!
143 * \brief Returns the topic for a specific endpoint.
144 *
145 * \param endpoint The endpoint.
146 * \return The topic for the given endpoint.
147 * \return ast_endpoint_topic_all() if endpoint is \c NULL.
148 * \since 12
149 */
150struct stasis_topic *ast_endpoint_topic(struct ast_endpoint *endpoint);
151
152/*!
153 * \brief Returns the topic for a specific endpoint.
154 *
155 * \ref ast_endpoint_snapshot messages are replaced with
156 * \ref stasis_cache_update
157 *
158 * \param endpoint The endpoint.
159 * \return The topic for the given endpoint.
160 * \return ast_endpoint_topic_all() if endpoint is \c NULL.
161 * \since 12
162 */
163struct stasis_topic *ast_endpoint_topic_cached(struct ast_endpoint *endpoint);
164
165/*!
166 * \internal
167 * \brief Cache and global topics for endpoints.
168 *
169 * This is public simply to be used by endpoints.c. Please use the accessor
170 * functions (ast_endpoint_topic_all(), ast_endpoint_topic_all_cached(),
171 * ast_endpoint_cache(), etc.) instead of calling this directly.
172 *
173 * \since 12
174 */
176
177/*!
178 * \brief Topic for all endpoint related messages.
179 * \since 12
180 */
182
183/*!
184 * \brief Cached topic for all endpoint related messages.
185 * \since 12
186 */
188
189/*!
190 * \brief Backend cache for ast_endpoint_topic_all_cached().
191 * \return Cache of \ref ast_endpoint_snapshot.
192 * \since 12
193 */
194struct stasis_cache *ast_endpoint_cache(void);
195
196/*!
197 * \brief Retrieve the most recent snapshot for the endpoint with the given
198 * name.
199 *
200 * \param tech Name of the endpoint's technology.
201 * \param resource Resource name of the endpoint.
202 * \return Snapshot of the endpoint with the given name.
203 * \retval NULL if endpoint is not found, or on error.
204 * \since 12
205 */
207 const char *resource
208);
209
210/*! @} */
211
212/*!
213 * \brief Build a JSON object from a \ref ast_endpoint_snapshot.
214 *
215 * \param snapshot Endpoint snapshot.
216 * \param sanitize The message sanitizer to use on the snapshot
217 *
218 * \return JSON object representing endpoint snapshot.
219 * \retval NULL on error
220 */
222 const struct ast_endpoint_snapshot *snapshot,
223 const struct stasis_message_sanitizer *sanitize);
224
225/*!
226 * \brief Initialization function for endpoint stasis support.
227 *
228 * \return 0 on success.
229 * \return non-zero on error.
230 * \since 12
231 */
233
234#endif /* _ASTERISK_STASIS_ENDPOINTS_H */
static const char type[]
Definition: chan_ooh323.c:109
Endpoint abstractions.
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
struct stasis_topic * ast_endpoint_topic_cached(struct ast_endpoint *endpoint)
Returns the topic for a specific endpoint.
void ast_endpoint_blob_publish(struct ast_endpoint *endpoint, struct stasis_message_type *type, struct ast_json *blob)
Creates and publishes a ast_endpoint_blob message.
struct stasis_topic * ast_endpoint_topic_all(void)
Topic for all endpoint related messages.
struct stasis_message_type * ast_endpoint_contact_state_type(void)
Message type for endpoint contact state changes.
struct stasis_message_type * ast_endpoint_snapshot_type(void)
Message type for ast_endpoint_snapshot.
struct stasis_topic * ast_endpoint_topic(struct ast_endpoint *endpoint)
Returns the topic for a specific endpoint.
struct stasis_topic * ast_endpoint_topic_all_cached(void)
Cached topic for all endpoint related messages.
struct stasis_cp_all * ast_endpoint_cache_all(void)
struct ast_endpoint_snapshot * ast_endpoint_snapshot_create(struct ast_endpoint *endpoint)
Create a snapshot of an endpoint.
struct ast_endpoint_snapshot * ast_endpoint_latest_snapshot(const char *tech, const char *resource)
Retrieve the most recent snapshot for the endpoint with the given name.
struct stasis_message_type * ast_endpoint_state_type(void)
Message type for endpoint state changes.
struct stasis_message * ast_endpoint_blob_create(struct ast_endpoint *endpoint, struct stasis_message_type *type, struct ast_json *blob)
Creates a ast_endpoint_blob message.
struct stasis_cache * ast_endpoint_cache(void)
Backend cache for ast_endpoint_topic_all_cached().
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
Caching pattern for Stasis Message Bus API topics.
struct ast_json * ast_endpoint_snapshot_to_json(const struct ast_endpoint_snapshot *snapshot, const struct stasis_message_sanitizer *sanitize)
Build a JSON object from a ast_endpoint_snapshot.
int ast_endpoint_stasis_init(void)
Initialization function for endpoint stasis support.
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Blob of data associated with an endpoint.
struct ast_endpoint_snapshot * snapshot
struct ast_json * blob
A snapshot of an endpoint's state.
const ast_string_field tech
enum ast_endpoint_state state
const ast_string_field resource
Abstract JSON element (object, array, string, int, ...).
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200