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