[asterisk-commits] file: branch group/media_formats-reviewed r410186 - in /team/group/media_form...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Fri Mar 7 15:01:02 CST 2014


Author: file
Date: Fri Mar  7 15:00:57 2014
New Revision: 410186

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=410186
Log:
Merge in new format API and unit tests.

Added:
    team/group/media_formats-reviewed/include/asterisk/codec.h
      - copied unchanged from r410178, team/file/media_formats-impl/include/asterisk/codec.h
    team/group/media_formats-reviewed/include/asterisk/format_cache.h
      - copied unchanged from r410178, team/file/media_formats-impl/include/asterisk/format_cache.h
    team/group/media_formats-reviewed/include/asterisk/smoother.h
      - copied unchanged from r410178, team/file/media_formats-impl/include/asterisk/smoother.h
    team/group/media_formats-reviewed/main/codec.c
      - copied unchanged from r410178, team/file/media_formats-impl/main/codec.c
    team/group/media_formats-reviewed/main/codec_builtin.c
      - copied unchanged from r410178, team/file/media_formats-impl/main/codec_builtin.c
    team/group/media_formats-reviewed/main/format_cache.c
      - copied unchanged from r410178, team/file/media_formats-impl/main/format_cache.c
    team/group/media_formats-reviewed/main/smoother.c
      - copied unchanged from r410178, team/file/media_formats-impl/main/smoother.c
    team/group/media_formats-reviewed/tests/test_core_codec.c
      - copied unchanged from r410178, team/file/media_formats-impl/tests/test_core_codec.c
    team/group/media_formats-reviewed/tests/test_core_format.c
      - copied unchanged from r410178, team/file/media_formats-impl/tests/test_core_format.c
    team/group/media_formats-reviewed/tests/test_format_cache.c
      - copied unchanged from r410178, team/file/media_formats-impl/tests/test_format_cache.c
    team/group/media_formats-reviewed/tests/test_format_cap.c
      - copied unchanged from r410178, team/file/media_formats-impl/tests/test_format_cap.c
Modified:
    team/group/media_formats-reviewed/include/asterisk/format.h
    team/group/media_formats-reviewed/include/asterisk/format_cap.h
    team/group/media_formats-reviewed/include/asterisk/frame.h
    team/group/media_formats-reviewed/include/asterisk/vector.h
    team/group/media_formats-reviewed/main/asterisk.c
    team/group/media_formats-reviewed/main/format.c
    team/group/media_formats-reviewed/main/format_cap.c
    team/group/media_formats-reviewed/main/frame.c
    team/group/media_formats-reviewed/res/res_fax.c
    team/group/media_formats-reviewed/res/res_rtp_asterisk.c

Modified: team/group/media_formats-reviewed/include/asterisk/format.h
URL: http://svnview.digium.com/svn/asterisk/team/group/media_formats-reviewed/include/asterisk/format.h?view=diff&rev=410186&r1=410185&r2=410186
==============================================================================
--- team/group/media_formats-reviewed/include/asterisk/format.h (original)
+++ team/group/media_formats-reviewed/include/asterisk/format.h Fri Mar  7 15:00:57 2014
@@ -1,9 +1,9 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2010, Digium, Inc.
- *
- * David Vossel <dvossel at digium.com>
+ * Copyright (C) 2014, Digium, Inc.
+ *
+ * Joshua Colp <jcolp at digium.com>
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -18,228 +18,153 @@
 
 /*!
  * \file
- * \brief Format API
- *
- * \author David Vossel <dvossel at digium.com>
+ * \brief Media Format API
+ *
+ * \author Joshua Colp <jcolp at digium.com>
  */
 
 #ifndef _AST_FORMAT_H_
 #define _AST_FORMAT_H_
 
