diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/asterisk/event.h | 2 | ||||
| -rw-r--r-- | include/asterisk/http_websocket.h | 86 | ||||
| -rw-r--r-- | include/asterisk/rtp_engine.h | 2 | ||||
| -rw-r--r-- | include/asterisk/sem.h | 4 | ||||
| -rw-r--r-- | include/asterisk/stasis.h | 34 | ||||
| -rw-r--r-- | include/asterisk/stasis_test.h | 3 |
6 files changed, 97 insertions, 34 deletions
diff --git a/include/asterisk/event.h b/include/asterisk/event.h index 7eea0581d..dbc080da8 100644 --- a/include/asterisk/event.h +++ b/include/asterisk/event.h @@ -35,7 +35,7 @@ * modules in Asterisk. * - CEL uses the \ref ast_event representation to pass information to registered * backends. - * - The \file res_corosync module publishes \ref ast_event representations of + * - The \file res_corosync.c module publishes \ref ast_event representations of * information to other Asterisk instances in a cluster. * - Security event represent their event types and data using this system. * - Theoretically, any \ref stasis message can use this system to pass diff --git a/include/asterisk/http_websocket.h b/include/asterisk/http_websocket.h index 3e07e608b..5adc08925 100644 --- a/include/asterisk/http_websocket.h +++ b/include/asterisk/http_websocket.h @@ -68,6 +68,24 @@ struct ast_websocket_server; struct ast_websocket; /*! + * \brief Callback from the HTTP request attempting to establish a websocket connection + * + * This callback occurs when an HTTP request is made to establish a websocket connection. + * Implementers of \ref ast_websocket_protocol can use this to deny a request, or to + * set up application specific data before invocation of \ref ast_websocket_callback. + * + * \param ser The TCP/TLS session + * \param parameters Parameters extracted from the request URI + * \param headers Headers included in the request + * + * \retval 0 The session should be accepted + * \retval -1 The session should be rejected. Note that the caller must send an error + * response using \ref ast_http_error. + * \since 13.5.0 + */ +typedef int (*ast_websocket_pre_callback)(struct ast_tcptls_session_instance *ser, struct ast_variable *parameters, struct ast_variable *headers); + +/*! * \brief Callback for when a new connection for a sub-protocol is established * * \param session A WebSocket session structure @@ -81,6 +99,32 @@ struct ast_websocket; typedef void (*ast_websocket_callback)(struct ast_websocket *session, struct ast_variable *parameters, struct ast_variable *headers); /*! + * \brief A websocket protocol implementation + * + * Users of the Websocket API can register themselves as a websocket + * protocol. See \ref ast_websocket_add_protocol2 and \ref ast_websocket_server_add_protocol2. + * Simpler implementations may use only \ref ast_websocket_add_protocol and + * \ref ast_websocket_server_add_protocol. + * + * \since 13.5.0 + */ +struct ast_websocket_protocol { + /*! \brief Name of the protocol */ + char *name; +/*! + * \brief Protocol version. This prevents dynamically loadable modules from registering + * if this struct is changed. + */ +#define AST_WEBSOCKET_PROTOCOL_VERSION 1 + /*! \brief Protocol version. Should be set to /ref AST_WEBSOCKET_PROTOCOL_VERSION */ + unsigned int version; + /*! \brief Callback called when a new session is attempted. Optional. */ + ast_websocket_pre_callback session_attempted; + /* \brief Callback called when a new session is established. Mandatory. */ + ast_websocket_callback session_established; +}; + +/*! * \brief Creates a \ref websocket_server * * \retval New \ref websocket_server instance @@ -98,6 +142,15 @@ AST_OPTIONAL_API(struct ast_websocket_server *, ast_websocket_server_create, (vo AST_OPTIONAL_API(int, ast_websocket_uri_cb, (struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_vars, struct ast_variable *headers), { return -1; }); /*! + * \brief Allocate a websocket sub-protocol instance + * + * \retval An instance of \ref ast_websocket_protocol on success + * \retval NULL on error + * \since 13.5.0 + */ +AST_OPTIONAL_API(struct ast_websocket_protocol *, ast_websocket_sub_protocol_alloc, (const char *name), {return NULL;}); + +/*! * \brief Add a sub-protocol handler to the default /ws server * * \param name Name of the sub-protocol to register @@ -109,10 +162,25 @@ AST_OPTIONAL_API(int, ast_websocket_uri_cb, (struct ast_tcptls_session_instance AST_OPTIONAL_API(int, ast_websocket_add_protocol, (const char *name, ast_websocket_callback callback), {return -1;}); /*! + * \brief Add a sub-protocol handler to the default /ws server + * + * \param protocol The sub-protocol to register. Note that this must + * be allocated using /ref ast_websocket_sub_protocol_alloc. + * + * \note This method is reference stealing. It will steal the reference to \ref protocol + * on success. + * + * \retval 0 success + * \retval -1 if sub-protocol handler could not be registered + * \since 13.5.0 + */ +AST_OPTIONAL_API(int, ast_websocket_add_protocol2, (struct ast_websocket_protocol *protocol), {return -1;}); + +/*! * \brief Remove a sub-protocol handler from the default /ws server. * * \param name Name of the sub-protocol to unregister - * \param callback Callback that was previously registered with the sub-protocol + * \param callback Session Established callback that was previously registered with the sub-protocol * * \retval 0 success * \retval -1 if sub-protocol was not found or if callback did not match @@ -132,6 +200,22 @@ AST_OPTIONAL_API(int, ast_websocket_remove_protocol, (const char *name, ast_webs AST_OPTIONAL_API(int, ast_websocket_server_add_protocol, (struct ast_websocket_server *server, const char *name, ast_websocket_callback callback), {return -1;}); /*! + * \brief Add a sub-protocol handler to the given server. + * + * \param server The server to add the sub-protocol to. + * \param protocol The sub-protocol to register. Note that this must + * be allocated using /ref ast_websocket_sub_protocol_alloc. + * + * \note This method is reference stealing. It will steal the reference to \ref protocol + * on success. + * + * \retval 0 success + * \retval -1 if sub-protocol handler could not be registered + * \since 13.5.0 + */ +AST_OPTIONAL_API(int, ast_websocket_server_add_protocol2, (struct ast_websocket_server *server, struct ast_websocket_protocol *protocol), {return -1;}); + +/*! * \brief Remove a sub-protocol handler from the given server. * * \param name Name of the sub-protocol to unregister diff --git a/include/asterisk/rtp_engine.h b/include/asterisk/rtp_engine.h index a94cb4213..c7f6511f9 100644 --- a/include/asterisk/rtp_engine.h +++ b/include/asterisk/rtp_engine.h @@ -2316,7 +2316,7 @@ struct stasis_message_type *ast_rtp_rtcp_received_type(void); */ struct stasis_topic *ast_rtp_topic(void); -/* }@ */ +/* @} */ #if defined(__cplusplus) || defined(c_plusplus) } diff --git a/include/asterisk/sem.h b/include/asterisk/sem.h index 6d655d63e..fcab82a5e 100644 --- a/include/asterisk/sem.h +++ b/include/asterisk/sem.h @@ -20,7 +20,9 @@ #define ASTERISK_SEMAPHORE_H /*! - * \file Asterisk semaphore API + * \file + * + * \brief Asterisk semaphore API * * This API is a thin wrapper around the POSIX semaphore API (when available), * so see the POSIX documentation for further details. diff --git a/include/asterisk/stasis.h b/include/asterisk/stasis.h index 0b1b1e83f..aa681e13e 100644 --- a/include/asterisk/stasis.h +++ b/include/asterisk/stasis.h @@ -173,8 +173,6 @@ #include "asterisk/utils.h" #include "asterisk/event.h" -/*! @{ */ - /*! * \brief Metadata about a \ref stasis_message. * \since 12 @@ -451,10 +449,6 @@ struct ast_manager_event_blob *stasis_message_to_ami( struct ast_event *stasis_message_to_event( struct stasis_message *message); -/*! @} */ - -/*! @{ */ - /*! * \brief A topic to which messages may be posted, and subscribers, well, subscribe * \since 12 @@ -508,10 +502,6 @@ void stasis_publish(struct stasis_topic *topic, struct stasis_message *message); */ void stasis_publish_sync(struct stasis_subscription *sub, struct stasis_message *message); -/*! @} */ - -/*! @{ */ - /*! * \brief Callback function type for Stasis subscriptions. * \param data Data field provided with subscription. @@ -699,8 +689,6 @@ struct stasis_message_type *stasis_subscription_change_type(void); /*! @} */ -/*! @{ */ - /*! * \brief Pool for topic aggregation */ @@ -723,8 +711,6 @@ struct stasis_topic_pool *stasis_topic_pool_create(struct stasis_topic *pooled_t */ struct stasis_topic *stasis_topic_pool_get_topic(struct stasis_topic_pool *pool, const char *topic_name); -/*! @} */ - /*! \addtogroup StasisTopicsAndMessages * @{ */ @@ -757,8 +743,6 @@ struct stasis_message_type *stasis_cache_clear_type(void); /*! @} */ -/*! @{ */ - /*! * \brief A message cache, for use with \ref stasis_caching_topic. * \since 12 @@ -1090,6 +1074,10 @@ struct ao2_container *stasis_cache_dump_by_eid(struct stasis_cache *cache, struc */ struct ao2_container *stasis_cache_dump_all(struct stasis_cache *cache, struct stasis_message_type *type); +/*! \addtogroup StasisTopicsAndMessages + * @{ + */ + /*! * \brief Object type code for multi user object snapshots */ @@ -1163,8 +1151,6 @@ void ast_multi_object_blob_single_channel_publish(struct ast_channel *chan, stru /*! @} */ -/*! @{ */ - /*! * \internal * \brief Log a message about invalid attempt to access a type. @@ -1267,10 +1253,6 @@ void stasis_log_bad_type_access(const char *name); _priv_ ## name = NULL; \ }) -/*! @} */ - -/*! @{ */ - /*! * \brief Initialize the Stasis subsystem. * \return 0 on success. @@ -1279,10 +1261,6 @@ void stasis_log_bad_type_access(const char *name); */ int stasis_init(void); -/*! @} */ - -/*! @{ */ - /*! * \internal * \brief called by stasis_init() for cache initialization. @@ -1301,12 +1279,10 @@ int stasis_cache_init(void); */ int stasis_config_init(void); -/*! @} */ - /*! * \defgroup StasisTopicsAndMessages Stasis topics, and their messages. * - * This group contains the topics, messages and corresponding message types + * \brief This group contains the topics, messages and corresponding message types * found within Asterisk. */ diff --git a/include/asterisk/stasis_test.h b/include/asterisk/stasis_test.h index ad4020a08..d9df1c97f 100644 --- a/include/asterisk/stasis_test.h +++ b/include/asterisk/stasis_test.h @@ -20,7 +20,8 @@ #define _ASTERISK_STASIS_TEST_H /*! - * \file \brief Test infrastructure for dealing with Stasis. + * \file + * \brief Test infrastructure for dealing with Stasis. * * \author David M. Lee, II <dlee@digium.com> * |