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 int (*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 format_t (*get_codec)(struct ast_channel *chan); 00417 /*! Linked list information */ 00418 AST_RWLIST_ENTRY(ast_rtp_glue) entry; 00419 }; 00420 00421 #define ast_rtp_engine_register(engine) ast_rtp_engine_register2(engine, ast_module_info->self) 00422 00423 /*! 00424 * \brief Register an RTP engine 00425 * 00426 * \param engine Structure of the RTP engine to register 00427 * \param module Module that the RTP engine is part of 00428 * 00429 * \retval 0 success 00430 * \retval -1 failure 00431 * 00432 * Example usage: 00433 * 00434 * \code 00435 * ast_rtp_engine_register2(&example_rtp_engine, NULL); 00436 * \endcode 00437 * 00438 * This registers the RTP engine declared as example_rtp_engine with the RTP engine core, but does not 00439 * associate a module with it. 00440 * 00441 * \note It is recommended that you use the ast_rtp_engine_register macro so that the module is 00442 * associated with the RTP engine and use counting is performed. 00443 * 00444 * \since 1.8 00445 */ 00446 int ast_rtp_engine_register2(struct ast_rtp_engine *engine, struct ast_module *module); 00447 00448 /*! 00449 * \brief Unregister an RTP engine 00450 * 00451 * \param engine Structure of the RTP engine to unregister 00452 * 00453 * \retval 0 success 00454 * \retval -1 failure 00455 * 00456 * Example usage: 00457 * 00458 * \code 00459 * ast_rtp_engine_unregister(&example_rtp_engine); 00460 * \endcode 00461 * 00462 * This unregisters the RTP engine declared as example_rtp_engine from the RTP engine core. If a module 00463 * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use. 00464 * 00465 * \since 1.8 00466 */ 00467 int ast_rtp_engine_unregister(struct ast_rtp_engine *engine); 00468 00469 int ast_rtp_engine_register_srtp(struct ast_srtp_res *srtp_res, struct ast_srtp_policy_res *policy_res); 00470 00471 void ast_rtp_engine_unregister_srtp(void); 00472 int ast_rtp_engine_srtp_is_registered(void); 00473 00474 #define ast_rtp_glue_register(glue) ast_rtp_glue_register2(glue, ast_module_info->self) 00475 00476 /*! 00477 * \brief Register RTP glue 00478 * 00479 * \param glue The glue to register 00480 * \param module Module that the RTP glue is part of 00481 * 00482 * \retval 0 success 00483 * \retval -1 failure 00484 * 00485 * Example usage: 00486 * 00487 * \code 00488 * ast_rtp_glue_register2(&example_rtp_glue, NULL); 00489 * \endcode 00490 * 00491 * This registers the RTP glue declared as example_rtp_glue with the RTP engine core, but does not 00492 * associate a module with it. 00493 * 00494 * \note It is recommended that you use the ast_rtp_glue_register macro so that the module is 00495 * associated with the RTP glue and use counting is performed. 00496 * 00497 * \since 1.8 00498 */ 00499 int ast_rtp_glue_register2(struct ast_rtp_glue *glue, struct ast_module *module); 00500 00501 /*! 00502 * \brief Unregister RTP glue 00503 * 00504 * \param glue The glue to unregister 00505 * 00506 * \retval 0 success 00507 * \retval -1 failure 00508 * 00509 * Example usage: 00510 * 00511 * \code 00512 * ast_rtp_glue_unregister(&example_rtp_glue); 00513 * \endcode 00514 * 00515 * This unregisters the RTP glue declared as example_rtp_gkue from the RTP engine core. If a module 00516 * reference was provided when it was registered then this will only be called once the RTP engine is no longer in use. 00517 * 00518 * \since 1.8 00519 */ 00520 int ast_rtp_glue_unregister(struct ast_rtp_glue *glue); 00521 00522 /*! 00523 * \brief Create a new RTP instance 00524 * 00525 * \param engine_name Name of the engine to use for the RTP instance 00526 * \param sched Scheduler context that the RTP engine may want to use 00527 * \param sa Address we want to bind to 00528 * \param data Unique data for the engine 00529 * 00530 * \retval non-NULL success 00531 * \retval NULL failure 00532 * 00533 * Example usage: 00534 * 00535 * \code 00536 * struct ast_rtp_instance *instance = NULL; 00537 * instance = ast_rtp_instance_new(NULL, sched, &sin, NULL); 00538 * \endcode 00539 * 00540 * This creates a new RTP instance using the default engine and asks the RTP engine to bind to the address given 00541 * in the address structure. 00542 * 00543 * \note The RTP engine does not have to use the address provided when creating an RTP instance. It may choose to use 00544 * another depending on it's own configuration. 00545 * 00546 * \since 1.8 00547 */ 00548 struct ast_rtp_instance *ast_rtp_instance_new(const char *engine_name, 00549 struct sched_context *sched, const struct ast_sockaddr *sa, 00550 void *data); 00551 00552 /*! 00553 * \brief Destroy an RTP instance 00554 * 00555 * \param instance The RTP instance to destroy 00556 * 00557 * \retval 0 success 00558 * \retval -1 failure 00559 * 00560 * Example usage: 00561 * 00562 * \code 00563 * ast_rtp_instance_destroy(instance); 00564 * \endcode 00565 * 00566 * This destroys the RTP instance pointed to by instance. Once this function returns instance no longer points to valid 00567 * memory and may not be used again. 00568 * 00569 * \since 1.8 00570 */ 00571 int ast_rtp_instance_destroy(struct ast_rtp_instance *instance); 00572 00573 /*! 00574 * \brief Set the data portion of an RTP instance 00575 * 00576 * \param instance The RTP instance to manipulate 00577 * \param data Pointer to data 00578 * 00579 * Example usage: 00580 * 00581 * \code 00582 * ast_rtp_instance_set_data(instance, blob); 00583 * \endcode 00584 * 00585 * This sets the data pointer on the RTP instance pointed to by 'instance' to 00586 * blob. 00587 * 00588 * \since 1.8 00589 */ 00590 void ast_rtp_instance_set_data(struct ast_rtp_instance *instance, void *data); 00591 00592 /*! 00593 * \brief Get the data portion of an RTP instance 00594 * 00595 * \param instance The RTP instance we want the data portion from 00596 * 00597 * Example usage: 00598 * 00599 * \code 00600 * struct *blob = ast_rtp_instance_get_data(instance); 00601 ( \endcode 00602 * 00603 * This gets the data pointer on the RTP instance pointed to by 'instance'. 00604 * 00605 * \since 1.8 00606 */ 00607 void *ast_rtp_instance_get_data(struct ast_rtp_instance *instance); 00608 00609 /*! 00610 * \brief Send a frame out over RTP 00611 * 00612 * \param instance The RTP instance to send frame out on 00613 * \param frame the frame to send out 00614 * 00615 * \retval 0 success 00616 * \retval -1 failure 00617 * 00618 * Example usage: 00619 * 00620 * \code 00621 * ast_rtp_instance_write(instance, frame); 00622 * \endcode 00623 * 00624 * This gives the frame pointed to by frame to the RTP engine being used for the instance 00625 * and asks that it be transmitted to the current remote address set on the RTP instance. 00626 * 00627 * \since 1.8 00628 */ 00629 int ast_rtp_instance_write(struct ast_rtp_instance *instance, struct ast_frame *frame); 00630 00631 /*! 00632 * \brief Receive a frame over RTP 00633 * 00634 * \param instance The RTP instance to receive frame on 00635 * \param rtcp Whether to read in RTCP or not 00636 * 00637 * \retval non-NULL success 00638 * \retval NULL failure 00639 * 00640 * Example usage: 00641 * 00642 * \code 00643 * struct ast_frame *frame; 00644 * frame = ast_rtp_instance_read(instance, 0); 00645 * \endcode 00646 * 00647 * This asks the RTP engine to read in RTP from the instance and return it as an Asterisk frame. 00648 * 00649 * \since 1.8 00650 */ 00651 struct ast_frame *ast_rtp_instance_read(struct ast_rtp_instance *instance, int rtcp); 00652 00653 /*! 00654 * \brief Set the address of the remote endpoint that we are sending RTP to 00655 * 00656 * \param instance The RTP instance to change the address on 00657 * \param address Address to set it to 00658 * 00659 * \retval 0 success 00660 * \retval -1 failure 00661 * 00662 * Example usage: 00663 * 00664 * \code 00665 * ast_rtp_instance_set_remote_address(instance, &sin); 00666 * \endcode 00667 * 00668 * This changes the remote address that RTP will be sent to on instance to the address given in the sin 00669 * structure. 00670 * 00671 * \since 1.8 00672 */ 00673 int ast_rtp_instance_set_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address); 00674 00675 00676 /*! 00677 * \brief Set the address of an an alternate RTP address to receive from 00678 * 00679 * \param instance The RTP instance to change the address on 00680 * \param address Address to set it to 00681 * 00682 * \retval 0 success 00683 * \retval -1 failure 00684 * 00685 * Example usage: 00686 * 00687 * \code 00688 * ast_rtp_instance_set_alt_remote_address(instance, &address); 00689 * \endcode 00690 * 00691 * This changes the alternate remote address that RTP will be sent to on instance to the address given in the sin 00692 * structure. 00693 * 00694 * \since 1.8 00695 */ 00696 int ast_rtp_instance_set_alt_remote_address(struct ast_rtp_instance *instance, const struct ast_sockaddr *address); 00697 00698 /*! 00699 * \brief Set the address that we are expecting to receive RTP on 00700 * 00701 * \param instance The RTP instance to change the address on 00702 * \param address Address to set it to 00703 * 00704 * \retval 0 success 00705 * \retval -1 failure 00706 * 00707 * Example usage: 00708 * 00709 * \code 00710 * ast_rtp_instance_set_local_address(instance, &sin); 00711 * \endcode 00712 * 00713 * This changes the local address that RTP is expected on to the address given in the sin 00714 * structure. 00715 * 00716 * \since 1.8 00717 */ 00718 int ast_rtp_instance_set_local_address(struct ast_rtp_instance *instance, 00719 const struct ast_sockaddr *address); 00720 00721 /*! 00722 * \brief Get the local address that we are expecting RTP on 00723 * 00724 * \param instance The RTP instance to get the address from 00725 * \param address The variable to store the address in 00726 * 00727 * Example usage: 00728 * 00729 * \code 00730 * struct ast_sockaddr address; 00731 * ast_rtp_instance_get_local_address(instance, &address); 00732 * \endcode 00733 * 00734 * This gets the local address that we are expecting RTP on and stores it in the 'address' structure. 00735 * 00736 * \since 1.8 00737 */ 00738 void ast_rtp_instance_get_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address); 00739 00740 /*! 00741 * \brief Get the address of the local endpoint that we are sending RTP to, comparing its address to another 00742 * 00743 * \param instance The instance that we want to get the local address for 00744 * \param address An initialized address that may be overwritten if the local address is different 00745 * 00746 * \retval 0 address was not changed 00747 * \retval 1 address was changed 00748 * Example usage: 00749 * 00750 * \code 00751 * struct ast_sockaddr address; 00752 * int ret; 00753 * ret = ast_rtp_instance_get_and_cmp_local_address(instance, &address); 00754 * \endcode 00755 * 00756 * This retrieves the current local address set on the instance pointed to by instance and puts the value 00757 * into the address structure. 00758 * 00759 * \since 1.8 00760 */ 00761 int ast_rtp_instance_get_and_cmp_local_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address); 00762 00763 /*! 00764 * \brief Get the address of the remote endpoint that we are sending RTP to 00765 * 00766 * \param instance The instance that we want to get the remote address for 00767 * \param address A structure to put the address into 00768 * 00769 * Example usage: 00770 * 00771 * \code 00772 * struct ast_sockaddr address; 00773 * ast_rtp_instance_get_remote_address(instance, &address); 00774 * \endcode 00775 * 00776 * This retrieves the current remote address set on the instance pointed to by instance and puts the value 00777 * into the address structure. 00778 * 00779 * \since 1.8 00780 */ 00781 void ast_rtp_instance_get_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address); 00782 00783 /*! 00784 * \brief Get the address of the remote endpoint that we are sending RTP to, comparing its address to another 00785 * 00786 * \param instance The instance that we want to get the remote address for 00787 * \param address An initialized address that may be overwritten if the remote address is different 00788 * 00789 * \retval 0 address was not changed 00790 * \retval 1 address was changed 00791 * Example usage: 00792 * 00793 * \code 00794 * struct ast_sockaddr address; 00795 * int ret; 00796 * ret = ast_rtp_instance_get_and_cmp_remote_address(instance, &address); 00797 * \endcode 00798 * 00799 * This retrieves the current remote address set on the instance pointed to by instance and puts the value 00800 * into the address structure. 00801 * 00802 * \since 1.8 00803 */ 00804 00805 int ast_rtp_instance_get_and_cmp_remote_address(struct ast_rtp_instance *instance, struct ast_sockaddr *address); 00806 00807 /*! 00808 * \brief Set the value of an RTP instance extended property 00809 * 00810 * \param instance The RTP instance to set the extended property on 00811 * \param property The extended property to set 00812 * \param value The value to set the extended property to 00813 * 00814 * \since 1.8 00815 */ 00816 void ast_rtp_instance_set_extended_prop(struct ast_rtp_instance *instance, int property, void *value); 00817 00818 /*! 00819 * \brief Get the value of an RTP instance extended property 00820 * 00821 * \param instance The RTP instance to get the extended property on 00822 * \param property The extended property to get 00823 * 00824 * \since 1.8 00825 */ 00826 void *ast_rtp_instance_get_extended_prop(struct ast_rtp_instance *instance, int property); 00827 00828 /*! 00829 * \brief Set the value of an RTP instance property 00830 * 00831 * \param instance The RTP instance to set the property on 00832 * \param property The property to modify 00833 * \param value The value to set the property to 00834 * 00835 * Example usage: 00836 * 00837 * \code 00838 * ast_rtp_instance_set_prop(instance, AST_RTP_PROPERTY_NAT, 1); 00839 * \endcode 00840 * 00841 * This enables the AST_RTP_PROPERTY_NAT property on the instance pointed to by instance. 00842 * 00843 * \since 1.8 00844 */ 00845 void ast_rtp_instance_set_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property, int value); 00846 00847 /*! 00848 * \brief Get the value of an RTP instance property 00849 * 00850 * \param instance The RTP instance to get the property from 00851 * \param property The property to get 00852 * 00853 * \retval Current value of the property 00854 * 00855 * Example usage: 00856 * 00857 * \code 00858 * ast_rtp_instance_get_prop(instance, AST_RTP_PROPERTY_NAT); 00859 * \endcode 00860 * 00861 * This returns the current value of the NAT property on the instance pointed to by instance. 00862 * 00863 * \since 1.8 00864 */ 00865 int ast_rtp_instance_get_prop(struct ast_rtp_instance *instance, enum ast_rtp_property property); 00866 00867 /*! 00868 * \brief Get the codecs structure of an RTP instance 00869 * 00870 * \param instance The RTP instance to get the codecs structure from 00871 * 00872 * Example usage: 00873 * 00874 * \code 00875 * struct ast_rtp_codecs *codecs = ast_rtp_instance_get_codecs(instance); 00876 * \endcode 00877 * 00878 * This gets the codecs structure on the RTP instance pointed to by 'instance'. 00879 * 00880 * \since 1.8 00881 */ 00882 struct ast_rtp_codecs *ast_rtp_instance_get_codecs(struct ast_rtp_instance *instance); 00883 00884 /*! 00885 * \brief Clear payload information from an RTP instance 00886 * 00887 * \param codecs The codecs structure that payloads will be cleared from 00888 * \param instance Optionally the instance that the codecs structure belongs to 00889 * 00890 * Example usage: 00891 * 00892 * \code 00893 * struct ast_rtp_codecs codecs; 00894 * ast_rtp_codecs_payloads_clear(&codecs, NULL); 00895 * \endcode 00896 * 00897 * This clears the codecs structure and puts it into a pristine state. 00898 * 00899 * \since 1.8 00900 */ 00901 void ast_rtp_codecs_payloads_clear(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance); 00902 00903 /*! 00904 * \brief Set payload information on an RTP instance to the default 00905 * 00906 * \param codecs The codecs structure to set defaults on 00907 * \param instance Optionally the instance that the codecs structure belongs to 00908 * 00909 * Example usage: 00910 * 00911 * \code 00912 * struct ast_rtp_codecs codecs; 00913 * ast_rtp_codecs_payloads_default(&codecs, NULL); 00914 * \endcode 00915 * 00916 * This sets the default payloads on the codecs structure. 00917 * 00918 * \since 1.8 00919 */ 00920 void ast_rtp_codecs_payloads_default(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance); 00921 00922 /*! 00923 * \brief Copy payload information from one RTP instance to another 00924 * 00925 * \param src The source codecs structure 00926 * \param dest The destination codecs structure that the values from src will be copied to 00927 * \param instance Optionally the instance that the dst codecs structure belongs to 00928 * 00929 * Example usage: 00930 * 00931 * \code 00932 * ast_rtp_codecs_payloads_copy(&codecs0, &codecs1, NULL); 00933 * \endcode 00934 * 00935 * This copies the payloads from the codecs0 structure to the codecs1 structure, overwriting any current values. 00936 * 00937 * \since 1.8 00938 */ 00939 void ast_rtp_codecs_payloads_copy(struct ast_rtp_codecs *src, struct ast_rtp_codecs *dest, struct ast_rtp_instance *instance); 00940 00941 /*! 00942 * \brief Record payload information that was seen in an m= SDP line 00943 * 00944 * \param codecs The codecs structure to muck with 00945 * \param instance Optionally the instance that the codecs structure belongs to 00946 * \param payload Numerical payload that was seen in the m= SDP line 00947 * 00948 * Example usage: 00949 * 00950 * \code 00951 * ast_rtp_codecs_payloads_set_m_type(&codecs, NULL, 0); 00952 * \endcode 00953 * 00954 * This records that the numerical payload '0' was seen in the codecs structure. 00955 * 00956 * \since 1.8 00957 */ 00958 void ast_rtp_codecs_payloads_set_m_type(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload); 00959 00960 /*! 00961 * \brief Record payload information that was seen in an a=rtpmap: SDP line 00962 * 00963 * \param codecs The codecs structure to muck with 00964 * \param instance Optionally the instance that the codecs structure belongs to 00965 * \param payload Numerical payload that was seen in the a=rtpmap: SDP line 00966 * \param mimetype The string mime type that was seen 00967 * \param mimesubtype The strin mime sub type that was seen 00968 * \param options Optional options that may change the behavior of this specific payload 00969 * 00970 * \retval 0 success 00971 * \retval -1 failure, invalid payload numbe 00972 * \retval -2 failure, unknown mimetype 00973 * 00974 * Example usage: 00975 * 00976 * \code 00977 * ast_rtp_codecs_payloads_set_rtpmap_type(&codecs, NULL, 0, "audio", "PCMU", 0); 00978 * \endcode 00979 * 00980 * This records that the numerical payload '0' was seen with mime type 'audio' and sub mime type 'PCMU' in the codecs structure. 00981 * 00982 * \since 1.8 00983 */ 00984 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); 00985 00986 /*! 00987 * \brief Set payload type to a known MIME media type for a codec with a specific sample rate 00988 * 00989 * \param codecs RTP structure to modify 00990 * \param instance Optionally the instance that the codecs structure belongs to 00991 * \param pt Payload type entry to modify 00992 * \param mimetype top-level MIME type of media stream (typically "audio", "video", "text", etc.) 00993 * \param mimesubtype MIME subtype of media stream (typically a codec name) 00994 * \param options Zero or more flags from the ast_rtp_options enum 00995 * \param sample_rate The sample rate of the media stream 00996 * 00997 * This function 'fills in' an entry in the list of possible formats for 00998 * a media stream associated with an RTP structure. 00999 * 01000 * \retval 0 on success 01001 * \retval -1 if the payload type is out of range 01002 * \retval -2 if the mimeType/mimeSubtype combination was not found 01003 * 01004 * \since 1.8 01005 */ 01006 int ast_rtp_codecs_payloads_set_rtpmap_type_rate(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int pt, 01007 char *mimetype, char *mimesubtype, 01008 enum ast_rtp_options options, 01009 unsigned int sample_rate); 01010 01011 /*! 01012 * \brief Remove payload information 01013 * 01014 * \param codecs The codecs structure to muck with 01015 * \param instance Optionally the instance that the codecs structure belongs to 01016 * \param payload Numerical payload to unset 01017 * 01018 * Example usage: 01019 * 01020 * \code 01021 * ast_rtp_codecs_payloads_unset(&codecs, NULL, 0); 01022 * \endcode 01023 * 01024 * This clears the payload '0' from the codecs structure. It will be as if it was never set. 01025 * 01026 * \since 1.8 01027 */ 01028 void ast_rtp_codecs_payloads_unset(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, int payload); 01029 01030 /*! 01031 * \brief Retrieve payload information by payload 01032 * 01033 * \param codecs Codecs structure to look in 01034 * \param payload Numerical payload to look up 01035 * 01036 * \retval Payload information 01037 * 01038 * Example usage: 01039 * 01040 * \code 01041 * struct ast_rtp_payload_type payload_type; 01042 * payload_type = ast_rtp_codecs_payload_lookup(&codecs, 0); 01043 * \endcode 01044 * 01045 * This looks up the information for payload '0' from the codecs structure. 01046 * 01047 * \since 1.8 01048 */ 01049 struct ast_rtp_payload_type ast_rtp_codecs_payload_lookup(struct ast_rtp_codecs *codecs, int payload); 01050 01051 /*! 01052 * \brief Get the sample rate associated with known RTP payload types 01053 * 01054 * \param asterisk_format True if the value in the 'code' parameter is an AST_FORMAT value 01055 * \param code Format code, either from AST_FORMAT list or from AST_RTP list 01056 * 01057 * \return the sample rate if the format was found, zero if it was not found 01058 * 01059 * \since 1.8 01060 */ 01061 unsigned int ast_rtp_lookup_sample_rate2(int asterisk_format, format_t code); 01062 01063 /*! 01064 * \brief Retrieve all formats that were found 01065 * 01066 * \param codecs Codecs structure to look in 01067 * \param astformats An integer to put the Asterisk formats in 01068 * \param nonastformats An integer to put the non-Asterisk formats in 01069 * 01070 * Example usage: 01071 * 01072 * \code 01073 * int astformats, nonastformats; 01074 * ast_rtp_codecs_payload_Formats(&codecs, &astformats, &nonastformats); 01075 * \endcode 01076 * 01077 * This retrieves all the formats known about in the codecs structure and puts the Asterisk ones in the integer 01078 * pointed to by astformats and the non-Asterisk ones in the integer pointed to by nonastformats. 01079 * 01080 * \since 1.8 01081 */ 01082 void ast_rtp_codecs_payload_formats(struct ast_rtp_codecs *codecs, format_t *astformats, int *nonastformats); 01083 01084 /*! 01085 * \brief Retrieve a payload based on whether it is an Asterisk format and the code 01086 * 01087 * \param codecs Codecs structure to look in 01088 * \param asterisk_format Non-zero if the given code is an Asterisk format value 01089 * \param code The format to look for 01090 * 01091 * \retval Numerical payload 01092 * 01093 * Example usage: 01094 * 01095 * \code 01096 * int payload = ast_rtp_codecs_payload_code(&codecs, 1, AST_FORMAT_ULAW); 01097 * \endcode 01098 * 01099 * This looks for the numerical payload for ULAW in the codecs structure. 01100 * 01101 * \since 1.8 01102 */ 01103 int ast_rtp_codecs_payload_code(struct ast_rtp_codecs *codecs, const int asterisk_format, const format_t code); 01104 01105 /*! 01106 * \brief Retrieve mime subtype information on a payload 01107 * 01108 * \param asterisk_format Non-zero if the given code is an Asterisk format value 01109 * \param code Format to look up 01110 * \param options Additional options that may change the result 01111 * 01112 * \retval Mime subtype success 01113 * \retval NULL failure 01114 * 01115 * Example usage: 01116 * 01117 * \code 01118 * const char *subtype = ast_rtp_lookup_mime_subtype2(1, AST_FORMAT_ULAW, 0); 01119 * \endcode 01120 * 01121 * This looks up the mime subtype for the ULAW format. 01122 * 01123 * \since 1.8 01124 */ 01125 const char *ast_rtp_lookup_mime_subtype2(const int asterisk_format, const format_t code, enum ast_rtp_options options); 01126 01127 /*! 01128 * \brief Convert formats into a string and put them into a buffer 01129 * 01130 * \param buf Buffer to put the mime output into 01131 * \param capability Formats that we are looking up 01132 * \param asterisk_format Non-zero if the given capability are Asterisk format capabilities 01133 * \param options Additional options that may change the result 01134 * 01135 * \retval non-NULL success 01136 * \retval NULL failure 01137 * 01138 * Example usage: 01139 * 01140 * \code 01141 * char buf[256] = ""; 01142 * char *mime = ast_rtp_lookup_mime_multiple2(&buf, sizeof(buf), AST_FORMAT_ULAW | AST_FORMAT_ALAW, 1, 0); 01143 * \endcode 01144 * 01145 * This returns the mime values for ULAW and ALAW in the buffer pointed to by buf. 01146 * 01147 * \since 1.8 01148 */ 01149 char *ast_rtp_lookup_mime_multiple2(struct ast_str *buf, const format_t capability, const int asterisk_format, enum ast_rtp_options options); 01150 01151 /*! 01152 * \brief Set codec packetization preferences 01153 * 01154 * \param codecs Codecs structure to muck with 01155 * \param instance Optionally the instance that the codecs structure belongs to 01156 * \param prefs Codec packetization preferences 01157 * 01158 * Example usage: 01159 * 01160 * \code 01161 * ast_rtp_codecs_packetization_set(&codecs, NULL, &prefs); 01162 * \endcode 01163 * 01164 * This sets the packetization preferences pointed to by prefs on the codecs structure pointed to by codecs. 01165 * 01166 * \since 1.8 01167 */ 01168 void ast_rtp_codecs_packetization_set(struct ast_rtp_codecs *codecs, struct ast_rtp_instance *instance, struct ast_codec_pref *prefs); 01169 01170 /*! 01171 * \brief Begin sending a DTMF digit 01172 * 01173 * \param instance The RTP instance to send the DTMF on 01174 * \param digit What DTMF digit to send 01175 * 01176 * \retval 0 success 01177 * \retval -1 failure 01178 * 01179 * Example usage: 01180 * 01181 * \code 01182 * ast_rtp_instance_dtmf_begin(instance, '1'); 01183 * \endcode 01184 * 01185 * This starts sending the DTMF '1' on the RTP instance pointed to by instance. It will 01186 * continue being sent until it is ended. 01187 * 01188 * \since 1.8 01189 */ 01190 int ast_rtp_instance_dtmf_begin(struct ast_rtp_instance *instance, char digit); 01191 01192 /*! 01193 * \brief Stop sending a DTMF digit 01194 * 01195 * \param instance The RTP instance to stop the DTMF on 01196 * \param digit What DTMF digit to stop 01197 * 01198 * \retval 0 success 01199 * \retval -1 failure 01200 * 01201 * Example usage: 01202 * 01203 * \code 01204 * ast_rtp_instance_dtmf_end(instance, '1'); 01205 * \endcode 01206 * 01207 * This stops sending the DTMF '1' on the RTP instance pointed to by instance. 01208 * 01209 * \since 1.8 01210 */ 01211 int ast_rtp_instance_dtmf_end(struct ast_rtp_instance *instance, char digit); 01212 int ast_rtp_instance_dtmf_end_with_duration(struct ast_rtp_instance *instance, char digit, unsigned int duration); 01213 01214 /*! 01215 * \brief Set the DTMF mode that should be used 01216 * 01217 * \param instance the RTP instance to set DTMF mode on 01218 * \param dtmf_mode The DTMF mode that is in use 01219 * 01220 * \retval 0 success 01221 * \retval -1 failure 01222 * 01223 * Example usage: 01224 * 01225 * \code 01226 * ast_rtp_instance_dtmf_mode_set(instance, AST_RTP_DTMF_MODE_RFC2833); 01227 * \endcode 01228 * 01229 * This sets the RTP instance to use RFC2833 for DTMF transmission and receiving. 01230 * 01231 * \since 1.8 01232 */ 01233 int ast_rtp_instance_dtmf_mode_set(struct ast_rtp_instance *instance, enum ast_rtp_dtmf_mode dtmf_mode); 01234 01235 /*! 01236 * \brief Get the DTMF mode of an RTP instance 01237 * 01238 * \param instance The RTP instance to get the DTMF mode of 01239 * 01240 * \retval DTMF mode 01241 * 01242 * Example usage: 01243 * 01244 * \code 01245 * enum ast_rtp_dtmf_mode dtmf_mode = ast_rtp_instance_dtmf_mode_get(instance); 01246 * \endcode 01247 * 01248 * This gets the DTMF mode set on the RTP instance pointed to by 'instance'. 01249 * 01250 * \since 1.8 01251 */ 01252 enum ast_rtp_dtmf_mode ast_rtp_instance_dtmf_mode_get(struct ast_rtp_instance *instance); 01253 01254 /*! 01255 * \brief Indicate that the RTP marker bit should be set on an RTP stream 01256 * 01257 * \param instance Instance that the new media source is feeding into 01258 * 01259 * Example usage: 01260 * 01261 * \code 01262 * ast_rtp_instance_update_source(instance); 01263 * \endcode 01264 * 01265 * This indicates that the source of media that is feeding the instance pointed to by 01266 * instance has been updated and that the marker bit should be set. 01267 * 01268 * \since 1.8 01269 */ 01270 void ast_rtp_instance_update_source(struct ast_rtp_instance *instance); 01271 01272 /*! 01273 * \brief Indicate a new source of audio has dropped in and the ssrc should change 01274 * 01275 * \param instance Instance that the new media source is feeding into 01276 * 01277 * Example usage: 01278 * 01279 * \code 01280 * ast_rtp_instance_change_source(instance); 01281 * \endcode 01282 * 01283 * This indicates that the source of media that is feeding the instance pointed to by 01284 * instance has changed and that the marker bit should be set and the SSRC updated. 01285 * 01286 * \since 1.8 01287 */ 01288 void ast_rtp_instance_change_source(struct ast_rtp_instance *instance); 01289 01290 /*! 01291 * \brief Set QoS parameters on an RTP session 01292 * 01293 * \param instance Instance to set the QoS parameters on 01294 * \param tos Terms of service value 01295 * \param cos Class of service value 01296 * \param desc What is setting the QoS values 01297 * 01298 * \retval 0 success 01299 * \retval -1 failure 01300 * 01301 * Example usage: 01302 * 01303 * \code 01304 * ast_rtp_instance_set_qos(instance, 0, 0, "Example"); 01305 * \endcode 01306 * 01307 * This sets the TOS and COS values to 0 on the instance pointed to by instance. 01308 * 01309 * \since 1.8 01310 */ 01311 int ast_rtp_instance_set_qos(struct ast_rtp_instance *instance, int tos, int cos, const char *desc); 01312 01313 /*! 01314 * \brief Stop an RTP instance 01315 * 01316 * \param instance Instance that media is no longer going to at this time 01317 * 01318 * Example usage: 01319 * 01320 * \code 01321 * ast_rtp_instance_stop(instance); 01322 * \endcode 01323 * 01324 * This tells the RTP engine being used for the instance pointed to by instance 01325 * that media is no longer going to it at this time, but may in the future. 01326 * 01327 * \since 1.8 01328 */ 01329 void ast_rtp_instance_stop(struct ast_rtp_instance *instance); 01330 01331 /*! 01332 * \brief Get the file descriptor for an RTP session (or RTCP) 01333 * 01334 * \param instance Instance to get the file descriptor for 01335 * \param rtcp Whether to retrieve the file descriptor for RTCP or not 01336 * 01337 * \retval fd success 01338 * \retval -1 failure 01339 * 01340 * Example usage: 01341 * 01342 * \code 01343 * int rtp_fd = ast_rtp_instance_fd(instance, 0); 01344 * \endcode 01345 * 01346 * This retrieves the file descriptor for the socket carrying media on the instance 01347 * pointed to by instance. 01348 * 01349 * \since 1.8 01350 */ 01351 int ast_rtp_instance_fd(struct ast_rtp_instance *instance, int rtcp); 01352 01353 /*! 01354 * \brief Get the RTP glue that binds a channel to the RTP engine 01355 * 01356 * \param type Name of the glue we want 01357 * 01358 * \retval non-NULL success 01359 * \retval NULL failure 01360 * 01361 * Example usage: 01362 * 01363 * \code 01364 * struct ast_rtp_glue *glue = ast_rtp_instance_get_glue("Example"); 01365 * \endcode 01366 * 01367 * This retrieves the RTP glue that has the name 'Example'. 01368 * 01369 * \since 1.8 01370 */ 01371 struct ast_rtp_glue *ast_rtp_instance_get_glue(const char *type); 01372 01373 /*! 01374 * \brief Bridge two channels that use RTP instances 01375 * 01376 * \param c0 First channel part of the bridge 01377 * \param c1 Second channel part of the bridge 01378 * \param flags Bridging flags 01379 * \param fo If a frame needs to be passed up it is stored here 01380 * \param rc Channel that passed the above frame up 01381 * \param timeoutms How long the channels should be bridged for 01382 * 01383 * \retval Bridge result 01384 * 01385 * \note This should only be used by channel drivers in their technology declaration. 01386 * 01387 * \since 1.8 01388 */ 01389 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); 01390 01391 /*! 01392 * \brief Get the other RTP instance that an instance is bridged to 01393 * 01394 * \param instance The RTP instance that we want 01395 * 01396 * \retval non-NULL success 01397 * \retval NULL failure 01398 * 01399 * Example usage: 01400 * 01401 * \code 01402 * struct ast_rtp_instance *bridged = ast_rtp_instance_get_bridged(instance0); 01403 * \endcode 01404 * 01405 * This gets the RTP instance that instance0 is bridged to. 01406 * 01407 * \since 1.8 01408 */ 01409 struct ast_rtp_instance *ast_rtp_instance_get_bridged(struct ast_rtp_instance *instance); 01410 01411 /*! 01412 * \brief Make two channels compatible for early bridging 01413 * 01414 * \param c0 First channel part of the bridge 01415 * \param c1 Second channel part of the bridge 01416 * 01417 * \since 1.8 01418 */ 01419 void ast_rtp_instance_early_bridge_make_compatible(struct ast_channel *c0, struct ast_channel *c1); 01420 01421 /*! 01422 * \brief Early bridge two channels that use RTP instances 01423 * 01424 * \param c0 First channel part of the bridge 01425 * \param c1 Second channel part of the bridge 01426 * 01427 * \retval 0 success 01428 * \retval -1 failure 01429 * 01430 * \note This should only be used by channel drivers in their technology declaration. 01431 * 01432 * \since 1.8 01433 */ 01434 int ast_rtp_instance_early_bridge(struct ast_channel *c0, struct ast_channel *c1); 01435 01436 /*! 01437 * \brief Initialize RED support on an RTP instance 01438 * 01439 * \param instance The instance to initialize RED support on 01440 * \param buffer_time How long to buffer before sending 01441 * \param payloads Payload values 01442 * \param generations Number of generations 01443 * 01444 * \retval 0 success 01445 * \retval -1 failure 01446 * 01447 * \since 1.8 01448 */ 01449 int ast_rtp_red_init(struct ast_rtp_instance *instance, int buffer_time, int *payloads, int generations); 01450 01451 /*! 01452 * \brief Buffer a frame in an RTP instance for RED 01453 * 01454 * \param instance The instance to buffer the frame on 01455 * \param frame Frame that we want to buffer 01456 * 01457 * \retval 0 success 01458 * \retval -1 failure 01459 * 01460 * \since 1.8 01461 */ 01462 int ast_rtp_red_buffer(struct ast_rtp_instance *instance, struct ast_frame *frame); 01463 01464 /*! 01465 * \brief Retrieve statistics about an RTP instance 01466 * 01467 * \param instance Instance to get statistics on 01468 * \param stats Structure to put results into 01469 * \param stat What statistic(s) to retrieve 01470 * 01471 * \retval 0 success 01472 * \retval -1 failure 01473 * 01474 * Example usage: 01475 * 01476 * \code 01477 * struct ast_rtp_instance_stats stats; 01478 * ast_rtp_instance_get_stats(instance, &stats, AST_RTP_INSTANCE_STAT_ALL); 01479 * \endcode 01480 * 01481 * This retrieves all statistics the underlying RTP engine supports and puts the values into the 01482 * stats structure. 01483 * 01484 * \since 1.8 01485 */ 01486 int ast_rtp_instance_get_stats(struct ast_rtp_instance *instance, struct ast_rtp_instance_stats *stats, enum ast_rtp_instance_stat stat); 01487 01488 /*! 01489 * \brief Set standard statistics from an RTP instance on a channel 01490 * 01491 * \param chan Channel to set the statistics on 01492 * \param instance The RTP instance that statistics will be retrieved from 01493 * 01494 * Example usage: 01495 * 01496 * \code 01497 * ast_rtp_instance_set_stats_vars(chan, rtp); 01498 * \endcode 01499 * 01500 * This retrieves standard statistics from the RTP instance rtp and sets it on the channel pointed to 01501 * by chan. 01502 * 01503 * \since 1.8 01504 */ 01505 void ast_rtp_instance_set_stats_vars(struct ast_channel *chan, struct ast_rtp_instance *instance); 01506 01507 /*! 01508 * \brief Retrieve quality statistics about an RTP instance 01509 * 01510 * \param instance Instance to get statistics on 01511 * \param field What quality statistic to retrieve 01512 * \param buf What buffer to put the result into 01513 * \param size Size of the above buffer 01514 * 01515 * \retval non-NULL success 01516 * \retval NULL failure 01517 * 01518 * Example usage: 01519 * 01520 * \code 01521 * char quality[AST_MAX_USER_FIELD]; 01522 * ast_rtp_instance_get_quality(instance, AST_RTP_INSTANCE_STAT_FIELD_QUALITY, &buf, sizeof(buf)); 01523 * \endcode 01524 * 01525 * This retrieves general quality statistics and places a text representation into the buf pointed to by buf. 01526 * 01527 * \since 1.8 01528 */ 01529 char *ast_rtp_instance_get_quality(struct ast_rtp_instance *instance, enum ast_rtp_instance_stat_field field, char *buf, size_t size); 01530 01531 /*! 01532 * \brief Request that the underlying RTP engine provide audio frames in a specific format 01533 * 01534 * \param instance The RTP instance to change read format on 01535 * \param format Format that frames are wanted in 01536 * 01537 * \retval 0 success 01538 * \retval -1 failure 01539 * 01540 * Example usage: 01541 * 01542 * \code 01543 * ast_rtp_instance_set_read_format(instance, AST_FORMAT_ULAW); 01544 * \endcode 01545 * 01546 * This requests that the RTP engine provide audio frames in the ULAW format. 01547 * 01548 * \since 1.8 01549 */ 01550 int ast_rtp_instance_set_read_format(struct ast_rtp_instance *instance, format_t format); 01551 01552 /*! 01553 * \brief Tell underlying RTP engine that audio frames will be provided in a specific format 01554 * 01555 * \param instance The RTP instance to change write format on 01556 * \param format Format that frames will be provided in 01557 * 01558 * \retval 0 success 01559 * \retval -1 failure 01560 * 01561 * Example usage: 01562 * 01563 * \code 01564 * ast_rtp_instance_set_write_format(instance, AST_FORMAT_ULAW); 01565 * \endcode 01566 * 01567 * This tells the underlying RTP engine that audio frames will be provided to it in ULAW format. 01568 * 01569 * \since 1.8 01570 */ 01571 int ast_rtp_instance_set_write_format(struct ast_rtp_instance *instance, format_t format); 01572 01573 /*! 01574 * \brief Request that the underlying RTP engine make two RTP instances compatible with eachother 01575 * 01576 * \param chan Our own Asterisk channel 01577 * \param instance The first RTP instance 01578 * \param peer The peer Asterisk channel 01579 * 01580 * \retval 0 success 01581 * \retval -1 failure 01582 * 01583 * Example usage: 01584 * 01585 * \code 01586 * ast_rtp_instance_make_compatible(instance, peer); 01587 * \endcode 01588 * 01589 * This makes the RTP instance for 'peer' compatible with 'instance' and vice versa. 01590 * 01591 * \since 1.8 01592 */ 01593 int ast_rtp_instance_make_compatible(struct ast_channel *chan, struct ast_rtp_instance *instance, struct ast_channel *peer); 01594 01595 /*! \brief Request the formats that can be transcoded 01596 * 01597 * \param instance The RTP instance 01598 * \param to_endpoint Formats being sent/received towards the endpoint 01599 * \param to_asterisk Formats being sent/received towards Asterisk 01600 * 01601 * \retval supported formats 01602 * 01603 * Example usage: 01604 * 01605 * \code 01606 * ast_rtp_instance_available_formats(instance, AST_FORMAT_ULAW, AST_FORMAT_SLINEAR); 01607 * \endcode 01608 * 01609 * This sees if it is possible to have ulaw communicated to the endpoint but signed linear received into Asterisk. 01610 * 01611 * \since 1.8 01612 */ 01613 format_t ast_rtp_instance_available_formats(struct ast_rtp_instance *instance, format_t to_endpoint, format_t to_asterisk); 01614 01615 /*! 01616 * \brief Indicate to the RTP engine that packets are now expected to be sent/received on the RTP instance 01617 * 01618 * \param instance The RTP instance 01619 * 01620 * \retval 0 success 01621 * \retval -1 failure 01622 * 01623 * Example usage: 01624 * 01625 * \code 01626 * ast_rtp_instance_activate(instance); 01627 * \endcode 01628 * 01629 * This tells the underlying RTP engine of instance that packets will now flow. 01630 * 01631 * \since 1.8 01632 */ 01633 int ast_rtp_instance_activate(struct ast_rtp_instance *instance); 01634 01635 /*! 01636 * \brief Request that the underlying RTP engine send a STUN BIND request 01637 * 01638 * \param instance The RTP instance 01639 * \param suggestion The suggested destination 01640 * \param username Optionally a username for the request 01641 * 01642 * Example usage: 01643 * 01644 * \code 01645 * ast_rtp_instance_stun_request(instance, NULL, NULL); 01646 * \endcode 01647 * 01648 * This requests that the RTP engine send a STUN BIND request on the session pointed to by 01649 * 'instance'. 01650 * 01651 * \since 1.8 01652 */ 01653 void ast_rtp_instance_stun_request(struct ast_rtp_instance *instance, struct ast_sockaddr *suggestion, const char *username); 01654 01655 /*! 01656 * \brief Set the RTP timeout value 01657 * 01658 * \param instance The RTP instance 01659 * \param timeout Value to set the timeout to 01660 * 01661 * Example usage: 01662 * 01663 * \code 01664 * ast_rtp_instance_set_timeout(instance, 5000); 01665 * \endcode 01666 * 01667 * This sets the RTP timeout value on 'instance' to be 5000. 01668 * 01669 * \since 1.8 01670 */ 01671 void ast_rtp_instance_set_timeout(struct ast_rtp_instance *instance, int timeout); 01672 01673 /*! 01674 * \brief Set the RTP timeout value for when the instance is on hold 01675 * 01676 * \param instance The RTP instance 01677 * \param timeout Value to set the timeout to 01678 * 01679 * Example usage: 01680 * 01681 * \code 01682 * ast_rtp_instance_set_hold_timeout(instance, 5000); 01683 * \endcode 01684 * 01685 * This sets the RTP hold timeout value on 'instance' to be 5000. 01686 * 01687 * \since 1.8 01688 */ 01689 void ast_rtp_instance_set_hold_timeout(struct ast_rtp_instance *instance, int timeout); 01690 01691 /*! 01692 * \brief Set the RTP keepalive interval 01693 * 01694 * \param instance The RTP instance 01695 * \param period Value to set the keepalive interval to 01696 * 01697 * Example usage: 01698 * 01699 * \code 01700 * ast_rtp_instance_set_keepalive(instance, 5000); 01701 * \endcode 01702 * 01703 * This sets the RTP keepalive interval on 'instance' to be 5000. 01704 * 01705 * \since 1.8 01706 */ 01707 void ast_rtp_instance_set_keepalive(struct ast_rtp_instance *instance, int timeout); 01708 01709 /*! 01710 * \brief Get the RTP timeout value 01711 * 01712 * \param instance The RTP instance 01713 * 01714 * \retval timeout value 01715 * 01716 * Example usage: 01717 * 01718 * \code 01719 * int timeout = ast_rtp_instance_get_timeout(instance); 01720 * \endcode 01721 * 01722 * This gets the RTP timeout value for the RTP instance pointed to by 'instance'. 01723 * 01724 * \since 1.8 01725 */ 01726 int ast_rtp_instance_get_timeout(struct ast_rtp_instance *instance); 01727 01728 /*! 01729 * \brief Get the RTP timeout value for when an RTP instance is on hold 01730 * 01731 * \param instance The RTP instance 01732 * 01733 * \retval timeout value 01734 * 01735 * Example usage: 01736 * 01737 * \code 01738 * int timeout = ast_rtp_instance_get_hold_timeout(instance); 01739 * \endcode 01740 * 01741 * This gets the RTP hold timeout value for the RTP instance pointed to by 'instance'. 01742 * 01743 * \since 1.8 01744 */ 01745 int ast_rtp_instance_get_hold_timeout(struct ast_rtp_instance *instance); 01746 01747 /*! 01748 * \brief Get the RTP keepalive interval 01749 * 01750 * \param instance The RTP instance 01751 * 01752 * \retval period Keepalive interval value 01753 * 01754 * Example usage: 01755 * 01756 * \code 01757 * int interval = ast_rtp_instance_get_keepalive(instance); 01758 * \endcode 01759 * 01760 * This gets the RTP keepalive interval value for the RTP instance pointed to by 'instance'. 01761 * 01762 * \since 1.8 01763 */ 01764 int ast_rtp_instance_get_keepalive(struct ast_rtp_instance *instance); 01765 01766 /*! 01767 * \brief Get the RTP engine in use on an RTP instance 01768 * 01769 * \param instance The RTP instance 01770 * 01771 * \retval pointer to the engine 01772 * 01773 * Example usage: 01774 * 01775 * \code 01776 * struct ast_rtp_engine *engine = ast_rtp_instance_get_engine(instance); 01777 * \endcode 01778 * 01779 * This gets the RTP engine currently in use on the RTP instance pointed to by 'instance'. 01780 * 01781 * \since 1.8 01782 */ 01783 struct ast_rtp_engine *ast_rtp_instance_get_engine(struct ast_rtp_instance *instance); 01784 01785 /*! 01786 * \brief Get the RTP glue in use on an RTP instance 01787 * 01788 * \param instance The RTP instance 01789 * 01790 * \retval pointer to the glue 01791 * 01792 * Example: 01793 * 01794 * \code 01795 * struct ast_rtp_glue *glue = ast_rtp_instance_get_active_glue(instance); 01796 * \endcode 01797 * 01798 * This gets the RTP glue currently in use on the RTP instance pointed to by 'instance'. 01799 * 01800 * \since 1.8 01801 */ 01802 struct ast_rtp_glue *ast_rtp_instance_get_active_glue(struct ast_rtp_instance *instance); 01803 01804 /*! 01805 * \brief Get the channel that is associated with an RTP instance while in a bridge 01806 * 01807 * \param instance The RTP instance 01808 * 01809 * \retval pointer to the channel 01810 * 01811 * Example: 01812 * 01813 * \code 01814 * struct ast_channel *chan = ast_rtp_instance_get_chan(instance); 01815 * \endcode 01816 * 01817 * This gets the channel associated with the RTP instance pointed to by 'instance'. 01818 * 01819 * \note This will only return a channel while in a local or remote bridge. 01820 * 01821 * \since 1.8 01822 */ 01823 struct ast_channel *ast_rtp_instance_get_chan(struct ast_rtp_instance *instance); 01824 01825 /*! 01826 * \brief Send a comfort noise packet to the RTP instance 01827 * 01828 * \param instance The RTP instance 01829 * \param level Magnitude of the noise level 01830 * 01831 * \retval 0 Success 01832 * \retval non-zero Failure 01833 */ 01834 int ast_rtp_instance_sendcng(struct ast_rtp_instance *instance, int level); 01835 01836 int ast_rtp_instance_add_srtp_policy(struct ast_rtp_instance *instance, struct ast_srtp_policy *policy); 01837 struct ast_srtp *ast_rtp_instance_get_srtp(struct ast_rtp_instance *instance); 01838 01839 #if defined(__cplusplus) || defined(c_plusplus) 01840 } 01841 #endif 01842 01843 #endif /* _ASTERISK_RTP_ENGINE_H */