[svn-commits] file: branch file/rtp_engine r131074 - /team/file/rtp_engine/include/asterisk/
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Tue Jul 15 13:57:46 CDT 2008
Author: file
Date: Tue Jul 15 13:57:45 2008
New Revision: 131074
URL: http://svn.digium.com/view/asterisk?view=rev&rev=131074
Log:
Doxygenify the header file.
Modified:
team/file/rtp_engine/include/asterisk/rtp_engine.h
Modified: team/file/rtp_engine/include/asterisk/rtp_engine.h
URL: http://svn.digium.com/view/asterisk/team/file/rtp_engine/include/asterisk/rtp_engine.h?view=diff&rev=131074&r1=131073&r2=131074
==============================================================================
--- team/file/rtp_engine/include/asterisk/rtp_engine.h (original)
+++ team/file/rtp_engine/include/asterisk/rtp_engine.h Tue Jul 15 13:57:45 2008
@@ -18,6 +18,41 @@
/*! \file
* \brief Pluggable RTP Architecture
+ * \author Joshua Colp <jcolp at digium.com>
+ * \ref AstRTPEngine
+ */
+
+/*!
+ * \page AstRTPEngine Asterisk RTP Engine API
+ *
+ * The purpose of this API is to provide a way for multiple RTP stacks to be used inside
+ * of Asterisk without any module that uses RTP knowing any different. To the module each RTP
+ * stack behaves the same.
+ *
+ * An RTP session is called an instance and is made up of a combination of codec information,
+ * RTP engine, RTP properties, and address information. An engine name may be passed in to explicitly
+ * choose an RTP stack to be used but a default one will be used if none is provided. An address to use
+ * for RTP may also be provided but the underlying RTP engine may choose a different address depending on
+ * it's configuration.
+ *
+ * An RTP engine is the layer between the RTP engine core and the RTP stack itself. The RTP engine core provides
+ * a set of callbacks to do various things (such as write audio out) that the RTP engine has to have implemented.
+ *
+ * Glue is what binds an RTP instance to a channel. It is used to retrieve RTP instance information when
+ * performing remote or local bridging and is used to have the channel driver tell the remote side to change
+ * destination of the RTP stream.
+ *
+ * Statistics from an RTP instance can be retrieved using the ast_rtp_instance_get_stats API call. This essentially
+ * asks the RTP engine in use to fill in a structure with the requested values. It is not required for an RTP engine
+ * to support all statistic values.
+ *
+ * Properties allow behavior of the RTP engine and RTP engine core to be changed. For example, there is a property named
+ * AST_RTP_PROPERTY_NAT which is used to tell the RTP engine to enable symmetric RTP if it supports it. It is not required
+ * for an RTP engine to support all properties.
+ *
+ * Codec information is stored using a separate data structure which has it's own set of API calls to add/remove/retrieve
+ * information. They are used by the module after an RTP instance is created so that payload information is available for
+ * the RTP engine.
*/
#ifndef _ASTERISK_RTP_ENGINE_H
@@ -30,63 +65,111 @@
/* Maximum number of payloads supported */
#define AST_RTP_MAX_PT 256
+/* Maximum number of generations */
#define AST_RED_MAX_GENERATION 5
struct ast_rtp_instance;
struct ast_rtp_glue;
+/*!< RTP Properties that can be set on an RTP instance */
enum ast_rtp_property {
- AST_RTP_PROPERTY_NAT = 0, /*!< Perform symmetric RTP actions */
- AST_RTP_PROPERTY_DTMF, /*!< RTP instance is carrying DTMF */
- AST_RTP_PROPERTY_DTMF_COMPENSATE, /*!< Expect unreliable DTMF from remote party */
- AST_RTP_PROPERTY_STUN, /*!< Use STUN */
- AST_RTP_PROPERTY_RTCP, /*!< Use RTCP */
- AST_RTP_PROPERTY_MAX, /*!< Maximum number of properties supported */
+ /*! Enable symmetric RTP support */
+ AST_RTP_PROPERTY_NAT = 0,
+ /*! RTP instance will be carrying DTMF (using RFC2833) */
+ AST_RTP_PROPERTY_DTMF,
+ /*! Expect unreliable DTMF from remote party */
+ AST_RTP_PROPERTY_DTMF_COMPENSATE,
+ /*! Enable STUN support */
+ AST_RTP_PROPERTY_STUN,
+ /*! Enable RTCP support */
+ AST_RTP_PROPERTY_RTCP,
+ /*! Maximum number of RTP properties supported */
+ AST_RTP_PROPERTY_MAX,
};
+/*!< Additional RTP options */
enum ast_rtp_options {
+ /*! Remote side is using non-standard G.726 */
AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
};
+/*!< Result codes when RTP glue is queried for information */
enum ast_rtp_glue_result {
+ /*! No remote or local bridging is permitted */
AST_RTP_GLUE_RESULT_FORBID = 0,
+ /*! Move RTP stream to be remote between devices directly */
AST_RTP_GLUE_RESULT_REMOTE,
+ /*! Perform RTP engine level bridging if possible */
AST_RTP_GLUE_RESULT_LOCAL,
};
+/*!< Statistics that can be retrieved from an RTP instance */
enum ast_rtp_instance_stat {
+ /*! Retrieve all statistics */
AST_RTP_INSTANCE_STAT_ALL = 0,
+ /*! Retrieve number of packets transmitted */
AST_RTP_INSTANCE_STAT_TXCOUNT,
+ /*! Retrieve number of packets received */
AST_RTP_INSTANCE_STAT_RXCOUNT,
- AST_RTP_INSTANCE_STAT_COMBINED_LOSS, /*!< Special stat which grabs only loss values */
+ /*! Retrieve ALL statistics relating to packet loss */
+ AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
+ /*! Retrieve number of packets lost for transmitting */
AST_RTP_INSTANCE_STAT_TXPLOSS,
+ /*! Retrieve number of packets lost for receiving */
AST_RTP_INSTANCE_STAT_RXPLOSS,
+ /*! Retrieve maximum number of packets lost on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
+ /*! Retrieve minimum number of packets lost on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
+ /*! Retrieve average number of packets lost on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
+ /*! Retrieve standard deviation of packets lost on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
+ /*! Retrieve maximum number of packets lost on local side */
AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
+ /*! Retrieve minimum number of packets lost on local side */
AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
+ /*! Retrieve average number of packets lost on local side */
AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
+ /*! Retrieve standard deviation of packets lost on local side */
AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
- AST_RTP_INSTANCE_STAT_COMBINED_JITTER, /*!< Special stat which grabs only jitter values */
+ /*! Retrieve ALL statistics relating to jitter */
+ AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
+ /*! Retrieve jitter on transmitted packets */
AST_RTP_INSTANCE_STAT_TXJITTER,
+ /*! Retrieve jitter on received packets */
AST_RTP_INSTANCE_STAT_RXJITTER,
+ /*! Retrieve maximum jitter on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
+ /*! Retrieve minimum jitter on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
+ /*! Retrieve average jitter on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
+ /*! Retrieve standard deviation jitter on remote side */
AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
+ /*! Retrieve maximum jitter on local side */
AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
+ /*! Retrieve minimum jitter on local side */
AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
+ /*! Retrieve average jitter on local side */
AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
+ /*! Retrieve standard deviation jitter on local side */
AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
- AST_RTP_INSTANCE_STAT_COMBINED_RTT, /*!< Special stat which grabs only round trip time values */
+ /*! Retrieve ALL statistics relating to round trip time */
+ AST_RTP_INSTANCE_STAT_COMBINED_RTT,
+ /*! Retrieve round trip time */
AST_RTP_INSTANCE_STAT_RTT,
+ /*! Retrieve maximum round trip time */
AST_RTP_INSTANCE_STAT_MAX_RTT,
+ /*! Retrieve minimum round trip time */
AST_RTP_INSTANCE_STAT_MIN_RTT,
+ /*! Retrieve average round trip time */
AST_RTP_INSTANCE_STAT_NORMDEVRTT,
+ /*! Retrieve standard deviation round trip time */
AST_RTP_INSTANCE_STAT_STDEVRTT,
+ /*! Retrieve local SSRC */
AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
+ /*! Retrieve remote SSRC */
AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
};
@@ -100,46 +183,74 @@
/*! Maximum RTP-specific code */
#define AST_RTP_MAX AST_RTP_CISCO_DTMF
+/*!< Structure that represents a payload */
struct ast_rtp_payload_type {
- int isAstFormat; /*!< Is this an Asterisk value? */
- int code; /*!< Actual internal value */
+ /*! Is this an Asterisk value */
+ int isAstFormat;
+ /*! Actual internal value of the payload */
+ int code;
};
+/*!< Structure that represents statistics from an RTP instance */
struct ast_rtp_instance_stats {
- /* Packet count parts */
- unsigned int txcount; /*!< Number of packets transmitted */
- unsigned int rxcount; /*!< Number of packets received */
- /* Jitter parts */
- unsigned int txjitter; /*!< Jitter on transmitted packets */
- unsigned int rxjitter; /*!< Jitter on received packets */
- double remote_maxjitter; /*!< Maximum jitter on remote side */
- double remote_minjitter; /*!< Minimum jitter on remote side */
- double remote_normdevjitter; /*!< Normal deviation jitter on remote side */
- double remote_stdevjitter; /*!< Standard deviation jitter on remote side */
- double local_maxjitter; /*!< Maximum jitter on local side */
- double local_minjitter; /*!< Minimum jitter on local side */
- double local_normdevjitter; /*!< Normal deviation jitter on local side */
- double local_stdevjitter; /*!< Standard deviation jitter on local side */
- /* Packet loss parts */
- unsigned int txploss; /*!< Number of transmitted packets lost */
- unsigned int rxploss; /*!< Number of received packets lost */
- double remote_maxrxploss; /*!< Maximum number of packets lost on remote side */
- double remote_minrxploss; /*!< Minimum number of packets lost on remote side */
- double remote_normdevrxploss; /*!< Normal deviation of packets lost on remote side */
- double remote_stdevrxploss; /*!< Standard deviation of packets lost on remote side */
- double local_maxrxploss; /*!< Maximum number of packets lost on local side */
- double local_minrxploss; /*!< Minimum number of packets lost on local side */
- double local_normdevrxploss; /*!< Normal deviation of packets lost on local side */
- double local_stdevrxploss; /*!< Standard deviation of packets lost on local side */
- /* Round trip time parts */
- unsigned int rtt; /*!< Total round trip time */
- double maxrtt; /*!< Maximum round trip time */
- double minrtt; /*!< Minimum round trip time */
- double normdevrtt; /*!< Normal deviation round trip time */
- double stdevrtt; /*!< Standard deviation round trip time */
- /* Source parts */
- unsigned int local_ssrc; /*!< Our SSRC */
- unsigned int remote_ssrc; /*!< SSRC of the other side */
+ /*! Number of packets transmitted */
+ unsigned int txcount;
+ /*! Number of packets received */
+ unsigned int rxcount;
+ /*! Jitter on transmitted packets */
+ unsigned int txjitter;
+ /*! Jitter on received packets */
+ unsigned int rxjitter;
+ /*! Maximum jitter on remote side */
+ double remote_maxjitter;
+ /*! Minimum jitter on remote side */
+ double remote_minjitter;
+ /*! Average jitter on remote side */
+ double remote_normdevjitter;
+ /*! Standard deviation jitter on remote side */
+ double remote_stdevjitter;
+ /*! Maximum jitter on local side */
+ double local_maxjitter;
+ /*! Minimum jitter on local side */
+ double local_minjitter;
+ /*! Average jitter on local side */
+ double local_normdevjitter;
+ /*! Standard deviation jitter on local side */
+ double local_stdevjitter;
+ /*! Number of transmitted packets lost */
+ unsigned int txploss;
+ /*! Number of received packets lost */
+ unsigned int rxploss;
+ /*! Maximum number of packets lost on remote side */
+ double remote_maxrxploss;
+ /*! Minimum number of packets lost on remote side */
+ double remote_minrxploss;
+ /*! Average number of packets lost on remote side */
+ double remote_normdevrxploss;
+ /*! Standard deviation packets lost on remote side */
+ double remote_stdevrxploss;
+ /*! Maximum number of packets lost on local side */
+ double local_maxrxploss;
+ /*! Minimum number of packets lost on local side */
+ double local_minrxploss;
+ /*! Average number of packets lost on local side */
+ double local_normdevrxploss;
+ /*! Standard deviation packets lost on local side */
+ double local_stdevrxploss;
+ /*! Total round trip time */
+ unsigned int rtt;
+ /*! Maximum round trip time */
+ double maxrtt;
+ /*! Minimum round trip time */
+ double minrtt;
+ /*! Average round trip time */
+ double normdevrtt;
+ /*! Standard deviation round trip time */
+ double stdevrtt;
+ /*! Our SSRC */
+ unsigned int local_ssrc;
+ /*! Their SSRC */
+ unsigned int remote_ssrc;
};
#define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
@@ -155,57 +266,102 @@
return 0; \
}
+/*!< Structure that represents an RTP stack (engine) */
struct ast_rtp_engine {
- const char *name; /*!< Name of the RTP engine */
- struct ast_module *mod; /*!< Module this RTP engine belongs to */
- int (*new)(struct ast_rtp_instance *instance, struct sched_context *sched, struct sockaddr_in *sin); /*!< Callback for creating an RTP instance */
- int (*destroy)(struct ast_rtp_instance *instance); /*!< Callback for destroying an RTP instance */
- int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame); /*!< Callback for writing a frame out */
- void (*stop)(struct ast_rtp_instance *instance); /*!< Callback for stopping the RTP session */
- int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit); /*!< Callback for sending a DTMF digit */
- int (*dtmf_end)(struct ast_rtp_instance *instance, char digit); /*!< Callback for ending a DTMF digit */
- void (*new_source)(struct ast_rtp_instance *instance); /*!< Callback for when a new source of audio has come in */
- void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value); /*!< Callback for when an RTP property is set */
- void (*payload_set)(struct ast_rtp_instance *instance, int payload, int AstFormat, int format); /*!< Callback for when a payload is set */
- void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref); /*!< Callback for setting codec packetization preferences */
- void (*remote_address_set)(struct ast_rtp_instance *instance, struct sockaddr_in *sin); /*!< Callback for when the remote address is set on an RTP instance */
- int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat); /*!< Callback for retrieving statistics about the session */
- int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc); /*!< Callback for setting QoS parameters on the RTP session */
- int (*fd)(struct ast_rtp_instance *instance, int rtcp); /*!< Callback for retrieving a file descriptor for RTP or RTCP */
- int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations); /*!< Callback for initializing RED support */
- int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame); /*!< Callback for buffering a frame over RED */
- struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp); /*!< Callback for reading a frame in */
- int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1); /*!< Locally bridge two RTP instances together */
- AST_RWLIST_ENTRY(ast_rtp_engine) entry; /*!< Linked list information */
+ /*! Name of the RTP engine, used when explicitly requested */
+ const char *name;
+ /*! Module this RTP engine came from, used for reference counting */
+ struct ast_module *mod;
+ /*! Callback for setting up a new RTP instance */
+ int (*new)(struct ast_rtp_instance *instance, struct sched_context *sched, struct sockaddr_in *sin);
+ /*! Callback for destroying an RTP instance */
+ int (*destroy)(struct ast_rtp_instance *instance);
+ /*! Callback for writing out a frame */
+ int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
+ /*! Callback for stopping the RTP instance */
+ void (*stop)(struct ast_rtp_instance *instance);
+ /*! Callback for starting RFC2833 DTMF transmission */
+ int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
+ /*! Callback for stopping RFC2833 DTMF transmission */
+ int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
+ /*! Callback to indicate that a new source of media has come in */
+ void (*new_source)(struct ast_rtp_instance *instance);
+ /*! 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, int format);
+ /*! 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 */
+ void (*remote_address_set)(struct ast_rtp_instance *instance, struct sockaddr_in *sin);
+ /*! Callback for retrieving statistics */
+ int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
+ /*! Callback for setting QoS values */
+ int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
+ /*! Callback for retrieving a file descriptor to poll on, not always required */
+ int (*fd)(struct ast_rtp_instance *instance, int rtcp);
+ /*! Callback for initializing RED support */
+ int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
+ /*! Callback for buffering a frame using RED */
+ int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
+ /*! Callback for reading a frame from the RTP engine */
+ struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
+ /*! Callback to locally bridge two RTP instances */
+ int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
+ /*! Linked list information */
+ AST_RWLIST_ENTRY(ast_rtp_engine) entry;
};
+/*!< Structure that represents codec and packetization information */
struct ast_rtp_codecs {
- struct ast_codec_pref pref; /*!< Codec packetization preferences */
- struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT]; /*!< Payloads present */
+ /*! Codec packetization preferences */
+ struct ast_codec_pref pref;
+ /*! Payloads present */
+ struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT];
};
+/*!< Structure that represents an RTP session (instance) */
struct ast_rtp_instance {
- struct ast_rtp_engine *engine; /*!< Engine handling this RTP session instance */
- void *data; /*!< Unique data for the RTP engine */
- int properties[AST_RTP_PROPERTY_MAX]; /*!< Properties and their values */
- struct sockaddr_in local_address; /*!< The address we are expecting RTP to be received on */
- struct sockaddr_in remote_address; /*!< The address we are sending RTP to */
- struct ast_rtp_instance *bridged; /*!< Who we are directly bridged to */
- struct ast_rtp_codecs codecs; /*!< Codec information */
- int timeout; /*!< RTP timeout time (negative or zero means disabled, negative value means temporarily disabled) */
- int holdtimeout; /*!< RTP timeout when on hold (negative or zero means disabled, negative value means temporarily disabled). */
- int keepalive; /*!< Send RTP comfort noice packets for keepalive */
+ /*! Engine that is handling this RTP instance */
+ struct ast_rtp_engine *engine;
+ /*! Data unique to the RTP engine */
+ void *data;
+ /*! RTP properties that have been set and their value */
+ int properties[AST_RTP_PROPERTY_MAX];
+ /*! Address that we are expecting RTP to come in to */
+ struct sockaddr_in local_address;
+ /*! Address that we are sending RTP to */
+ struct sockaddr_in remote_address;
+ /*! Instance that we are bridged to if doing remote or local bridging */
+ struct ast_rtp_instance *bridged;
+ /*! Payload and packetization information */
+ struct ast_rtp_codecs codecs;
+ /*! RTP timeout time (negative or zero means disabled, negative value means temporarily disabled) */
+ int timeout;
+ /*! RTP timeout when on hold (negative or zero means disabled, negative value means temporarily disabled). */
+ int holdtimeout;
+ /*! Send RTP comfort noice packets for keepalive */
+ int keepalive;
};
+/*!< Structure that represents the glue that binds an RTP instance to a channel */
struct ast_rtp_glue {
+ /*! Name of the channel driver that this glue is responsible for */
const char *type;
+ /*! Module that the RTP glue came from */
struct ast_module *mod;
+ /*! Callback for retrieving the RTP instance carrying audio */
enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
+ /*! Callback for retrieving the RTP instance carrying video */
enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
+ /*! Callback for retrieving the RTP instance caryrying text */
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, int codecs, int nat_active);
+ /*! Callback for retrieving codecs that the channel can do */
int (*get_codec)(struct ast_channel *chan);
- AST_RWLIST_ENTRY(ast_rtp_glue) entry; /*!< Linked list information */
+ /*! Linked list information */
+ AST_RWLIST_ENTRY(ast_rtp_glue) entry;
};
#define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
@@ -217,6 +373,18 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_engine_register2(&example_rtp_engine, NULL);
+ * \endcode
+ *
+ * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
+ * associate a module with it.
+ *
+ * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
+ * associated with the RTP engine and use counting is performed.
*/
int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
@@ -226,6 +394,15 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_engine_unregister(&example_rtp_engine);
+ * \endcode
+ *
+ * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
+ * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
*/
int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
@@ -238,6 +415,18 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_glue_register2(&example_rtp_glue, NULL);
+ * \endcode
+ *
+ * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
+ * associate a module with it.
+ *
+ * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
+ * associated with the RTP glue and use counting is performed.
*/
int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
@@ -247,6 +436,15 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_glue_unregister(&example_rtp_glue);
+ * \endcode
+ *
+ * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
+ * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
*/
int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
@@ -258,6 +456,19 @@
*
* \retval non-NULL success
* \retval NULL failure
+ *
+ * Example usage:
+ *
+ * \code
+ * struct ast_rtp_instance *instance = NULL;
+ * instance = ast_rtp_instance_new(NULL, sched, &sin);
+ * \endcode
+ *
+ * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
+ * in the sin structure.
+ *
+ * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
+ * another depending on it's own configuration.
*/
struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name, struct sched_context *sched, struct sockaddr_in *sin);
@@ -267,6 +478,15 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_destroy(instance);
+ * \endcode
+ *
+ * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
+ * memory and may not be used again.
*/
int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
@@ -276,6 +496,15 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_write(instance, frame);
+ * \endcode
+ *
+ * This gives the frame pointed to by frame to the RTP engine being used for the instance
+ * and asks that it be transmitted to the current remote address set on the RTP instance.
*/
int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
@@ -286,6 +515,15 @@
*
* \retval non-NULL success
* \retval NULL failure
+ *
+ * Example usage:
+ *
+ * \code
+ * struct ast_frame *frame;
+ * frame = ast_rtp_instance_read(instance, 0);
+ * \endcode
+ *
+ * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
*/
struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
@@ -296,10 +534,36 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_set_remote_address(instance, &sin);
+ * \endcode
+ *
+ * This changes the remote address that RTP will be sent to on instance to the address given in the sin
+ * structure.
*/
int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
-/*! \brief Get the address of the remote endpoint that we are sending RTP to */
+/*! \brief Get the address of the remote endpoint that we are sending RTP to
+ *
+ * \param instance The instance that we want to get the remote address for
+ * \param address A structure to put the address into
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * struct sockaddr_in sin;
+ * ast_rtp_instance_get_remote_address(instance, &sin);
+ * \endcode
+ *
+ * This retrieves the current remote address set on the instance pointed to by instance and puts the value
+ * into the sin structure.
+ */
int ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct sockaddr_in *address);
/*! \brief Set the value of an RTP instance property
@@ -307,43 +571,228 @@
* \param instance The RTP instance to set the property on
* \param property The property to modify
* \param value The value to set the property to
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
+ * \endcode
+ *
+ * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
*/
void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
-/*! \brief Clear payload information from an RTP instance */
+/*! \brief Clear payload information from an RTP instance
+ *
+ * \param codecs The codecs structure that payloads will be cleared from
+ * \param instance Optionally the instance that the codecs structure belongs to
+ *
+ * Example usage:
+ *
+ * \code
+ * struct ast_rtp_codecs codecs;
+ * ast_rtp_codecs_payloads_clear(&codecs, NULL);
+ * \endcode
+ *
+ * This clears the codecs structure and puts it into a pristine state.
+ */
void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
-/*! \brief Set payload information on an RTP instance to the default */
+/*! \brief Set payload information on an RTP instance to the default
+ *
+ * \param codecs The codecs structure to set defaults on
+ * \param instance Optionally the instance that the codecs structure belongs to
+ *
+ * Example usage:
+ *
+ * \code
+ * struct ast_rtp_codecs codecs;
+ * ast_rtp_codecs_payloads_default(&codecs, NULL);
+ * \endcode
+ *
+ * This sets the default payloads on the codecs structure.
+ */
void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
-/*! \brief Copy payload information from one RTP instance to another */
+/*! \brief Copy payload information from one RTP instance to another
+ *
+ * \param src The source codecs structure
+ * \param dst The destination codecs structure that the values from src will be copied to
+ * \param instance Optionally the instance that the dst codecs structure belongs to
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
+ * \endcode
+ *
+ * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
+ */
void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
-/*! \brief Record payload information that was seen in an m= SDP line */
+/*! \brief Record payload information that was seen in an m= SDP line
+ *
+ * \param codecs The codecs structure to muck with
+ * \param instance Optionally the instance that the codecs structure belongs to
+ * \param payload Numerical payload that was seen in the m= SDP line
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
+ * \endcode
+ *
+ * This records that the numerical payload '0' was seen in the codecs structure.
+ */
void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
-/*! \brief Record payload information that was seen in an a=rtpmap: SDP line */
+/*! \brief Record payload information that was seen in an a=rtpmap: SDP line
+ *
+ * \param codecs The codecs structure to muck with
+ * \param instance Optionally the instance that the codecs structure belongs to
+ * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
+ * \param mimeType The string mime type that was seen
+ * \param mimeSubtype The strin mime sub type that was seen
+ * \param options Optional options that may change the behavior of this specific payload
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
+ * \endcode
+ *
+ * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
+ */
int ast_rtp_codecs_payloads_set_rtpmap_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload, const char *mimeType, const char *mimeSubtype, enum ast_rtp_options options);
-/*! \brief Remove payload information */
+/*! \brief Remove payload information
+ *
+ * \param codecs The codecs structure to muck with
+ * \param instance Optionally the instance that the codecs structure belongs to
+ * \param payload Numerical payload to unset
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
+ * \endcode
+ *
+ * This clears the payload '0' from the codecs structure. It will be as if it was never set.
+ */
void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
-/*! \brief Retrieve payload information by payload */
+/*! \brief Retrieve payload information by payload
+ *
+ * \param codecs Codecs structure to look in
+ * \param payload Numerical payload to look up
+ *
+ * \retval Payload information
+ *
+ * Example usage:
+ *
+ * \code
+ * struct ast_rtp_payload_type payload_type;
+ * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
+ * \endcode
+ *
+ * This looks up the information for payload '0' from the codecs structure.
+ */
struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
-/*! \brief Retrieve all formats that were found */
+/*! \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 nonAstFormats An integer to put the non-Asterisk formats in
+ *
+ * Example usage:
+ *
+ * \code
+ * int AstFormats, 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
+ * pointed to by AstFormats and the non-Asterisk ones in the integer pointed to by nonAstFormats.
+ */
void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, int *AstFormats, int *nonAstFormats);
-/*! \brief Retrieve a payload based on whether it is an Asterisk format and the code */
+/*! \brief Retrieve a payload based on whether it is an Asterisk format and the code
+ *
+ * \param codecs Codecs structure to look in
+ * \param isAstFormat Non-zero if the given code is an Asterisk format value
+ * \param code The format to look for
+ *
+ * \retval Numerical payload
+ *
+ * Example usage:
+ *
+ * \code
+ * int payload = ast_rtp_codecs_payload_code(&codecs, 1, AST_FORMAT_ULAW);
+ * \endcode
+ *
+ * This looks for the numerical payload for ULAW in the codecs structure.
+ */
int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int isAstFormat, const int code);
-/*! \brief Retrieve mime subtype information on a payload */
+/*! \brief Retrieve mime subtype information on a payload
+ *
+ * \param isAstFormat Non-zero if the given code is an Asterisk format value
+ * \param code Format to look up
+ * \param options Additional options that may change the result
+ *
+ * \retval Mime subtype success
+ * \retval NULL failure
+ *
+ * Example usage:
+ *
+ * \code
+ * const char *subtype = ast_rtp_lookup_mime_subtype(1, AST_FORMAT_ULAW, 0);
+ * \endcode
+ *
+ * This looks up the mime subtype for the ULAW format.
+ */
const char *ast_rtp_lookup_mime_subtype(const int isAstFormat, const int code, enum ast_rtp_options options);
-/*! \brief Convert formats into a string and put them into a buffer */
+/*! \brief Convert formats into a string and put them into a buffer
+ *
+ * \param buf Buffer to put the mime output into
+ * \param size Size of the above buffer
+ * \param capability Formats that we are looking up
+ * \param isAstFormat Non-zero if the given capability are Asterisk format capabilities
+ * \param options Additional options that may change the result
+ *
+ * \retval non-NULL success
+ * \retval NULL failure
+ *
+ * Example usage:
+ *
+ * \code
+ * char buf[256] = "";
+ * char *mime = ast_rtp_lookup_mime_multiple(&buf, sizeof(buf), AST_FORMAT_ULAW | AST_FORMAT_ALAW, 1, 0);
+ * \endcode
+ *
+ * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
+ */
char *ast_rtp_lookup_mime_multiple(char *buf, size_t size, const int capability, const int isAstFormat, enum ast_rtp_options options);
-/*! \brief Set codec packetization preferences */
+/*! \brief Set codec packetization preferences
+ *
+ * \param codecs Codecs structure to muck with
+ * \param instance Optionally the instance that the codecs structure belongs to
+ * \param prefs Codec packetization preferences
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
+ * \endcode
+ *
+ * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
+ */
void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
/*! \brief Begin sending a DTMF digit
@@ -353,6 +802,15 @@
*
* \retval 0 success
* \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_dtmf_begin(instance, '1');
+ * \endcode
+ *
+ * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
+ * continue being sent until it is ended.
*/
int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
@@ -360,36 +818,162 @@
*
* \param instance The RTP instance to stop the DTMF on
* \param digit What DTMF digit to stop
- * \retval 0 success
- * \retval -1 failure
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_dtmf_end(instance, '1');
+ * \endcode
+ *
+ * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
*/
int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
-/*! \brief Indicate a new source of audio has dropped in */
+/*! \brief Indicate a new source of audio has dropped in
+ *
+ * \param instance Instance that the new media source is feeding into
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_new_source(instance);
+ * \endcode
+ *
+ * This indicates that a new source of media is feeding the instance pointed to by
+ * instance.
+ */
void ast_rtp_instance_new_source(struct ast_rtp_instance *instance);
-/*! \brief Set QoS parameters on an RTP session */
+/*! \brief Set QoS parameters on an RTP session
+ *
+ * \param instance Instance to set the QoS parameters on
+ * \param tos Terms of service value
+ * \param cos Class of service value
+ * \param desc What is setting the QoS values
+ *
+ * \retval 0 success
+ * \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
+ * \endcode
+ *
+ * This sets the TOS and COS values to 0 on the instance pointed to by instance.
+ */
int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
-/*! \brief Stop an RTP instance */
+/*! \brief Stop an RTP instance
+ *
+ * \param instance Instance that media is no longer going to at this time
+ *
+ * Example usage:
+ *
+ * \code
+ * ast_rtp_instance_stop(instance);
+ * \endcode
+ *
+ * This tells the RTP engine being used for the instance pointed to by instance
+ * that media is no longer going to it at this time, but may in the future.
+ */
void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
-/*! \brief Get the file descriptor for an RTP session (or RTCP) */
+/*! \brief Get the file descriptor for an RTP session (or RTCP)
+ *
+ * \param instance Instance to get the file descriptor for
+ * \param rtcp Whether to retrieve the file descriptor for RTCP or not
+ *
+ * \retval fd success
+ * \retval -1 failure
+ *
+ * Example usage:
+ *
+ * \code
+ * int rtp_fd = ast_rtp_instance_fd(instance, 0);
+ * \endcode
+ *
+ * This retrieves the file descriptor for the socket carrying media on the instance
+ * pointed to by instance.
+ */
int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
-/*! \brief Get the RTP glue that binds a channel to the RTP engine */
[... 81 lines stripped ...]
More information about the svn-commits
mailing list