codec.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 Codec API
00022  *
00023  * \author Joshua Colp <jcolp@digium.com>
00024  */
00025 
00026 #ifndef _AST_CODEC_H_
00027 #define _AST_CODEC_H_
00028 
00029 /*! \brief Types of media */
00030 enum ast_media_type {
00031    AST_MEDIA_TYPE_UNKNOWN = 0,
00032    AST_MEDIA_TYPE_AUDIO,
00033    AST_MEDIA_TYPE_VIDEO,
00034    AST_MEDIA_TYPE_IMAGE,
00035    AST_MEDIA_TYPE_TEXT,
00036 };
00037 
00038 struct ast_module;
00039 
00040 /*! \brief Represents a media codec within Asterisk. */
00041 struct ast_codec {
00042    /*! \brief Internal unique identifier for this codec, set at registration time (starts at 1) */
00043    unsigned int id;
00044    /*! \brief Name for this codec */
00045    const char *name;
00046    /*! \brief Brief description */
00047    const char *description;
00048    /*! \brief Type of media this codec contains */
00049    enum ast_media_type type;
00050    /*! \brief Sample rate (number of samples carried in a second) */
00051    unsigned int sample_rate;
00052    /*! \brief Minimum length of media that can be carried (in milliseconds) in a frame */
00053    unsigned int minimum_ms;
00054    /*! \brief Maximum length of media that can be carried (in milliseconds) in a frame */
00055    unsigned int maximum_ms;
00056    /*! \brief Default length of media carried (in milliseconds) in a frame */
00057    unsigned int default_ms;
00058    /*! \brief Length in bytes of the data payload of a minimum_ms frame */
00059    unsigned int minimum_bytes;
00060    /*!
00061     * \brief Retrieve the number of samples in a frame
00062     *
00063     * \param frame The frame to examine
00064     *
00065     * \return the number of samples
00066     */
00067    int (*samples_count)(struct ast_frame *frame);
00068    /*!
00069     * \brief Retrieve the length of media from number of samples
00070     *
00071     * \param samples The number of samples
00072     *
00073     * \return The length of media in milliseconds
00074     */
00075    int (*get_length)(unsigned int samples);
00076    /*! \brief Whether the media can be smoothed or not */
00077    unsigned int smooth;
00078    /*! \brief The module that registered this codec */
00079    struct ast_module *mod;
00080 };
00081 
00082 /*!
00083  * \brief Initialize codec support within the core.
00084  *
00085  * \retval 0 success
00086  * \retval -1 failure
00087  */
00088 int ast_codec_init(void);
00089 
00090 /*!
00091  * \brief Initialize built-in codecs within the core.
00092  *
00093  * \retval 0 success
00094  * \retval -1 failure
00095  */
00096 int ast_codec_builtin_init(void);
00097 
00098 /*!
00099  * \brief This function is used to register a codec with the Asterisk core. Registering
00100  * allows it to be passed through in frames and configured in channel drivers.
00101  *
00102  * \param codec to register
00103  * \param mod the module this codec is provided by
00104  *
00105  * \retval 0 success
00106  * \retval -1 failure
00107  */
00108 int __ast_codec_register(struct ast_codec *codec, struct ast_module *mod);
00109 
00110 /*!
00111  * \brief This function is used to register a codec with the Asterisk core. Registering
00112  * allows it to be passed through in frames and configured in channel drivers.
00113  *
00114  * \param codec to register
00115  *
00116  * \retval 0 success
00117  * \retval -1 failure
00118  */
00119 #define ast_codec_register(codec) __ast_codec_register(codec, ast_module_info->self)
00120 
00121 /*!
00122  * \brief Retrieve a codec given a name, type, and sample rate
00123  *
00124  * \param name The name of the codec
00125  * \param type The type of the codec
00126  * \param sample_rate Optional sample rate, may not be applicable for some types
00127  *
00128  * \retval non-NULL success
00129  * \retval NULL failure
00130  *
00131  * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
00132  * must be used to release the reference.
00133  */
00134 struct ast_codec *ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate);
00135 
00136 /*!
00137  * \brief Retrieve a codec given the unique identifier
00138  *
00139  * \param id The unique identifier
00140  *
00141  * \retval non-NULL success
00142  * \retval NULL failure
00143  *
00144  * \note Identifiers start at 1 so if iterating don't start at 0.
00145  *
00146  * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
00147  * must be used to release the reference.
00148  */
00149 struct ast_codec *ast_codec_get_by_id(int id);
00150 
00151 /*!
00152  * \brief Retrieve the current maximum identifier for codec iteration
00153  *
00154  * \return Maximum codec identifier
00155  */
00156 int ast_codec_get_max(void);
00157 
00158 /*!
00159  * \brief Conversion function to take a media type and turn it into a string
00160  *
00161  * \param type The media type
00162  *
00163  * \retval string representation of the media type
00164  */
00165 const char *ast_codec_media_type2str(enum ast_media_type type);
00166 
00167 /*!
00168  * \brief Get the number of samples contained within a frame
00169  *
00170  * \param frame The frame itself
00171  *
00172  * \retval number of samples in the frame
00173  */
00174 unsigned int ast_codec_samples_count(struct ast_frame *frame);
00175 
00176 /*!
00177  * \brief Get the length of media (in milliseconds) given a number of samples
00178  *
00179  * \param codec The codec itself
00180  * \param samples The number of samples
00181  *
00182  * \retval length of media (in milliseconds)
00183  */
00184 unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples);
00185 
00186 #endif /* _AST_CODEC_H */

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