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