stasis_endpoints.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234
  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. #ifndef _ASTERISK_STASIS_ENDPOINTS_H
  19. #define _ASTERISK_STASIS_ENDPOINTS_H
  20. /*! \file
  21. *
  22. * \brief Endpoint abstractions.
  23. *
  24. * \author David M. Lee, II <dlee@digium.com>
  25. * \since 12
  26. */
  27. #include "asterisk/endpoints.h"
  28. #include "asterisk/stasis.h"
  29. #include "asterisk/stasis_cache_pattern.h"
  30. #include "asterisk/stringfields.h"
  31. /*! \addtogroup StasisTopicsAndMessages
  32. * @{
  33. */
  34. /*!
  35. * \brief A snapshot of an endpoint's state.
  36. *
  37. * The id for an endpoint is tech/resource. The duplication is needed because
  38. * there are several cases where any of the three values would be needed, and
  39. * constantly splitting or reassembling would be a pain.
  40. *
  41. * \since 12
  42. */
  43. struct ast_endpoint_snapshot {
  44. AST_DECLARE_STRING_FIELDS(
  45. AST_STRING_FIELD(id); /*!< unique id for this endpoint. */
  46. AST_STRING_FIELD(tech); /*!< Channel technology */
  47. AST_STRING_FIELD(resource); /*!< Tech-unique name */
  48. );
  49. /*! Endpoint state */
  50. enum ast_endpoint_state state;
  51. /*!
  52. * Maximum number of channels this endpoint supports. If the upper limit
  53. * for an endpoint is unknown, this field is set to -1.
  54. */
  55. int max_channels;
  56. /*! Number of channels currently active on this endpoint */
  57. int num_channels;
  58. /*! Channel ids */
  59. char *channel_ids[];
  60. };
  61. /*!
  62. * \brief Blob of data associated with an endpoint.
  63. *
  64. * The blob is actually a JSON object of structured data. It has a "type" field
  65. * which contains the type string describing this blob.
  66. *
  67. * \since 12
  68. */
  69. struct ast_endpoint_blob {
  70. struct ast_endpoint_snapshot *snapshot;
  71. struct ast_json *blob;
  72. };
  73. /*!
  74. * \since 12
  75. * \brief Creates a \ref ast_endpoint_blob message.
  76. *
  77. * The given \a blob should be treated as immutable and not modified after it is
  78. * put into the message.
  79. *
  80. * \param endpoint Endpoint blob is associated with.
  81. * \param type Message type for this blob.
  82. * \param blob JSON object representing the data, or \c NULL for no data. If
  83. * \c NULL, ast_json_null() is put into the object.
  84. *
  85. * \return \ref ast_endpoint_blob message.
  86. * \return \c NULL on error
  87. */
  88. struct stasis_message *ast_endpoint_blob_create(struct ast_endpoint *endpoint,
  89. struct stasis_message_type *type, struct ast_json *blob);
  90. /*!
  91. * \since 12
  92. * \brief Creates and publishes a \ref ast_endpoint_blob message.
  93. *
  94. * The given \a blob should be treated as immutable and not modified after it is
  95. * put into the message.
  96. *
  97. * \param endpoint Endpoint blob is associated with.
  98. * \param type Message type for this blob.
  99. * \param blob JSON object representing the data, or \c NULL for no data. If
  100. * \c NULL, ast_json_null() is put into the object.
  101. */
  102. void ast_endpoint_blob_publish(struct ast_endpoint *endpoint, struct stasis_message_type *type,
  103. struct ast_json *blob);
  104. /*!
  105. * \brief Message type for endpoint state changes.
  106. * \since 12
  107. */
  108. struct stasis_message_type *ast_endpoint_state_type(void);
  109. /*!
  110. * \brief Message type for endpoint contact state changes.
  111. * \since 13.5
  112. */
  113. struct stasis_message_type *ast_endpoint_contact_state_type(void);
  114. /*!
  115. * \brief Message type for \ref ast_endpoint_snapshot.
  116. * \since 12
  117. */
  118. struct stasis_message_type *ast_endpoint_snapshot_type(void);
  119. /*!
  120. * \brief Create a snapshot of an endpoint
  121. * \param endpoint Endpoint to snap a shot of.
  122. * \return Snapshot of the endpoint.
  123. * \return \c NULL on error.
  124. * \since 12
  125. */
  126. struct ast_endpoint_snapshot *ast_endpoint_snapshot_create(
  127. struct ast_endpoint *endpoint);
  128. /*!
  129. * \brief Returns the topic for a specific endpoint.
  130. *
  131. * \param endpoint The endpoint.
  132. * \return The topic for the given endpoint.
  133. * \return ast_endpoint_topic_all() if endpoint is \c NULL.
  134. * \since 12
  135. */
  136. struct stasis_topic *ast_endpoint_topic(struct ast_endpoint *endpoint);
  137. /*!
  138. * \brief Returns the topic for a specific endpoint.
  139. *
  140. * \ref ast_endpoint_snapshot messages are replaced with
  141. * \ref stasis_cache_update
  142. *
  143. * \param endpoint The endpoint.
  144. * \return The topic for the given endpoint.
  145. * \return ast_endpoint_topic_all() if endpoint is \c NULL.
  146. * \since 12
  147. */
  148. struct stasis_topic *ast_endpoint_topic_cached(struct ast_endpoint *endpoint);
  149. /*!
  150. * \internal
  151. * \brief Cache and global topics for endpoints.
  152. *
  153. * This is public simply to be used by endpoints.c. Please use the accessor
  154. * functions (ast_endpoint_topic_all(), ast_endpoint_topic_all_cached(),
  155. * ast_endpoint_cache(), etc.) instead of calling this directly.
  156. *
  157. * \since 12
  158. */
  159. struct stasis_cp_all *ast_endpoint_cache_all(void);
  160. /*!
  161. * \brief Topic for all endpoint releated messages.
  162. * \since 12
  163. */
  164. struct stasis_topic *ast_endpoint_topic_all(void);
  165. /*!
  166. * \brief Cached topic for all endpoint related messages.
  167. * \since 12
  168. */
  169. struct stasis_topic *ast_endpoint_topic_all_cached(void);
  170. /*!
  171. * \brief Backend cache for ast_endpoint_topic_all_cached().
  172. * \return Cache of \ref ast_endpoint_snapshot.
  173. * \since 12
  174. */
  175. struct stasis_cache *ast_endpoint_cache(void);
  176. /*!
  177. * \brief Retrieve the most recent snapshot for the endpoint with the given
  178. * name.
  179. *
  180. * \param tech Name of the endpoint's technology.
  181. * \param resource Resource name of the endpoint.
  182. * \return Snapshot of the endpoint with the given name.
  183. * \return \c NULL if endpoint is not found, or on error.
  184. * \since 12
  185. */
  186. struct ast_endpoint_snapshot *ast_endpoint_latest_snapshot(const char *tech,
  187. const char *resource
  188. );
  189. /*! @} */
  190. /*!
  191. * \brief Build a JSON object from a \ref ast_endpoint_snapshot.
  192. *
  193. * \param snapshot Endpoint snapshot.
  194. * \param sanitize The message sanitizer to use on the snapshot
  195. *
  196. * \return JSON object representing endpoint snapshot.
  197. * \return \c NULL on error
  198. */
  199. struct ast_json *ast_endpoint_snapshot_to_json(
  200. const struct ast_endpoint_snapshot *snapshot,
  201. const struct stasis_message_sanitizer *sanitize);
  202. /*!
  203. * \brief Initialization function for endpoint stasis support.
  204. *
  205. * \return 0 on success.
  206. * \return non-zero on error.
  207. * \since 12
  208. */
  209. int ast_endpoint_stasis_init(void);
  210. #endif /* _ASTERISK_STASIS_ENDPOINTS_H */