-#include "asterisk/astobj2.h"
-#include "asterisk/silk.h"
-#include "asterisk/celt.h"
-#include "asterisk/opus.h"
-#define AST_FORMAT_ATTR_SIZE 64
-#define AST_FORMAT_INC 100000
-
-/*! This is the value that ends a var list of format attribute
- * key value pairs. */
-#define AST_FORMAT_ATTR_END -1
-
-/* \brief Format Categories*/
-enum ast_format_type {
-	AST_FORMAT_TYPE_AUDIO = 1 * AST_FORMAT_INC,
-	AST_FORMAT_TYPE_VIDEO = 2 * AST_FORMAT_INC,
-	AST_FORMAT_TYPE_IMAGE = 3 * AST_FORMAT_INC,
-	AST_FORMAT_TYPE_TEXT  = 4 * AST_FORMAT_INC,
-};
-
-enum ast_format_id {
-	/*! G.723.1 compression */
-	AST_FORMAT_G723_1           = 1 + AST_FORMAT_TYPE_AUDIO,
-	/*! GSM compression */
-	AST_FORMAT_GSM              = 2 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw mu-law data (G.711) */
-	AST_FORMAT_ULAW             = 3 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw A-law data (G.711) */
-	AST_FORMAT_ALAW             = 4 + AST_FORMAT_TYPE_AUDIO,
-	/*! ADPCM (G.726, 32kbps, AAL2 codeword packing) */
-	AST_FORMAT_G726_AAL2        = 5 + AST_FORMAT_TYPE_AUDIO,
-	/*! ADPCM (IMA) */
-	AST_FORMAT_ADPCM            = 6 + AST_FORMAT_TYPE_AUDIO,
-	/*! LPC10, 180 samples/frame */
-	AST_FORMAT_LPC10            = 7 + AST_FORMAT_TYPE_AUDIO,
-	/*! G.729A audio */
-	AST_FORMAT_G729A            = 8 + AST_FORMAT_TYPE_AUDIO,
-	/*! SpeeX Free Compression */
-	AST_FORMAT_SPEEX            = 9 + AST_FORMAT_TYPE_AUDIO,
-	/*! iLBC Free Compression */
-	AST_FORMAT_ILBC             = 10 + AST_FORMAT_TYPE_AUDIO,
-	/*! ADPCM (G.726, 32kbps, RFC3551 codeword packing) */
-	AST_FORMAT_G726             = 11 + AST_FORMAT_TYPE_AUDIO,
-	/*! G.722 */
-	AST_FORMAT_G722             = 12 + AST_FORMAT_TYPE_AUDIO,
-	/*! G.722.1 (also known as Siren7, 32kbps assumed) */
-	AST_FORMAT_SIREN7           = 13 + AST_FORMAT_TYPE_AUDIO,
-	/*! G.722.1 Annex C (also known as Siren14, 48kbps assumed) */
-	AST_FORMAT_SIREN14          = 14 + AST_FORMAT_TYPE_AUDIO,
-	/*! G.719 (64 kbps assumed) */
-	AST_FORMAT_G719             = 15 + AST_FORMAT_TYPE_AUDIO,
-	/*! SpeeX Wideband (16kHz) Free Compression */
-	AST_FORMAT_SPEEX16          = 16 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw mu-law data (G.711) */
-	AST_FORMAT_TESTLAW          = 17 + AST_FORMAT_TYPE_AUDIO,
-	/*! SILK format */
-	AST_FORMAT_SILK             = 18 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (8000 Hz) PCM */
-	AST_FORMAT_SLINEAR          = 19 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (12000 Hz) PCM */
-	AST_FORMAT_SLINEAR12        = 20 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (16000 Hz) PCM */
-	AST_FORMAT_SLINEAR16        = 21 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (24000 Hz) PCM */
-	AST_FORMAT_SLINEAR24        = 22 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (32000 Hz) PCM */
-	AST_FORMAT_SLINEAR32        = 23 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (44100 Hz) PCM just because we can. */
-	AST_FORMAT_SLINEAR44        = 24 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (48000 Hz) PCM */
-	AST_FORMAT_SLINEAR48        = 25 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (96000 Hz) PCM */
-	AST_FORMAT_SLINEAR96        = 26 + AST_FORMAT_TYPE_AUDIO,
-	/*! Raw 16-bit Signed Linear (192000 Hz) PCM.  maybe we're taking this too far. */
-	AST_FORMAT_SLINEAR192       = 27 + AST_FORMAT_TYPE_AUDIO,
-	AST_FORMAT_SPEEX32          = 28 + AST_FORMAT_TYPE_AUDIO,
-	AST_FORMAT_CELT             = 29 + AST_FORMAT_TYPE_AUDIO,
-	/*! Opus */
-	AST_FORMAT_OPUS             = 30 + AST_FORMAT_TYPE_AUDIO,
-
-	/*! H.261 Video */
-	AST_FORMAT_H261             = 1 + AST_FORMAT_TYPE_VIDEO,
-	/*! H.263 Video */
-	AST_FORMAT_H263             = 2 + AST_FORMAT_TYPE_VIDEO,
-	/*! H.263+ Video */
-	AST_FORMAT_H263_PLUS        = 3 + AST_FORMAT_TYPE_VIDEO,
-	/*! H.264 Video */
-	AST_FORMAT_H264             = 4 + AST_FORMAT_TYPE_VIDEO,
-	/*! MPEG4 Video */
-	AST_FORMAT_MP4_VIDEO        = 5 + AST_FORMAT_TYPE_VIDEO,
-	/*! VP8 */
-	AST_FORMAT_VP8              = 6 + AST_FORMAT_TYPE_VIDEO,
-
-	/*! JPEG Images */
-	AST_FORMAT_JPEG             = 1 + AST_FORMAT_TYPE_IMAGE,
-	/*! PNG Images */
-	AST_FORMAT_PNG              = 2 + AST_FORMAT_TYPE_IMAGE,
-
-	/*! T.140 RED Text format RFC 4103 */
-	AST_FORMAT_T140RED          = 1 + AST_FORMAT_TYPE_TEXT,
-	/*! T.140 Text format - ITU T.140, RFC 4103 */
-	AST_FORMAT_T140             = 2 + AST_FORMAT_TYPE_TEXT,
-};
-
-/*! Determine what type of media a ast_format_id is. */
-#define AST_FORMAT_GET_TYPE(id) (((int) (id / AST_FORMAT_INC)) * AST_FORMAT_INC)
-
-
-/*! \brief This structure contains the buffer used for format attributes */
-struct ast_format_attr {
-	/*! The buffer formats can use to represent attributes */
-	uint32_t format_attr[AST_FORMAT_ATTR_SIZE];
-	/*! If a format's payload needs to pass through that a new marker is required
-	 * for RTP, this variable will be set. */
-	uint8_t rtp_marker_bit;
-};
-
-/*! \brief Represents a media format within Asterisk. */
-struct ast_format {
-	/*! The unique id representing this format from all the other formats. */
-	enum ast_format_id id;
-	/*!  Attribute structure used to associate attributes with a format. */
-	struct ast_format_attr fattr;
-};
-
+struct ast_codec;
+struct ast_format;
+
+/*! \brief Format comparison results */
 enum ast_format_cmp_res {
-	/*! structure 1 is identical to structure 2. */
+	/*! Both formats are equivalent to eachother */
 	AST_FORMAT_CMP_EQUAL = 0,
-	/*! structure 1 contains elements not in structure 2. */
+	/*! Both formats are completely different and not the same in any way */
 	AST_FORMAT_CMP_NOT_EQUAL,
-	/*! structure 1 is a proper subset of the elements in structure 2.*/
+	/*! Both formats are similar but not equivalent */
 	AST_FORMAT_CMP_SUBSET,
 };
 
