&adminguide;

Functions

<function moreinfo="none">set_rtpengine_set(setid[, setid])</function> Sets the ID of the &rtp; proxy set to be used for the next rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or rtpengine_manage() command. The parameter can be an integer or a config variable holding an integer. A second set ID can be specified to daisy-chain two &rtp; proxies. The two set IDs must be distinct from each other and there must not be any overlap in the proxies present in both sets. In this use case, the request (offer, answer, etc) is first sent to an &rtp; proxy from the first set, which rewrites the &sdp; body and sends it back to the module. The rewritten &sdp; body is then used to make another request to an &rtp; proxy from the second set, which rewrites the &sdp; body another time and sends it back to the module to be placed back into the &sip; message. This is useful if you have a set of &rtp; proxies that the caller must use, and another distinct set of &rtp; proxies that the callee must use. This is supported by all rtpengine commands except rtpengine_manage(). This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE. <function>set_rtpengine_set</function> usage ... set_rtpengine_set("2"); rtpengine_offer(); ...

<function moreinfo="none">rtpengine_offer([flags])</function> Rewrites &sdp; body to ensure that media is passed through an &rtp; proxy. To be invoked on INVITE for the cases the &sdp; bodies are in INVITE and 200 OK and on 200 OK when &sdp; bodies are in 200 OK and ACK. Meaning of the parameters is as follows: flags - flags to turn on some features. The flags string is a list of space-separated items. Each item is either an individual token, or a token in key=value format. The possible tokens are described below. via-branch=... - Include the branch value of one of the Via headers in the request to the &rtp; proxy. Possible values are: 1 - use the first Via header; 2 - use the second Via header; auto - use the first Via header if this is a request, or the second one if this is a reply; extra - don't take the value from a header, but instead use the value of the extra_id_pv variable. This can be used to create one media session per branch on the &rtp; proxy. When sending a subsequent delete command to the &rtp; proxy, you can then stop just the session for a specific branch when passing the flag '1' or '2' in the rtpengine_delete, or stop all sessions for a call when not passing one of those two flags there. This is especially useful if you have serially forked call scenarios where the &rtp; proxy gets an offer command for a new branch, and then a delete command for the previous branch, which would otherwise delete the full call, breaking the subsequent answer for the new branch. This flag is only supported by the Sipwise rtpengine &rtp; proxy at the moment! asymmetric - flags that UA from which message is received doesn't support symmetric &rtp;. Disables learning of endpoint addresses in the Sipwise rtpengine proxy. force-answer - force answer, that is, only rewrite &sdp; when corresponding session already exists in the &rtp; proxy. By default is on when the session is to be completed. direction=... - this option specifies a logical network interface and should be given exactly twice. It enables &rtp; bridging between different addresses or networks of the same family (e.g. IPv4 to IPv4). The first instance of the option specifies the interface that the originator of this message should be using, while the second instance specifies the interface that the target should be using. For example, if the &sip; message was sent by an endpoint on a private network and will be sent to an endpoint on the public internet, you would use direction=priv direction=pub if those two logical network interfaces were called priv and pub in your &rtp; proxy's configuration respectively. The direction must only be specified in for initial &sdp; offer; answers or subsequent offers can omit this option. internal, external - shorthand for direction=internal and direction=external respectively. Useful for brevity or as legacy option if the &rtp; proxy only supports two network interfaces instead of multiple, arbitrarily named ones. auto-bridge - this flag an alternative to the internal and external flags in order to do automatic bridging between IPv4 on the "internal network" and IPv6 on the "external network". Instead of explicitly instructing the &rtp; proxy to select a particular address family, the distinction is done by the given IP in the &sdp; body by the &rtp; proxy itself. Not supported by Sipwise rtpengine. address-family=... - instructs the &rtp; proxy that the recipient of this &sdp; body expects to see addresses of a particular family. Possible values are IP4 and IP6. For example, if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6, you would use address-family=IP6 to bridge between the two address families. Sipwise rtpengine remembers the address family preference of each party after it has seen an &sdp; body from them. This means that normally it is only necessary to explicitly specify the address family in the offer, but not in the answer. Note: Please note, that this will only work properly with non-dual-stack user-agents or with dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations). This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests having different m-lines with different IP-protocols grouped together. force - instructs the &rtp; proxy to ignore marks inserted by another &rtp; proxy in transit to indicate that the session is already goes through another proxy. Allows creating a chain of proxies. Not supported and ignored by Sipwise rtpengine. trust-address - flags that IP address in &sdp; should be trusted. Without this flag, the &rtp; proxy ignores address in the &sdp; and uses source address of the &sip; message as media address which is passed to the &rtp; proxy. replace-origin - flags that IP from the origin description (o=) should be also changed. replace-session-connection - flags to change the session-level &sdp; connection (c=) IP if media description also includes connection information. symmetric - flags that for the UA from which message is received, support symmetric &rtp; must be forced. Does nothing with the Sipwise rtpengine proxy as it is the default. repacketize=NN - requests the &rtp; proxy to perform re-packetization of &rtp; traffic coming from the UA which has sent the current message to increase or decrease payload size per each &rtp; packet forwarded if possible. The NN is the target payload size in ms, for the most codecs its value should be in 10ms increments, however for some codecs the increment could differ (e.g. 30ms for GSM or 20ms for G.723). The &rtp; proxy would select the closest value supported by the codec. This feature could be used for significantly reducing bandwith overhead for low bitrate codecs, for example with G.729 going from 10ms to 100ms saves two thirds of the network bandwith. Not supported by Sipwise rtpengine. ICE=... - controls the &rtp; proxy's behaviour regarding ICE attributes within the &sdp; body. Possible values are: force - discard any ICE attributes already present in the &sdp; body and then generate and insert new ICE data, leaving itself as the only ICE candidates; force-relay - discard any relay type ICE attributes already present in the &sdp; body and then generate and insert itself as the only ICE relay candidates; remove instructs the &rtp; proxy to discard any ICE attributes and not insert any new ones into the &sdp;. The default (if no ICE=... is given at all), new ICE data will only be generated if no ICE was present in the &sdp; originally; otherwise the &rtp; proxy will only insert itself as additional ICE candidate. Other &sdp; substitutions (c=, m=, etc) are unaffected by this flag. RTP, SRTP, AVP, AVPF - These flags control the &rtp; transport protocol that should be used towards the recipient of the &sdp;. If none of them are specified, the protocol given in the &sdp; is left untouched. Otherwise, the SRTP flag indicates that SRTP should be used, while RTP indicates that SRTP should not be used. AVPF indicates that the advanced RTCP profile with feedback messages should be used, and AVP indicates that the regular RTCP profile should be used. See also the next set of flags below. RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve as an alternative, more explicit way to select between the different &rtp; protocols and profiles supported by the &rtp; proxy. For example, giving the flag RTP/SAVPF has the same effect as giving the two flags SRTP AVPF. to-tag - force inclusion of the To tag. Normally, the To tag is always included when present, except for delete messages. Including the To tag in a delete messages allows you to be more selective about which dialogues within a call are being torn down. rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the &rtp; proxy accept the offer, but not offer it to the recipient of this message. rtcp-mux-reject - if rtcp-mux was offered, make the &rtp; proxy reject the offer, but still offer it to the recipient. Can be combined with rtcp-mux-offer to always offer it. rtcp-mux-offer - make the &rtp; proxy offer rtcp-mux to the recipient of this message, regardless of whether it was offered originally or not. rtcp-mux-accept - if rtcp-mux was offered, make the &rtp; proxy accept the offer and also offer it to the recipient of this message. Can be combined with rtcp-mux-offer to always offer it. media-address=... - force a particular media address to be used in the &sdp; body. Address family is detected automatically. TOS=... - change the IP TOS value for all outgoing &rtp; packets within the entire call in both directions. Only honoured in an offer, ignored for an answer. Valid values are 0 through 255, given in decimal. If this option is not specified, the TOS value will revert to the default TOS (normally 184). A value of -1 may be used to leave the currently used TOS unchanged. This function can be used from ANY_ROUTE. <function>rtpengine_offer</function> usage route { ... if (is_method("INVITE")) { if (has_body("application/sdp")) { if (rtpengine_offer()) t_on_reply("1"); } else { t_on_reply("2"); } } if (is_method("ACK") && has_body("application/sdp")) rtpengine_answer(); ... } onreply_route[1] { ... if (has_body("application/sdp")) rtpengine_answer(); ... } onreply_route[2] { ... if (has_body("application/sdp")) rtpengine_offer(); ... }

