format_cap.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2014, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \brief Format Capabilities API
00022  *
00023  * \author Joshua Colp <jcolp@digium.com>
00024  */
00025 
00026 #ifndef _AST_FORMAT_CAP_H_
00027 #define _AST_FORMAT_CAP_H_
00028 
00029 #include "asterisk/codec.h"
00030 
00031 /*! Capabilities are represented by an opaque structure statically defined in format_cap.c */
00032 struct ast_format_cap;
00033 
00034 enum ast_format_cap_flags {
00035    /*!
00036     * Default format capabilities settings
00037     */
00038    AST_FORMAT_CAP_FLAG_DEFAULT = 0,
00039 };
00040 
00041 /*!
00042  * \brief Allocate a new ast_format_cap structure
00043  *
00044  * \param flags Modifiers of struct behavior.
00045  *
00046  * \retval ast_format_cap object on success.
00047  * \retval NULL on failure.
00048  */
00049 struct ast_format_cap *__ast_format_cap_alloc(enum ast_format_cap_flags flags);
00050 struct ast_format_cap *__ast_format_cap_alloc_debug(enum ast_format_cap_flags flags, const char *tag, const char *file, int line, const char *func);
00051 
00052 #ifdef REF_DEBUG
00053 #define ast_format_cap_alloc(flags) \
00054    __ast_format_cap_alloc_debug((flags), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
00055 #define ast_t_format_cap_alloc(flags, tag) \
00056    __ast_format_cap_alloc_debug((flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00057 #else
00058 #define ast_format_cap_alloc(flags) \
00059    __ast_format_cap_alloc((flags))
00060 #define ast_t_format_cap_alloc(flags, tag) \
00061    __ast_format_cap_alloc((flags))
00062 #endif
00063 
00064 /*!
00065  * \brief Set the global framing.
00066  *
00067  * \param cap The capabilities structure.
00068  * \param framing The framing value (in milliseconds).
00069  *
00070  * \note This is used if a format does not provide a framing itself. Note that
00071  *       adding subsequent formats to the \c ast_format_cap structure may
00072  *       override this value, if the framing they require is less than the
00073  *       value set by this function.
00074  */
00075 void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing);
00076 
00077 /*!
00078  * \brief Get the global framing.
00079  *
00080  * \param cap The capabilities structure.
00081  *
00082  * \retval 0 if no formats are in the structure and no framing has been provided
00083  * \retval The global framing value (in milliseconds)
00084  *
00085  * \note This will be the minimum framing allowed across all formats in the
00086  *       capabilities structure, or an overridden value
00087  */
00088 unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap);
00089 
00090 /*!
00091  * \brief Add format capability to capabilities structure.
00092  *
00093  * \param cap The capabilities structure to add to.
00094  * \param format The format to add.
00095  * \param framing The framing for the format (in milliseconds).
00096  *
00097  * \retval 0 success
00098  * \retval -1 failure
00099  *
00100  * \note A reference to the format is taken and used in the capabilities structure.
00101  *
00102  * \note The order in which add is called determines the format preference order.
00103  *
00104  * \note If framing is specified here it overrides any global framing that has been set.
00105  */
00106 int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing);
00107 int __ast_format_cap_append_debug(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing, const char *tag, const char *file, int line, const char *func);
00108 
00109 #ifdef REF_DEBUG
00110 #define ast_format_cap_append(cap, format, framing) \
00111    __ast_format_cap_append_debug((cap), (format), (framing), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
00112 #define ast_t_format_cap_append(cap, format, framing, tag) \
00113    __ast_format_cap_append_debug((cap), (format), (framing), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
00114 #else
00115 #define ast_format_cap_append(cap, format, framing) \
00116    __ast_format_cap_append((cap), (format), (framing))
00117 #define ast_t_format_cap_append(cap, format, framing, tag) \
00118    __ast_format_cap_append((cap), (format), (framing))
00119 #endif
00120 
00121 /*!
00122  * \brief Add all codecs Asterisk knows about for a specific type to
00123  * the capabilities structure.
00124  *
00125  * \param cap The capabilities structure to add to.
00126  * \param type The type of formats to add.
00127  *
00128  * \retval 0 success
00129  * \retval -1 failure
00130  *
00131  * \note A generic format with no attributes is created using the codec.
00132  *
00133  * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
00134  */
00135 int ast_format_cap_append_by_type(struct ast_format_cap *cap, enum ast_media_type type);
00136 
00137 /*!
00138  * \brief Append the formats of provided type in src to dst
00139  *
00140  * \param dst The destination capabilities structure
00141  * \param src The source capabilities structure
00142  * \param type The type of formats to append.
00143  *
00144  * \retval 0 success
00145  * \retval -1 failure
00146  *
00147  * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
00148  */
00149 int ast_format_cap_append_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
00150 
00151 /*!
00152  * \brief Replace the formats of provided type in dst with equivalent formats from src
00153  *
00154  * \param dst The destination capabilities structure
00155  * \param src The source capabilities structure
00156  * \param type The type of formats to replace.
00157  *
00158  * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be replaced.
00159  * \note Formats present in src but not dst will not be appended to dst.
00160  */
00161 void ast_format_cap_replace_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
00162 
00163 /*!
00164  * \brief Parse an "allow" or "deny" list and modify a format capabilities structure accordingly
00165  *
00166  * \param cap The capabilities structure to modify
00167  * \param list The list containing formats to append or remove
00168  * \param allowing If zero, start removing formats specified in the list. If non-zero,
00169  *        start appending formats specified in the list.
00170  *
00171  * \retval 0 on success
00172  * \retval -1 on failure
00173  */
00174 int ast_format_cap_update_by_allow_disallow(struct ast_format_cap *cap, const char *list, int allowing);
00175 
00176 /*!
00177  * \brief Get the number of formats present within the capabilities structure
00178  *
00179  * \param cap The capabilities structure
00180  *
00181  * \return the number of formats
00182  */
00183 size_t ast_format_cap_count(const struct ast_format_cap *cap);
00184 
00185 /*!
00186  * \brief Get the format at a specific index
00187  *
00188  * \param cap The capabilities structure
00189  * \param position The position to get
00190  *
00191  * \retval non-NULL success
00192  * \retval NULL failure
00193  *
00194  * \note This is a zero based index.
00195  *
00196  * \note Formats are returned in order of preference.
00197  *
00198  * \note The reference count of the returned format is increased. It must be released using ao2_ref
00199  * or ao2_cleanup.
00200  */
00201 struct ast_format *ast_format_cap_get_format(const struct ast_format_cap *cap, int position);
00202 
00203 /*!
00204  * \brief Get the most preferred format for a particular media type
00205  *
00206  * \param cap The capabilities structure
00207  * \param type The type of media to get
00208  *
00209  * \retval non-NULL the preferred format
00210  * \retval NULL no media of \c type present
00211  *
00212  * \note The reference count of the returned format is increased. It must be released using ao2_ref
00213  * or ao2_cleanup.
00214  */
00215 struct ast_format *ast_format_cap_get_best_by_type(const struct ast_format_cap *cap, enum ast_media_type type);
00216 
00217 /*!
00218  * \brief Get the framing for a format
00219  *
00220  * \param cap The capabilities structure
00221  * \param format The format to retrieve
00222  *
00223  * \return the framing (in milliseconds)
00224  */
00225 unsigned int ast_format_cap_get_format_framing(const struct ast_format_cap *cap, const struct ast_format *format);
00226 
00227 /*!
00228  * \brief Remove format capability from capability structure.
00229  *
00230  * \note format must be an exact pointer match to remove from capabilities structure.
00231  *
00232  * \retval 0, remove was successful
00233  * \retval -1, remove failed. Could not find format to remove
00234  */
00235 int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
00236 
00237 /*!
00238  * \brief Remove all formats matching a specific format type.
00239  *
00240  * \param cap The capabilities structure
00241  * \param type The media type to remove formats of
00242  *
00243  * \note All formats can be removed by using the AST_MEDIA_TYPE_UNKNOWN type.
00244  */
00245 void ast_format_cap_remove_by_type(struct ast_format_cap *cap, enum ast_media_type type);
00246 
00247 /*!
00248  * \brief Find if input ast_format is within the capabilities of the ast_format_cap object
00249  * then return the compatible format from the capabilities structure in the result.
00250  *
00251  * \retval non-NULL if format is compatible
00252  * \retval NULL if not compatible
00253  *
00254  * \note The reference count of the returned format is increased. It must be released using ao2_ref
00255  * or ao2_cleanup.
00256  */
00257 struct ast_format *ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
00258 
00259 /*!
00260  * \brief Find if ast_format is within the capabilities of the ast_format_cap object.
00261  *
00262 * \retval ast_format_cmp_res representing the result of the compatibility check between cap and format.
00263  */
00264 enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
00265 
00266 /*!
00267  * \brief Find the compatible formats between two capabilities structures
00268  *
00269  * \param cap1 The first capabilities structure
00270  * \param cap2 The second capabilities structure
00271  * \param[out] result The capabilities structure to place the results into
00272  *
00273  * \retval 0 success
00274  * \retval -1 failure
00275  *
00276  * \note The preference order of cap1 is respected.
00277  *
00278  * \note If failure occurs the result format capabilities structure may contain a partial result.
00279  */
00280 int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2,
00281    struct ast_format_cap *result);
00282 
00283 /*!
00284  * \brief Determine if any joint capabilities exist between two capabilities structures
00285  *
00286  * \param cap1 The first capabilities structure
00287  * \param cap2 The second capabilities structure
00288  *
00289  * \retval 0 no joint capabilities exist
00290  * \retval 1 joint capabilities exist
00291  */
00292 int ast_format_cap_iscompatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
00293 
00294 /*!
00295  * \brief Determine if two capabilities structures are identical
00296  *
00297  * \param cap1 The first capabilities structure
00298  * \param cap2 The second capabilities structure
00299  *
00300  * \retval 0 capabilities are not identical
00301  * \retval 1 capabilities are identical
00302  */
00303 int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
00304 
00305 /*!
00306  * \brief Find out if the capabilities structure has any formats
00307  * of a specific type.
00308  *
00309  * \retval 1 true
00310  * \retval 0 false, no formats of specific type.
00311  */
00312 int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_media_type type);
00313 
00314 /*!
00315  * \brief Get the names of codecs of a set of formats
00316  *
00317  * \param cap The capabilities structure containing the formats
00318  * \param buf A \c ast_str buffer to populate with the names of the formats
00319  *
00320  * \return The contents of the buffer in \c buf
00321  */
00322 const char *ast_format_cap_get_names(struct ast_format_cap *cap, struct ast_str **buf);
00323 
00324 /*!
00325  * \brief Determine if a format cap has no formats in it.
00326  *
00327  * \param cap The format cap to check for emptiness
00328  * \retval 1 The format cap has zero formats or only ast_format_none
00329  * \retval 0 The format cap has at least one format
00330  */
00331 int ast_format_cap_empty(struct ast_format_cap *cap);
00332 
00333 #endif /* _AST_FORMAT_CAP_H */

Generated on Thu Apr 16 06:27:34 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6