-/*! \brief Definition of supported media formats (codecs) */
-struct ast_format_list {
-	struct ast_format format; /*!< The unique format. */
-	char name[64];	/*!< short name */
-	unsigned int samplespersecond; /*!< Number of samples per second (8000/16000) */
-	char desc[128];	/*!< Description */
-	int fr_len;	/*!< Single frame length in bytes */
-	int min_ms;	/*!< Min value */
-	int max_ms;	/*!< Max value */
-	int inc_ms;	/*!< Increment */
-	int def_ms;	/*!< Default value */
-	unsigned int flags;	/*!< Smoother flags */
-	int cur_ms;	/*!< Current value */
-	int custom_entry;
-};
-
-/*! \brief A format must register an attribute interface if it requires the use of the format attributes void pointer */
-struct ast_format_attr_interface {
-	/*! format type */
-	enum ast_format_id id;
-
-	/*! \brief Determine if format_attr 1 is a subset of format_attr 2.
-	 *
-	 * \retval ast_format_cmp_res representing the result of comparing fattr1 and fattr2.
-	 */
-	enum ast_format_cmp_res (* const format_attr_cmp)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2);
-
-	/*! \brief Get joint attributes of same format type if they exist.
-	 *
-	 * \retval 0 if joint attributes exist
-	 * \retval -1 if no joint attributes are present
-	 */
-	int (* const format_attr_get_joint)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2, struct ast_format_attr *result);
-
-	/*! \brief Set format capabilities from a list of key value pairs ending with AST_FORMAT_ATTR_END.
-	 * \note This function does not need to call va_end of the va_list. */
-	void (* const format_attr_set)(struct ast_format_attr *format_attr, va_list ap);
-
-	/*!
-	 * \brief Find out if format capabilities in va_list are in format.
-	 * \note This function does not need to call va_end of the va_list.
-	 *
-	 * \note This function is optional.  In many cases the format_attr_cmp
-	 * function can be used to derive these results.  If it is possible
-	 * that some format attributes have no bearing on the equality of two formats, this
-	 * function must exist.
-	 *
-	 * \retval 0 if all attributes exist
-	 * \retval -1 if any of the attributes not present
-	 */
-	int (* const format_attr_isset)(const struct ast_format_attr *format_attr, va_list ap);
+/*! \brief Optional format interface to extend format operations */
+struct ast_format_interface {
+	/*!
+	 * \brief Callback for when the format is destroyed, used to release attribute resources
+	 *
+	 * \param format The format structure to destroy
+	 */
+	void (*const format_destroy)(struct ast_format *format);
+
+	/*!
+	 * \brief Determine if format 1 is a subset of format 2.
+	 *
+	 * \param format1 First format to compare
+	 * \param format2 Second format which the first is compared against
+	 *
+	 * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
+	 */
+	enum ast_format_cmp_res (* const format_cmp)(const struct ast_format *format1,
+		const struct ast_format *format2);
+
+	/*! 
+	 * \brief Get a format with the joint compatible attributes of both provided formats.
+	 *
+	 * \param format1 The first format
+	 * \param format2 The second format
+	 *
+	 * \retval non-NULL if joint format
+	 * \retval NULL if no joint format
+	 *
+	 * \note The returned format has its reference count incremented and must be released using
+	 * ao2_ref or ao2_cleanup.
+	 */
+	struct ast_format *(* const format_get_joint)(const struct ast_format *format1,
+		const struct ast_format *format2);
+
+	/*!
+	 * \brief Set an attribute on a format
+	 *
+	 * \param name The name of the attribute
+	 * \param value The value of the attribute
+	 *
+	 * \retval 0 success
+	 * \retval -1 failure
+	 */
+	int (* const format_attribute_set)(struct ast_format *format, const char *name, const char *value);
 
 	/*
-	 * \brief Return a value for a specific format key.   Return that value in the void pointer.
-	 *
-	 * \note It is not expected that all key value pairs can be returned, but those that can should
-	 * be documented as such.
-	 *
-	 * \note This function is optional if key value pairs are not allowed to be accessed.  This
-	 * will result in -1 always being returned.
-	 *
-	 * \retval 0 Success, value was found and copied into void pointer.
-	 * \retval -1 failure, Value was either not found, or not allowed to be accessed.
-	 */
-	int (* const format_attr_get_val)(const struct ast_format_attr *format_attr, int key, void *val);
-
-	/*
-	 * \brief Parse SDP attribute information, interpret it, and store it in ast_format_attr structure.
+	 * \brief Parse SDP attribute information, interpret it, and store it in the format structure.
+	 *
+	 * \param format Format to set attributes on
+	 * \param attributes A string containing only the attributes from the fmtp line
 	 *
 	 * \retval 0 Success, values were valid
 	 * \retval -1 Failure, some values were not acceptable
 	 */
-	int (* const format_attr_sdp_parse)(struct ast_format_attr *format_attr, const char *attributes);
+	int (* const format_sdp_parse)(struct ast_format *format, const char *attributes);
 
 	/*!
 	 * \brief Generate SDP attribute information from an ast_format_attr structure.
 	 *
+	 * \param format The format containing attributes
+	 * \param payload The payload number to place into the fmtp line
+	 * \param str The generated fmtp line
+	 *
 	 * \note This callback should generate a full fmtp line using the provided payload number.
 	 */
-	void (* const format_attr_sdp_generate)(const struct ast_format_attr *format_attr, unsigned int payload, struct ast_str **str);
+	void (* const format_sdp_generate)(const struct ast_format *format, unsigned int payload,
+		struct ast_str **str);
 };