<function moreinfo="none">rtpengine_answer([flags])</function> Rewrites &sdp; body to ensure that media is passed through an &rtp; proxy. To be invoked on 200 OK for the cases the &sdp; bodies are in INVITE and 200 OK and on ACK when &sdp; bodies are in 200 OK and ACK. See rtpengine_offer() function description above for the meaning of the parameters. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. <function>rtpengine_answer</function> usage See rtpengine_offer() function example above for example.

<function moreinfo="none">rtpengine_delete([flags])</function> Tears down the RTPProxy session for the current call. See rtpengine_offer() function description above for the meaning of the parameters. Note that not all flags make sense for a delete. This function can be used from ANY_ROUTE. <function>rtpengine_delete</function> usage ... rtpengine_delete(); ...

<function moreinfo="none">rtpengine_manage([flags])</function> Manage the RTPProxy session - it combines the functionality of rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting internally based on message type and method which one to execute. It can take the same parameters as rtpengine_offer(). The flags parameter to rtpengine_manage() can be a configuration variable containing the flags as a string. Functionality: If INVITE with &sdp;, then do rtpengine_offer() If INVITE with &sdp;, when the tm module is loaded, mark transaction with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for rtpengine_answer() If ACK with &sdp;, then do rtpengine_answer() If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do rtpengine_delete() If reply to INVITE with code >= 300 do rtpengine_delete() If reply with &sdp; to INVITE having code 1xx and 2xx, then do rtpengine_answer() if the request had &sdp; or tm is not loaded, otherwise do rtpengine_offer() This function can be used from ANY_ROUTE. <function>rtpengine_manage</function> usage ... rtpengine_manage(); ...

<function moreinfo="none">start_recording()</function> This function will send a signal to the &rtp; proxy to record the &rtp; stream on the &rtp; proxy. This function is not supported by Sipwise rtpengine at the moment! This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE. <function>start_recording</function> usage ... start_recording(); ...