include/asterisk/format_cap.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2010, Digium, Inc.
   5  *
   6  * David Vossel <dvossel@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
  19 /*!
  20  * \file
  21  * \brief Format Capability API
  22  *
  23  * \author David Vossel <dvossel@digium.com>
  24  */
  25
  26 #ifndef _AST_FORMATCAP_H_
  27 #define _AST_FORMATCAP_H_
  28
  29 /*! Capabilities are represented by an opaque structure statically defined in format_capability.c */
  30 struct ast_format_cap;
  31
  32 /*!
  33  * \brief Allocate a new ast_format_cap structure.
  34  *
  35  * \note Allocation of this object assumes locking
  36  * is already occuring and that the point of contention
  37  * is above this capabilities structure.  For example,
  38  * a tech_pvt object referencing a capabilities structure
  39  * can use this function as long as it always holds the
  40  * tech_pvt lock while accessing its capabilities.
  41  *
  42  * \retval ast_format_cap object on success.
  43  * \retval NULL on failure.
  44  */
  45 struct ast_format_cap *ast_format_cap_alloc_nolock(void);
  46
  47 /*!
  48  * \brief Allocate a new ast_format_cap structure with locking
  49  *
  50  * \note If no other form of locking is taking place, use this function.
  51  * This function makes most sense for globally accessible capabilities structures
  52  * that have no other means of locking.
  53  *
  54  * \retval ast_format_cap object on success.
  55  * \retval NULL on failure.
  56  */
  57 struct ast_format_cap *ast_format_cap_alloc(void);
  58
  59 /*!
  60  * \brief Destroy an ast_format_cap structure.
  61  *
  62  * \return NULL
  63  */
  64 void *ast_format_cap_destroy(struct ast_format_cap *cap);
  65
  66 /*!
  67  * \brief Add format capability to capabilities structure.
  68  *
  69  * \note A copy of the input format is made and that copy is
  70  * what is placed in the ast_format_cap structure.  The actual
  71  * input format ptr is not stored.
  72  */
  73 void ast_format_cap_add(struct ast_format_cap *cap, const struct ast_format *format);
  74
  75 /*!
  76  * \brief Add all formats Asterisk knows about for a specific type to
  77  * the capabilities structure.  Formats with attributes are set, but their
  78  * attributes are initilized to 0's.  An attribute structure of 0's should
  79  * indicate to the format attribute interface that the format has full
  80  * capabilities.
  81  *
  82  * \note A copy of the input format is made and that copy is
  83  * what is placed in the ast_format_cap structure.  The actual
  84  * input format ptr is not stored.
  85  */
  86 void ast_format_cap_add_all_by_type(struct ast_format_cap *cap, enum ast_format_type type);
  87
  88 /*!
  89  * \brief Add all known formats to the capabilities structure using default format attribute.
  90  */
  91 void ast_format_cap_add_all(struct ast_format_cap *cap);
  92
  93 /*!
  94  * \brief Append the formats in src to dst
  95  */
  96 void ast_format_cap_append(struct ast_format_cap *dst, const struct ast_format_cap *src);
  97
  98 /*!
  99  * \brief Copy all items in src to dst.
 100  * \note any items in dst will be removed before copying
 101  */
 102 void ast_format_cap_copy(struct ast_format_cap *dst, const struct ast_format_cap *src);
 103
 104 /*!
 105  * \brief create a deep copy of an ast_format_cap structure
 106  *
 107  * \retval cap on success
 108  * \retval NULL on failure
 109  */
 110 struct ast_format_cap *ast_format_cap_dup(const struct ast_format_cap *src);
 111
 112 /*!
 113  * \brief determine if a capabilities structure is empty or not
 114  *
 115  * \retval 1, true is empty
 116  * \retval 0, false, not empty
 117  */
 118 int ast_format_cap_is_empty(const struct ast_format_cap *cap);
 119
 120 /*!
 121  * \brief Remove format capability from capability structure.
 122  *
 123  * \note format must match Exactly to format in ast_format_cap object in order
 124  * to be removed.
 125  *
 126  * \retval 0, remove was successful
 127  * \retval -1, remove failed. Could not find format to remove
 128  */
 129 int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
 130
 131 /*!
 132  * \brief Remove all format capabilities from capability
 133  * structure for a specific format id.
 134  *
 135  * \note This will remove _ALL_ formats matching the format id from the
 136  * capabilities structure.
 137  *
 138  * \retval 0, remove was successful
 139  * \retval -1, remove failed. Could not find formats to remove
 140  */
 141 int ast_format_cap_remove_byid(struct ast_format_cap *cap, enum ast_format_id id);
 142
 143 /*!
 144  * \brief Remove all formats matching a specific format type.
 145  */
 146 void ast_format_cap_remove_bytype(struct ast_format_cap *cap, enum ast_format_type type);
 147
 148 /*!
 149  * \brief Remove all format capabilities from capability structure
 150  */
 151 void ast_format_cap_remove_all(struct ast_format_cap *cap);
 152
 153 /*!
 154  * \brief Remove all previous formats and set a single new format.
 155  */
 156 void ast_format_cap_set(struct ast_format_cap *cap, struct ast_format *format);
 157
 158 /*!
 159  * \brief Find if input ast_format is within the capabilities of the ast_format_cap object
 160  * then return the compatible format from the capabilities structure in the result.
 161  *
 162  * \retval 1 format is compatible with formats held in ast_format_cap object.
 163  * \retval 0 format is not compatible with any formats in ast_format_cap object.
 164  */
 165 int ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format, struct ast_format *result);
 166
 167 /*!
 168  * \brief Find if ast_format is within the capabilities of the ast_format_cap object.
 169  *
 170  * \retval 1 format is compatible with formats held in ast_format_cap object.
 171  * \retval 0 format is not compatible with any formats in ast_format_cap object.
 172  */
 173 int ast_format_cap_iscompatible(const struct ast_format_cap *cap, const struct ast_format *format);
 174
 175 /*!
 176  * \brief Finds the best quality audio format for a given format id and returns it in result.
 177  *
 178  * \retval 1 format found and set to result structure.
 179  * \retval 0 no format found, result structure is cleared.
 180  */
 181 int ast_format_cap_best_byid(const struct ast_format_cap *cap, enum ast_format_id, struct ast_format *result);
 182
 183 /*!
 184  * \brief is cap1 identical to cap2
 185  *
 186  * retval 1 true, identical
 187  * retval 0 false, not identical
 188  */
 189 int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
 190
 191 /*!
 192  * \brief Get joint capability structure.
 193  *
 194  * \note returns an ast_format_cap object containing the joint capabilities on success.  This new
 195  * capabilities structure is allocated with _NO_ locking enabled.  If a joint structure requires
 196  * locking, allocate it and use the ast_format_cap_joint_copy function to fill it with the joint
 197  * capabilities.
 198  *
 199  * \retval !NULL success, joint capabilties structure with _NO_ locking enabled.
 200  * \retval NULL failure
 201  */
 202 struct ast_format_cap *ast_format_cap_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
 203
 204 /*!
 205  * \brief Get joint capability structure, copy into result capabilities structure
 206  *
 207  * \retval 1, joint capabilities exist
 208  * \retval 0, joint capabilities do not exist
 209  */
 210 int ast_format_cap_joint_copy(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
 211
 212 /*!
 213  * \brief Get joint capability structure, append into result capabilities structure
 214  *
 215  * \retval 1, joint capabilities exist
 216  * \retval 0, joint capabilities do not exist
 217  */
 218 int ast_format_cap_joint_append(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
 219
 220 /*!
 221  * \brief Find out if capability structures have any joint capabilities without
 222  * returning those capabilities.
 223  *
 224  * \retval 1 true, has joint capabilities
 225  * \retval 0 false, failure
 226  */
 227 int ast_format_cap_has_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
 228
 229 /*!
 230  * \brief Get all capabilities for a specific media type
 231  *
 232  * \retval !NULL success, new capabilities structure with _NO_ locking enabled on the new structure.
 233  * \retval NULL failure
 234  */
 235 struct ast_format_cap *ast_format_cap_get_type(const struct ast_format_cap *cap, enum ast_format_type ftype);
 236
 237 /*!
 238  * \brief Find out if the capabilities structure has any formats
 239  * of a specific type.
 240  *
 241  * \retval 1 true
 242  * \retval 0 false, no formats of specific type.
 243  */
 244 int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_format_type type);
 245
 246 /*! \brief Start iterating formats */
 247 void ast_format_cap_iter_start(struct ast_format_cap *cap);
 248
 249 /*!
 250  * \brief Next format in interation
 251  *
 252  * \details
 253  * Here is how to use the ast_format_cap iterator.
 254  *
 255  * 1. call ast_format_cap_iter_start
 256  * 2. call ast_format_cap_iter_next in a loop until it returns -1
 257  * 3. call ast_format_cap_iter_end to terminate the iterator.
 258  *
 259  * example:
 260  *
 261  * ast_format_cap_iter_start(cap);
 262  * while (!ast_format_cap_iter_next(cap, &format)) {
 263  * }
 264  * ast_format_cap_iter_end(Cap);
 265  *
 266  * \note Unless the container was alloced using no_lock, the container
 267  * will be locked during the entire iteration until ast_format_cap_iter_end
 268  * is called. XXX Remember this, and do not attempt to lock any containers
 269  * within this iteration that will violate locking order.
 270  *
 271  * \retval 0 on success, new format is copied into input format struct
 272  * \retval -1, no more formats are present.
 273  */
 274 int ast_format_cap_iter_next(struct ast_format_cap *cap, struct ast_format *format);
 275
 276 /*!
 277  * \brief Ends ast_format_cap iteration.
 278  * \note this must be call after every ast_format_cap_iter_start
 279  */
 280 void ast_format_cap_iter_end(struct ast_format_cap *cap);
 281
 282 /*!
 283  * \brief ast_format_cap to old bitfield format represenatation
 284  *
 285  * \note This is only to be used for IAX2 compatibility
 286  *
 287  * \retval old bitfield representation of ast_format_cap
 288  * \retval 0, if no old bitfield capabilities are present in ast_format_cap
 289  */
 290 uint64_t ast_format_cap_to_old_bitfield(const struct ast_format_cap *cap);
 291
 292 /*!
 293  * \brief convert old bitfield format to ast_format_cap represenatation
 294  * \note This is only to be used for IAX2 compatibility
 295  */
 296 void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src);
 297
 298 /*! \brief Get the names of a set of formats
 299  * \param buf a buffer for the output string
 300  * \param size size of buf (bytes)
 301  * \param cap format the format (combined IDs of codecs)
 302  * Prints a list of readable codec names corresponding to "format".
 303  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
 304  * \return The return value is buf.
 305  */
 306 char *ast_getformatname_multiple(char *buf, size_t size, struct ast_format_cap *cap);
 307
 308 #endif /* _AST_FORMATCAP_H */