diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/asterisk/astmm.h | 87 | ||||
| -rw-r--r-- | include/asterisk/audiohook.h | 1 | ||||
| -rw-r--r-- | include/asterisk/config.h | 17 | ||||
| -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/sorcery.h | 119 | ||||
| -rw-r--r-- | include/asterisk/stasis.h | 34 | ||||
| -rw-r--r-- | include/asterisk/stasis_test.h | 3 | ||||
| -rw-r--r-- | include/asterisk/tcptls.h | 1 |
11 files changed, 309 insertions, 47 deletions
diff --git a/include/asterisk/astmm.h b/include/asterisk/astmm.h index 1d778d4c5..6c9a8aeee 100644 --- a/include/asterisk/astmm.h +++ b/include/asterisk/astmm.h @@ -44,16 +44,6 @@ extern "C" { #include <stdio.h> #include <stdarg.h> -/* Undefine any macros */ -#undef malloc -#undef calloc -#undef realloc -#undef strdup -#undef strndup -#undef asprintf -#undef vasprintf -#undef free - void *ast_std_malloc(size_t size); void *ast_std_calloc(size_t nmemb, size_t size); void *ast_std_realloc(void *ptr, size_t size); @@ -74,9 +64,72 @@ int __ast_vasprintf(char **strp, const char *format, va_list ap, const char *fil void __ast_mm_init_phase_1(void); void __ast_mm_init_phase_2(void); -/* Redefine libc malloc to our own versions */ +/*! + * \brief ASTMM_LIBC can be defined to control the meaning of standard allocators. + * + * \note The standard allocators effected by this compiler define are: + * malloc, calloc, realloc, strdup, strndup, asprintf, vasprintf and free. + * + * @{ + */ + +/*! + * \brief Produce compiler errors if standard allocators are used. + * + * \note This is the default option, and in most cases the correct option. + * Any use of standard allocators will cause an error, even if those uses + * are in unused static inline header functions. + */ +#define ASTMM_BLOCK 0 + +/*! + * \brief Redirect standard allocators to use Asterisk functions. + * + * \note This option is used in some cases instead of changing the + * existing source to use Asterisk functions. New code should + * generally avoid this option, except where it's needed to work + * with situations where switching the code is unreasonable, such + * as output from code generators that are hard coded to use + * standard functions. + */ +#define ASTMM_REDIRECT 1 + +/*! + * \brief Standard allocators are used directly. + * + * \note This option is needed when including 3rd party headers with calls + * to standard allocators from inline functions. Using ASTMM_REDIRECT in + * this situation could result in an object being allocated by malloc and + * freed by ast_free, or the reverse. + */ +#define ASTMM_IGNORE 2 + +/*! + * }@ + */ + +#if !defined(ASTMM_LIBC) +/* BLOCK libc allocators by default. */ +#define ASTMM_LIBC ASTMM_BLOCK +#endif -#ifdef WRAP_LIBC_MALLOC +#if ASTMM_LIBC == ASTMM_IGNORE +/* Don't touch the libc functions. */ +#else + +/* Undefine any macros */ +#undef malloc +#undef calloc +#undef realloc +#undef strdup +#undef strndup +#undef asprintf +#undef vasprintf +#undef free + +#if ASTMM_LIBC == ASTMM_REDIRECT + +/* Redefine libc functions to our own versions */ #define calloc(a,b) \ __ast_calloc(a,b,__FILE__, __LINE__, __PRETTY_FUNCTION__) #define malloc(a) \ @@ -93,7 +146,10 @@ void __ast_mm_init_phase_2(void); __ast_asprintf(__FILE__, __LINE__, __PRETTY_FUNCTION__, a, b, c) #define vasprintf(a,b,c) \ __ast_vasprintf(a,b,c,__FILE__, __LINE__, __PRETTY_FUNCTION__) -#else + +#elif ASTMM_LIBC == ASTMM_BLOCK + +/* Redefine libc functions to cause compile errors */ #define calloc(a,b) \ Do_not_use_calloc__use_ast_calloc->fail(a,b) #define malloc(a) \ @@ -110,6 +166,11 @@ void __ast_mm_init_phase_2(void); Do_not_use_asprintf__use_ast_asprintf->fail(a,b,c) #define vasprintf(a,b,c) \ Do_not_use_vasprintf__use_ast_vasprintf->fail(a,b,c) + +#else +#error "Unacceptable value for the macro ASTMM_LIBC" +#endif + #endif /* Provide our own definitions */ diff --git a/include/asterisk/audiohook.h b/include/asterisk/audiohook.h index 375b2dd9d..cae8cc071 100644 --- a/include/asterisk/audiohook.h +++ b/include/asterisk/audiohook.h @@ -63,6 +63,7 @@ enum ast_audiohook_flags { AST_AUDIOHOOK_SMALL_QUEUE = (1 << 4), AST_AUDIOHOOK_MUTE_READ = (1 << 5), /*!< audiohook should be mute frames read */ AST_AUDIOHOOK_MUTE_WRITE = (1 << 6), /*!< audiohook should be mute frames written */ + AST_AUDIOHOOK_COMPATIBLE = (1 << 7), /*!< is the audiohook native slin compatible */ }; enum ast_audiohook_init_flags { diff --git a/include/asterisk/config.h b/include/asterisk/config.h index 6489344ad..bd268a333 100644 --- a/include/asterisk/config.h +++ b/include/asterisk/config.h @@ -335,6 +335,23 @@ const char *ast_variable_find(const struct ast_category *category, const char *v const char *ast_variable_find_in_list(const struct ast_variable *list, const char *variable); /*! + * \brief Gets the LAST occurrence of a variable from a variable list + * + * \param list The ast_variable list to search + * \param variable The name of the ast_variable you wish to fetch data for + * + * \details + * Iterates over a given ast_variable list to search for the last occurrence of an + * ast_variable entry with a name attribute matching the given name (variable). + * This is useful if the list has duplicate entries (such as in cases where entries + * are created by a template) + * + * \retval The variable value on success + * \retval NULL if unable to find it. + */ +const char *ast_variable_find_last_in_list(const struct ast_variable *list, const char *variable); + +/*! * \brief Retrieve a category if it exists * * \param config which config to use 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/sorcery.h b/include/asterisk/sorcery.h index a5061c6ab..9d39ce492 100644 --- a/include/asterisk/sorcery.h +++ b/include/asterisk/sorcery.h @@ -497,6 +497,125 @@ enum ast_sorcery_apply_result __ast_sorcery_apply_wizard_mapping(struct ast_sorc #define ast_sorcery_apply_wizard_mapping(sorcery, type, name, data, caching) \ __ast_sorcery_apply_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), (caching)); + +/*! + * \brief Pre-defined locations to insert at + */ +enum ast_sorcery_wizard_position { + AST_SORCERY_WIZARD_POSITION_LAST = -1, + AST_SORCERY_WIZARD_POSITION_FIRST = 0, +}; + +/*! + * \brief Insert an additional object wizard mapping at a specific position + * in the wizard list + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object to apply to + * \param module The name of the module, typically AST_MODULE + * \param name Name of the wizard to use + * \param data Data to be passed to wizard + * \param caching Wizard should cache + * \param position An index to insert to or one of ast_sorcery_wizard_position + * + * \return What occurred when applying the mapping + * + * \note This should be called *after* applying default mappings + * \note Wizards can be retrieved by using ast_sorcery_get_wizard_mapping_count + * and iterating over them using ast_sorcery_get_wizard_mapping. + * + * \since 13.4.0 + */ +enum ast_sorcery_apply_result __ast_sorcery_insert_wizard_mapping(struct ast_sorcery *sorcery, + const char *type, const char *module, const char *name, const char *data, + unsigned int caching, int position); + +/*! + * \brief Insert an additional object wizard mapping at a specific position + * in the wizard list + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object to apply to + * \param module The name of the module, typically AST_MODULE + * \param name Name of the wizard to use + * \param data Data to be passed to wizard + * \param position One of ast_sorcery_wizard_position + * + * \return What occurred when applying the mapping + * + * \note This should be called *after* applying default mappings + * \since 13.4.0 + */ +#define ast_sorcery_insert_wizard_mapping(sorcery, type, name, data, caching, position) \ + __ast_sorcery_insert_wizard_mapping((sorcery), (type), AST_MODULE, (name), (data), \ + (caching), (position)) + +/*! + * \brief Remove an object wizard mapping + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object to remove from + * \param module The name of the module, typically AST_MODULE + * \param name The name of the wizard to remove + * + * \retval 0 success + * \retval -1 failure + * + * \since 13.4.0 + */ +int __ast_sorcery_remove_wizard_mapping(struct ast_sorcery *sorcery, + const char *type, const char *module, const char *name); + +/*! + * \brief Remove an object wizard mapping + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object to remove from + * \param name The name of the wizard to remove + * + * \retval 0 success + * \retval -1 failure + * + * \since 13.4.0 + */ +#define ast_sorcery_remove_wizard_mapping(sorcery, type, name) \ + __ast_sorcery_remove_wizard_mapping((sorcery), (type), AST_MODULE, (name)) + +/*! + * \brief Return the number of wizards mapped to an object type + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object + * + * \return Number of wizards or -1 for error + * \since 13.4.0 + */ +int ast_sorcery_get_wizard_mapping_count(struct ast_sorcery *sorcery, + const char *type); + +/*! + * \brief By index, return a wizard mapped to an object type + * + * \param sorcery Pointer to a sorcery structure + * \param type Type of object + * \param index Index of the wizard + * \param wizard A pointer to receive the wizard pointer + * \param data A pointer to receive the data pointer + * + * \retval 0 success + * \retval -1 failure + * + * \warning The wizard will have its reference count bumped so you must + * call ao2_cleanup when you're done with it. + * + * \note The wizard and data returned are valid only for this object type + * and only while the wizard is applied to the object type. + * + * \since 13.4.0 + */ +int ast_sorcery_get_wizard_mapping(struct ast_sorcery *sorcery, + const char *type, int index, struct ast_sorcery_wizard **wizard, void **data); + /*! * \brief Register an object type * 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> * diff --git a/include/asterisk/tcptls.h b/include/asterisk/tcptls.h index 0e8d9d042..a3f3f2884 100644 --- a/include/asterisk/tcptls.h +++ b/include/asterisk/tcptls.h @@ -65,6 +65,7 @@ #ifdef DO_SSL #include <openssl/ssl.h> #include <openssl/err.h> +#include <openssl/x509v3.h> #else /* declare dummy types so we can define a pointer to them */ typedef struct {} SSL; |