Thu Sep 7 01:03:04 2017

Asterisk developer's documentation


rtp_engine.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2009, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  * Joshua Colp <jcolp@digium.com>
00008  *
00009  * See http://www.asterisk.org for more information about
00010  * the Asterisk project. Please do not directly contact
00011  * any of the maintainers of this project for assistance;
00012  * the project provides a web site, mailing lists and IRC
00013  * channels for your use.
00014  *
00015  * This program is free software, distributed under the terms of
00016  * the GNU General Public License Version 2. See the LICENSE file
00017  * at the top of the source tree.
00018  */
00019 
00020 /*! \file
00021  * \brief Pluggable RTP Architecture
00022  * \author Joshua Colp <jcolp@digium.com>
00023  * \ref AstRTPEngine
00024  */
00025 
00026 /*!
00027  * \page AstRTPEngine Asterisk RTP Engine API
00028  *
00029  * The purpose of this API is to provide a way for multiple RTP stacks to be
00030  * used inside of Asterisk without any module that uses RTP knowing any
00031  * different. To the module each RTP stack behaves the same.
00032  *
00033  * An RTP session is called an instance and is made up of a combination of codec
00034  * information, RTP engine, RTP properties, and address information. An engine
00035  * name may be passed in to explicitly choose an RTP stack to be used but a
00036  * default one will be used if none is provided. An address to use for RTP may
00037  * also be provided but the underlying RTP engine may choose a different address
00038  * depending on it's configuration.
00039  *
00040  * An RTP engine is the layer between the RTP engine core and the RTP stack
00041  * itself. The RTP engine core provides a set of callbacks to do various things
00042  * (such as write audio out) that the RTP engine has to have implemented.
00043  *
00044  * Glue is what binds an RTP instance to a channel. It is used to retrieve RTP
00045  * instance information when performing remote or local bridging and is used to
00046  * have the channel driver tell the remote side to change destination of the RTP
00047  * stream.
00048  *
00049  * Statistics from an RTP instance can be retrieved using the
00050  * ast_rtp_instance_get_stats API call. This essentially asks the RTP engine in
00051  * use to fill in a structure with the requested values. It is not required for
00052  * an RTP engine to support all statistic values.
00053  *
00054  * Properties allow behavior of the RTP engine and RTP engine core to be
00055  * changed. For example, there is a property named AST_RTP_PROPERTY_NAT which is
00056  * used to tell the RTP engine to enable symmetric RTP if it supports it. It is
00057  * not required for an RTP engine to support all properties.
00058  *
00059  * Codec information is stored using a separate data structure which has it's
00060  * own set of API calls to add/remove/retrieve information. They are used by the
00061  * module after an RTP instance is created so that payload information is
00062  * available for the RTP engine.
00063  */
00064 
00065 #ifndef _ASTERISK_RTP_ENGINE_H
00066 #define _ASTERISK_RTP_ENGINE_H
00067 
00068 #if defined(__cplusplus) || defined(c_plusplus)
00069 extern "C" {
00070 #endif
00071 
00072 #include "asterisk/astobj2.h"
00073 #include "asterisk/frame.h"
00074 #include "asterisk/netsock2.h"
00075 #include "asterisk/sched.h"
00076 #include "asterisk/res_srtp.h"
00077 
00078 /* Maximum number of payloads supported */
00079 #define AST_RTP_MAX_PT 256
00080 
00081 /* Maximum number of generations */
00082 #define AST_RED_MAX_GENERATION 5
00083 
00084 struct ast_rtp_instance;
00085 struct ast_rtp_glue;
00086 
00087 /*! RTP Properties that can be set on an RTP instance */
00088 enum ast_rtp_property {
00089    /*! Enable symmetric RTP support */
00090    AST_RTP_PROPERTY_NAT = 0,
00091    /*! RTP instance will be carrying DTMF (using RFC2833) */
00092    AST_RTP_PROPERTY_DTMF,
00093    /*! Expect unreliable DTMF from remote party */
00094    AST_RTP_PROPERTY_DTMF_COMPENSATE,
00095    /*! Enable STUN support */
00096    AST_RTP_PROPERTY_STUN,
00097    /*! Enable RTCP support */
00098    AST_RTP_PROPERTY_RTCP,
00099 
00100    /*!
00101     * \brief Maximum number of RTP properties supported
00102     *
00103     * \note THIS MUST BE THE LAST ENTRY IN THIS ENUM.
00104     */
00105    AST_RTP_PROPERTY_MAX,
00106 };
00107 
00108 /*! Additional RTP options */
00109 enum ast_rtp_options {
00110    /*! Remote side is using non-standard G.726 */
00111    AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
00112 };
00113 
00114 /*! RTP DTMF Modes */
00115 enum ast_rtp_dtmf_mode {
00116    /*! No DTMF is being carried over the RTP stream */
00117    AST_RTP_DTMF_MODE_NONE = 0,
00118    /*! DTMF is being carried out of band using RFC2833 */
00119    AST_RTP_DTMF_MODE_RFC2833,
00120    /*! DTMF is being carried inband over the RTP stream */
00121    AST_RTP_DTMF_MODE_INBAND,
00122 };
00123 
00124 /*! Result codes when RTP glue is queried for information */
00125 enum ast_rtp_glue_result {
00126    /*! No remote or local bridging is permitted */
00127    AST_RTP_GLUE_RESULT_FORBID = 0,
00128    /*! Move RTP stream to be remote between devices directly */
00129    AST_RTP_GLUE_RESULT_REMOTE,
00130    /*! Perform RTP engine level bridging if possible */
00131    AST_RTP_GLUE_RESULT_LOCAL,
00132 };
00133 
00134 /*! Field statistics that can be retrieved from an RTP instance */
00135 enum ast_rtp_instance_stat_field {
00136    /*! Retrieve quality information */
00137    AST_RTP_INSTANCE_STAT_FIELD_QUALITY = 0,
00138    /*! Retrieve quality information about jitter */
00139    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_JITTER,
00140    /*! Retrieve quality information about packet loss */
00141    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_LOSS,
00142    /*! Retrieve quality information about round trip time */
00143    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_RTT,
00144 };
00145 
00146 /*! Statistics that can be retrieved from an RTP instance */
00147 enum ast_rtp_instance_stat {
00148    /*! Retrieve all statistics */
00149    AST_RTP_INSTANCE_STAT_ALL = 0,
00150    /*! Retrieve number of packets transmitted */
00151    AST_RTP_INSTANCE_STAT_TXCOUNT,
00152    /*! Retrieve number of packets received */
00153    AST_RTP_INSTANCE_STAT_RXCOUNT,
00154    /*! Retrieve ALL statistics relating to packet loss */
00155    AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
00156    /*! Retrieve number of packets lost for transmitting */
00157    AST_RTP_INSTANCE_STAT_TXPLOSS,
00158    /*! Retrieve number of packets lost for receiving */
00159    AST_RTP_INSTANCE_STAT_RXPLOSS,
00160    /*! Retrieve maximum number of packets lost on remote side */
00161    AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
00162    /*! Retrieve minimum number of packets lost on remote side */
00163    AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
00164    /*! Retrieve average number of packets lost on remote side */
00165    AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
00166    /*! Retrieve standard deviation of packets lost on remote side */
00167    AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
00168    /*! Retrieve maximum number of packets lost on local side */
00169    AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
00170    /*! Retrieve minimum number of packets lost on local side */
00171    AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
00172    /*! Retrieve average number of packets lost on local side */
00173    AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
00174    /*! Retrieve standard deviation of packets lost on local side */
00175    AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
00176    /*! Retrieve ALL statistics relating to jitter */
00177    AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
00178    /*! Retrieve jitter on transmitted packets */
00179    AST_RTP_INSTANCE_STAT_TXJITTER,
00180    /*! Retrieve jitter on received packets */
00181    AST_RTP_INSTANCE_STAT_RXJITTER,
00182    /*! Retrieve maximum jitter on remote side */
00183    AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
00184    /*! Retrieve minimum jitter on remote side */
00185    AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
00186    /*! Retrieve average jitter on remote side */
00187    AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
00188    /*! Retrieve standard deviation jitter on remote side */
00189    AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
00190    /*! Retrieve maximum jitter on local side */
00191    AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
00192    /*! Retrieve minimum jitter on local side */
00193    AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
00194    /*! Retrieve average jitter on local side */
00195    AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
00196    /*! Retrieve standard deviation jitter on local side */
00197    AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
00198    /*! Retrieve ALL statistics relating to round trip time */
00199    AST_RTP_INSTANCE_STAT_COMBINED_RTT,
00200    /*! Retrieve round trip time */
00201    AST_RTP_INSTANCE_STAT_RTT,
00202    /*! Retrieve maximum round trip time */
00203    AST_RTP_INSTANCE_STAT_MAX_RTT,
00204    /*! Retrieve minimum round trip time */
00205    AST_RTP_INSTANCE_STAT_MIN_RTT,
00206    /*! Retrieve average round trip time */
00207    AST_RTP_INSTANCE_STAT_NORMDEVRTT,
00208    /*! Retrieve standard deviation round trip time */
00209    AST_RTP_INSTANCE_STAT_STDEVRTT,
00210    /*! Retrieve local SSRC */
00211    AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
00212    /*! Retrieve remote SSRC */
00213    AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
00214 };
00215 
00216 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
00217 /*! DTMF (RFC2833) */
00218 #define AST_RTP_DTMF                    (1 << 0)
00219 /*! 'Comfort Noise' (RFC3389) */
00220 #define AST_RTP_CN                      (1 << 1)
00221 /*! DTMF (Cisco Proprietary) */
00222 #define AST_RTP_CISCO_DTMF              (1 << 2)
00223 /*! Maximum RTP-specific code */
00224 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
00225 
00226 /*! Structure that represents a payload */
00227 struct ast_rtp_payload_type {
00228    /*! Is this an Asterisk value */
00229    int asterisk_format;
00230    /*! Actual internal value of the payload */
00231    format_t code;
00232 };
00233 
00234 /*! Structure that represents statistics from an RTP instance */
00235 struct ast_rtp_instance_stats {
00236    /*! Number of packets transmitted */
00237    unsigned int txcount;
00238    /*! Number of packets received */
00239    unsigned int rxcount;
00240    /*! Jitter on transmitted packets */
00241    double txjitter;
00242    /*! Jitter on received packets */
00243    double rxjitter;
00244    /*! Maximum jitter on remote side */
00245    double remote_maxjitter;
00246    /*! Minimum jitter on remote side */
00247    double remote_minjitter;
00248    /*! Average jitter on remote side */
00249    double remote_normdevjitter;
00250    /*! Standard deviation jitter on remote side */
00251    double remote_stdevjitter;
00252    /*! Maximum jitter on local side */
00253    double local_maxjitter;
00254    /*! Minimum jitter on local side */
00255    double local_minjitter;
00256    /*! Average jitter on local side */
00257    double local_normdevjitter;
00258    /*! Standard deviation jitter on local side */
00259    double local_stdevjitter;
00260    /*! Number of transmitted packets lost */
00261    unsigned int txploss;
00262    /*! Number of received packets lost */
00263    unsigned int rxploss;
00264    /*! Maximum number of packets lost on remote side */
00265    double remote_maxrxploss;
00266    /*! Minimum number of packets lost on remote side */
00267    double remote_minrxploss;
00268    /*! Average number of packets lost on remote side */
00269    double remote_normdevrxploss;
00270    /*! Standard deviation packets lost on remote side */
00271    double remote_stdevrxploss;
00272    /*! Maximum number of packets lost on local side */
00273    double local_maxrxploss;
00274    /*! Minimum number of packets lost on local side */
00275    double local_minrxploss;
00276    /*! Average number of packets lost on local side */
00277    double local_normdevrxploss;
00278    /*! Standard deviation packets lost on local side */
00279    double local_stdevrxploss;
00280    /*! Total round trip time */
00281    double rtt;
00282    /*! Maximum round trip time */
00283    double maxrtt;
00284    /*! Minimum round trip time */
00285    double minrtt;
00286    /*! Average round trip time */
00287    double normdevrtt;
00288    /*! Standard deviation round trip time */
00289    double stdevrtt;
00290    /*! Our SSRC */
00291    unsigned int local_ssrc;
00292    /*! Their SSRC */
00293    unsigned int remote_ssrc;
00294 };
00295 
00296 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
00297 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
00298 placement = value; \
00299 if (stat == current_stat) { \
00300 return 0; \
00301 } \
00302 }
00303 
00304 #define AST_RTP_STAT_TERMINATOR(combined) \
00305 if (stat == combined) { \
00306 return 0; \
00307 }
00308 
00309 /*! Structure that represents an RTP stack (engine) */
00310 struct ast_rtp_engine {
00311    /*! Name of the RTP engine, used when explicitly requested */
00312    const char *name;
00313    /*! Module this RTP engine came from, used for reference counting */
00314    struct ast_module *mod;
00315    /*! Callback for setting up a new RTP instance */
00316    int (*new)(struct ast_rtp_instance *instance, struct sched_context *sched, struct ast_sockaddr *sa, void *data);
00317    /*! Callback for destroying an RTP instance */
00318    int (*destroy)(struct ast_rtp_instance *instance);
00319    /*! Callback for writing out a frame */
00320    int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
00321    /*! Callback for stopping the RTP instance */
00322    void (*stop)(struct ast_rtp_instance *instance);
00323    /*! Callback for starting RFC2833 DTMF transmission */
00324    int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
00325    /*! Callback for stopping RFC2833 DTMF transmission */
00326    int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
00327    int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
00328    /*! Callback to indicate that we should update the marker bit */
00329    void (*update_source)(struct ast_rtp_instance *instance);
00330    /*! Callback to indicate that we should update the marker bit and ssrc */
00331    void (*change_source)(struct ast_rtp_instance *instance);
00332    /*! Callback for setting an extended RTP property */
00333    int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
00334    /*! Callback for getting an extended RTP property */
00335    void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
00336    /*! Callback for setting an RTP property */
00337    void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
00338    /*! Callback for setting a payload */
00339    void (*payload_set)(struct ast_rtp_instance *instance, int payload, int astformat, format_t format);
00340    /*! Callback for setting packetization preferences */
00341    void (*packetization_set)(struct ast_rtp_instance *instance, struct ast_codec_pref *pref);
00342    /*! Callback for setting the remote address that RTP is to be sent to */
00343    void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
00344    /*! Callback for setting an alternate remote address */
00345    void (*alt_remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
00346    /*! Callback for changing DTMF mode */
00347    int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
00348    /*! Callback for getting DTMF mode */
00349    enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
00350    /*! Callback for retrieving statistics */
00351    int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
00352    /*! Callback for setting QoS values */
00353    int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
00354    /*! Callback for retrieving a file descriptor to poll on, not always required */
00355    int (*fd)(struct ast_rtp_instance *instance, int rtcp);
00356    /*! Callback for initializing RED support */
00357    int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
00358    /*! Callback for buffering a frame using RED */
00359    int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
00360    /*! Callback for reading a frame from the RTP engine */
00361    struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
00362    /*! Callback to locally bridge two RTP instances */
00363    int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
00364    /*! Callback to set the read format */
00365    int (*set_read_format)(struct ast_rtp_instance *instance, format_t format);
00366    /*! Callback to set the write format */
00367    int (*set_write_format)(struct ast_rtp_instance *instance, format_t format);
00368    /*! Callback to make two instances compatible */
00369    int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
00370    /*! Callback to see if two instances are compatible with DTMF */
00371    int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
00372    /*! Callback to indicate that packets will now flow */
00373    int (*activate)(struct ast_rtp_instance *instance);
00374    /*! Callback to request that the RTP engine send a STUN BIND request */
00375    void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
00376    /*! Callback to get the transcodeable formats supported */
00377    format_t (*available_formats)(struct ast_rtp_instance *instance, format_t to_endpoint, format_t to_asterisk);
00378    /*! Callback to send CNG */
00379    int (*sendcng)(struct ast_rtp_instance *instance, int level);
00380    /*! Linked list information */
00381    AST_RWLIST_ENTRY(ast_rtp_engine) entry;
00382 };
00383 
00384 /*! Structure that represents codec and packetization information */
00385 struct ast_rtp_codecs {
00386    /*! Codec packetization preferences */
00387    struct ast_codec_pref pref;
00388    /*! Payloads present */
00389    struct ast_rtp_payload_type payloads[AST_RTP_MAX_PT];
00390 };
00391 
00392 /*! Structure that represents the glue that binds an RTP instance to a channel */
00393 struct ast_rtp_glue {
00394    /*! Name of the channel driver that this glue is responsible for */
00395    const char *type;
00396    /*! Module that the RTP glue came from */
00397    struct ast_module *mod;
00398    /*!
00399     * \brief Callback for retrieving the RTP instance carrying audio
00400     * \note This function increases the reference count on the returned RTP instance.
00401     */
00402    enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00403    /*!
00404     * \brief Callback for retrieving the RTP instance carrying video
00405     * \note This function increases the reference count on the returned RTP instance.
00406     */
00407    enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00408    /*!
00409     * \brief Callback for retrieving the RTP instance carrying text
00410     * \note This function increases the reference count on the returned RTP instance.
00411     */
00412    enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00413    /*! Callback for updating the destination that the remote side should send RTP to */
00414    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);
00415    /*! Callback for retrieving codecs that the channel can do
00416     * \note chan will be locked when this function is called
00417     */
00418    format_t (*get_codec)(struct ast_channel *chan);
00419    /*! Linked list information */
00420    AST_RWLIST_ENTRY(ast_rtp_glue) entry;
00421 };
00422 
00423 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
00424 
00425 /*!
00426  * \brief Register an RTP engine
00427  *
00428  * \param engine Structure of the RTP engine to register
00429  * \param module Module that the RTP engine is part of
00430  *
00431  * \retval 0 success
00432  * \retval -1 failure
00433  *
00434  * Example usage:
00435  *
00436  * \code
00437  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
00438  * \endcode
00439  *
00440  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
00441  * associate a module with it.
00442  *
00443  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
00444  *       associated with the RTP engine and use counting is performed.
00445  *
00446  * \since 1.8
00447  */
00448 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
00449 
00450 /*!
00451  * \brief Unregister an RTP engine
00452  *
00453  * \param engine Structure of the RTP engine to unregister
00454  *
00455  * \retval 0 success
00456  * \retval -1 failure
00457  *
00458  * Example usage:
00459  *
00460  * \code
00461  * ast_rtp_engine_unregister(&example_rtp_engine);
00462  * \endcode
00463  *
00464  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
00465  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
00466  *
00467  * \since 1.8
00468  */
00469 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
00470 
00471 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
00472 
00473 void ast_rtp_engine_unregister_srtp(void);
00474 int ast_rtp_engine_srtp_is_registered(void);
00475 
00476 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
00477 
00478 /*!
00479  * \brief Register RTP glue
00480  *
00481  * \param glue The glue to register
00482  * \param module Module that the RTP glue is part of
00483  *
00484  * \retval 0 success
00485  * \retval -1 failure
00486  *
00487  * Example usage:
00488  *
00489  * \code
00490  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
00491  * \endcode
00492  *
00493  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
00494  * associate a module with it.
00495  *
00496  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
00497  *       associated with the RTP glue and use counting is performed.
00498  *
00499  * \since 1.8
00500  */
00501 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
00502 
00503 /*!
00504  * \brief Unregister RTP glue
00505  *
00506  * \param glue The glue to unregister
00507  *
00508  * \retval 0 success
00509  * \retval -1 failure
00510  *
00511  * Example usage:
00512  *
00513  * \code
00514  * ast_rtp_glue_unregister(&example_rtp_glue);
00515  * \endcode
00516  *
00517  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
00518  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
00519  *
00520  * \since 1.8
00521  */
00522 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
00523 
00524 /*!
00525  * \brief Create a new RTP instance
00526  *
00527  * \param engine_name Name of the engine to use for the RTP instance
00528  * \param sched Scheduler context that the RTP engine may want to use
00529  * \param sa Address we want to bind to
00530  * \param data Unique data for the engine
00531  *
00532  * \retval non-NULL success
00533  * \retval NULL failure
00534  *
00535  * Example usage:
00536  *
00537  * \code
00538  * struct ast_rtp_instance *instance = NULL;
00539  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
00540  * \endcode
00541  *
00542  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
00543  * in the address structure.
00544  *
00545  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
00546  *       another depending on it's own configuration.
00547  *
00548  * \since 1.8
00549  */
00550 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
00551                 struct sched_context *sched, const struct ast_sockaddr *sa,
00552                 void *data);
00553 
00554 /*!
00555  * \brief Destroy an RTP instance
00556  *
00557  * \param instance The RTP instance to destroy
00558  *
00559  * \retval 0 success
00560  * \retval -1 failure
00561  *
00562  * Example usage:
00563  *
00564  * \code
00565  * ast_rtp_instance_destroy(instance);
00566  * \endcode
00567  *
00568  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
00569  * memory and may not be used again.
00570  *
00571  * \since 1.8
00572  */
00573 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
00574 
00575 /*!
00576  * \brief Set the data portion of an RTP instance
00577  *
00578  * \param instance The RTP instance to manipulate
00579  * \param data Pointer to data
00580  *
00581  * Example usage:
00582  *
00583  * \code
00584  * ast_rtp_instance_set_data(instance, blob);
00585  * \endcode
00586  *
00587  * This sets the data pointer on the RTP instance pointed to by 'instance' to
00588  * blob.
00589  *
00590  * \since 1.8
00591  */
00592 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
00593 
00594 /*!
00595  * \brief Get the data portion of an RTP instance
00596  *
00597  * \param instance The RTP instance we want the data portion from
00598  *
00599  * Example usage:
00600  *
00601  * \code
00602  * struct *blob = ast_rtp_instance_get_data(instance);
00603  ( \endcode
00604  *
00605  * This gets the data pointer on the RTP instance pointed to by 'instance'.
00606  *
00607  * \since 1.8
00608  */
00609 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
00610 
00611 /*!
00612  * \brief Send a frame out over RTP
00613  *
00614  * \param instance The RTP instance to send frame out on
00615  * \param frame the frame to send out
00616  *
00617  * \retval 0 success
00618  * \retval -1 failure
00619  *
00620  * Example usage:
00621  *
00622  * \code
00623  * ast_rtp_instance_write(instance, frame);
00624  * \endcode
00625  *
00626  * This gives the frame pointed to by frame to the RTP engine being used for the instance
00627  * and asks that it be transmitted to the current remote address set on the RTP instance.
00628  *
00629  * \since 1.8
00630  */
00631 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
00632 
00633 /*!
00634  * \brief Receive a frame over RTP
00635  *
00636  * \param instance The RTP instance to receive frame on
00637  * \param rtcp Whether to read in RTCP or not
00638  *
00639  * \retval non-NULL success
00640  * \retval NULL failure
00641  *
00642  * Example usage:
00643  *
00644  * \code
00645  * struct ast_frame *frame;
00646  * frame = ast_rtp_instance_read(instance, 0);
00647  * \endcode
00648  *
00649  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
00650  *
00651  * \since 1.8
00652  */
00653 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
00654 
00655 /*!
00656  * \brief Set the address of the remote endpoint that we are sending RTP to
00657  *
00658  * \param instance The RTP instance to change the address on
00659  * \param address Address to set it to
00660  *
00661  * \retval 0 success
00662  * \retval -1 failure
00663  *
00664  * Example usage:
00665  *
00666  * \code
00667  * ast_rtp_instance_set_remote_address(instance, &sin);
00668  * \endcode
00669  *
00670  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
00671  * structure.
00672  *
00673  * \since 1.8
00674  */
00675 int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
00676 
00677 
00678 /*!
00679  * \brief Set the address of an an alternate RTP address to receive from
00680  *
00681  * \param instance The RTP instance to change the address on
00682  * \param address Address to set it to
00683  *
00684  * \retval 0 success
00685  * \retval -1 failure
00686  *
00687  * Example usage:
00688  *
00689  * \code
00690  * ast_rtp_instance_set_alt_remote_address(instance, &address);
00691  * \endcode
00692  *
00693  * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin
00694  * structure.
00695  *
00696  * \since 1.8
00697  */
00698 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address);
00699 
00700 /*!
00701  * \brief Set the address that we are expecting to receive RTP on
00702  *
00703  * \param instance The RTP instance to change the address on
00704  * \param address Address to set it to
00705  *
00706  * \retval 0 success
00707  * \retval -1 failure
00708  *
00709  * Example usage:
00710  *
00711  * \code
00712  * ast_rtp_instance_set_local_address(instance, &sin);
00713  * \endcode
00714  *
00715  * This changes the local address that RTP is expected on to the address given in the sin
00716  * structure.
00717  *
00718  * \since 1.8
00719  */
00720 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
00721                 const struct ast_sockaddr *address);
00722 
00723 /*!
00724  * \brief Get the local address that we are expecting RTP on
00725  *
00726  * \param instance The RTP instance to get the address from
00727  * \param address The variable to store the address in
00728  *
00729  * Example usage:
00730  *
00731  * \code
00732  * struct ast_sockaddr address;
00733  * ast_rtp_instance_get_local_address(instance, &address);
00734  * \endcode
00735  *
00736  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
00737  *
00738  * \since 1.8
00739  */
00740 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00741 
00742 /*!
00743  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
00744  *
00745  * \param instance The instance that we want to get the local address for
00746  * \param address An initialized address that may be overwritten if the local address is different
00747  *
00748  * \retval 0 address was not changed
00749  * \retval 1 address was changed
00750  * Example usage:
00751  *
00752  * \code
00753  * struct ast_sockaddr address;
00754  * int ret;
00755  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
00756  * \endcode
00757  *
00758  * This retrieves the current local address set on the instance pointed to by instance and puts the value
00759  * into the address structure.
00760  *
00761  * \since 1.8
00762  */
00763 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00764 
00765 /*!
00766  * \brief Get the address of the remote endpoint that we are sending RTP to
00767  *
00768  * \param instance The instance that we want to get the remote address for
00769  * \param address A structure to put the address into
00770  *
00771  * Example usage:
00772  *
00773  * \code
00774  * struct ast_sockaddr address;
00775  * ast_rtp_instance_get_remote_address(instance, &address);
00776  * \endcode
00777  *
00778  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
00779  * into the address structure.
00780  *
00781  * \since 1.8
00782  */
00783 void ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00784 
00785 /*!
00786  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
00787  *
00788  * \param instance The instance that we want to get the remote address for
00789  * \param address An initialized address that may be overwritten if the remote address is different
00790  *
00791  * \retval 0 address was not changed
00792  * \retval 1 address was changed
00793  * Example usage:
00794  *
00795  * \code
00796  * struct ast_sockaddr address;
00797  * int ret;
00798  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
00799  * \endcode
00800  *
00801  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
00802  * into the address structure.
00803  *
00804  * \since 1.8
00805  */
00806 
00807 int ast_rtp_instance_get_and_cmp_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00808 
00809 /*!
00810  * \brief Set the value of an RTP instance extended property
00811  *
00812  * \param instance The RTP instance to set the extended property on
00813  * \param property The extended property to set
00814  * \param value The value to set the extended property to
00815  *
00816  * \since 1.8
00817  */
00818 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
00819 
00820 /*!
00821  * \brief Get the value of an RTP instance extended property
00822  *
00823  * \param instance The RTP instance to get the extended property on
00824  * \param property The extended property to get
00825  *
00826  * \since 1.8
00827  */
00828 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
00829 
00830 /*!
00831  * \brief Set the value of an RTP instance property
00832  *
00833  * \param instance The RTP instance to set the property on
00834  * \param property The property to modify
00835  * \param value The value to set the property to
00836  *
00837  * Example usage:
00838  *
00839  * \code
00840  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
00841  * \endcode
00842  *
00843  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
00844  *
00845  * \since 1.8
00846  */
00847 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
00848 
00849 /*!
00850  * \brief Get the value of an RTP instance property
00851  *
00852  * \param instance The RTP instance to get the property from
00853  * \param property The property to get
00854  *
00855  * \retval Current value of the property
00856  *
00857  * Example usage:
00858  *
00859  * \code
00860  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
00861  * \endcode
00862  *
00863  * This returns the current value of the NAT property on the instance pointed to by instance.
00864  *
00865  * \since 1.8
00866  */
00867 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
00868 
00869 /*!
00870  * \brief Get the codecs structure of an RTP instance
00871  *
00872  * \param instance The RTP instance to get the codecs structure from
00873  *
00874  * Example usage:
00875  *
00876  * \code
00877  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
00878  * \endcode
00879  *
00880  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
00881  *
00882  * \since 1.8
00883  */
00884 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
00885 
00886 /*!
00887  * \brief Clear payload information from an RTP instance
00888  *
00889  * \param codecs The codecs structure that payloads will be cleared from
00890  * \param instance Optionally the instance that the codecs structure belongs to
00891  *
00892  * Example usage:
00893  *
00894  * \code
00895  * struct ast_rtp_codecs codecs;
00896  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
00897  * \endcode
00898  *
00899  * This clears the codecs structure and puts it into a pristine state.
00900  *
00901  * \since 1.8
00902  */
00903 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
00904 
00905 /*!
00906  * \brief Set payload information on an RTP instance to the default
00907  *
00908  * \param codecs The codecs structure to set defaults on
00909  * \param instance Optionally the instance that the codecs structure belongs to
00910  *
00911  * Example usage:
00912  *
00913  * \code
00914  * struct ast_rtp_codecs codecs;
00915  * ast_rtp_codecs_payloads_default(&codecs, NULL);
00916  * \endcode
00917  *
00918  * This sets the default payloads on the codecs structure.
00919  *
00920  * \since 1.8
00921  */
00922 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
00923 
00924 /*!
00925  * \brief Copy payload information from one RTP instance to another
00926  *
00927  * \param src The source codecs structure
00928  * \param dest The destination codecs structure that the values from src will be copied to
00929  * \param instance Optionally the instance that the dst codecs structure belongs to
00930  *
00931  * Example usage:
00932  *
00933  * \code
00934  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
00935  * \endcode
00936  *
00937  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
00938  *
00939  * \since 1.8
00940  */
00941 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
00942 
00943 /*!
00944  * \brief Record payload information that was seen in an m= SDP line
00945  *
00946  * \param codecs The codecs structure to muck with
00947  * \param instance Optionally the instance that the codecs structure belongs to
00948  * \param payload Numerical payload that was seen in the m= SDP line
00949  *
00950  * Example usage:
00951  *
00952  * \code
00953  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
00954  * \endcode
00955  *
00956  * This records that the numerical payload '0' was seen in the codecs structure.
00957  *
00958  * \since 1.8
00959  */
00960 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
00961 
00962 /*!
00963  * \brief Record payload information that was seen in an a=rtpmap: SDP line
00964  *
00965  * \param codecs The codecs structure to muck with
00966  * \param instance Optionally the instance that the codecs structure belongs to
00967  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
00968  * \param mimetype The string mime type that was seen
00969  * \param mimesubtype The strin mime sub type that was seen
00970  * \param options Optional options that may change the behavior of this specific payload
00971  *
00972  * \retval 0 success
00973  * \retval -1 failure, invalid payload numbe
00974  * \retval -2 failure, unknown mimetype
00975  *
00976  * Example usage:
00977  *
00978  * \code
00979  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
00980  * \endcode
00981  *
00982  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
00983  *
00984  * \since 1.8
00985  */
00986 int ast_rtp_codecs_payloads_set_rtpmap_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload, char *mimetype, char *mimesubtype, enum ast_rtp_options options);
00987 
00988 /*!
00989  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
00990  *
00991  * \param codecs RTP structure to modify
00992  * \param instance Optionally the instance that the codecs structure belongs to
00993  * \param pt Payload type entry to modify
00994  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
00995  * \param mimesubtype MIME subtype of media stream (typically a codec name)
00996  * \param options Zero or more flags from the ast_rtp_options enum
00997  * \param sample_rate The sample rate of the media stream
00998  *
00999  * This function 'fills in' an entry in the list of possible formats for
01000  * a media stream associated with an RTP structure.
01001  *
01002  * \retval 0 on success
01003  * \retval -1 if the payload type is out of range
01004  * \retval -2 if the mimeType/mimeSubtype combination was not found
01005  *
01006  * \since 1.8
01007  */
01008 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
01009               char *mimetype, char *mimesubtype,
01010               enum ast_rtp_options options,
01011               unsigned int sample_rate);
01012 
01013 /*!
01014  * \brief Remove payload information
01015  *
01016  * \param codecs The codecs structure to muck with
01017  * \param instance Optionally the instance that the codecs structure belongs to
01018  * \param payload Numerical payload to unset
01019  *
01020  * Example usage:
01021  *
01022  * \code
01023  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
01024  * \endcode
01025  *
01026  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
01027  *
01028  * \since 1.8
01029  */
01030 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
01031 
01032 /*!
01033  * \brief Retrieve payload information by payload
01034  *
01035  * \param codecs Codecs structure to look in
01036  * \param payload Numerical payload to look up
01037  *
01038  * \retval Payload information
01039  *
01040  * Example usage:
01041  *
01042  * \code
01043  * struct ast_rtp_payload_type payload_type;
01044  * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0);
01045  * \endcode
01046  *
01047  * This looks up the information for payload '0' from the codecs structure.
01048  *
01049  * \since 1.8
01050  */
01051 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload);
01052 
01053 /*!
01054  * \brief Get the sample rate associated with known RTP payload types
01055  *
01056  * \param asterisk_format True if the value in the 'code' parameter is an AST_FORMAT value
01057  * \param code Format code, either from AST_FORMAT list or from AST_RTP list
01058  *
01059  * \return the sample rate if the format was found, zero if it was not found
01060  *
01061  * \since 1.8
01062  */
01063 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, format_t code);
01064 
01065 /*!
01066  * \brief Retrieve all formats that were found
01067  *
01068  * \param codecs Codecs structure to look in
01069  * \param astformats An integer to put the Asterisk formats in
01070  * \param nonastformats An integer to put the non-Asterisk formats in
01071  *
01072  * Example usage:
01073  *
01074  * \code
01075  * int astformats, nonastformats;
01076  * ast_rtp_codecs_payload_Formats(&codecs, &astformats, &nonastformats);
01077  * \endcode
01078  *
01079  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
01080  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
01081  *
01082  * \since 1.8
01083  */
01084 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, format_t *astformats, int *nonastformats);
01085 
01086 /*!
01087  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
01088  *
01089  * \param codecs Codecs structure to look in
01090  * \param asterisk_format Non-zero if the given code is an Asterisk format value
01091  * \param code The format to look for
01092  *
01093  * \retval Numerical payload
01094  *
01095  * Example usage:
01096  *
01097  * \code
01098  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, AST_FORMAT_ULAW);
01099  * \endcode
01100  *
01101  * This looks for the numerical payload for ULAW in the codecs structure.
01102  *
01103  * \since 1.8
01104  */
01105 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int asterisk_format, const format_t code);
01106 
01107 /*!
01108  * \brief Retrieve mime subtype information on a payload
01109  *
01110  * \param asterisk_format Non-zero if the given code is an Asterisk format value
01111  * \param code Format to look up
01112  * \param options Additional options that may change the result
01113  *
01114  * \retval Mime subtype success
01115  * \retval NULL failure
01116  *
01117  * Example usage:
01118  *
01119  * \code
01120  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, AST_FORMAT_ULAW, 0);
01121  * \endcode
01122  *
01123  * This looks up the mime subtype for the ULAW format.
01124  *
01125  * \since 1.8
01126  */
01127 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, const format_t code, enum ast_rtp_options options);
01128 
01129 /*!
01130  * \brief Convert formats into a string and put them into a buffer
01131  *
01132  * \param buf Buffer to put the mime output into
01133  * \param capability Formats that we are looking up
01134  * \param asterisk_format Non-zero if the given capability are Asterisk format capabilities
01135  * \param options Additional options that may change the result
01136  *
01137  * \retval non-NULL success
01138  * \retval NULL failure
01139  *
01140  * Example usage:
01141  *
01142  * \code
01143  * char buf[256] = "";
01144  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), AST_FORMAT_ULAW | AST_FORMAT_ALAW, 1, 0);
01145  * \endcode
01146  *
01147  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
01148  *
01149  * \since 1.8
01150  */
01151 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, const format_t capability, const int asterisk_format, enum ast_rtp_options options);
01152 
01153 /*!
01154  * \brief Set codec packetization preferences
01155  *
01156  * \param codecs Codecs structure to muck with
01157  * \param instance Optionally the instance that the codecs structure belongs to
01158  * \param prefs Codec packetization preferences
01159  *
01160  * Example usage:
01161  *
01162  * \code
01163  * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs);
01164  * \endcode
01165  *
01166  * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs.
01167  *
01168  * \since 1.8
01169  */
01170 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs);
01171 
01172 /*!
01173  * \brief Begin sending a DTMF digit
01174  *
01175  * \param instance The RTP instance to send the DTMF on
01176  * \param digit What DTMF digit to send
01177  *
01178  * \retval 0 success
01179  * \retval -1 failure
01180  *
01181  * Example usage:
01182  *
01183  * \code
01184  * ast_rtp_instance_dtmf_begin(instance, '1');
01185  * \endcode
01186  *
01187  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
01188  * continue being sent until it is ended.
01189  *
01190  * \since 1.8
01191  */
01192 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
01193 
01194 /*!
01195  * \brief Stop sending a DTMF digit
01196  *
01197  * \param instance The RTP instance to stop the DTMF on
01198  * \param digit What DTMF digit to stop
01199  *
01200  * \retval 0 success
01201  * \retval -1 failure
01202  *
01203  * Example usage:
01204  *
01205  * \code
01206  * ast_rtp_instance_dtmf_end(instance, '1');
01207  * \endcode
01208  *
01209  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
01210  *
01211  * \since 1.8
01212  */
01213 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
01214 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
01215 
01216 /*!
01217  * \brief Set the DTMF mode that should be used
01218  *
01219  * \param instance the RTP instance to set DTMF mode on
01220  * \param dtmf_mode The DTMF mode that is in use
01221  *
01222  * \retval 0 success
01223  * \retval -1 failure
01224  *
01225  * Example usage:
01226  *
01227  * \code
01228  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
01229  * \endcode
01230  *
01231  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
01232  *
01233  * \since 1.8
01234  */
01235 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
01236 
01237 /*!
01238  * \brief Get the DTMF mode of an RTP instance
01239  *
01240  * \param instance The RTP instance to get the DTMF mode of
01241  *
01242  * \retval DTMF mode
01243  *
01244  * Example usage:
01245  *
01246  * \code
01247  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
01248  * \endcode
01249  *
01250  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
01251  *
01252  * \since 1.8
01253  */
01254 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
01255 
01256 /*!
01257  * \brief Indicate that the RTP marker bit should be set on an RTP stream
01258  *
01259  * \param instance Instance that the new media source is feeding into
01260  *
01261  * Example usage:
01262  *
01263  * \code
01264  * ast_rtp_instance_update_source(instance);
01265  * \endcode
01266  *
01267  * This indicates that the source of media that is feeding the instance pointed to by
01268  * instance has been updated and that the marker bit should be set.
01269  *
01270  * \since 1.8
01271  */
01272 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
01273 
01274 /*!
01275  * \brief Indicate a new source of audio has dropped in and the ssrc should change
01276  *
01277  * \param instance Instance that the new media source is feeding into
01278  *
01279  * Example usage:
01280  *
01281  * \code
01282  * ast_rtp_instance_change_source(instance);
01283  * \endcode
01284  *
01285  * This indicates that the source of media that is feeding the instance pointed to by
01286  * instance has changed and that the marker bit should be set and the SSRC updated.
01287  *
01288  * \since 1.8
01289  */
01290 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
01291 
01292 /*!
01293  * \brief Set QoS parameters on an RTP session
01294  *
01295  * \param instance Instance to set the QoS parameters on
01296  * \param tos Terms of service value
01297  * \param cos Class of service value
01298  * \param desc What is setting the QoS values
01299  *
01300  * \retval 0 success
01301  * \retval -1 failure
01302  *
01303  * Example usage:
01304  *
01305  * \code
01306  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
01307  * \endcode
01308  *
01309  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
01310  *
01311  * \since 1.8
01312  */
01313 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
01314 
01315 /*!
01316  * \brief Stop an RTP instance
01317  *
01318  * \param instance Instance that media is no longer going to at this time
01319  *
01320  * Example usage:
01321  *
01322  * \code
01323  * ast_rtp_instance_stop(instance);
01324  * \endcode
01325  *
01326  * This tells the RTP engine being used for the instance pointed to by instance
01327  * that media is no longer going to it at this time, but may in the future.
01328  *
01329  * \since 1.8
01330  */
01331 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
01332 
01333 /*!
01334  * \brief Get the file descriptor for an RTP session (or RTCP)
01335  *
01336  * \param instance Instance to get the file descriptor for
01337  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
01338  *
01339  * \retval fd success
01340  * \retval -1 failure
01341  *
01342  * Example usage:
01343  *
01344  * \code
01345  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
01346  * \endcode
01347  *
01348  * This retrieves the file descriptor for the socket carrying media on the instance
01349  * pointed to by instance.
01350  *
01351  * \since 1.8
01352  */
01353 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
01354 
01355 /*!
01356  * \brief Get the RTP glue that binds a channel to the RTP engine
01357  *
01358  * \param type Name of the glue we want
01359  *
01360  * \retval non-NULL success
01361  * \retval NULL failure
01362  *
01363  * Example usage:
01364  *
01365  * \code
01366  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
01367  * \endcode
01368  *
01369  * This retrieves the RTP glue that has the name 'Example'.
01370  *
01371  * \since 1.8
01372  */
01373 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
01374 
01375 /*!
01376  * \brief Bridge two channels that use RTP instances
01377  *
01378  * \param c0 First channel part of the bridge
01379  * \param c1 Second channel part of the bridge
01380  * \param flags Bridging flags
01381  * \param fo If a frame needs to be passed up it is stored here
01382  * \param rc Channel that passed the above frame up
01383  * \param timeoutms How long the channels should be bridged for
01384  *
01385  * \retval Bridge result
01386  *
01387  * \note This should only be used by channel drivers in their technology declaration.
01388  *
01389  * \since 1.8
01390  */
01391 enum ast_bridge_result ast_rtp_instance_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
01392 
01393 /*!
01394  * \brief Get the other RTP instance that an instance is bridged to
01395  *
01396  * \param instance The RTP instance that we want
01397  *
01398  * \retval non-NULL success
01399  * \retval NULL failure
01400  *
01401  * Example usage:
01402  *
01403  * \code
01404  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
01405  * \endcode
01406  *
01407  * This gets the RTP instance that instance0 is bridged to.
01408  *
01409  * \since 1.8
01410  */
01411 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
01412 
01413 /*!
01414  * \brief Make two channels compatible for early bridging
01415  *
01416  * \param c_dst Destination channel to copy to
01417  * \param c_src Source channel to copy from
01418  *
01419  * \since 1.8
01420  */
01421 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c_dst, struct ast_channel *c_src);
01422 
01423 /*!
01424  * \brief Early bridge two channels that use RTP instances
01425  *
01426  * \param c0 First channel part of the bridge
01427  * \param c1 Second channel part of the bridge
01428  *
01429  * \retval 0 success
01430  * \retval -1 failure
01431  *
01432  * \note This should only be used by channel drivers in their technology declaration.
01433  *
01434  * \since 1.8
01435  */
01436 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
01437 
01438 /*!
01439  * \brief Initialize RED support on an RTP instance
01440  *
01441  * \param instance The instance to initialize RED support on
01442  * \param buffer_time How long to buffer before sending
01443  * \param payloads Payload values
01444  * \param generations Number of generations
01445  *
01446  * \retval 0 success
01447  * \retval -1 failure
01448  *
01449  * \since 1.8
01450  */
01451 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
01452 
01453 /*!
01454  * \brief Buffer a frame in an RTP instance for RED
01455  *
01456  * \param instance The instance to buffer the frame on
01457  * \param frame Frame that we want to buffer
01458  *
01459  * \retval 0 success
01460  * \retval -1 failure
01461  *
01462  * \since 1.8
01463  */
01464 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
01465 
01466 /*!
01467  * \brief Retrieve statistics about an RTP instance
01468  *
01469  * \param instance Instance to get statistics on
01470  * \param stats Structure to put results into
01471  * \param stat What statistic(s) to retrieve
01472  *
01473  * \retval 0 success
01474  * \retval -1 failure
01475  *
01476  * Example usage:
01477  *
01478  * \code
01479  * struct ast_rtp_instance_stats stats;
01480  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
01481  * \endcode
01482  *
01483  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
01484  * stats structure.
01485  *
01486  * \since 1.8
01487  */
01488 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
01489 
01490 /*!
01491  * \brief Set standard statistics from an RTP instance on a channel
01492  *
01493  * \param chan Channel to set the statistics on
01494  * \param instance The RTP instance that statistics will be retrieved from
01495  *
01496  * Example usage:
01497  *
01498  * \code
01499  * ast_rtp_instance_set_stats_vars(chan, rtp);
01500  * \endcode
01501  *
01502  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
01503  * by chan.
01504  *
01505  * \since 1.8
01506  */
01507 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
01508 
01509 /*!
01510  * \brief Retrieve quality statistics about an RTP instance
01511  *
01512  * \param instance Instance to get statistics on
01513  * \param field What quality statistic to retrieve
01514  * \param buf What buffer to put the result into
01515  * \param size Size of the above buffer
01516  *
01517  * \retval non-NULL success
01518  * \retval NULL failure
01519  *
01520  * Example usage:
01521  *
01522  * \code
01523  * char quality[AST_MAX_USER_FIELD];
01524  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
01525  * \endcode
01526  *
01527  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
01528  *
01529  * \since 1.8
01530  */
01531 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
01532 
01533 /*!
01534  * \brief Request that the underlying RTP engine provide audio frames in a specific format
01535  *
01536  * \param instance The RTP instance to change read format on
01537  * \param format Format that frames are wanted in
01538  *
01539  * \retval 0 success
01540  * \retval -1 failure
01541  *
01542  * Example usage:
01543  *
01544  * \code
01545  * ast_rtp_instance_set_read_format(instance, AST_FORMAT_ULAW);
01546  * \endcode
01547  *
01548  * This requests that the RTP engine provide audio frames in the ULAW format.
01549  *
01550  * \since 1.8
01551  */
01552 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, format_t format);
01553 
01554 /*!
01555  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
01556  *
01557  * \param instance The RTP instance to change write format on
01558  * \param format Format that frames will be provided in
01559  *
01560  * \retval 0 success
01561  * \retval -1 failure
01562  *
01563  * Example usage:
01564  *
01565  * \code
01566  * ast_rtp_instance_set_write_format(instance, AST_FORMAT_ULAW);
01567  * \endcode
01568  *
01569  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
01570  *
01571  * \since 1.8
01572  */
01573 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, format_t format);
01574 
01575 /*!
01576  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
01577  *
01578  * \param chan Our own Asterisk channel
01579  * \param instance The first RTP instance
01580  * \param peer The peer Asterisk channel
01581  *
01582  * \retval 0 success
01583  * \retval -1 failure
01584  *
01585  * Example usage:
01586  *
01587  * \code
01588  * ast_rtp_instance_make_compatible(instance, peer);
01589  * \endcode
01590  *
01591  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
01592  *
01593  * \since 1.8
01594  */
01595 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
01596 
01597 /*! \brief Request the formats that can be transcoded
01598  *
01599  * \param instance The RTP instance
01600  * \param to_endpoint Formats being sent/received towards the endpoint
01601  * \param to_asterisk Formats being sent/received towards Asterisk
01602  *
01603  * \retval supported formats
01604  *
01605  * Example usage:
01606  *
01607  * \code
01608  * ast_rtp_instance_available_formats(instance, AST_FORMAT_ULAW, AST_FORMAT_SLINEAR);
01609  * \endcode
01610  *
01611  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
01612  *
01613  * \since 1.8
01614  */
01615 format_t ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, format_t to_endpoint, format_t to_asterisk);
01616 
01617 /*!
01618  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
01619  *
01620  * \param instance The RTP instance
01621  *
01622  * \retval 0 success
01623  * \retval -1 failure
01624  *
01625  * Example usage:
01626  *
01627  * \code
01628  * ast_rtp_instance_activate(instance);
01629  * \endcode
01630  *
01631  * This tells the underlying RTP engine of instance that packets will now flow.
01632  *
01633  * \since 1.8
01634  */
01635 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
01636 
01637 /*!
01638  * \brief Request that the underlying RTP engine send a STUN BIND request
01639  *
01640  * \param instance The RTP instance
01641  * \param suggestion The suggested destination
01642  * \param username Optionally a username for the request
01643  *
01644  * Example usage:
01645  *
01646  * \code
01647  * ast_rtp_instance_stun_request(instance, NULL, NULL);
01648  * \endcode
01649  *
01650  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
01651  * 'instance'.
01652  *
01653  * \since 1.8
01654  */
01655 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
01656 
01657 /*!
01658  * \brief Set the RTP timeout value
01659  *
01660  * \param instance The RTP instance
01661  * \param timeout Value to set the timeout to
01662  *
01663  * Example usage:
01664  *
01665  * \code
01666  * ast_rtp_instance_set_timeout(instance, 5000);
01667  * \endcode
01668  *
01669  * This sets the RTP timeout value on 'instance' to be 5000.
01670  *
01671  * \since 1.8
01672  */
01673 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
01674 
01675 /*!
01676  * \brief Set the RTP timeout value for when the instance is on hold
01677  *
01678  * \param instance The RTP instance
01679  * \param timeout Value to set the timeout to
01680  *
01681  * Example usage:
01682  *
01683  * \code
01684  * ast_rtp_instance_set_hold_timeout(instance, 5000);
01685  * \endcode
01686  *
01687  * This sets the RTP hold timeout value on 'instance' to be 5000.
01688  *
01689  * \since 1.8
01690  */
01691 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
01692 
01693 /*!
01694  * \brief Set the RTP keepalive interval
01695  *
01696  * \param instance The RTP instance
01697  * \param period Value to set the keepalive interval to
01698  *
01699  * Example usage:
01700  *
01701  * \code
01702  * ast_rtp_instance_set_keepalive(instance, 5000);
01703  * \endcode
01704  *
01705  * This sets the RTP keepalive interval on 'instance' to be 5000.
01706  *
01707  * \since 1.8
01708  */
01709 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
01710 
01711 /*!
01712  * \brief Get the RTP timeout value
01713  *
01714  * \param instance The RTP instance
01715  *
01716  * \retval timeout value
01717  *
01718  * Example usage:
01719  *
01720  * \code
01721  * int timeout = ast_rtp_instance_get_timeout(instance);
01722  * \endcode
01723  *
01724  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
01725  *
01726  * \since 1.8
01727  */
01728 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
01729 
01730 /*!
01731  * \brief Get the RTP timeout value for when an RTP instance is on hold
01732  *
01733  * \param instance The RTP instance
01734  *
01735  * \retval timeout value
01736  *
01737  * Example usage:
01738  *
01739  * \code
01740  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
01741  * \endcode
01742  *
01743  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
01744  *
01745  * \since 1.8
01746  */
01747 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
01748 
01749 /*!
01750  * \brief Get the RTP keepalive interval
01751  *
01752  * \param instance The RTP instance
01753  *
01754  * \retval period Keepalive interval value
01755  *
01756  * Example usage:
01757  *
01758  * \code
01759  * int interval = ast_rtp_instance_get_keepalive(instance);
01760  * \endcode
01761  *
01762  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
01763  *
01764  * \since 1.8
01765  */
01766 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
01767 
01768 /*!
01769  * \brief Get the RTP engine in use on an RTP instance
01770  *
01771  * \param instance The RTP instance
01772  *
01773  * \retval pointer to the engine
01774  *
01775  * Example usage:
01776  *
01777  * \code
01778  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
01779  * \endcode
01780  *
01781  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
01782  *
01783  * \since 1.8
01784  */
01785 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
01786 
01787 /*!
01788  * \brief Get the RTP glue in use on an RTP instance
01789  *
01790  * \param instance The RTP instance
01791  *
01792  * \retval pointer to the glue
01793  *
01794  * Example:
01795  *
01796  * \code
01797  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
01798  * \endcode
01799  *
01800  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
01801  *
01802  * \since 1.8
01803  */
01804 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
01805 
01806 /*!
01807  * \brief Get the channel that is associated with an RTP instance while in a bridge
01808  *
01809  * \param instance The RTP instance
01810  *
01811  * \retval pointer to the channel
01812  *
01813  * Example:
01814  *
01815  * \code
01816  * struct ast_channel *chan = ast_rtp_instance_get_chan(instance);
01817  * \endcode
01818  *
01819  * This gets the channel associated with the RTP instance pointed to by 'instance'.
01820  *
01821  * \note This will only return a channel while in a local or remote bridge.
01822  *
01823  * \since 1.8
01824  */
01825 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance);
01826 
01827 /*!
01828  * \brief Send a comfort noise packet to the RTP instance
01829  *
01830  * \param instance The RTP instance
01831  * \param level Magnitude of the noise level
01832  *
01833  * \retval 0 Success
01834  * \retval non-zero Failure
01835  */
01836 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
01837 
01838 /*!
01839  * \brief Add or replace the SRTP policies for the given RTP instance
01840  *
01841  * \param instance the RTP instance
01842  * \param remote_policy the remote endpoint's policy
01843  * \param local_policy our policy for this RTP instance's remote endpoint
01844  *
01845  * \retval 0 Success
01846  * \retval non-zero Failure
01847  */
01848 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy);
01849 
01850 /*!
01851  * \brief Obtain the SRTP instance associated with an RTP instance
01852  *
01853  * \param instance the RTP instance
01854  * \retval the SRTP instance on success
01855  * \retval NULL if no SRTP instance exists
01856  */
01857 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance);
01858 
01859 #if defined(__cplusplus) || defined(c_plusplus)
01860 }
01861 #endif
01862 
01863 #endif /* _ASTERISK_RTP_ENGINE_H */

Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1