format.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 Media Format API
00022  *
00023  * \author Joshua Colp <jcolp@digium.com>
00024  */
00025 
00026 #include "asterisk/codec.h"
00027 
00028 #ifndef _AST_FORMAT_H_
00029 #define _AST_FORMAT_H_
00030 
00031 struct ast_format;
00032 
00033 /*! \brief Format comparison results */
00034 enum ast_format_cmp_res {
00035    /*! Both formats are equivalent to eachother */
00036    AST_FORMAT_CMP_EQUAL = 0,
00037    /*! Both formats are completely different and not the same in any way */
00038    AST_FORMAT_CMP_NOT_EQUAL,
00039    /*! Both formats are similar but not equivalent */
00040    AST_FORMAT_CMP_SUBSET,
00041 };
00042 
00043 /*! \brief Optional format interface to extend format operations */
00044 struct ast_format_interface {
00045    /*!
00046     * \brief Callback for when the format is destroyed, used to release attribute resources
00047     *
00048     * \param format The format structure to destroy
00049     */
00050    void (*const format_destroy)(struct ast_format *format);
00051 
00052    /*!
00053     * \brief Callback for when the format is cloned, used to clone attributes
00054     *
00055     * \param src Source format of attributes
00056     * \param dst Destination format for attributes
00057     *
00058     * \retval 0 success
00059     * \retval -1 failure
00060     */
00061    int (*const format_clone)(const struct ast_format *src, struct ast_format *dst);
00062 
00063    /*!
00064     * \brief Determine if format 1 is a subset of format 2.
00065     *
00066     * \param format1 First format to compare
00067     * \param format2 Second format which the first is compared against
00068     *
00069     * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
00070     */
00071    enum ast_format_cmp_res (* const format_cmp)(const struct ast_format *format1,
00072       const struct ast_format *format2);
00073 
00074    /*! 
00075     * \brief Get a format with the joint compatible attributes of both provided formats.
00076     *
00077     * \param format1 The first format
00078     * \param format2 The second format
00079     *
00080     * \retval non-NULL if joint format
00081     * \retval NULL if no joint format
00082     *
00083     * \note The returned format has its reference count incremented and must be released using
00084     * ao2_ref or ao2_cleanup.
00085     */
00086    struct ast_format *(* const format_get_joint)(const struct ast_format *format1,
00087       const struct ast_format *format2);
00088 
00089    /*!
00090     * \brief Set an attribute on a format
00091     *
00092     * \param name The name of the attribute
00093     * \param value The value of the attribute
00094     *
00095     * \retval non-NULL success
00096     * \retval NULL failure
00097     */
00098    struct ast_format *(* const format_attribute_set)(const struct ast_format *format,
00099       const char *name, const char *value);
00100 
00101    /*!
00102     * \brief Parse SDP attribute information, interpret it, and store it in the format structure.
00103     *
00104     * \param format Format to set attributes on
00105     * \param attributes A string containing only the attributes from the fmtp line
00106     *
00107     * \retval non-NULL Success, values were valid
00108     * \retval NULL Failure, some values were not acceptable
00109     */
00110    struct ast_format *(* const format_parse_sdp_fmtp)(const struct ast_format *format, const char *attributes);
00111 
00112    /*!
00113     * \brief Generate SDP attribute information from an ast_format_attr structure.
00114     *
00115     * \param format The format containing attributes
00116     * \param payload The payload number to place into the fmtp line
00117     * \param str The generated fmtp line
00118     *
00119     * \note This callback should generate a full fmtp line using the provided payload number.
00120     */
00121    void (* const format_generate_sdp_fmtp)(const struct ast_format *format, unsigned int payload,
00122       struct ast_str **str);
00123 };
00124 
00125 /*!
00126  * \brief Initialize media format support
00127  *
00128  * \retval 0 success
00129  * \retval -1 failure
00130  */
00131 int ast_format_init(void);
00132 
00133 /*!
00134  * \brief Create a new media format
00135  *
00136  * \param codec The codec to use
00137  *
00138  * \retval non-NULL success
00139  * \retval NULL failure
00140  *
00141  * \note The format is returned with reference count incremented. It must be released using
00142  * ao2_ref or ao2_cleanup.
00143  */
00144 struct ast_format *ast_format_create(struct ast_codec *codec);
00145 
00146 /*!
00147  * \brief Create a new media format with a specific name
00148  *
00149  * \param format_name The name to use for the format
00150  * \param codec The codec to use
00151  *
00152  * \note This creation function should be used when the name of the \c codec
00153  * cannot be explicitly used for the name of the format. This is the case for
00154  * codecs with multiple sample rates
00155  *
00156  * \note The format is returned with reference count incremented. It must be released using
00157  * ao2_ref or ao2_cleanup.
00158  *
00159  * \retval non-NULL success
00160  * \retval NULL failure
00161  */
00162 struct ast_format *ast_format_create_named(const char *format_name, struct ast_codec *codec);
00163 
00164 /*!
00165  * \brief Clone an existing media format so it can be modified
00166  *
00167  * \param format The existing media format
00168  *
00169  * \note The returned format is a new ao2 object. It must be released using ao2_cleanup.
00170  *
00171  * \retval non-NULL success
00172  * \retval NULL failure
00173  */
00174 struct ast_format *ast_format_clone(const struct ast_format *format);
00175 
00176 /*!
00177  * \brief Compare two formats
00178  *
00179  * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
00180  */
00181 enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
00182 
00183 /*!
00184  * \brief Get a common joint capability between two formats
00185  *
00186  * \retval non-NULL if joint capability exists
00187  * \retval NULL if no joint capability exists
00188  *
00189  * \note The returned format must be treated as immutable.
00190  */
00191 struct ast_format *ast_format_joint(const struct ast_format *format1, const struct ast_format *format2);
00192 
00193 /*!
00194  * \brief Set an attribute on a format to a specific value
00195  *
00196  * \param format The format to set the attribute on
00197  * \param name Attribute name
00198  * \param value Attribute value
00199  *
00200  * \retval non-NULL success
00201  * \retval NULL failure
00202  */
00203 struct ast_format *ast_format_attribute_set(const struct ast_format *format, const char *name,
00204    const char *value);
00205 
00206 /*!
00207  * \brief This function is used to have a media format aware module parse and interpret
00208  * SDP attribute information. Once interpreted this information is stored on the format
00209  * itself using Asterisk format attributes.
00210  *
00211  * \param format to set
00212  * \param attributes string containing the fmtp line from the SDP
00213  *
00214  * \retval non-NULL success, attribute values were valid
00215  * \retval NULL failure, values were not acceptable
00216  */
00217 struct ast_format *ast_format_parse_sdp_fmtp(const struct ast_format *format, const char *attributes);
00218 
00219 /*!
00220  * \brief This function is used to produce an fmtp SDP line for an Asterisk format. The
00221  * attributes present on the Asterisk format are translated into the SDP equivalent.
00222  *
00223  * \param format to generate an fmtp line for
00224  * \param payload numerical payload for the fmtp line
00225  * \param str structure that the fmtp line will be appended to
00226  */
00227 void ast_format_generate_sdp_fmtp(const struct ast_format *format, unsigned int payload, struct ast_str **str);
00228 
00229 /*!
00230  * \brief Register a format interface for use with the provided codec
00231  *
00232  * \param codec The name of codec the interface is applicable to
00233  * \param interface A pointer to the interface implementation
00234  * \param mod The module this format interface is provided by
00235  *
00236  * \retval 0 success
00237  * \retval -1 failure
00238  */
00239 int __ast_format_interface_register(const char *codec, const struct ast_format_interface *interface, struct ast_module *mod);
00240 
00241 /*!
00242  * \brief Register a format interface for use with the provided codec
00243  *
00244  * \param codec The name of codec the interface is applicable to
00245  * \param interface A pointer to the interface implementation
00246  *
00247  * \retval 0 success
00248  * \retval -1 failure
00249  */
00250 #define ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, ast_module_info->self)
00251 
00252 /*!
00253  * \brief Get the attribute data on a format
00254  *
00255  * \param format The media format
00256  *
00257  * \return Currently set attribute data
00258  */
00259 void *ast_format_get_attribute_data(const struct ast_format *format);
00260 
00261 /*!
00262  * \brief Set the attribute data on a format
00263  *
00264  * \param format The media format
00265  * \param attribute_data The attribute data
00266  */
00267 void ast_format_set_attribute_data(struct ast_format *format, void *attribute_data);
00268 
00269 /*!
00270  * \brief Get the name associated with a format
00271  *
00272  * \param format The media format
00273  *
00274  * \return The name of the format
00275  */
00276 const char *ast_format_get_name(const struct ast_format *format);
00277 
00278 /*!
00279  * \brief Get the codec associated with a format
00280  *
00281  * \param format The media format
00282  *
00283  * \return The codec
00284  *
00285  * \note The reference count of the returned codec is increased by 1 and must be decremented
00286  */
00287 struct ast_codec *ast_format_get_codec(const struct ast_format *format);
00288 
00289 /*!
00290  * \brief Get the codec identifier associated with a format
00291  *
00292  * \param format The media format
00293  *
00294  * \return codec identifier
00295  */
00296 unsigned int ast_format_get_codec_id(const struct ast_format *format);
00297 
00298 /*!
00299  * \brief Get the codec name associated with a format
00300  *
00301  * \param format The media format
00302  *
00303  * \return The codec name
00304  */
00305 const char *ast_format_get_codec_name(const struct ast_format *format);
00306 
00307 /*!
00308  * \brief Get whether or not the format can be smoothed
00309  *
00310  * \param format The media format
00311  *
00312  * \retval 0 the format cannot be smoothed
00313  * \retval 1 the format can be smoothed
00314  */
00315 int ast_format_can_be_smoothed(const struct ast_format *format);
00316 
00317 /*!
00318  * \brief Get the media type of a format
00319  *
00320  * \param format The media format
00321  *
00322  * \return the media type
00323  */
00324 enum ast_media_type ast_format_get_type(const struct ast_format *format);
00325 
00326 /*!
00327  * \brief Get the default framing size (in milliseconds) for a format
00328  *
00329  * \param format The media format
00330  *
00331  * \return default framing size in milliseconds
00332  */
00333 unsigned int ast_format_get_default_ms(const struct ast_format *format);
00334 
00335 /*!
00336  * \brief Get the minimum amount of media carried in this format
00337  *
00338  * \param format The media format
00339  *
00340  * \return minimum framing size in milliseconds
00341  */
00342 unsigned int ast_format_get_minimum_ms(const struct ast_format *format);
00343 
00344 /*!
00345  * \brief Get the maximum amount of media carried in this format
00346  *
00347  * \param format The media format
00348  *
00349  * \return maximum framing size in milliseconds
00350  */
00351 unsigned int ast_format_get_maximum_ms(const struct ast_format *format);
00352 
00353 /*!
00354  * \brief Get the minimum number of bytes expected in a frame for this format
00355  *
00356  * \param format The media format
00357  *
00358  * \return minimum expected bytes in a frame for this format
00359  */
00360 unsigned int ast_format_get_minimum_bytes(const struct ast_format *format);
00361 
00362 /*!
00363  * \brief Get the sample rate of a media format
00364  *
00365  * \param format The media format
00366  *
00367  * \return sample rate
00368  */
00369 unsigned int ast_format_get_sample_rate(const struct ast_format *format);
00370 
00371 /*!
00372  * \brief Get the length (in milliseconds) for the format with a given number of samples
00373  *
00374  * \param format The media format
00375  * \param samples The number of samples
00376  *
00377  * \return length of media (in milliseconds)
00378  */
00379 unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples);
00380 
00381 /*!
00382  * \since 12
00383  * \brief Get the message type used for signaling a format registration
00384  *
00385  * \retval Stasis message type for format registration
00386  * \retval NULL on error
00387  */
00388 struct stasis_message_type *ast_format_register_type(void);
00389 
00390 /*!
00391  * \since 12
00392  * \brief Get the message type used for signaling a format unregistration
00393  *
00394  * \retval Stasis message type for format unregistration
00395  * \retval NULL on error
00396  */
00397 struct stasis_message_type *ast_format_unregister_type(void);
00398 
00399 #endif /* _AST_FORMAT_H */

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