Asterisk - The Open Source Telephony Project  GIT-master-09303e8
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"
33 #include "asterisk/stringfields.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  * \return \c 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  */
111 void ast_endpoint_blob_publish(struct ast_endpoint *endpoint, struct stasis_message_type *type,
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  * \return \c 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  */
150 struct 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  */
163 struct 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 releated 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  */
194 struct 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  * \return \c 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  * \return \c 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  */
232 int ast_endpoint_stasis_init(void);
233 
234 #endif /* _ASTERISK_STASIS_ENDPOINTS_H */
static const char type[]
Definition: chan_ooh323.c:109
Caching pattern for Stasis Message Bus API topics.
struct ast_endpoint_snapshot * ast_endpoint_snapshot_create(struct ast_endpoint *endpoint)
Create a snapshot of an endpoint.
struct stasis_cp_all * ast_endpoint_cache_all(void)
Stasis Message Bus API. See Stasis Message Bus API for detailed documentation.
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_message_type * ast_endpoint_snapshot_type(void)
Message type for ast_endpoint_snapshot.
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_topic * ast_endpoint_topic(struct ast_endpoint *endpoint)
Returns the topic for a specific endpoint.
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:337
Endpoint abstractions.
ast_endpoint_state
Valid states for an endpoint.
Definition: endpoints.h:51
Blob of data associated with an endpoint.
Structure containing callbacks for Stasis message sanitization.
Definition: stasis.h:200
struct stasis_topic * ast_endpoint_topic_all_cached(void)
Cached topic for all endpoint related messages.
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:299
const ast_string_field resource
A snapshot of an endpoint&#39;s state.
struct stasis_topic * ast_endpoint_topic_cached(struct ast_endpoint *endpoint)
Returns the topic for a specific endpoint.
const ast_string_field tech
struct stasis_message_type * ast_endpoint_state_type(void)
Message type for endpoint state changes.
struct ast_json * blob
struct stasis_topic * ast_endpoint_topic_all(void)
Topic for all endpoint releated messages.
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 ast_endpoint_snapshot * snapshot
struct stasis_message_type * ast_endpoint_contact_state_type(void)
Message type for endpoint contact state changes.
Abstract JSON element (object, array, string, int, ...).
enum ast_endpoint_state state
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.
struct stasis_cache * ast_endpoint_cache(void)
Backend cache for ast_endpoint_topic_all_cached().