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/format_cap.h"
00075 #include "asterisk/netsock2.h"
00076 #include "asterisk/sched.h"
00077 #include "asterisk/res_srtp.h"
00078 #include "asterisk/stasis.h"
00079 #include "asterisk/vector.h"
00080 
00081 /* Maximum number of payloads supported */
00082 #if defined(LOW_MEMORY)
00083 #define AST_RTP_MAX_PT 128
00084 #else
00085 #define AST_RTP_MAX_PT 196
00086 #endif
00087 
00088 /* Maximum number of generations */
00089 #define AST_RED_MAX_GENERATION 5
00090 
00091 /*!
00092  * Maximum size of an internal Asterisk channel unique ID.
00093  *
00094  * \note Must match the AST_MAX_UNIQUEID(AST_MAX_PUBLIC_UNIQUEID) value.
00095  * We don't use that defined value directly here to avoid a hard
00096  * dependency on channel.h.
00097  */
00098 #define MAX_CHANNEL_ID 152
00099 
00100 struct ast_rtp_instance;
00101 struct ast_rtp_glue;
00102 
00103 /*! RTP Properties that can be set on an RTP instance */
00104 enum ast_rtp_property {
00105    /*! Enable symmetric RTP support */
00106    AST_RTP_PROPERTY_NAT = 0,
00107    /*! RTP instance will be carrying DTMF (using RFC2833) */
00108    AST_RTP_PROPERTY_DTMF,
00109    /*! Expect unreliable DTMF from remote party */
00110    AST_RTP_PROPERTY_DTMF_COMPENSATE,
00111    /*! Enable STUN support */
00112    AST_RTP_PROPERTY_STUN,
00113    /*! Enable RTCP support */
00114    AST_RTP_PROPERTY_RTCP,
00115 
00116    /*!
00117     * \brief Maximum number of RTP properties supported
00118     *
00119     * \note THIS MUST BE THE LAST ENTRY IN THIS ENUM.
00120     */
00121    AST_RTP_PROPERTY_MAX,
00122 };
00123 
00124 /*! Additional RTP options */
00125 enum ast_rtp_options {
00126    /*! Remote side is using non-standard G.726 */
00127    AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
00128 };
00129 
00130 /*! RTP DTMF Modes */
00131 enum ast_rtp_dtmf_mode {
00132    /*! No DTMF is being carried over the RTP stream */
00133    AST_RTP_DTMF_MODE_NONE = 0,
00134    /*! DTMF is being carried out of band using RFC2833 */
00135    AST_RTP_DTMF_MODE_RFC2833,
00136    /*! DTMF is being carried inband over the RTP stream */
00137    AST_RTP_DTMF_MODE_INBAND,
00138 };
00139 
00140 /*! Result codes when RTP glue is queried for information */
00141 enum ast_rtp_glue_result {
00142    /*! No remote or local bridging is permitted */
00143    AST_RTP_GLUE_RESULT_FORBID = 0,
00144    /*! Move RTP stream to be remote between devices directly */
00145    AST_RTP_GLUE_RESULT_REMOTE,
00146    /*! Perform RTP engine level bridging if possible */
00147    AST_RTP_GLUE_RESULT_LOCAL,
00148 };
00149 
00150 /*! Field statistics that can be retrieved from an RTP instance */
00151 enum ast_rtp_instance_stat_field {
00152    /*! Retrieve quality information */
00153    AST_RTP_INSTANCE_STAT_FIELD_QUALITY = 0,
00154    /*! Retrieve quality information about jitter */
00155    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_JITTER,
00156    /*! Retrieve quality information about packet loss */
00157    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_LOSS,
00158    /*! Retrieve quality information about round trip time */
00159    AST_RTP_INSTANCE_STAT_FIELD_QUALITY_RTT,
00160 };
00161 
00162 /*! Statistics that can be retrieved from an RTP instance */
00163 enum ast_rtp_instance_stat {
00164    /*! Retrieve all statistics */
00165    AST_RTP_INSTANCE_STAT_ALL = 0,
00166    /*! Retrieve number of packets transmitted */
00167    AST_RTP_INSTANCE_STAT_TXCOUNT,
00168    /*! Retrieve number of packets received */
00169    AST_RTP_INSTANCE_STAT_RXCOUNT,
00170    /*! Retrieve ALL statistics relating to packet loss */
00171    AST_RTP_INSTANCE_STAT_COMBINED_LOSS,
00172    /*! Retrieve number of packets lost for transmitting */
00173    AST_RTP_INSTANCE_STAT_TXPLOSS,
00174    /*! Retrieve number of packets lost for receiving */
00175    AST_RTP_INSTANCE_STAT_RXPLOSS,
00176    /*! Retrieve maximum number of packets lost on remote side */
00177    AST_RTP_INSTANCE_STAT_REMOTE_MAXRXPLOSS,
00178    /*! Retrieve minimum number of packets lost on remote side */
00179    AST_RTP_INSTANCE_STAT_REMOTE_MINRXPLOSS,
00180    /*! Retrieve average number of packets lost on remote side */
00181    AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVRXPLOSS,
00182    /*! Retrieve standard deviation of packets lost on remote side */
00183    AST_RTP_INSTANCE_STAT_REMOTE_STDEVRXPLOSS,
00184    /*! Retrieve maximum number of packets lost on local side */
00185    AST_RTP_INSTANCE_STAT_LOCAL_MAXRXPLOSS,
00186    /*! Retrieve minimum number of packets lost on local side */
00187    AST_RTP_INSTANCE_STAT_LOCAL_MINRXPLOSS,
00188    /*! Retrieve average number of packets lost on local side */
00189    AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVRXPLOSS,
00190    /*! Retrieve standard deviation of packets lost on local side */
00191    AST_RTP_INSTANCE_STAT_LOCAL_STDEVRXPLOSS,
00192    /*! Retrieve ALL statistics relating to jitter */
00193    AST_RTP_INSTANCE_STAT_COMBINED_JITTER,
00194    /*! Retrieve jitter on transmitted packets */
00195    AST_RTP_INSTANCE_STAT_TXJITTER,
00196    /*! Retrieve jitter on received packets */
00197    AST_RTP_INSTANCE_STAT_RXJITTER,
00198    /*! Retrieve maximum jitter on remote side */
00199    AST_RTP_INSTANCE_STAT_REMOTE_MAXJITTER,
00200    /*! Retrieve minimum jitter on remote side */
00201    AST_RTP_INSTANCE_STAT_REMOTE_MINJITTER,
00202    /*! Retrieve average jitter on remote side */
00203    AST_RTP_INSTANCE_STAT_REMOTE_NORMDEVJITTER,
00204    /*! Retrieve standard deviation jitter on remote side */
00205    AST_RTP_INSTANCE_STAT_REMOTE_STDEVJITTER,
00206    /*! Retrieve maximum jitter on local side */
00207    AST_RTP_INSTANCE_STAT_LOCAL_MAXJITTER,
00208    /*! Retrieve minimum jitter on local side */
00209    AST_RTP_INSTANCE_STAT_LOCAL_MINJITTER,
00210    /*! Retrieve average jitter on local side */
00211    AST_RTP_INSTANCE_STAT_LOCAL_NORMDEVJITTER,
00212    /*! Retrieve standard deviation jitter on local side */
00213    AST_RTP_INSTANCE_STAT_LOCAL_STDEVJITTER,
00214    /*! Retrieve ALL statistics relating to round trip time */
00215    AST_RTP_INSTANCE_STAT_COMBINED_RTT,
00216    /*! Retrieve round trip time */
00217    AST_RTP_INSTANCE_STAT_RTT,
00218    /*! Retrieve maximum round trip time */
00219    AST_RTP_INSTANCE_STAT_MAX_RTT,
00220    /*! Retrieve minimum round trip time */
00221    AST_RTP_INSTANCE_STAT_MIN_RTT,
00222    /*! Retrieve average round trip time */
00223    AST_RTP_INSTANCE_STAT_NORMDEVRTT,
00224    /*! Retrieve standard deviation round trip time */
00225    AST_RTP_INSTANCE_STAT_STDEVRTT,
00226    /*! Retrieve local SSRC */
00227    AST_RTP_INSTANCE_STAT_LOCAL_SSRC,
00228    /*! Retrieve remote SSRC */
00229    AST_RTP_INSTANCE_STAT_REMOTE_SSRC,
00230    /*! Retrieve channel unique ID */
00231    AST_RTP_INSTANCE_STAT_CHANNEL_UNIQUEID,
00232 };
00233 
00234 /* Codes for RTP-specific data - not defined by our AST_FORMAT codes */
00235 /*! DTMF (RFC2833) */
00236 #define AST_RTP_DTMF                    (1 << 0)
00237 /*! 'Comfort Noise' (RFC3389) */
00238 #define AST_RTP_CN                      (1 << 1)
00239 /*! DTMF (Cisco Proprietary) */
00240 #define AST_RTP_CISCO_DTMF              (1 << 2)
00241 /*! Maximum RTP-specific code */
00242 #define AST_RTP_MAX                     AST_RTP_CISCO_DTMF
00243 
00244 /*! Structure that represents a payload */
00245 struct ast_rtp_payload_type {
00246    /*! Is this an Asterisk value */
00247    int asterisk_format;
00248    /*! If asterisk_format is set, this is the internal
00249     * asterisk format represented by the payload */
00250    struct ast_format *format;
00251    /*! Actual internal RTP specific value of the payload */
00252    int rtp_code;
00253    /*! Actual payload number */
00254    int payload;
00255 };
00256 
00257 /* Common RTCP report types */
00258 /*! Sender Report */
00259 #define AST_RTP_RTCP_SR 200
00260 /*! Receiver Report */
00261 #define AST_RTP_RTCP_RR 201
00262 
00263 /*!
00264  * \since 12
00265  * \brief A report block within a SR/RR report */
00266 struct ast_rtp_rtcp_report_block {
00267    unsigned int source_ssrc;         /*< The SSRC of the source for this report block */
00268    struct {
00269       unsigned short fraction;      /*< The fraction of packets lost since last SR/RR */
00270       unsigned int packets;         /*< The cumulative packets since the beginning */
00271    } lost_count;                     /*< Statistics regarding missed packets */
00272    unsigned int highest_seq_no;      /*< Extended highest sequence number received */
00273    unsigned int ia_jitter;           /*< Calculated interarrival jitter */
00274    unsigned int lsr;                 /*< The time the last SR report was received */
00275    unsigned int dlsr;                /*< Delay in sending this report */
00276 };
00277 
00278 /*!
00279  * \since 12
00280  * \brief An object that represents data sent during a SR/RR RTCP report */
00281 struct ast_rtp_rtcp_report {
00282    unsigned short reception_report_count;     /*< The number of report blocks */
00283    unsigned int ssrc;                         /*< Our SSRC */
00284    unsigned int type;                         /*< The type of report. 200=SR; 201=RR */
00285    struct {
00286       struct timeval ntp_timestamp;          /*< Our NTP timestamp */
00287       unsigned int rtp_timestamp;            /*< Our last RTP timestamp */
00288       unsigned int packet_count;             /*< Number of packets sent */
00289       unsigned int octet_count;              /*< Number of bytes sent */
00290    } sender_information;                      /*< Sender information for SR */
00291    /*! A dynamic array of report blocks. The number of elements is given by
00292     * \c reception_report_count.
00293     */
00294    struct ast_rtp_rtcp_report_block *report_block[0];
00295 };
00296 
00297 /*! Structure that represents statistics from an RTP instance */
00298 struct ast_rtp_instance_stats {
00299    /*! Number of packets transmitted */
00300    unsigned int txcount;
00301    /*! Number of packets received */
00302    unsigned int rxcount;
00303    /*! Jitter on transmitted packets */
00304    double txjitter;
00305    /*! Jitter on received packets */
00306    double rxjitter;
00307    /*! Maximum jitter on remote side */
00308    double remote_maxjitter;
00309    /*! Minimum jitter on remote side */
00310    double remote_minjitter;
00311    /*! Average jitter on remote side */
00312    double remote_normdevjitter;
00313    /*! Standard deviation jitter on remote side */
00314    double remote_stdevjitter;
00315    /*! Maximum jitter on local side */
00316    double local_maxjitter;
00317    /*! Minimum jitter on local side */
00318    double local_minjitter;
00319    /*! Average jitter on local side */
00320    double local_normdevjitter;
00321    /*! Standard deviation jitter on local side */
00322    double local_stdevjitter;
00323    /*! Number of transmitted packets lost */
00324    unsigned int txploss;
00325    /*! Number of received packets lost */
00326    unsigned int rxploss;
00327    /*! Maximum number of packets lost on remote side */
00328    double remote_maxrxploss;
00329    /*! Minimum number of packets lost on remote side */
00330    double remote_minrxploss;
00331    /*! Average number of packets lost on remote side */
00332    double remote_normdevrxploss;
00333    /*! Standard deviation packets lost on remote side */
00334    double remote_stdevrxploss;
00335    /*! Maximum number of packets lost on local side */
00336    double local_maxrxploss;
00337    /*! Minimum number of packets lost on local side */
00338    double local_minrxploss;
00339    /*! Average number of packets lost on local side */
00340    double local_normdevrxploss;
00341    /*! Standard deviation packets lost on local side */
00342    double local_stdevrxploss;
00343    /*! Total round trip time */
00344    double rtt;
00345    /*! Maximum round trip time */
00346    double maxrtt;
00347    /*! Minimum round trip time */
00348    double minrtt;
00349    /*! Average round trip time */
00350    double normdevrtt;
00351    /*! Standard deviation round trip time */
00352    double stdevrtt;
00353    /*! Our SSRC */
00354    unsigned int local_ssrc;
00355    /*! Their SSRC */
00356    unsigned int remote_ssrc;
00357    /*! The Asterisk channel's unique ID that owns this instance */
00358    char channel_uniqueid[MAX_CHANNEL_ID];
00359 };
00360 
00361 #define AST_RTP_STAT_SET(current_stat, combined, placement, value) \
00362 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
00363 placement = value; \
00364 if (stat == current_stat) { \
00365 return 0; \
00366 } \
00367 }
00368 
00369 #define AST_RTP_STAT_STRCPY(current_stat, combined, placement, value) \
00370 if (stat == current_stat || stat == AST_RTP_INSTANCE_STAT_ALL || (combined >= 0 && combined == current_stat)) { \
00371    ast_copy_string(placement, value, sizeof(placement)); \
00372    if (stat == current_stat) { \
00373       return 0; \
00374    } \
00375 }
00376 
00377 #define AST_RTP_STAT_TERMINATOR(combined) \
00378 if (stat == combined) { \
00379 return 0; \
00380 }
00381 
00382 /*! \brief ICE candidate types */
00383 enum ast_rtp_ice_candidate_type {
00384    AST_RTP_ICE_CANDIDATE_TYPE_HOST,    /*!< ICE host candidate. A host candidate represents the actual local transport address in the host. */
00385    AST_RTP_ICE_CANDIDATE_TYPE_SRFLX,   /*!< ICE server reflexive candidate, which represents the public mapped address of the local address. */
00386    AST_RTP_ICE_CANDIDATE_TYPE_RELAYED, /*!< ICE relayed candidate, which represents the address allocated in TURN server. */
00387 };
00388 
00389 /*! \brief ICE component types */
00390 enum ast_rtp_ice_component_type {
00391    AST_RTP_ICE_COMPONENT_RTP = 1,
00392    AST_RTP_ICE_COMPONENT_RTCP = 2,
00393 };
00394 
00395 /*! \brief ICE role during negotiation */
00396 enum ast_rtp_ice_role {
00397    AST_RTP_ICE_ROLE_CONTROLLED,
00398    AST_RTP_ICE_ROLE_CONTROLLING,
00399 };
00400 
00401 /*! \brief Structure for an ICE candidate */
00402 struct ast_rtp_engine_ice_candidate {
00403    char *foundation;                     /*!< Foundation identifier */
00404    enum ast_rtp_ice_component_type id;   /*!< Component identifier */
00405    char *transport;                      /*!< Transport for the media */
00406    int priority;                         /*!< Priority which is used if multiple candidates can be used */
00407    struct ast_sockaddr address;          /*!< Address of the candidate */
00408    struct ast_sockaddr relay_address;    /*!< Relay address for the candidate */
00409    enum ast_rtp_ice_candidate_type type; /*!< Type of candidate */
00410 };
00411 
00412 /*! \brief Structure that represents the optional ICE support within an RTP engine */
00413 struct ast_rtp_engine_ice {
00414    /*! Callback for setting received authentication information */
00415    void (*set_authentication)(struct ast_rtp_instance *instance, const char *ufrag, const char *password);
00416    /*! Callback for adding a remote candidate */
00417    void (*add_remote_candidate)(struct ast_rtp_instance *instance, const struct ast_rtp_engine_ice_candidate *candidate);
00418    /*! Callback for starting ICE negotiation */
00419    void (*start)(struct ast_rtp_instance *instance);
00420    /*! Callback for stopping ICE support */
00421    void (*stop)(struct ast_rtp_instance *instance);
00422    /*! Callback for getting local username */
00423    const char *(*get_ufrag)(struct ast_rtp_instance *instance);
00424    /*! Callback for getting local password */
00425    const char *(*get_password)(struct ast_rtp_instance *instance);
00426    /*! Callback for getting local candidates */
00427    struct ao2_container *(*get_local_candidates)(struct ast_rtp_instance *instance);
00428    /*! Callback for telling the ICE support that it is talking to an ice-lite implementation */
00429    void (*ice_lite)(struct ast_rtp_instance *instance);
00430    /*! Callback for changing our role in negotiation */
00431    void (*set_role)(struct ast_rtp_instance *instance, enum ast_rtp_ice_role role);
00432    /*! Callback for requesting a TURN session */
00433    void (*turn_request)(struct ast_rtp_instance *instance, enum ast_rtp_ice_component_type component,
00434       enum ast_transport transport, const char *server, unsigned int port,
00435       const char *username, const char *password);
00436 };
00437 
00438 /*! \brief DTLS setup types */
00439 enum ast_rtp_dtls_setup {
00440    AST_RTP_DTLS_SETUP_ACTIVE,   /*!< Endpoint is willing to inititate connections */
00441    AST_RTP_DTLS_SETUP_PASSIVE,  /*!< Endpoint is willing to accept connections */
00442    AST_RTP_DTLS_SETUP_ACTPASS,  /*!< Endpoint is willing to both accept and initiate connections */
00443    AST_RTP_DTLS_SETUP_HOLDCONN, /*!< Endpoint does not want the connection to be established right now */
00444 };
00445 
00446 /*! \brief DTLS connection states */
00447 enum ast_rtp_dtls_connection {
00448    AST_RTP_DTLS_CONNECTION_NEW,      /*!< Endpoint wants to use a new connection */
00449    AST_RTP_DTLS_CONNECTION_EXISTING, /*!< Endpoint wishes to use existing connection */
00450 };
00451 
00452 /*! \brief DTLS fingerprint hashes */
00453 enum ast_rtp_dtls_hash {
00454    AST_RTP_DTLS_HASH_SHA256, /*!< SHA-256 fingerprint hash */
00455    AST_RTP_DTLS_HASH_SHA1,   /*!< SHA-1 fingerprint hash */
00456 };
00457 
00458 /*! \brief DTLS verification settings */
00459 enum ast_rtp_dtls_verify {
00460    AST_RTP_DTLS_VERIFY_NONE = 0,               /*!< Don't verify anything */
00461    AST_RTP_DTLS_VERIFY_FINGERPRINT = (1 << 0), /*!< Verify the fingerprint */
00462    AST_RTP_DTLS_VERIFY_CERTIFICATE = (1 << 1), /*!< Verify the certificate */
00463 };
00464 
00465 /*! \brief DTLS configuration structure */
00466 struct ast_rtp_dtls_cfg {
00467    unsigned int enabled:1;                /*!< Whether DTLS support is enabled or not */
00468    unsigned int rekey;                    /*!< Interval at which to renegotiate and rekey - defaults to 0 (off) */
00469    enum ast_rtp_dtls_setup default_setup; /*!< Default setup type to use for outgoing */
00470    enum ast_srtp_suite suite;             /*!< Crypto suite in use */
00471    enum ast_rtp_dtls_hash hash;        /*!< Hash to use for fingerprint */
00472    enum ast_rtp_dtls_verify verify;    /*!< What should be verified */
00473    char *certfile;                        /*!< Certificate file */
00474    char *pvtfile;                         /*!< Private key file */
00475    char *cipher;                          /*!< Cipher to use */
00476    char *cafile;                          /*!< Certificate authority file */
00477    char *capath;                          /*!< Path to certificate authority */
00478 };
00479 
00480 /*! \brief Structure that represents the optional DTLS SRTP support within an RTP engine */
00481 struct ast_rtp_engine_dtls {
00482    /*! Set the configuration of the DTLS support on the instance */
00483    int (*set_configuration)(struct ast_rtp_instance *instance, const struct ast_rtp_dtls_cfg *dtls_cfg);
00484    /*! Get if the DTLS SRTP support is active or not */
00485    int (*active)(struct ast_rtp_instance *instance);
00486    /*! Stop and terminate DTLS SRTP support */
00487    void (*stop)(struct ast_rtp_instance *instance);
00488    /*! Reset the connection and start fresh */
00489    void (*reset)(struct ast_rtp_instance *instance);
00490    /*! Get the current connection state */
00491    enum ast_rtp_dtls_connection (*get_connection)(struct ast_rtp_instance *instance);
00492    /*! Get the current setup state */
00493    enum ast_rtp_dtls_setup (*get_setup)(struct ast_rtp_instance *instance);
00494    /*! Set the remote setup state */
00495    void (*set_setup)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_setup setup);
00496    /*! Set the remote fingerprint */
00497    void (*set_fingerprint)(struct ast_rtp_instance *instance, enum ast_rtp_dtls_hash hash, const char *fingerprint);
00498    /*! Get the local fingerprint hash type */
00499    enum ast_rtp_dtls_hash (*get_fingerprint_hash)(struct ast_rtp_instance *instance);
00500    /*! Get the local fingerprint */
00501    const char *(*get_fingerprint)(struct ast_rtp_instance *instance);
00502 };
00503 
00504 /*! Structure that represents an RTP stack (engine) */
00505 struct ast_rtp_engine {
00506    /*! Name of the RTP engine, used when explicitly requested */
00507    const char *name;
00508    /*! Module this RTP engine came from, used for reference counting */
00509    struct ast_module *mod;
00510    /*! Callback for setting up a new RTP instance */
00511    int (*new)(struct ast_rtp_instance *instance, struct ast_sched_context *sched, struct ast_sockaddr *sa, void *data);
00512    /*! Callback for destroying an RTP instance */
00513    int (*destroy)(struct ast_rtp_instance *instance);
00514    /*! Callback for writing out a frame */
00515    int (*write)(struct ast_rtp_instance *instance, struct ast_frame *frame);
00516    /*! Callback for stopping the RTP instance */
00517    void (*stop)(struct ast_rtp_instance *instance);
00518    /*! Callback for starting RFC2833 DTMF transmission */
00519    int (*dtmf_begin)(struct ast_rtp_instance *instance, char digit);
00520    /*! Callback for stopping RFC2833 DTMF transmission */
00521    int (*dtmf_end)(struct ast_rtp_instance *instance, char digit);
00522    int (*dtmf_end_with_duration)(struct ast_rtp_instance *instance, char digit, unsigned int duration);
00523    /*! Callback to indicate that we should update the marker bit */
00524    void (*update_source)(struct ast_rtp_instance *instance);
00525    /*! Callback to indicate that we should update the marker bit and ssrc */
00526    void (*change_source)(struct ast_rtp_instance *instance);
00527    /*! Callback for setting an extended RTP property */
00528    int (*extended_prop_set)(struct ast_rtp_instance *instance, int property, void *value);
00529    /*! Callback for getting an extended RTP property */
00530    void *(*extended_prop_get)(struct ast_rtp_instance *instance, int property);
00531    /*! Callback for setting an RTP property */
00532    void (*prop_set)(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
00533    /*! Callback for setting a payload.  If asterisk  is to be used, asterisk_format will be set, otherwise value in code is used. */
00534    void (*payload_set)(struct ast_rtp_instance *instance, int payload, int asterisk_format, struct ast_format *format, int code);
00535    /*! Callback for setting the remote address that RTP is to be sent to */
00536    void (*remote_address_set)(struct ast_rtp_instance *instance, struct ast_sockaddr *sa);
00537    /*! Callback for changing DTMF mode */
00538    int (*dtmf_mode_set)(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
00539    /*! Callback for getting DTMF mode */
00540    enum ast_rtp_dtmf_mode (*dtmf_mode_get)(struct ast_rtp_instance *instance);
00541    /*! Callback for retrieving statistics */
00542    int (*get_stat)(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
00543    /*! Callback for setting QoS values */
00544    int (*qos)(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
00545    /*! Callback for retrieving a file descriptor to poll on, not always required */
00546    int (*fd)(struct ast_rtp_instance *instance, int rtcp);
00547    /*! Callback for initializing RED support */
00548    int (*red_init)(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
00549    /*! Callback for buffering a frame using RED */
00550    int (*red_buffer)(struct ast_rtp_instance *instance, struct ast_frame *frame);
00551    /*! Callback for reading a frame from the RTP engine */
00552    struct ast_frame *(*read)(struct ast_rtp_instance *instance, int rtcp);
00553    /*! Callback to locally bridge two RTP instances */
00554    int (*local_bridge)(struct ast_rtp_instance *instance0, struct ast_rtp_instance *instance1);
00555    /*! Callback to set the read format */
00556    int (*set_read_format)(struct ast_rtp_instance *instance, struct ast_format *format);
00557    /*! Callback to set the write format */
00558    int (*set_write_format)(struct ast_rtp_instance *instance, struct ast_format *format);
00559    /*! Callback to make two instances compatible */
00560    int (*make_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
00561    /*! Callback to see if two instances are compatible with DTMF */
00562    int (*dtmf_compatible)(struct ast_channel *chan0, struct ast_rtp_instance *instance0, struct ast_channel *chan1, struct ast_rtp_instance *instance1);
00563    /*! Callback to indicate that packets will now flow */
00564    int (*activate)(struct ast_rtp_instance *instance);
00565    /*! Callback to request that the RTP engine send a STUN BIND request */
00566    void (*stun_request)(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
00567    /*! Callback to get the transcodeable formats supported. result returned in ast_format_cap *result */
00568    void (*available_formats)(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
00569    /*! Callback to send CNG */
00570    int (*sendcng)(struct ast_rtp_instance *instance, int level);
00571    /*! Callback to pointer for optional ICE support */
00572    struct ast_rtp_engine_ice *ice;
00573    /*! Callback to pointer for optional DTLS SRTP support */
00574    struct ast_rtp_engine_dtls *dtls;
00575    /*! Linked list information */
00576    AST_RWLIST_ENTRY(ast_rtp_engine) entry;
00577 };
00578 
00579 /*! Structure that represents codec and packetization information */
00580 struct ast_rtp_codecs {
00581    /*! Payloads present */
00582    AST_VECTOR(, struct ast_rtp_payload_type *) payloads;
00583    /*! The framing for this media session */
00584    unsigned int framing;
00585    /*! RW lock that protects elements in this structure */
00586    ast_rwlock_t codecs_lock;
00587 };
00588 
00589 #define AST_RTP_CODECS_NULL_INIT \
00590     { .payloads = { 0, }, .framing = 0, .codecs_lock = AST_RWLOCK_INIT_VALUE, }
00591 
00592 /*! Structure that represents the glue that binds an RTP instance to a channel */
00593 struct ast_rtp_glue {
00594    /*! Name of the channel driver that this glue is responsible for */
00595    const char *type;
00596    /*! Module that the RTP glue came from */
00597    struct ast_module *mod;
00598    /*!
00599     * \brief Callback for retrieving the RTP instance carrying audio
00600     * \note This function increases the reference count on the returned RTP instance.
00601     */
00602    enum ast_rtp_glue_result (*get_rtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00603    /*!
00604     * \brief Used to prevent two channels from remotely bridging audio rtp if the channel tech has a
00605     *        reason for prohibiting it based on qualities that need to be compared from both channels.
00606     * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, function this is not used.
00607     */
00608    int (*allow_rtp_remote)(struct ast_channel *chan1, struct ast_rtp_instance *instance);
00609    /*!
00610     * \brief Callback for retrieving the RTP instance carrying video
00611     * \note This function increases the reference count on the returned RTP instance.
00612     */
00613    enum ast_rtp_glue_result (*get_vrtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00614    /*!
00615     * \brief Used to prevent two channels from remotely bridging video rtp if the channel tech has a
00616     *        reason for prohibiting it based on qualities that need to be compared from both channels.
00617     * \note This function may be NULL for a given channel driver. This should be accounted for and if that is the case, this function is not used.
00618     */
00619    int (*allow_vrtp_remote)(struct ast_channel *chan1, struct ast_rtp_instance *instance);
00620 
00621    /*!
00622     * \brief Callback for retrieving the RTP instance carrying text
00623     * \note This function increases the reference count on the returned RTP instance.
00624     */
00625    enum ast_rtp_glue_result (*get_trtp_info)(struct ast_channel *chan, struct ast_rtp_instance **instance);
00626    /*! Callback for updating the destination that the remote side should send RTP to */
00627    int (*update_peer)(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_rtp_instance *vinstance, struct ast_rtp_instance *tinstance, const struct ast_format_cap *cap, int nat_active);
00628    /*! Callback for retrieving codecs that the channel can do.  Result returned in result_cap*/
00629    void (*get_codec)(struct ast_channel *chan, struct ast_format_cap *result_cap);
00630    /*! Linked list information */
00631    AST_RWLIST_ENTRY(ast_rtp_glue) entry;
00632 };
00633 
00634 /*!
00635  * \brief Allocation routine for \ref ast_rtp_payload_type
00636  *
00637  * \retval NULL on error
00638  * \retval An ao2 ref counted \c ast_rtp_payload_type on success.
00639  *
00640  * \note The \c ast_rtp_payload_type returned by this function is an
00641  *       ao2 ref counted object.
00642  *
00643  */
00644 struct ast_rtp_payload_type *ast_rtp_engine_alloc_payload_type(void);
00645 
00646 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self)
00647 
00648 /*!
00649  * \brief Register an RTP engine
00650  *
00651  * \param engine Structure of the RTP engine to register
00652  * \param module Module that the RTP engine is part of
00653  *
00654  * \retval 0 success
00655  * \retval -1 failure
00656  *
00657  * Example usage:
00658  *
00659  * \code
00660  * ast_rtp_engine_register2(&example_rtp_engine, NULL);
00661  * \endcode
00662  *
00663  * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not
00664  * associate a module with it.
00665  *
00666  * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is
00667  *       associated with the RTP engine and use counting is performed.
00668  *
00669  * \since 1.8
00670  */
00671 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module);
00672 
00673 /*!
00674  * \brief Unregister an RTP engine
00675  *
00676  * \param engine Structure of the RTP engine to unregister
00677  *
00678  * \retval 0 success
00679  * \retval -1 failure
00680  *
00681  * Example usage:
00682  *
00683  * \code
00684  * ast_rtp_engine_unregister(&example_rtp_engine);
00685  * \endcode
00686  *
00687  * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module
00688  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
00689  *
00690  * \since 1.8
00691  */
00692 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine);
00693 
00694 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res);
00695 
00696 void ast_rtp_engine_unregister_srtp(void);
00697 int ast_rtp_engine_srtp_is_registered(void);
00698 
00699 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self)
00700 
00701 /*!
00702  * \brief Register RTP glue
00703  *
00704  * \param glue The glue to register
00705  * \param module Module that the RTP glue is part of
00706  *
00707  * \retval 0 success
00708  * \retval -1 failure
00709  *
00710  * Example usage:
00711  *
00712  * \code
00713  * ast_rtp_glue_register2(&example_rtp_glue, NULL);
00714  * \endcode
00715  *
00716  * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not
00717  * associate a module with it.
00718  *
00719  * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is
00720  *       associated with the RTP glue and use counting is performed.
00721  *
00722  * \since 1.8
00723  */
00724 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module);
00725 
00726 /*!
00727  * \brief Unregister RTP glue
00728  *
00729  * \param glue The glue to unregister
00730  *
00731  * \retval 0 success
00732  * \retval -1 failure
00733  *
00734  * Example usage:
00735  *
00736  * \code
00737  * ast_rtp_glue_unregister(&example_rtp_glue);
00738  * \endcode
00739  *
00740  * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module
00741  * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use.
00742  *
00743  * \since 1.8
00744  */
00745 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue);
00746 
00747 /*!
00748  * \brief Create a new RTP instance
00749  *
00750  * \param engine_name Name of the engine to use for the RTP instance
00751  * \param sched Scheduler context that the RTP engine may want to use
00752  * \param sa Address we want to bind to
00753  * \param data Unique data for the engine
00754  *
00755  * \retval non-NULL success
00756  * \retval NULL failure
00757  *
00758  * Example usage:
00759  *
00760  * \code
00761  * struct ast_rtp_instance *instance = NULL;
00762  * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL);
00763  * \endcode
00764  *
00765  * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given
00766  * in the address structure.
00767  *
00768  * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use
00769  *       another depending on it's own configuration.
00770  *
00771  * \since 1.8
00772  */
00773 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name,
00774                 struct ast_sched_context *sched, const struct ast_sockaddr *sa,
00775                 void *data);
00776 
00777 /*!
00778  * \brief Destroy an RTP instance
00779  *
00780  * \param instance The RTP instance to destroy
00781  *
00782  * \retval 0 success
00783  * \retval -1 failure
00784  *
00785  * Example usage:
00786  *
00787  * \code
00788  * ast_rtp_instance_destroy(instance);
00789  * \endcode
00790  *
00791  * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid
00792  * memory and may not be used again.
00793  *
00794  * \since 1.8
00795  */
00796 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance);
00797 
00798 /*!
00799  * \brief Set the data portion of an RTP instance
00800  *
00801  * \param instance The RTP instance to manipulate
00802  * \param data Pointer to data
00803  *
00804  * Example usage:
00805  *
00806  * \code
00807  * ast_rtp_instance_set_data(instance, blob);
00808  * \endcode
00809  *
00810  * This sets the data pointer on the RTP instance pointed to by 'instance' to
00811  * blob.
00812  *
00813  * \since 1.8
00814  */
00815 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data);
00816 
00817 /*!
00818  * \brief Get the data portion of an RTP instance
00819  *
00820  * \param instance The RTP instance we want the data portion from
00821  *
00822  * Example usage:
00823  *
00824  * \code
00825  * struct *blob = ast_rtp_instance_get_data(instance);
00826  ( \endcode
00827  *
00828  * This gets the data pointer on the RTP instance pointed to by 'instance'.
00829  *
00830  * \since 1.8
00831  */
00832 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance);
00833 
00834 /*!
00835  * \brief Send a frame out over RTP
00836  *
00837  * \param instance The RTP instance to send frame out on
00838  * \param frame the frame to send out
00839  *
00840  * \retval 0 success
00841  * \retval -1 failure
00842  *
00843  * Example usage:
00844  *
00845  * \code
00846  * ast_rtp_instance_write(instance, frame);
00847  * \endcode
00848  *
00849  * This gives the frame pointed to by frame to the RTP engine being used for the instance
00850  * and asks that it be transmitted to the current remote address set on the RTP instance.
00851  *
00852  * \since 1.8
00853  */
00854 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame);
00855 
00856 /*!
00857  * \brief Receive a frame over RTP
00858  *
00859  * \param instance The RTP instance to receive frame on
00860  * \param rtcp Whether to read in RTCP or not
00861  *
00862  * \retval non-NULL success
00863  * \retval NULL failure
00864  *
00865  * Example usage:
00866  *
00867  * \code
00868  * struct ast_frame *frame;
00869  * frame = ast_rtp_instance_read(instance, 0);
00870  * \endcode
00871  *
00872  * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame.
00873  *
00874  * \since 1.8
00875  */
00876 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp);
00877 
00878 /*!
00879  * \brief Set the incoming source address of the remote endpoint that we are sending RTP to
00880  *
00881  * This sets the incoming source address the engine is sending RTP to. Usually this
00882  * will be the same as the requested target address, however in the case where
00883  * the engine "learns" the address (for instance, symmetric RTP enabled) this
00884  * will then contain the learned address.
00885  *
00886  * \param instance The RTP instance to change the address on
00887  * \param address Address to set it to
00888  *
00889  * \retval 0 success
00890  * \retval -1 failure
00891  */
00892 int ast_rtp_instance_set_incoming_source_address(struct ast_rtp_instance *instance,
00893                    const struct ast_sockaddr *address);
00894 
00895 /*!
00896  * \brief Set the requested target address of the remote endpoint
00897  *
00898  * This should always be the address of the remote endpoint. Consequently, this can differ
00899  * from the address the engine is sending RTP to.  However, usually they will be the same
00900  * except in some circumstances (for instance when the engine "learns" the address if
00901  * symmetric RTP is enabled).
00902  *
00903  * \param instance The RTP instance to change the address on
00904  * \param address Address to set it to
00905  *
00906  * \retval 0 success
00907  * \retval -1 failure
00908  */
00909 int ast_rtp_instance_set_requested_target_address(struct ast_rtp_instance *instance,
00910                     const struct ast_sockaddr *address);
00911 
00912 /*!
00913  * \brief Set the address of the remote endpoint that we are sending RTP to
00914  *
00915  * \param instance The RTP instance to change the address on
00916  * \param address Address to set it to
00917  *
00918  * \retval 0 success
00919  * \retval -1 failure
00920  *
00921  * Example usage:
00922  *
00923  * \code
00924  * ast_rtp_instance_set_remote_address(instance, &sin);
00925  * \endcode
00926  *
00927  * This changes the remote address that RTP will be sent to on instance to the address given in the sin
00928  * structure.
00929  *
00930  * \since 1.8
00931  */
00932 #define ast_rtp_instance_set_remote_address(instance, address) \
00933    ast_rtp_instance_set_requested_target_address((instance), (address));
00934 
00935 /*!
00936  * \brief Set the address that we are expecting to receive RTP on
00937  *
00938  * \param instance The RTP instance to change the address on
00939  * \param address Address to set it to
00940  *
00941  * \retval 0 success
00942  * \retval -1 failure
00943  *
00944  * Example usage:
00945  *
00946  * \code
00947  * ast_rtp_instance_set_local_address(instance, &sin);
00948  * \endcode
00949  *
00950  * This changes the local address that RTP is expected on to the address given in the sin
00951  * structure.
00952  *
00953  * \since 1.8
00954  */
00955 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance,
00956                 const struct ast_sockaddr *address);
00957 
00958 /*!
00959  * \brief Get the local address that we are expecting RTP on
00960  *
00961  * \param instance The RTP instance to get the address from
00962  * \param address The variable to store the address in
00963  *
00964  * Example usage:
00965  *
00966  * \code
00967  * struct ast_sockaddr address;
00968  * ast_rtp_instance_get_local_address(instance, &address);
00969  * \endcode
00970  *
00971  * This gets the local address that we are expecting RTP on and stores it in the 'address' structure.
00972  *
00973  * \since 1.8
00974  */
00975 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00976 
00977 /*!
00978  * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another
00979  *
00980  * \param instance The instance that we want to get the local address for
00981  * \param address An initialized address that may be overwritten if the local address is different
00982  *
00983  * \retval 0 address was not changed
00984  * \retval 1 address was changed
00985  * Example usage:
00986  *
00987  * \code
00988  * struct ast_sockaddr address;
00989  * int ret;
00990  * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address);
00991  * \endcode
00992  *
00993  * This retrieves the current local address set on the instance pointed to by instance and puts the value
00994  * into the address structure.
00995  *
00996  * \since 1.8
00997  */
00998 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
00999 
01000 /*!
01001  * \brief Get the incoming source address of the remote endpoint
01002  *
01003  * This returns the remote address the engine is sending RTP to. Usually this
01004  * will be the same as the requested target address, however in the case where
01005  * the engine "learns" the address (for instance, symmetric RTP enabled) this
01006  * will then contain the learned address.
01007  *
01008  * \param instance The instance that we want to get the incoming source address for
01009  * \param address A structure to put the address into
01010  */
01011 void ast_rtp_instance_get_incoming_source_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
01012 
01013 /*!
01014  * \brief Get the requested target address of the remote endpoint
01015  *
01016  * This returns the explicitly set address of a remote endpoint. Meaning this won't change unless
01017  * specifically told to change. In most cases this should be the same as the incoming source
01018  * address, except in cases where the engine "learns" the address in which case this and the
01019  * incoming source address might differ.
01020  *
01021  * \param instance The instance that we want to get the requested target address for
01022  * \param address A structure to put the address into
01023  */
01024 void ast_rtp_instance_get_requested_target_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
01025 
01026 /*!
01027  * \brief Get the address of the remote endpoint that we are sending RTP to
01028  *
01029  * \param instance The instance that we want to get the remote address for
01030  * \param address A structure to put the address into
01031  *
01032  * Example usage:
01033  *
01034  * \code
01035  * struct ast_sockaddr address;
01036  * ast_rtp_instance_get_remote_address(instance, &address);
01037  * \endcode
01038  *
01039  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
01040  * into the address structure.
01041  *
01042  * \since 1.8
01043  */
01044 #define ast_rtp_instance_get_remote_address(instance, address) \
01045    ast_rtp_instance_get_incoming_source_address((instance), (address));
01046 
01047 /*!
01048  * \brief Get the requested target address of the remote endpoint and
01049  *        compare it to the given address
01050  *
01051  * \param instance The instance that we want to get the remote address for
01052  * \param address An initialized address that may be overwritten addresses differ
01053  *
01054  * \retval 0 address was not changed
01055  * \retval 1 address was changed
01056  */
01057 int ast_rtp_instance_get_and_cmp_requested_target_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address);
01058 
01059 /*!
01060  * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another
01061  *
01062  * \param instance The instance that we want to get the remote address for
01063  * \param address An initialized address that may be overwritten if the remote address is different
01064  *
01065  * \retval 0 address was not changed
01066  * \retval 1 address was changed
01067  * Example usage:
01068  *
01069  * \code
01070  * struct ast_sockaddr address;
01071  * int ret;
01072  * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address);
01073  * \endcode
01074  *
01075  * This retrieves the current remote address set on the instance pointed to by instance and puts the value
01076  * into the address structure.
01077  *
01078  * \since 1.8
01079  */
01080 #define ast_rtp_instance_get_and_cmp_remote_address(instance, address) \
01081    ast_rtp_instance_get_and_cmp_requested_target_address((instance), (address));
01082 
01083 /*!
01084  * \brief Set the value of an RTP instance extended property
01085  *
01086  * \param instance The RTP instance to set the extended property on
01087  * \param property The extended property to set
01088  * \param value The value to set the extended property to
01089  *
01090  * \since 1.8
01091  */
01092 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value);
01093 
01094 /*!
01095  * \brief Get the value of an RTP instance extended property
01096  *
01097  * \param instance The RTP instance to get the extended property on
01098  * \param property The extended property to get
01099  *
01100  * \since 1.8
01101  */
01102 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property);
01103 
01104 /*!
01105  * \brief Set the value of an RTP instance property
01106  *
01107  * \param instance The RTP instance to set the property on
01108  * \param property The property to modify
01109  * \param value The value to set the property to
01110  *
01111  * Example usage:
01112  *
01113  * \code
01114  * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1);
01115  * \endcode
01116  *
01117  * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance.
01118  *
01119  * \since 1.8
01120  */
01121 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value);
01122 
01123 /*!
01124  * \brief Get the value of an RTP instance property
01125  *
01126  * \param instance The RTP instance to get the property from
01127  * \param property The property to get
01128  *
01129  * \retval Current value of the property
01130  *
01131  * Example usage:
01132  *
01133  * \code
01134  * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT);
01135  * \endcode
01136  *
01137  * This returns the current value of the NAT property on the instance pointed to by instance.
01138  *
01139  * \since 1.8
01140  */
01141 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property);
01142 
01143 /*!
01144  * \brief Get the codecs structure of an RTP instance
01145  *
01146  * \param instance The RTP instance to get the codecs structure from
01147  *
01148  * Example usage:
01149  *
01150  * \code
01151  * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance);
01152  * \endcode
01153  *
01154  * This gets the codecs structure on the RTP instance pointed to by 'instance'.
01155  *
01156  * \since 1.8
01157  */
01158 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance);
01159 
01160 /*!
01161  * \brief Initialize an RTP codecs structure
01162  *
01163  * \param codecs The codecs structure to initialize
01164  *
01165  * \retval 0 success
01166  * \retval -1 failure
01167  *
01168  * Example usage:
01169  *
01170  * \code
01171  * struct ast_rtp_codecs codecs;
01172  * ast_rtp_codecs_payloads_initialize(&codecs);
01173  * \endcode
01174  *
01175  * \since 11
01176  */
01177 int ast_rtp_codecs_payloads_initialize(struct ast_rtp_codecs *codecs);
01178 
01179 /*!
01180  * \brief Destroy the contents of an RTP codecs structure (but not the structure itself)
01181  *
01182  * \param codecs The codecs structure to destroy the contents of
01183  *
01184  * Example usage:
01185  *
01186  * \code
01187  * struct ast_rtp_codecs codecs;
01188  * ast_rtp_codecs_payloads_destroy(&codecs);
01189  * \endcode
01190  *
01191  * \since 11
01192  */
01193 void ast_rtp_codecs_payloads_destroy(struct ast_rtp_codecs *codecs);
01194 
01195 /*!
01196  * \brief Clear payload information from an RTP instance
01197  *
01198  * \param codecs The codecs structure that payloads will be cleared from
01199  * \param instance Optionally the instance that the codecs structure belongs to
01200  *
01201  * Example usage:
01202  *
01203  * \code
01204  * struct ast_rtp_codecs codecs;
01205  * ast_rtp_codecs_payloads_clear(&codecs, NULL);
01206  * \endcode
01207  *
01208  * This clears the codecs structure and puts it into a pristine state.
01209  *
01210  * \since 1.8
01211  */
01212 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance);
01213 
01214 /*!
01215  * \brief Copy payload information from one RTP instance to another
01216  *
01217  * \param src The source codecs structure
01218  * \param dest The destination codecs structure that the values from src will be copied to
01219  * \param instance Optionally the instance that the dst codecs structure belongs to
01220  *
01221  * Example usage:
01222  *
01223  * \code
01224  * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL);
01225  * \endcode
01226  *
01227  * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values.
01228  *
01229  * \since 1.8
01230  */
01231 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance);
01232 
01233 /*!
01234  * \brief Record payload information that was seen in an m= SDP line
01235  *
01236  * \param codecs The codecs structure to muck with
01237  * \param instance Optionally the instance that the codecs structure belongs to
01238  * \param payload Numerical payload that was seen in the m= SDP line
01239  *
01240  * Example usage:
01241  *
01242  * \code
01243  * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0);
01244  * \endcode
01245  *
01246  * This records that the numerical payload '0' was seen in the codecs structure.
01247  *
01248  * \since 1.8
01249  */
01250 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
01251 
01252 /*!
01253  * \brief Record payload information that was seen in an a=rtpmap: SDP line
01254  *
01255  * \param codecs The codecs structure to muck with
01256  * \param instance Optionally the instance that the codecs structure belongs to
01257  * \param payload Numerical payload that was seen in the a=rtpmap: SDP line
01258  * \param mimetype The string mime type that was seen
01259  * \param mimesubtype The strin mime sub type that was seen
01260  * \param options Optional options that may change the behavior of this specific payload
01261  *
01262  * \retval 0 success
01263  * \retval -1 failure, invalid payload numbe
01264  * \retval -2 failure, unknown mimetype
01265  *
01266  * Example usage:
01267  *
01268  * \code
01269  * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0);
01270  * \endcode
01271  *
01272  * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure.
01273  *
01274  * \since 1.8
01275  */
01276 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);
01277 
01278 /*!
01279  * \brief Set payload type to a known MIME media type for a codec with a specific sample rate
01280  *
01281  * \param codecs RTP structure to modify
01282  * \param instance Optionally the instance that the codecs structure belongs to
01283  * \param pt Payload type entry to modify
01284  * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.)
01285  * \param mimesubtype MIME subtype of media stream (typically a codec name)
01286  * \param options Zero or more flags from the ast_rtp_options enum
01287  * \param sample_rate The sample rate of the media stream
01288  *
01289  * This function 'fills in' an entry in the list of possible formats for
01290  * a media stream associated with an RTP structure.
01291  *
01292  * \retval 0 on success
01293  * \retval -1 if the payload type is out of range
01294  * \retval -2 if the mimeType/mimeSubtype combination was not found
01295  *
01296  * \since 1.8
01297  */
01298 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt,
01299               char *mimetype, char *mimesubtype,
01300               enum ast_rtp_options options,
01301               unsigned int sample_rate);
01302 
01303 /*!
01304  * \brief Remove payload information
01305  *
01306  * \param codecs The codecs structure to muck with
01307  * \param instance Optionally the instance that the codecs structure belongs to
01308  * \param payload Numerical payload to unset
01309  *
01310  * Example usage:
01311  *
01312  * \code
01313  * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0);
01314  * \endcode
01315  *
01316  * This clears the payload '0' from the codecs structure. It will be as if it was never set.
01317  *
01318  * \since 1.8
01319  */
01320 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload);
01321 
01322 /*!
01323  * \brief Retrieve payload information by payload
01324  *
01325  * \param codecs Codecs structure to look in
01326  * \param payload Numerical payload to look up
01327  *
01328  * \retval Payload information.
01329  * \retval NULL if payload does not exist.
01330  *
01331  * \note The payload returned by this function has its reference count increased.
01332  *       Callers are responsible for decrementing the reference count.
01333  *
01334  * Example usage:
01335  *
01336  * \code
01337  * struct ast_rtp_payload_type *payload_type;
01338  * payload_type = ast_rtp_codecs_get_payload(&codecs, 0);
01339  * \endcode
01340  *
01341  * This looks up the information for payload '0' from the codecs structure.
01342  */
01343 struct ast_rtp_payload_type *ast_rtp_codecs_get_payload(struct ast_rtp_codecs *codecs, int payload);
01344 
01345 /*!
01346  * \brief Update the format associated with a payload in a codecs structure
01347  *
01348  * \param codecs Codecs structure to operate on
01349  * \param payload Numerical payload to look up
01350  * \param format The format to replace the existing one
01351  *
01352  * \retval 0 success
01353  * \retval -1 failure
01354  *
01355  * \since 13
01356  */
01357 int ast_rtp_codecs_payload_replace_format(struct ast_rtp_codecs *codecs, int payload, struct ast_format *format);
01358 
01359 /*!
01360  * \brief Retrieve the actual ast_format stored on the codecs structure for a specific payload
01361  *
01362  * \param codecs Codecs structure to look in
01363  * \param payload Numerical payload to look up
01364  *
01365  * \retval pointer to format structure on success
01366  * \retval NULL on failure
01367  *
01368  * \note The format returned by this function has its reference count increased.
01369  *       Callers are responsible for decrementing the reference count.
01370  *
01371  * \since 10.0
01372  */
01373 struct ast_format *ast_rtp_codecs_get_payload_format(struct ast_rtp_codecs *codecs, int payload);
01374 
01375 /*!
01376  * \brief Set the framing used for a set of codecs
01377  *
01378  * \param codecs Codecs structure to set framing on
01379  * \param framing The framing value to set on the codecs
01380  *
01381  * \since 13.0.0
01382  */
01383 void ast_rtp_codecs_set_framing(struct ast_rtp_codecs *codecs, unsigned int framing);
01384 
01385 /*!
01386  * \brief Get the framing used for a set of codecs
01387  *
01388  * \param codecs Codecs structure to get the framing from
01389  *
01390  * \retval The framing to be used for the media stream associated with these codecs
01391  *
01392  * \since 13.0.0
01393  */
01394 unsigned int ast_rtp_codecs_get_framing(struct ast_rtp_codecs *codecs);
01395 
01396 /*!
01397  * \brief Get the sample rate associated with known RTP payload types
01398  *
01399  * \param asterisk_format True if the value in format is to be used.
01400  * \param format An asterisk format
01401  * \param code from AST_RTP list
01402  *
01403  * \return the sample rate if the format was found, zero if it was not found
01404  *
01405  * \since 1.8
01406  */
01407 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, struct ast_format *format, int code);
01408 
01409 /*!
01410  * \brief Retrieve all formats that were found
01411  *
01412  * \param codecs Codecs structure to look in
01413  * \param astformats A capabilities structure to put the Asterisk formats in.
01414  * \param nonastformats An integer to put the non-Asterisk formats in
01415  *
01416  * Example usage:
01417  *
01418  * \code
01419  * struct ast_format_cap *astformats = ast_format_cap_alloc_nolock()
01420  * int nonastformats;
01421  * ast_rtp_codecs_payload_formats(&codecs, &astformats, &nonastformats);
01422  * \endcode
01423  *
01424  * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer
01425  * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats.
01426  *
01427  * \since 1.8
01428  */
01429 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, struct ast_format_cap *astformats, int *nonastformats);
01430 
01431 /*!
01432  * \brief Retrieve a payload based on whether it is an Asterisk format and the code
01433  *
01434  * \param codecs Codecs structure to look in
01435  * \param asterisk_format Non-zero if the given Asterisk format is present
01436  * \param format Asterisk format to look for
01437  * \param code The format to look for
01438  *
01439  * \retval Numerical payload
01440  *
01441  * Example usage:
01442  *
01443  * \code
01444  * int payload = ast_rtp_codecs_payload_code(&codecs, 1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0);
01445  * \endcode
01446  *
01447  * This looks for the numerical payload for ULAW in the codecs structure.
01448  *
01449  * \since 1.8
01450  */
01451 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, int asterisk_format, const struct ast_format *format, int code);
01452 /*!
01453  * \brief Search for a payload code in the ast_rtp_codecs structure
01454  *
01455  * \param codecs Codecs structure to look in
01456  * \param code The format to look for
01457  *
01458  * \retval Numerical payload or -1 if unable to find payload in codecs
01459  *
01460  * Example usage:
01461  *
01462  * \code
01463  * int payload = ast_rtp_codecs_payload_code(&codecs, 0);
01464  * \endcode
01465  *
01466  * This looks for the numerical payload for ULAW in the codecs structure.
01467  *
01468  */
01469 int ast_rtp_codecs_find_payload_code(struct ast_rtp_codecs *codecs, int code);
01470 
01471 /*!
01472  * \brief Retrieve mime subtype information on a payload
01473  *
01474  * \param asterisk_format Non-zero to look up using Asterisk format
01475  * \param format Asterisk format to look up
01476  * \param code RTP code to look up
01477  * \param options Additional options that may change the result
01478  *
01479  * \retval Mime subtype success
01480  * \retval NULL failure
01481  *
01482  * Example usage:
01483  *
01484  * \code
01485  * const char *subtype = ast_rtp_lookup_mime_subtype2(1, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0), 0, 0);
01486  * \endcode
01487  *
01488  * This looks up the mime subtype for the ULAW format.
01489  *
01490  * \since 1.8
01491  */
01492 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, struct ast_format *format, int code, enum ast_rtp_options options);
01493 
01494 /*!
01495  * \brief Convert formats into a string and put them into a buffer
01496  *
01497  * \param buf Buffer to put the mime output into
01498  * \param ast_format_capability Asterisk Formats we are looking up.
01499  * \param rtp_capability RTP codes that we are looking up
01500  * \param asterisk_format Non-zero if the ast_format_capability structure is to be used, 0 if rtp_capability is to be used
01501  * \param options Additional options that may change the result
01502  *
01503  * \retval non-NULL success
01504  * \retval NULL failure
01505  *
01506  * Example usage:
01507  *
01508  * \code
01509  * char buf[256] = "";
01510  * struct ast_format tmp_fmt;
01511  * struct ast_format_cap *cap = ast_format_cap_alloc_nolock();
01512  * ast_format_cap_append(cap, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
01513  * ast_format_cap_append(cap, ast_format_set(&tmp_fmt, AST_FORMAT_GSM, 0));
01514  * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), cap, 0, 1, 0);
01515  * ast_format_cap_destroy(cap);
01516  * \endcode
01517  *
01518  * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf.
01519  *
01520  * \since 1.8
01521  */
01522 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, struct ast_format_cap *ast_format_capability, int rtp_capability, const int asterisk_format, enum ast_rtp_options options);
01523 
01524 /*!
01525  * \brief Begin sending a DTMF digit
01526  *
01527  * \param instance The RTP instance to send the DTMF on
01528  * \param digit What DTMF digit to send
01529  *
01530  * \retval 0 success
01531  * \retval -1 failure
01532  *
01533  * Example usage:
01534  *
01535  * \code
01536  * ast_rtp_instance_dtmf_begin(instance, '1');
01537  * \endcode
01538  *
01539  * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will
01540  * continue being sent until it is ended.
01541  *
01542  * \since 1.8
01543  */
01544 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit);
01545 
01546 /*!
01547  * \brief Stop sending a DTMF digit
01548  *
01549  * \param instance The RTP instance to stop the DTMF on
01550  * \param digit What DTMF digit to stop
01551  *
01552  * \retval 0 success
01553  * \retval -1 failure
01554  *
01555  * Example usage:
01556  *
01557  * \code
01558  * ast_rtp_instance_dtmf_end(instance, '1');
01559  * \endcode
01560  *
01561  * This stops sending the DTMF '1' on the RTP instance pointed to by instance.
01562  *
01563  * \since 1.8
01564  */
01565 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit);
01566 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration);
01567 
01568 /*!
01569  * \brief Set the DTMF mode that should be used
01570  *
01571  * \param instance the RTP instance to set DTMF mode on
01572  * \param dtmf_mode The DTMF mode that is in use
01573  *
01574  * \retval 0 success
01575  * \retval -1 failure
01576  *
01577  * Example usage:
01578  *
01579  * \code
01580  * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833);
01581  * \endcode
01582  *
01583  * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving.
01584  *
01585  * \since 1.8
01586  */
01587 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode);
01588 
01589 /*!
01590  * \brief Get the DTMF mode of an RTP instance
01591  *
01592  * \param instance The RTP instance to get the DTMF mode of
01593  *
01594  * \retval DTMF mode
01595  *
01596  * Example usage:
01597  *
01598  * \code
01599  * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance);
01600  * \endcode
01601  *
01602  * This gets the DTMF mode set on the RTP instance pointed to by 'instance'.
01603  *
01604  * \since 1.8
01605  */
01606 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance);
01607 
01608 /*!
01609  * \brief Indicate that the RTP marker bit should be set on an RTP stream
01610  *
01611  * \param instance Instance that the new media source is feeding into
01612  *
01613  * Example usage:
01614  *
01615  * \code
01616  * ast_rtp_instance_update_source(instance);
01617  * \endcode
01618  *
01619  * This indicates that the source of media that is feeding the instance pointed to by
01620  * instance has been updated and that the marker bit should be set.
01621  *
01622  * \since 1.8
01623  */
01624 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance);
01625 
01626 /*!
01627  * \brief Indicate a new source of audio has dropped in and the ssrc should change
01628  *
01629  * \param instance Instance that the new media source is feeding into
01630  *
01631  * Example usage:
01632  *
01633  * \code
01634  * ast_rtp_instance_change_source(instance);
01635  * \endcode
01636  *
01637  * This indicates that the source of media that is feeding the instance pointed to by
01638  * instance has changed and that the marker bit should be set and the SSRC updated.
01639  *
01640  * \since 1.8
01641  */
01642 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance);
01643 
01644 /*!
01645  * \brief Set QoS parameters on an RTP session
01646  *
01647  * \param instance Instance to set the QoS parameters on
01648  * \param tos Terms of service value
01649  * \param cos Class of service value
01650  * \param desc What is setting the QoS values
01651  *
01652  * \retval 0 success
01653  * \retval -1 failure
01654  *
01655  * Example usage:
01656  *
01657  * \code
01658  * ast_rtp_instance_set_qos(instance, 0, 0, "Example");
01659  * \endcode
01660  *
01661  * This sets the TOS and COS values to 0 on the instance pointed to by instance.
01662  *
01663  * \since 1.8
01664  */
01665 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc);
01666 
01667 /*!
01668  * \brief Stop an RTP instance
01669  *
01670  * \param instance Instance that media is no longer going to at this time
01671  *
01672  * Example usage:
01673  *
01674  * \code
01675  * ast_rtp_instance_stop(instance);
01676  * \endcode
01677  *
01678  * This tells the RTP engine being used for the instance pointed to by instance
01679  * that media is no longer going to it at this time, but may in the future.
01680  *
01681  * \since 1.8
01682  */
01683 void ast_rtp_instance_stop(struct ast_rtp_instance *instance);
01684 
01685 /*!
01686  * \brief Get the file descriptor for an RTP session (or RTCP)
01687  *
01688  * \param instance Instance to get the file descriptor for
01689  * \param rtcp Whether to retrieve the file descriptor for RTCP or not
01690  *
01691  * \retval fd success
01692  * \retval -1 failure
01693  *
01694  * Example usage:
01695  *
01696  * \code
01697  * int rtp_fd = ast_rtp_instance_fd(instance, 0);
01698  * \endcode
01699  *
01700  * This retrieves the file descriptor for the socket carrying media on the instance
01701  * pointed to by instance.
01702  *
01703  * \since 1.8
01704  */
01705 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp);
01706 
01707 /*!
01708  * \brief Get the RTP glue that binds a channel to the RTP engine
01709  *
01710  * \param type Name of the glue we want
01711  *
01712  * \retval non-NULL success
01713  * \retval NULL failure
01714  *
01715  * Example usage:
01716  *
01717  * \code
01718  * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example");
01719  * \endcode
01720  *
01721  * This retrieves the RTP glue that has the name 'Example'.
01722  *
01723  * \since 1.8
01724  */
01725 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type);
01726 
01727 /*!
01728  * \brief Get the unique ID of the channel that owns this RTP instance
01729  *
01730  * Note that this should remain valid for the lifetime of the RTP instance.
01731  *
01732  * \param instance The RTP instance
01733  *
01734  * \retval The unique ID of the channel
01735  * \retval Empty string if no channel owns this RTP instance
01736  *
01737  * \since 12
01738  */
01739 const char *ast_rtp_instance_get_channel_id(struct ast_rtp_instance *instance);
01740 
01741 /*!
01742  * \brief Set the channel that owns this RTP instance
01743  *
01744  * \param instance The RTP instance
01745  * \param uniqueid The uniqueid of the channel
01746  *
01747  * \since 12
01748  */
01749 void ast_rtp_instance_set_channel_id(struct ast_rtp_instance *instance, const char *uniqueid);
01750 
01751 /*!
01752  * \brief Get the other RTP instance that an instance is bridged to
01753  *
01754  * \param instance The RTP instance that we want
01755  *
01756  * \retval non-NULL success
01757  * \retval NULL failure
01758  *
01759  * Example usage:
01760  *
01761  * \code
01762  * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0);
01763  * \endcode
01764  *
01765  * This gets the RTP instance that instance0 is bridged to.
01766  *
01767  * \since 1.8
01768  */
01769 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance);
01770 
01771 /*!
01772  * \brief Set the other RTP instance that an instance is bridged to
01773  *
01774  * \param instance The RTP instance that we want to set the bridged value on
01775  * \param bridged The RTP instance they are bridged to
01776  *
01777  * \since 12
01778  */
01779 void ast_rtp_instance_set_bridged(struct ast_rtp_instance *instance, struct ast_rtp_instance *bridged);
01780 
01781 /*!
01782  * \brief Make two channels compatible for early bridging
01783  *
01784  * \param c_dst Destination channel to copy to
01785  * \param c_src Source channel to copy from
01786  *
01787  * \since 1.8
01788  */
01789 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c_dst, struct ast_channel *c_src);
01790 
01791 /*!
01792  * \brief Early bridge two channels that use RTP instances
01793  *
01794  * \param c0 First channel part of the bridge
01795  * \param c1 Second channel part of the bridge
01796  *
01797  * \retval 0 success
01798  * \retval -1 failure
01799  *
01800  * \note This should only be used by channel drivers in their technology declaration.
01801  *
01802  * \since 1.8
01803  */
01804 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
01805 
01806 /*!
01807  * \brief Initialize RED support on an RTP instance
01808  *
01809  * \param instance The instance to initialize RED support on
01810  * \param buffer_time How long to buffer before sending
01811  * \param payloads Payload values
01812  * \param generations Number of generations
01813  *
01814  * \retval 0 success
01815  * \retval -1 failure
01816  *
01817  * \since 1.8
01818  */
01819 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations);
01820 
01821 /*!
01822  * \brief Buffer a frame in an RTP instance for RED
01823  *
01824  * \param instance The instance to buffer the frame on
01825  * \param frame Frame that we want to buffer
01826  *
01827  * \retval 0 success
01828  * \retval -1 failure
01829  *
01830  * \since 1.8
01831  */
01832 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame);
01833 
01834 /*!
01835  * \brief Retrieve statistics about an RTP instance
01836  *
01837  * \param instance Instance to get statistics on
01838  * \param stats Structure to put results into
01839  * \param stat What statistic(s) to retrieve
01840  *
01841  * \retval 0 success
01842  * \retval -1 failure
01843  *
01844  * Example usage:
01845  *
01846  * \code
01847  * struct ast_rtp_instance_stats stats;
01848  * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL);
01849  * \endcode
01850  *
01851  * This retrieves all statistics the underlying RTP engine supports and puts the values into the
01852  * stats structure.
01853  *
01854  * \since 1.8
01855  */
01856 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat);
01857 
01858 /*!
01859  * \brief Set standard statistics from an RTP instance on a channel
01860  *
01861  * \param chan Channel to set the statistics on
01862  * \param instance The RTP instance that statistics will be retrieved from
01863  *
01864  * \note Absolutely _NO_ channel locks should be held before calling this function.
01865  *
01866  * Example usage:
01867  *
01868  * \code
01869  * ast_rtp_instance_set_stats_vars(chan, rtp);
01870  * \endcode
01871  *
01872  * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to
01873  * by chan.
01874  *
01875  * \since 1.8
01876  */
01877 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance);
01878 
01879 /*!
01880  * \brief Retrieve quality statistics about an RTP instance
01881  *
01882  * \param instance Instance to get statistics on
01883  * \param field What quality statistic to retrieve
01884  * \param buf What buffer to put the result into
01885  * \param size Size of the above buffer
01886  *
01887  * \retval non-NULL success
01888  * \retval NULL failure
01889  *
01890  * Example usage:
01891  *
01892  * \code
01893  * char quality[AST_MAX_USER_FIELD];
01894  * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf));
01895  * \endcode
01896  *
01897  * This retrieves general quality statistics and places a text representation into the buf pointed to by buf.
01898  *
01899  * \since 1.8
01900  */
01901 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size);
01902 
01903 /*!
01904  * \brief Request that the underlying RTP engine provide audio frames in a specific format
01905  *
01906  * \param instance The RTP instance to change read format on
01907  * \param format Format that frames are wanted in
01908  *
01909  * \retval 0 success
01910  * \retval -1 failure
01911  *
01912  * Example usage:
01913  *
01914  * \code
01915  * struct ast_format tmp_fmt;
01916  * ast_rtp_instance_set_read_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
01917  * \endcode
01918  *
01919  * This requests that the RTP engine provide audio frames in the ULAW format.
01920  *
01921  * \since 1.8
01922  */
01923 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, struct ast_format *format);
01924 
01925 /*!
01926  * \brief Tell underlying RTP engine that audio frames will be provided in a specific format
01927  *
01928  * \param instance The RTP instance to change write format on
01929  * \param format Format that frames will be provided in
01930  *
01931  * \retval 0 success
01932  * \retval -1 failure
01933  *
01934  * Example usage:
01935  *
01936  * \code
01937  * struct ast_format tmp_fmt;
01938  * ast_rtp_instance_set_write_format(instance, ast_format_set(&tmp_fmt, AST_FORMAT_ULAW, 0));
01939  * \endcode
01940  *
01941  * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format.
01942  *
01943  * \since 1.8
01944  */
01945 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, struct ast_format *format);
01946 
01947 /*!
01948  * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother
01949  *
01950  * \param chan Our own Asterisk channel
01951  * \param instance The first RTP instance
01952  * \param peer The peer Asterisk channel
01953  *
01954  * \retval 0 success
01955  * \retval -1 failure
01956  *
01957  * Example usage:
01958  *
01959  * \code
01960  * ast_rtp_instance_make_compatible(instance, peer);
01961  * \endcode
01962  *
01963  * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa.
01964  *
01965  * \since 1.8
01966  */
01967 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer);
01968 
01969 /*! \brief Request the formats that can be transcoded
01970  *
01971  * \param instance The RTP instance
01972  * \param to_endpoint Formats being sent/received towards the endpoint
01973  * \param to_asterisk Formats being sent/received towards Asterisk
01974  * \param result capabilities structure to store and return supported formats in.
01975  *
01976  * Example usage:
01977  *
01978  * \code
01979  * ast_rtp_instance_available_formats(instance, to_capabilities, from_capabilities, result_capabilities);
01980  * \endcode
01981  *
01982  * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk.
01983  *
01984  * \since 1.8
01985  */
01986 void ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, struct ast_format_cap *to_endpoint, struct ast_format_cap *to_asterisk, struct ast_format_cap *result);
01987 
01988 /*!
01989  * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance
01990  *
01991  * \param instance The RTP instance
01992  *
01993  * \retval 0 success
01994  * \retval -1 failure
01995  *
01996  * Example usage:
01997  *
01998  * \code
01999  * ast_rtp_instance_activate(instance);
02000  * \endcode
02001  *
02002  * This tells the underlying RTP engine of instance that packets will now flow.
02003  *
02004  * \since 1.8
02005  */
02006 int ast_rtp_instance_activate(struct ast_rtp_instance *instance);
02007 
02008 /*!
02009  * \brief Request that the underlying RTP engine send a STUN BIND request
02010  *
02011  * \param instance The RTP instance
02012  * \param suggestion The suggested destination
02013  * \param username Optionally a username for the request
02014  *
02015  * Example usage:
02016  *
02017  * \code
02018  * ast_rtp_instance_stun_request(instance, NULL, NULL);
02019  * \endcode
02020  *
02021  * This requests that the RTP engine send a STUN BIND request on the session pointed to by
02022  * 'instance'.
02023  *
02024  * \since 1.8
02025  */
02026 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username);
02027 
02028 /*!
02029  * \brief Set the RTP timeout value
02030  *
02031  * \param instance The RTP instance
02032  * \param timeout Value to set the timeout to
02033  *
02034  * Example usage:
02035  *
02036  * \code
02037  * ast_rtp_instance_set_timeout(instance, 5000);
02038  * \endcode
02039  *
02040  * This sets the RTP timeout value on 'instance' to be 5000.
02041  *
02042  * \since 1.8
02043  */
02044 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout);
02045 
02046 /*!
02047  * \brief Set the RTP timeout value for when the instance is on hold
02048  *
02049  * \param instance The RTP instance
02050  * \param timeout Value to set the timeout to
02051  *
02052  * Example usage:
02053  *
02054  * \code
02055  * ast_rtp_instance_set_hold_timeout(instance, 5000);
02056  * \endcode
02057  *
02058  * This sets the RTP hold timeout value on 'instance' to be 5000.
02059  *
02060  * \since 1.8
02061  */
02062 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout);
02063 
02064 /*!
02065  * \brief Set the RTP keepalive interval
02066  *
02067  * \param instance The RTP instance
02068  * \param timeout Value to set the keepalive interval to
02069  *
02070  * Example usage:
02071  *
02072  * \code
02073  * ast_rtp_instance_set_keepalive(instance, 5000);
02074  * \endcode
02075  *
02076  * This sets the RTP keepalive interval on 'instance' to be 5000.
02077  *
02078  * \since 1.8
02079  */
02080 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout);
02081 
02082 /*!
02083  * \brief Get the RTP timeout value
02084  *
02085  * \param instance The RTP instance
02086  *
02087  * \retval timeout value
02088  *
02089  * Example usage:
02090  *
02091  * \code
02092  * int timeout = ast_rtp_instance_get_timeout(instance);
02093  * \endcode
02094  *
02095  * This gets the RTP timeout value for the RTP instance pointed to by 'instance'.
02096  *
02097  * \since 1.8
02098  */
02099 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance);
02100 
02101 /*!
02102  * \brief Get the RTP timeout value for when an RTP instance is on hold
02103  *
02104  * \param instance The RTP instance
02105  *
02106  * \retval timeout value
02107  *
02108  * Example usage:
02109  *
02110  * \code
02111  * int timeout = ast_rtp_instance_get_hold_timeout(instance);
02112  * \endcode
02113  *
02114  * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'.
02115  *
02116  * \since 1.8
02117  */
02118 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance);
02119 
02120 /*!
02121  * \brief Get the RTP keepalive interval
02122  *
02123  * \param instance The RTP instance
02124  *
02125  * \retval period Keepalive interval value
02126  *
02127  * Example usage:
02128  *
02129  * \code
02130  * int interval = ast_rtp_instance_get_keepalive(instance);
02131  * \endcode
02132  *
02133  * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'.
02134  *
02135  * \since 1.8
02136  */
02137 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance);
02138 
02139 /*!
02140  * \brief Get the RTP engine in use on an RTP instance
02141  *
02142  * \param instance The RTP instance
02143  *
02144  * \retval pointer to the engine
02145  *
02146  * Example usage:
02147  *
02148  * \code
02149  * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance);
02150  * \endcode
02151  *
02152  * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'.
02153  *
02154  * \since 1.8
02155  */
02156 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance);
02157 
02158 /*!
02159  * \brief Get the RTP glue in use on an RTP instance
02160  *
02161  * \param instance The RTP instance
02162  *
02163  * \retval pointer to the glue
02164  *
02165  * Example:
02166  *
02167  * \code
02168  * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance);
02169  * \endcode
02170  *
02171  * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'.
02172  *
02173  * \since 1.8
02174  */
02175 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance);
02176 
02177 /*!
02178  * \brief Send a comfort noise packet to the RTP instance
02179  *
02180  * \param instance The RTP instance
02181  * \param level Magnitude of the noise level
02182  *
02183  * \retval 0 Success
02184  * \retval non-zero Failure
02185  */
02186 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level);
02187 
02188 /*!
02189  * \brief Add or replace the SRTP policies for the given RTP instance
02190  *
02191  * \param instance the RTP instance
02192  * \param remote_policy the remote endpoint's policy
02193  * \param local_policy our policy for this RTP instance's remote endpoint
02194  *
02195  * \retval 0 Success
02196  * \retval non-zero Failure
02197  */
02198 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy* remote_policy, struct ast_srtp_policy *local_policy);
02199 
02200 /*!
02201  * \brief Obtain the SRTP instance associated with an RTP instance
02202  *
02203  * \param instance the RTP instance
02204  * \retval the SRTP instance on success
02205  * \retval NULL if no SRTP instance exists
02206  */
02207 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance);
02208 
02209 /*! \brief Custom formats declared in codecs.conf at startup must be communicated to the rtp_engine
02210  * so their mime type can payload number can be initialized. */
02211 int ast_rtp_engine_load_format(struct ast_format *format);
02212 
02213 /*! \brief Formats requiring the use of a format attribute interface must have that
02214  * interface registered in order for the rtp engine to handle it correctly.  If an
02215  * attribute interface is unloaded, this function must be called to notify the rtp_engine. */
02216 int ast_rtp_engine_unload_format(struct ast_format *format);
02217 
02218 /*!
02219  * \brief Obtain a pointer to the ICE support present on an RTP instance
02220  *
02221  * \param instance the RTP instance
02222  *
02223  * \retval ICE support if present
02224  * \retval NULL if no ICE support available
02225  */
02226 struct ast_rtp_engine_ice *ast_rtp_instance_get_ice(struct ast_rtp_instance *instance);
02227 
02228 /*!
02229  * \brief Obtain a pointer to the DTLS support present on an RTP instance
02230  *
02231  * \param instance the RTP instance
02232  *
02233  * \retval DTLS support if present
02234  * \retval NULL if no DTLS support available
02235  */
02236 struct ast_rtp_engine_dtls *ast_rtp_instance_get_dtls(struct ast_rtp_instance *instance);
02237 
02238 /*!
02239  * \brief Parse DTLS related configuration options
02240  *
02241  * \param dtls_cfg a DTLS configuration structure
02242  * \param name name of the configuration option
02243  * \param value value of the configuration option
02244  *
02245  * \retval 0 if handled
02246  * \retval -1 if not handled
02247  */
02248 int ast_rtp_dtls_cfg_parse(struct ast_rtp_dtls_cfg *dtls_cfg, const char *name, const char *value);
02249 
02250 /*!
02251  * \brief Copy contents of a DTLS configuration structure
02252  *
02253  * \param src_cfg source DTLS configuration structure
02254  * \param dst_cfg destination DTLS configuration structure
02255  */
02256 void ast_rtp_dtls_cfg_copy(const struct ast_rtp_dtls_cfg *src_cfg, struct ast_rtp_dtls_cfg *dst_cfg);
02257 
02258 /*!
02259  * \brief Free contents of a DTLS configuration structure
02260  *
02261  * \param dtls_cfg a DTLS configuration structure
02262  */
02263 void ast_rtp_dtls_cfg_free(struct ast_rtp_dtls_cfg *dtls_cfg);
02264 
02265 struct ast_json;
02266 
02267 /*!
02268  * \brief Allocate an ao2 ref counted instance of \ref ast_rtp_rtcp_report
02269  *
02270  * \param report_blocks The number of report blocks to allocate
02271  * \retval An ao2 ref counted \ref ast_rtp_rtcp_report object on success
02272  * \retval NULL on error
02273  */
02274 struct ast_rtp_rtcp_report *ast_rtp_rtcp_report_alloc(unsigned int report_blocks);
02275 
02276 /*!
02277  * \since 12
02278  * \brief Publish an RTCP message to \ref stasis
02279  *
02280  * \param rtp The rtp instance object
02281  * \param message_type The RTP message type to publish
02282  * \param report The RTCP report object to publish. This should be an ao2 ref counted
02283  *  object. This routine will increase the reference count of the object.
02284  * \param blob Additional JSON objects to publish along with the RTCP information
02285  */
02286 void ast_rtp_publish_rtcp_message(struct ast_rtp_instance *rtp,
02287       struct stasis_message_type *message_type,
02288       struct ast_rtp_rtcp_report *report,
02289       struct ast_json *blob);
02290 
02291 /*! \addtogroup StasisTopicsAndMessages
02292  * @{
02293  */
02294 
02295 /*!
02296  * \since 12
02297  * \brief Message type for an RTCP message sent from this Asterisk instance
02298  *
02299  * \retval A stasis message type
02300  */
02301 struct stasis_message_type *ast_rtp_rtcp_sent_type(void);
02302 
02303 /*!
02304  * \since 12
02305  * \brief Message type for an RTCP message received from some external source
02306  *
02307  * \retval A stasis message type
02308  */
02309 struct stasis_message_type *ast_rtp_rtcp_received_type(void);
02310 
02311 /*!
02312  * \since 12
02313  * \brief \ref stasis topic for RTP and RTCP related messages
02314  *
02315  * \retval A \ref stasis topic
02316  */
02317 struct stasis_topic *ast_rtp_topic(void);
02318 
02319 /* }@ */
02320 
02321 #if defined(__cplusplus) || defined(c_plusplus)
02322 }
02323 #endif
02324 
02325 #endif /* _ASTERISK_RTP_ENGINE_H */

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