+
+/*!
+ * \brief Initialize media format support
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_format_init(void);
+
+/*!
+ * \brief Create a new media format
+ *
+ * \param codec The codec to use
+ *
+ * \param non-NULL success
+ * \param NULL failure
+ *
+ * \note The format is returned with reference count incremented. It must be released using
+ * ao2_ref or ao2_cleanup.
+ */
+struct ast_format *ast_format_create(struct ast_codec *codec);
+
+/*!
+ * \brief Compare two formats
+ *
+ * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
+ */
+enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
+
+/*1
+ * \brief Get a common joint capability between two formats
+ *
+ * \retval non-NULL if joint capability exists
+ * \retval NULL if no joint capability exists
+ *
+ * \note The returned format must be treated as immutable.
+ */
+struct ast_format *ast_format_joint(const struct ast_format *format1, const struct ast_format *format2);
+
+/*!
+ * \brief Copy a media format
+ *
+ * \note The returned format must be treated as immutable.
+ */
+struct ast_format *ast_format_copy(struct ast_format *format);
+
+/*!
+ * \brief Set an attribute on a format to a specific value
+ *
+ * \param format The format to set the attribute on
+ * \param name Attribute name
+ * \param value Attribute value
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int ast_format_attribute_set(struct ast_format *format, const char *name, const char *value);
 
 /*!
  * \brief This function is used to have a media format aware module parse and interpret
@@ -265,233 +190,89 @@
 void ast_format_sdp_generate(const struct ast_format *format, unsigned int payload, struct ast_str **str);
 
 /*!
- * \brief This function is used to set an ast_format object to represent a media format
- * with optional format attributes represented by format specific key value pairs.
- *
- * \param format to set
- * \param id format id to set on format
- * \param set_attributes are there attributes to set on this format. 0 == false, 1 == True.
- * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
- *
- * \details Example usage.
- * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW
- *
- * ast_format_set(format, AST_FORMAT_SILK, 1, // SILK has capability attributes.
- *	  AST_FORMAT_SILK_ATTR_RATE, 24000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 16000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 12000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 8000,
- *	  AST_FORMAT_ATTR_END);
- *
- * \note This function will initialize the ast_format structure.
- *
- * \return Pointer to ast_format object, same pointer that is passed in
- * by the first argument.
- */
-struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id id, int set_attributes, ... );
-
-/*!
- * \brief After ast_format_set has been used on a function, this function can be used to
- * set additional format attributes to the structure.
- *
- * \param format to set
- * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
- *
- * \details Example usage.
- * ast_format_set(format, AST_FORMAT_SILK, 0);
- * ast_format_append(format, // SILK has capability attributes.
- *	  AST_FORMAT_SILK_ATTR_RATE, 24000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 16000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 12000,
- *	  AST_FORMAT_SILK_ATTR_RATE, 8000,
- *	  AST_FORMAT_ATTR_END);
- *
- * \return Pointer to ast_format object, same pointer that is passed in
- * by the first argument.
- */
-struct ast_format *ast_format_append(struct ast_format *format, ... );
-
-/*!
- * \brief Clears the format stucture.
- */
-void ast_format_clear(struct ast_format *format);
-
-/*!
- * \brief This function is used to set an ast_format object to represent a media format
- * with optional capability attributes represented by format specific key value pairs.
- *
- * \details Example usage. Is this SILK format capable of 8khz
- * is_8khz = ast_format_isset(format, AST_FORMAT_SILK_CAP_RATE, 8000);
- *
- * \return 0, The format key value pairs are within the capabilities defined in this structure.
- * \return -1, The format key value pairs are _NOT_ within the capabilities of this structure.
- */
-int ast_format_isset(const struct ast_format *format, ... );
-
-/*!
- * \brief Get a value from a format containing attributes.
- * \note The key represents the format attribute to be retrieved, and the void pointer
- * is to the structure that value will be stored in.  It must be known what structure a
- * key represents.
- *
- * \retval 0, success
- * \retval -1, failure
- */
-int ast_format_get_value(const struct ast_format *format, int key, void *value);
-
-/*!
- * \brief Compare ast_formats structures
- *
- * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
- */
-enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
-
-/*!
- * \brief Find joint format attributes of two ast_format
- * structures containing the same uid and return the intersection in the
- * result structure.
- *
- * retval 0, joint attribute capabilities exist.
- * retval -1, no joint attribute capabilities exist.
- */
-int ast_format_joint(const struct ast_format *format1, const struct ast_format *format2, struct ast_format *result);
-
-/*!
- * \brief copy format src into format dst.
- */
-void ast_format_copy(struct ast_format *dst, const struct ast_format *src);
-
-/*!
- * \brief Set the rtp mark value on the format to indicate to the interface
- * writing this format's payload that a new RTP marker is necessary.
- */
-void ast_format_set_video_mark(struct ast_format *format);
-
-/*!
- * \brief Determine of the marker bit is set or not on this format.
- *
- * \retval 1, true
- * \retval 0, false
- */
-int ast_format_get_video_mark(const struct ast_format *format);
-
-/*!
- * \brief ast_format to old bitfield format represenatation
- *
- * \note This is only to be used for IAX2 compatibility 
- *
- * \retval iax2 representation of ast_format
- * \retval 0, if no representation existis for iax2
- */
-uint64_t ast_format_to_old_bitfield(const struct ast_format *format);
-
-/*!
- * \brief ast_format_id to old bitfield format represenatation
- *
- */
-uint64_t ast_format_id_to_old_bitfield(enum ast_format_id id);
-
-/*!
- * \brief convert old bitfield format to ast_format represenatation
- * \note This is only to be used for IAX2 compatibility 
- *
- * \retval on success, pointer to the dst format in the input parameters
- * \retval on failure, NULL
- */
-struct ast_format *ast_format_from_old_bitfield(struct ast_format *dst, uint64_t src);
-
-/*!
- * \brief convert old bitfield format to ast_format_id value
- */
-enum ast_format_id ast_format_id_from_old_bitfield(uint64_t src);
-
-/*!
- * \brief Retrieve the global format list in a read only array.
- * \note ast_format_list_destroy must be called on every format
- * list retrieved from this function.
- */
-const struct ast_format_list *ast_format_list_get(size_t *size);
-
-/*!
- * \brief Destroy an ast_format_list gotten from ast_format_list_get()
- */
-const struct ast_format_list *ast_format_list_destroy(const struct ast_format_list *list);
-
-/*! \brief Get the name of a format
- * \param format id of format
- * \return A static string containing the name of the format or "unknown" if unknown.
- */
-const char* ast_getformatname(const struct ast_format *format);
-
-/*! \brief Returns a string containing all formats pertaining to an format id.
- * \param buf a buffer for the output string
- * \param size size of buf (bytes)
- * \param id format id.
- * \return The return value is buf.
- */
-char* ast_getformatname_multiple_byid(char *buf, size_t size, enum ast_format_id id);
-
-/*!
- * \brief Gets a format from a name.
- * \param name string of format
- * \param format structure to return the format in.
- * \return This returns the format pointer given to it on success and NULL on failure
- */
-struct ast_format *ast_getformatbyname(const char *name, struct ast_format *format);
-
-/*!
- * \brief Get a name from a format 
- * \param format to get name of
- * \return This returns a static string identifying the format on success, 0 on error.
- */
-const char *ast_codec2str(struct ast_format *format);
-
-/*!
- * \brief Get the sample rate for a given format.
- */
-int ast_format_rate(const struct ast_format *format);
-
-/*!
- * \brief register ast_format_attr_interface with core.
- *
- * \retval 0 success
- * \retval -1 failure
- */
-int ast_format_attr_reg_interface(const struct ast_format_attr_interface *interface);
-
-/*!
- * \brief unregister format_attr interface with core.
- *
- * \retval 0 success
- * \retval -1 failure
- */
-int ast_format_attr_unreg_interface(const struct ast_format_attr_interface *interface);
-
-/*!
- * \brief Determine if a format is 16bit signed linear of any sample rate. 
- */
-int ast_format_is_slinear(const struct ast_format *format);
-
-/*!
- * \brief Get the best slinear format id for a given sample rate
- */
-enum ast_format_id ast_format_slin_by_rate(unsigned int rate);
-
-/*!
- * \since 12
- * \brief Get the message type used for signaling a format registration
- *
- * \retval Stasis message type for format registration
- * \retval NULL on error
- */
-struct stasis_message_type *ast_format_register_type(void);
-
-/*!
- * \since 12
- * \brief Get the message type used for signaling a format unregistration
- *
- * \retval Stasis message type for format unregistration
- * \retval NULL on error
- */
-struct stasis_message_type *ast_format_unregister_type(void);
+ * \brief Register a format interface for use with the provided codec
+ *
+ * \param codec The name of codec the interface is applicable to
+ * \param interface A pointer to the interface implementation
+ * \param mod The module this format interface is provided by
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+int __ast_format_interface_register(const char *codec, struct ast_format_interface *interface, struct ast_module *mod);
+
+/*!
+ * \brief Register a format interface for use with the provided codec
+ *
+ * \param codec The name of codec the interface is applicable to
+ * \param interface A pointer to the interface implementation
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ */
+#define ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, ast_module_info->self)
+
+/*!
+ * \brief Get the codec identifier associated with a format
+ *
+ * \param format The media format
+ *
+ * \return codec identifier
+ */
+unsigned int ast_format_get_codec_id(const struct ast_format *format);
+
+/*!
+ * \brief Get the codec name associated with a format
+ *
+ * \param format The media format
+ *
+ * \return codec name
+ */
+const char *ast_format_get_name(const struct ast_format *format);
+
+/*!
+ * \brief Get the media type of a format
+ *
+ * \param format The media format
+ *
+ * \return the media type
+ */
+enum ast_media_type ast_format_get_type(const struct ast_format *format);
+
+/*!
+ * \brief Get the default framing size (in milliseconds) for a format
+ *
+ * \param format The media format
+ *
+ * \return default framing size in milliseconds
+ */
+unsigned int ast_format_get_default_ms(const struct ast_format *format);
+
+/*!
+ * \brief Get the minimum amount of media carried in this format
+ *
+ * \param format The media format
+ *
+ * \return minimum framing size in milliseconds
+ */
+unsigned int ast_format_get_minimum_ms(const struct ast_format *format);
+
+/*!
+ * \brief Get the maximum amount of media carried in this format
+ *
+ * \param format The media format
+ *
+ * \return maximum framing size in milliseconds
+ */
+unsigned int ast_format_get_maximum_ms(const struct ast_format *format);
+
+/*!
+ * \brief Get the sample rate of a media format
+ *
+ * \param format The media format
+ *
+ * \return sample rate
+ */
+unsigned int ast_format_get_sample_rate(const struct ast_format *format);
+
 #endif /* _AST_FORMAT_H */

