diff options
Diffstat (limited to 'include/asterisk/format_cap.h')
| -rw-r--r-- | include/asterisk/format_cap.h | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/include/asterisk/format_cap.h b/include/asterisk/format_cap.h new file mode 100644 index 000000000..301ec1471 --- /dev/null +++ b/include/asterisk/format_cap.h @@ -0,0 +1,273 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2010, Digium, Inc. + * + * David Vossel <dvossel@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! + * \file + * \brief Format Capability API + * + * \author David Vossel <dvossel@digium.com> + */ + +#ifndef _AST_FORMATCAP_H_ +#define _AST_FORMATCAP_H_ + +/*! Capabilities are represented by an opaque structure statically defined in format_capability.c */ +struct ast_format_cap; + +/*! + * \brief Allocate a new ast_format_cap structure. + * + * \note Allocation of this object assumes locking + * is already occuring and that the point of contention + * is above this capabilities structure. For example, + * a tech_pvt object referencing a capabilities structure + * can use this function as long as it always holds the + * tech_pvt lock while accessing its capabilities. + * + * \retval ast_format_cap object on success. + * \retval NULL on failure. + */ +struct ast_format_cap *ast_format_cap_alloc_nolock(void); + +/*! + * \brief Allocate a new ast_format_cap structure with locking + * + * \note If no other form of locking is taking place, use this function. + * This function makes most sense for globally accessible capabilities structures + * that have no other means of locking. + * + * \retval ast_format_cap object on success. + * \retval NULL on failure. + */ +struct ast_format_cap *ast_format_cap_alloc(void); + +/*! + * \brief Destroy an ast_format_cap structure. + * + * \return NULL + */ +void *ast_format_cap_destroy(struct ast_format_cap *cap); + +/*! + * \brief Add format capability to capabilities structure. + * + * \note A copy of the input format is made and that copy is + * what is placed in the ast_format_cap structure. The actual + * input format ptr is not stored. + */ +void ast_format_cap_add(struct ast_format_cap *cap, struct ast_format *format); + +/*! + * \brief Add all formats Asterisk knows about for a specific type to + * the capabilities structure. Formats with attributes are set, but their + * attributes are initilized to 0's. An attribute structure of 0's should + * indicate to the format attribute interface that the format has full + * capabilities. + * + * \note A copy of the input format is made and that copy is + * what is placed in the ast_format_cap structure. The actual + * input format ptr is not stored. + */ +void ast_format_cap_add_all_by_type(struct ast_format_cap *cap, enum ast_format_type type); + +/*! + * \brief Add all known formats to the capabilities structure using default format attribute. */ +void ast_format_cap_add_all(struct ast_format_cap *cap); + +/*! + * \brief Append the formats in src to dst + */ +void ast_format_cap_append(struct ast_format_cap *dst, const struct ast_format_cap *src); + +/*! + * \brief Copy all items in src to dst. + * \note any items in dst will be removed before copying + */ +void ast_format_cap_copy(struct ast_format_cap *dst, const struct ast_format_cap *src); + +/*! + * \brief create a deep copy of an ast_format_cap structure + * + * \retval cap on success + * \retval NULL on failure + */ +struct ast_format_cap *ast_format_cap_dup(const struct ast_format_cap *src); + +/*! + * \brief determine if a capabilities structure is empty or not + * + * \retval 1, true is empty + * \retval 0, false, not empty + */ +int ast_format_cap_is_empty(const struct ast_format_cap *cap); + +/*! + * \brief Remove format capability from capability structure. + * + * \Note format must match Exactly to format in ast_format_cap object in order + * to be removed. + * + * \retval 0, remove was successful + * \retval -1, remove failed. Could not find format to remove + */ +int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format); + +/*! + * \brief Remove all format capabilities from capability + * structure for a specific format id. + * + * \Note This will remove _ALL_ formats matching the format id from the + * capabilities structure. + * + * \retval 0, remove was successful + * \retval -1, remove failed. Could not find formats to remove + */ +int ast_format_cap_remove_byid(struct ast_format_cap *cap, enum ast_format_id id); + +/*! + * \brief Remove all formats matching a specific format type. + */ +void ast_format_cap_remove_bytype(struct ast_format_cap *cap, enum ast_format_type type); + +/*! + * \brief Remove all format capabilities from capability structure + */ +void ast_format_cap_remove_all(struct ast_format_cap *cap); + +/*! + * \brief Remove all previous formats and set a single new format. + */ +void ast_format_cap_set(struct ast_format_cap *cap, struct ast_format *format); + +/*! + * \brief Find if ast_format is within the capabilities of the ast_format_cap object. + * + * retval 1 format is compatible with formats held in ast_format_cap object. + * retval 0 format is not compatible with any formats in ast_format_cap object. + */ +int ast_format_cap_iscompatible(const struct ast_format_cap *cap, const struct ast_format *format); + +/*! + * \brief is cap1 identical to cap2 + * + * retval 1 true, identical + * retval 0 false, not identical + */ +int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2); + +/*! + * \brief Get joint capability structure. + * + * \note returns an ast_format_cap object containing the joint capabilities on success. This new + * capabilities structure is allocated with _NO_ locking enabled. If a joint structure requires + * locking, allocate it and use the ast_format_cap_joint_copy function to fill it with the joint + * capabilities. + * + * \retval !NULL success, joint capabilties structure with _NO_ locking enabled. + * \retval NULL failure + */ +struct ast_format_cap *ast_format_cap_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2); + +/*! + * \brief Get joint capability structure, copy into result capabilities structure + * + * \retval 1, joint capabilities exist + * \retval 0, joint capabilities do not exist + */ +int ast_format_cap_joint_copy(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result); + +/*! + * \brief Find out if capability structures have any joint capabilities without + * returning those capabilities. + * + * \retval 1 true, has joint capabilities + * \retval 0 false, failure + */ +int ast_format_cap_has_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2); + +/*! + * \brief Get all capabilities for a specific media type + * + * \retval !NULL success, new capabilities structure with _NO_ locking enabled on the new structure. + * \retval NULL failure + */ +struct ast_format_cap *ast_format_cap_get_type(const struct ast_format_cap *cap, enum ast_format_type ftype); + +/*! + * \brief Find out if the capabilities structure has any formats + * of a specific type. + * + * \retval 1 true + * \retval 0 false, no formats of specific type. + */ +int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_format_type type); + +/*! \brief Start iterating formats */ +void ast_format_cap_iter_start(struct ast_format_cap *cap); + +/*! + * \brief Next format in interation + * + * \details + * Here is how to use the ast_format_cap iterator. + * + * 1. call ast_format_cap_iter_start + * 2. call ast_format_cap_iter_next in a loop until it returns -1 + * 3. call ast_format_cap_iter_end to terminate the iterator. + * + * example: + * + * ast_format_cap_iter_start(cap); + * while (!ast_format_cap_iter_next(cap, &format)) { + * + * } + * ast_format_cap_iter_end(Cap); + * + * \Note Unless the container was alloced using no_lock, the container + * will be locked during the entire iteration until ast_format_cap_iter_end + * is called. XXX Remember this, and do not attempt to lock any containers + * within this iteration that will violate locking order. + * + * \retval 0 on success, new format is copied into input format struct + * \retval -1, no more formats are present. + */ +int ast_format_cap_iter_next(struct ast_format_cap *cap, struct ast_format *format); + +/*! + * \brief Ends ast_format_cap iteration. + * \note this must be call after every ast_format_cap_iter_start + */ +void ast_format_cap_iter_end(struct ast_format_cap *cap); + +/*! + * \brief ast_format_cap to old bitfield format represenatation + * + * \note This is only to be used for IAX2 compatibility + * + * \retval old bitfield representation of ast_format_cap + * \retval 0, if no old bitfield capabilities are present in ast_format_cap + */ +uint64_t ast_format_cap_to_old_bitfield(const struct ast_format_cap *cap); + +/*! + * \brief convert old bitfield format to ast_format_cap represenatation + * \note This is only to be used for IAX2 compatibility + */ +void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src); + +#endif /* _AST_FORMATCAP_H */ |