Asterisk media architecture conversion - no more format bitfields

This patch is the foundation of an entire new way of looking at media in Asterisk.
The code present in this patch is everything required to complete phase1 of my
Media Architecture proposal.  For more information about this project visit the link below.
https://wiki.asterisk.org/wiki/display/AST/Media+Architecture+Proposal

The primary function of this patch is to convert all the usages of format
bitfields in Asterisk to use the new format and format_cap APIs.  Functionally
no change in behavior should be present in this patch.  Thanks to twilson
and russell for all the time they spent reviewing these changes.

Review: https://reviewboard.asterisk.org/r/1083/



git-svn-id: http://svn.digium.com/svn/asterisk/trunk@306010 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 52 insertions, 37 deletions

diff --git a/include/asterisk/rtp_engine.h b/include/asterisk/rtp_engine.h
index cd9179be1..f13538321 100644
--- a/include/asterisk/rtp_engine.h
+++ b/include/asterisk/rtp_engine.h
@@ -227,8 +227,12 @@ enum ast_rtp_instance_stat {
 struct ast_rtp_payload_type {
 	/*! Is this an Asterisk value */
 	int asterisk_format;
-	/*! Actual internal value of the payload */
-	format_t code;
+	/*! If asterisk_format is set, this is the internal
+	 * asterisk format represented by the payload */
+	struct ast_format format;
+	/*! Actual internal RTP specific value of the payload */
+	int rtp_code;
+
 };
 
 /*! Structure that represents statistics from an RTP instance */
@@ -335,8 +339,8 @@ struct ast_rtp_engine {
 	void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
 	/*! Callback for setting an RTP property */
 	void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
-	/*! Callback for setting a payload */
-	void (*payload_set)(struct ast_rtp_instance *instance, int payload, int astformat, format_t format);
+	/*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
+	void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
 	/*! Callback for setting packetization preferences */
 	void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
 	/*! Callback for setting the remote address that RTP is to be sent to */
@@ -360,9 +364,9 @@ struct ast_rtp_engine {
 	/*! Callback to locally bridge two RTP instances */
 	int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
 	/*! Callback to set the read format */
-	int (*set_read_format)(struct ast_rtp_instance *instance, format_t format);
+	int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
 	/*! Callback to set the write format */
-	int (*set_write_format)(struct ast_rtp_instance *instance, format_t format);
+	int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
 	/*! Callback to make two instances compatible */
 	int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
 	/*! Callback to see if two instances are compatible with DTMF */
@@ -371,8 +375,8 @@ struct ast_rtp_engine {
 	int (*activate)(struct ast_rtp_instance *instance);
 	/*! Callback to request that the RTP engine send a STUN BIND request */
 	void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
-	/*! Callback to get the transcodeable formats supported */
-	int (*available_formats)(struct ast_rtp_instance *instance, format_t to_endpoint, format_t to_asterisk);
+	/*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
+	void (*available_formats)(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
 	/*! Linked list information */
 	AST_RWLIST_ENTRY(ast_rtp_engine) entry;
 };
@@ -407,9 +411,9 @@ struct ast_rtp_glue {
 	 */
 	enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
 	/*! Callback for updating the destination that the remote side should send RTP to */
-	int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, format_t codecs, int nat_active);
-	/*! Callback for retrieving codecs that the channel can do */
-	format_t (*get_codec)(struct ast_channel *chan);
+	int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, const struct ast_format_cap *cap, int nat_active);
+	/*! Callback for retrieving codecs that the channel can do.  Result returned in result_cap*/
+	void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
 	/*! Linked list information */
 	AST_RWLIST_ENTRY(ast_rtp_glue) entry;
 };
@@ -1046,27 +1050,29 @@ struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs
 /*!
  * \brief Get the sample rate associated with known RTP payload types
  *
- * \param asterisk_format True if the value in the 'code' parameter is an AST_FORMAT value
- * \param code Format code, either from AST_FORMAT list or from AST_RTP list
+ * \param asterisk_format True if the value in format is to be used.
+ * \param An asterisk format
+ * \param code from AST_RTP list
  *
  * \return the sample rate if the format was found, zero if it was not found
  *
  * \since 1.8
  */
-unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, format_t code);
+unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, struct ast_format *format, int code);
 
 /*!
  * \brief Retrieve all formats that were found
  *
  * \param codecs Codecs structure to look in
- * \param astformats An integer to put the Asterisk formats in
+ * \param astformats A capabilities structure to put the Asterisk formats in.
  * \param nonastformats An integer to put the non-Asterisk formats in
  *
  * Example usage:
  *
  * \code
- * int astformats, nonastformats;
- * ast_rtp_codecs_payload_Formats(&codecs, &astformats, &nonastformats);
+ * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
+ * int nonastformats;
+ * ast_rtp_codecs_payload_formats(&codecs, &astformats, &nonastformats);
  * \endcode
  *
  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
@@ -1074,13 +1080,14 @@ unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, format_t code);
  *
  * \since 1.8
  */