Modified: team/group/media_formats-reviewed/include/asterisk/format_cap.h
URL: http://svnview.digium.com/svn/asterisk/team/group/media_formats-reviewed/include/asterisk/format_cap.h?view=diff&rev=410186&r1=410185&r2=410186
==============================================================================
--- team/group/media_formats-reviewed/include/asterisk/format_cap.h (original)
+++ team/group/media_formats-reviewed/include/asterisk/format_cap.h Fri Mar  7 15:00:57 2014
@@ -1,9 +1,9 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2010, Digium, Inc.
- *
- * David Vossel <dvossel at digium.com>
+ * Copyright (C) 2014, Digium, Inc.
+ *
+ * Joshua Colp <jcolp at digium.com>
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -18,105 +18,134 @@
 
 /*!
  * \file
- * \brief Format Capability API
- *
- * \author David Vossel <dvossel at digium.com>
- */
-
-#ifndef _AST_FORMATCAP_H_
-#define _AST_FORMATCAP_H_
-
-/*! Capabilities are represented by an opaque structure statically defined in format_capability.c */
+ * \brief Format Capabilities API
+ *
+ * \author Joshua Colp <jcolp at digium.com>
+ */
+
+#ifndef _AST_FORMAT_CAP_H_
+#define _AST_FORMAT_CAP_H_
+
+#include "asterisk/codec.h"
+
+/*! Capabilities are represented by an opaque structure statically defined in format_cap.c */
 struct ast_format_cap;
 
 enum ast_format_cap_flags {
 	/*!
-	 * The ast_format_cap will be allocated with no lock.
-	 * Useful if there is a separate lock used to protect the structure
+	 * Default format capabilities settings
 	 */
-	AST_FORMAT_CAP_FLAG_NOLOCK = (1 << 0),
-	/*!
-	 * String representations of the formats are cached on the structure.
-	 * Useful if string representation is frequently requested of the structure.
-	 */
-	AST_FORMAT_CAP_FLAG_CACHE_STRINGS = (1 << 1),
+	AST_FORMAT_CAP_FLAG_DEFAULT = 0,
 };
 
 /*!
  * \brief Allocate a new ast_format_cap structure
  *
  * \param flags Modifiers of struct behavior.
+ *
  * \retval ast_format_cap object on success.
  * \retval NULL on failure.
  */
 struct ast_format_cap *ast_format_cap_alloc(enum ast_format_cap_flags flags);
 
 /*!
- * \brief Destroy an ast_format_cap structure.
- *
- * \return NULL
- */
-void *ast_format_cap_destroy(struct ast_format_cap *cap);
+ * \brief Set the global framing.
+ *
+ * \param cap The capabilities structure.
+ * \param framing The framing value (in milliseconds).
+ *
+ * \note This is used if a format does not provide a framing itself.
+ */
+void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing);
 
 /*!
  * \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, const 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);
+ * \param cap The capabilities structure to add to.
+ * \param format The format to add.
+ * \param framing The framing for the format (in milliseconds).
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note A reference to the format is taken and used in the capabilities structure.
+ *
+ * \note The order in which add is called determines the format preference order.
+ *
+ * \note If framing is specified here it overrides any global framing that has been set.
+ */
+int ast_format_cap_add(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing);
+
+/*!
+ * \brief Add all codecs Asterisk knows about for a specific type to
+ * the capabilities structure.
+ *
+ * \param cap The capabilities structure to add to.
+ * \param type The type of formats to add.
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note A generic format with no attributes is created using the codec.
+ *
+ * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
+ */
+int ast_format_cap_add_all_by_type(struct ast_format_cap *cap, enum ast_media_type type);
+
+/*!
+ * \brief Copy all formats in src to dst
+ *
+ * \param dst The destination capabilities structure
+ * \param src The source capabilities structure
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note The source capabilities structure is left alone and remains valid afterwards.
+ */
+int ast_format_cap_append(struct ast_format_cap *dst, const struct ast_format_cap *src);
+
+/*!
+ * \brief Get the number of formats present within the capabilities structure
+ *
+ * \param cap The capabilities structure
+ *
+ * \return the number of formats
+ */
+size_t ast_format_cap_count(const struct ast_format_cap *cap);
+
+/*!
+ * \brief Get the format at a specific index
+ *
+ * \param cap The capabilities structure
+ * \param position The position to get
+ *
+ * \retval non-NULL success
+ * \retval NULL failure
+ *
+ * \note This is a zero based index.
+ *
+ * \note Formats are returned in order of preference.
+ *
+ * \note The reference count of the returned format is increased. It must be released using ao2_ref
+ * or ao2_cleanup.
+ */
+struct ast_format *ast_format_cap_get_format(const struct ast_format_cap *cap, int position);
+
+/*!
+ * \brief Get the framing for a format
+ *
+ * \param cap The capabilities structure
+ * \param format The format to retrieve
+ *
+ * \return the framing (in milliseconds)
+ */
+unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap, const struct ast_format *format);
 
 /*!
  * \brief Remove format capability from capability structure.
  *
- * \note format must match Exactly to format in ast_format_cap object in order
- * to be removed.
+ * \note format must be an exact pointer match to remove from capabilities structure.
  *
  * \retval 0, remove was successful
  * \retval -1, remove failed. Could not find format to remove
@@ -124,110 +153,61 @@
 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);
+ *
+ * \param cap The capabilities structure
+ * \param type The media type to remove formats of
+ *
+ * \note All formats can be removed by using the AST_MEDIA_TYPE_UNKNOWN type.
+ */
+void ast_format_cap_remove_bytype(struct ast_format_cap *cap, enum ast_media_type type);
 
 /*!
  * \brief Find if input ast_format is within the capabilities of the ast_format_cap object
  * then return the compatible format from the capabilities structure in the result.
  *
- * \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_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format, struct ast_format *result);
+ * \retval non-NULL if format is compatible
+ * \retval NULL if not compatible
+ *
+ * \note The reference count of the returned format is increased. It must be released using ao2_ref
+ * or ao2_cleanup.
+ */
+struct ast_format *ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const 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 Finds the best quality audio format for a given format id and returns it in result.
- *
- * \retval 1 format found and set to result structure.
- * \retval 0 no format found, result structure is cleared.
- */
-int ast_format_cap_best_byid(const struct ast_format_cap *cap, enum ast_format_id, struct ast_format *result);
-
-/*!
- * \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 Get joint capability structure, append into result capabilities structure
- *
- * \retval 1, joint capabilities exist
- * \retval 0, joint capabilities do not exist
- */
-int ast_format_cap_joint_append(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);
+* \retval ast_format_cmp_res representing the result of the compatibility check between cap and format.
+ */
+enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
+
+/*!
+ * \brief Find the compatible formats between two capabilities structures
+ *
+ * \param cap1 The first capabilities structure
+ * \param cap2 The second capabilities structure
+ * \param[out] result The capabilities structure to place the results into
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * \note The preference order of cap1 is respected.
+ *

[... 3752 lines stripped ...]



More information about the asterisk-commits mailing list