-void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, format_t *astformats, int *nonastformats);
+void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
 
 /*!
  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
  *
  * \param codecs Codecs structure to look in
- * \param asterisk_format Non-zero if the given code is an Asterisk format value
+ * \param asterisk_format Non-zero if the given Asterisk format is present
+ * \param format Asterisk format to look for
  * \param code The format to look for
  *
  * \retval Numerical payload
@@ -1088,20 +1095,21 @@ void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, format_t *ast
  * Example usage:
  *
  * \code
- * int payload = ast_rtp_codecs_payload_code(&codecs, 1, AST_FORMAT_ULAW);
+ * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
  * \endcode
  *
  * This looks for the numerical payload for ULAW in the codecs structure.
  *
  * \since 1.8
  */
-int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int asterisk_format, const format_t code);
+int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
 
 /*!
  * \brief Retrieve mime subtype information on a payload
  *
- * \param asterisk_format Non-zero if the given code is an Asterisk format value
- * \param code Format to look up
+ * \param asterisk_format Non-zero to look up using Asterisk format
+ * \param format Asterisk format to look up
+ * \param code RTP code to look up
  * \param options Additional options that may change the result
  *
  * \retval Mime subtype success
@@ -1110,21 +1118,22 @@ int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int asteris
  * Example usage:
  *
  * \code
- * const char *subtype = ast_rtp_lookup_mime_subtype2(1, AST_FORMAT_ULAW, 0);
+ * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
  * \endcode
  *
  * This looks up the mime subtype for the ULAW format.
  *
  * \since 1.8
  */
-const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, const format_t code, enum ast_rtp_options options);
+const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, struct ast_format *format, int code, enum ast_rtp_options options);
 
 /*!
  * \brief Convert formats into a string and put them into a buffer
  *
  * \param buf Buffer to put the mime output into
- * \param capability Formats that we are looking up
- * \param asterisk_format Non-zero if the given capability are Asterisk format capabilities
+ * \param ast_format_capability Asterisk Formats we are looking up.
+ * \param rtp_capability RTP codes that we are looking up
+ * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
  * \param options Additional options that may change the result
  *
  * \retval non-NULL success
@@ -1134,14 +1143,19 @@ const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, const format
  *
  * \code
  * char buf[256] = "";
- * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), AST_FORMAT_ULAW | AST_FORMAT_ALAW, 1, 0);
+ * struct ast_format tmp_fmt;
+ * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
+ * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
+ * ast_format_cap_add(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
+ * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
+ * ast_format_cap_destroy(cap);
  * \endcode
  *
  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
  *
  * \since 1.8
  */
-char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, const format_t capability, const int asterisk_format, enum ast_rtp_options options);
+char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, struct ast_format_cap *ast_format_capability, int rtp_capability, const int asterisk_format, enum ast_rtp_options options);
 
 /*!
  * \brief Set codec packetization preferences
@@ -1535,14 +1549,15 @@ char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_r
  * Example usage:
  *
  * \code
- * ast_rtp_instance_set_read_format(instance, AST_FORMAT_ULAW);
+ * struct ast_format tmp_fmt;
+ * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
  * \endcode
  *
  * This requests that the RTP engine provide audio frames in the ULAW format.
  *
  * \since 1.8
  */
-int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, format_t format);
+int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
 
 /*!
  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
@@ -1556,14 +1571,15 @@ int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, format_t
  * Example usage:
  *
  * \code
- * ast_rtp_instance_set_write_format(instance, AST_FORMAT_ULAW);
+ * struct ast_format tmp_fmt;
+ * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
  * \endcode
  *
  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
  *
  * \since 1.8
  */
-int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, format_t format);
+int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
 
 /*!
  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
@@ -1592,20 +1608,19 @@ int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_in
  * \param instance The RTP instance
  * \param to_endpoint Formats being sent/received towards the endpoint
  * \param to_asterisk Formats being sent/received towards Asterisk
- *
- * \retval supported formats
+ * \param result capabilities structure to store and return supported formats in.
  *
  * Example usage:
  *
  * \code
- * ast_rtp_instance_available_formats(instance, AST_FORMAT_ULAW, AST_FORMAT_SLINEAR);
+ * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
  * \endcode
  *
  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
  *
  * \since 1.8
  */
-format_t ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, format_t to_endpoint, format_t to_asterisk);
+void ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
 
 /*!
  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance