0x1949 Team - FAZEMRX - MANAGER

Edit File: Net::SIP::Simple::Call.3pm

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::SIP::Simple::Call 3pm" .TH Net::SIP::Simple::Call 3pm "2021-05-04" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::SIP::Simple::Call \- call context for Net::SIP::Simple .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& my $call = $simple\->invite(...); \& $call\->reinvite(... ); \& $call\->bye(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package manages the call context for Net::SIP::Simple, e.g. (re\-)invites on existing context etc. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "new ( \s-1CONTROL, CTX,\s0 \e%ARGS )" 4 .IX Item "new ( CONTROL, CTX, %ARGS )" Creates a new Net::SIP::Simple::Call object to control a call. Usually called from \fBinvite\fR in Net::SIP::Simple. .Sp \&\s-1CONTROL\s0 is the Net::SIP::Simple object managing the calls. .Sp \&\s-1CTX\s0 is either an existing Net::SIP::Endpoint::Context or the \&\s-1SIP\s0 address of the peer which will be contacted in this call or a hash which can be used to create the context. If no complete context is given missing information will be taken from \f(CW$call\fR if called as \f(CW\*(C`$call\-\*(C'\fRnew>. .Sp \&\f(CW%ARGS\fR are used to describe the behavior of the call and will be saved in the object as the connection parameter. The following options are used in the connection parameter and can be given in \f(CW%ARGS:\fR .RS 4 .IP "leg" 8 .IX Item "leg" Specifies which leg should be used for the call (default is first leg in dispatcher). .IP "sdp_on_ack" 8 .IX Item "sdp_on_ack" If given and \s-1TRUE\s0 it will not send the \s-1SDP\s0 body on \s-1INVITE\s0 request, but on \s-1ACK.\s0 Mainly used for testing behavior of proxies in between the two parties. .IP "init_media" 8 .IX Item "init_media" Callback used to initialize media for the connection, see method \fBrtp\fR in Net::SIP::Simple and Net::SIP::Simple::RTP. .Sp Callback will be invoked with the call \f(CW$self\fR and the connection parameter as an argument (as hash reference). .IP "rtp_param" 8 .IX Item "rtp_param" Data for the codec used in the media specified by \fBinit_media\fR and for the initialization of the default \s-1SDP\s0 data. This is an array reference \&\f(CW\*(C`[pt,size,interval,name]\*(C'\fR where \fBpt\fR is the payload type, \fBsize\fR is the size of the payload and \fBinterval\fR the interval in which the \s-1RTP\s0 packets will be send. \fBname\fR is optional and if given rtpmap and ptime entries will be added to the \s-1SDP\s0 so that the name is associated with the given payload type. The default is for \s-1PCMU/8000:\s0 \f(CW\*(C`[0,160,160/8000]\*(C'\fR. An alternative would be for example \f(CW\*(C`[97,50,0.03,\*(AqiLBC/8000\*(Aq]\*(C'\fR for iLBC. .IP "sdp" 8 .IX Item "sdp" Net::SIP::SDP object or argument for constructing this object. If not given it will create an \s-1SDP\s0 body with one \s-1RTP\s0 audio connection unless it got first \s-1SDP\s0 data from the peer in which case it simply matches them. .IP "sdp_peer" 8 .IX Item "sdp_peer" Holds the Net::SIP::SDP body send by the peer. Usually not set in the constructor but can be accessed from callbacks. .IP "media_lsocks" 8 .IX Item "media_lsocks" Contains a \e@list of sockets for each media-line in the \s-1SDP.\s0 Each item in this list is either a single socket (in case of port range 1) or a \e@list of sockets. .Sp If \fBsdp\fR is provided this parameter has to be provided too, e.g. the package will not allocate the sockets described in the \s-1SDP\s0 packet. .IP "media_ssocks" 8 .IX Item "media_ssocks" Sockets used for sending \s-1RTP\s0 data. If not given the socket for sending \s-1RTP\s0 is the same as for receiving \s-1RTP,\s0 unless \fBasymetric_rtp\fR is specified. .IP "asymetric_rtp" 8 .IX Item "asymetric_rtp" By default it will send the \s-1RTP\s0 data from the same port where it listens for the data. If this option is \s-1TRUE\s0 it will allocate a different port for receiving data. Mainly used for testing behavior of proxies in between the two parties. .IP "dtmf_methods" 8 .IX Item "dtmf_methods" If a \s-1DTMF\s0 callback is specified this is treated as a list of supported \s-1DTMF\s0 methods for receiving \s-1DTMF.\s0 If not given it defaults to 'rfc2833,audio'. .IP "recv_bye" 8 .IX Item "recv_bye" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when the peer initiated the close of the connection using \s-1BYE\s0 or \s-1CANCEL.\s0 .Sp Argument for the callback will be a hash reference containing the connection parameter. .IP "send_bye" 8 .IX Item "send_bye" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when the local side initiated the close of the connection using \s-1BYE\s0 or \s-1CANCEL.\s0 .Sp Argument for the callback will be a hash reference containing the connection parameter merged with the parameter from the \fBbye\fR method. .IP "clear_sdp" 8 .IX Item "clear_sdp" If \s-1TRUE\s0 the keys media_lsocks, media_ssocks, sdp and sdp_peer will be cleared on each new (re)INVITE request, so that it will allocate new sockets for \s-1RTP\s0 instead of reusing the existing. .IP "cb_final" 8 .IX Item "cb_final" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received the final answer on locally created \s-1INVITE\s0 requests (e.g. when it established the call by sending the \s-1ACK\s0). .Sp Callback will be invoked with \f(CW\*(C`( STATUS, SELF, %INFO )\*(C'\fR where \s-1STATUS\s0 is either '\s-1OK\s0' or '\s-1FAIL\s0' ('\s-1OK\s0' if final response meant success, else '\s-1FINAL\s0'), and \f(CW%INFO\fR contains more information, like \f(CW\*(C`( packet => packet )\*(C'\fR for the packet containing the final answer or \f(CW\*(C`( code => response_code )\*(C'\fR in case failures caused by an unsuccessful response. .IP "cb_preliminary" 8 .IX Item "cb_preliminary" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received a preliminary response on locally created \s-1INVITE.\s0 .Sp Callback will be invoked with \f(CW\*(C`( SELF, CODE, RESPONSE )\*(C'\fR where \&\s-1CODE\s0 is the response code and \s-1RESPONSE\s0 the Net::SIP::Response packet. .IP "cb_established" 8 .IX Item "cb_established" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received the final answer on locally created \s-1INVITE\s0 requests. .Sp Callback will be invoked with \f(CW\*(C`( \*(AqOK\*(Aq, SELF )\*(C'\fR. .IP "cb_invite" 8 .IX Item "cb_invite" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received an \s-1INVITE\s0 request .Sp Callback will be invoked with \f(CW\*(C`( SELF, REQUEST )\*(C'\fR where \s-1REQUEST\s0 is the Net::SIP::Request packet for the \s-1INVITE.\s0 If it returns a Net::SIP::Packet this will be used as response, otherwise a default response with code 200 will be created. .IP "cb_dtmf" 8 .IX Item "cb_dtmf" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received an \s-1DTMF\s0 event. .Sp Callback will be invoked with \f(CW\*(C`( EVENT, DURATION )\*(C'\fR where \s-1EVENT\s0 is the event ([0\-9A\-D*#]) and \s-1DURATION\s0 the duration in ms. .Sp Receiving \s-1DTMF\s0 needs to be supported by the active \s-1RTP\s0 handler set with \&\fBinit_media\fR. All builtin handlers from Net::SIP::Simple::RTP are supported. If no \s-1RTP\s0 handler is set up or if the \s-1RTP\s0 handler does not support \s-1DTMF\s0 sending no \s-1DTMF\s0 will be received without any warning. .IP "cb_notify" 8 .IX Item "cb_notify" Callback usable by \fBinvoke_callback\fR in Net::SIP::Util which will be invoked, when it received an \s-1NOTIFY\s0 request .Sp Callback will be invoked with \f(CW\*(C`( SELF, REQUEST )\*(C'\fR where \s-1REQUEST\s0 is the Net::SIP::Request packet for the \s-1NOTIFY.\s0 .IP "sip_header" 8 .IX Item "sip_header" A reference to a hash with additional \s-1SIP\s0 headers for the \s-1INVITE\s0 requests. .IP "call_on_hold" 8 .IX Item "call_on_hold" This option causes the next \s-1SDP\s0 to have 0.0.0.0 as it's address to put this side of the call on hold (will not receive data). This is a one-shot option, e.g. needs to be set with \fBset_param\fR or within \fBreinvite\fR each time the call should be put on hold. .IP "..." 8 More parameters may be specified and are accessible from the callbacks. For instance \fBmedia_send_recv\fR in Net::SIP::Simple::RTP uses a parameter \&\fBcb_rtp_done\fR. See there. .RE .RS 4 .RE .SH "METHODS" .IX Header "METHODS" .IP "cleanup" 4 .IX Item "cleanup" Will be called to clean up the call. Necessary because callbacks etc can cause cyclic references which need to be broken. Calls \fBrtp_cleanup\fR too. Works by invoking all callbacks which are stored as \e@list in \f(CW\*(C`$self\->{call_cleanup}\*(C'\fR. .Sp This will called automatically at a clean end of a call (e.g. on \s-1BYE\s0 or \s-1CANCEL,\s0 either issued locally or received from the peer). If there is not clean end and one wants to destroy the call unclean one need to call this method manually. .IP "rtp_cleanup" 4 .IX Item "rtp_cleanup" Cleanup of current \s-1RTP\s0 connection. Works be invoking all callbacks which are stored as \e@list in \f(CW\*(C`$self\->{rtp_cleanup}\*(C'\fR (these callbacks are inserted by Net::SIP::Simple::RTP etc). .IP "get_peer" 4 .IX Item "get_peer" Returns peer of call, see \fBpeer\fR in Net::SIP::Endpoint::Context. .ie n .IP "reinvite ( %ARGS )" 4 .el .IP "reinvite ( \f(CW%ARGS\fR )" 4 .IX Item "reinvite ( %ARGS )" Creates a \s-1INVITE\s0 request which causes either the initial \s-1SDP\s0 session or an update of the \s-1SDP\s0 session (reinvite). \f(CW%ARGS\fR will merged with the connection parameter, see description on the constructor. Additionally using \fBresp40x\fR an \fBauth\fR as a parameter here would make sense if you want to habe full control about the authorization process. .Sp Sets up callback for the connection, which will invoke \fBcb_final\fR once the final response for the \s-1INVITE\s0 was received and \fBinit_media\fR if this response was successful. .Sp If no \fBcb_final\fR callback was given it will wait in the event loop until a final response was received. Only in this case it will also use the param \&\fBring_time\fR which specifies the time it will wait for a final response. If no final response came in within this time it will send a \s-1CANCEL\s0 request for this call to close it. In this case a callback specified with \fBcb_noanswer\fR will be called after the \s-1CANCEL\s0 was delivered (or delivery failed). .Sp Returns the connection context as Net::SIP::Endpoint::Context object. .Sp This method is called within \fBinvite\fR in Net::SIP::Simple after creating the new Net::SIP::Simple::Call object to create the first \s-1SDP\s0 session. Changes on the \&\s-1SDP\s0 session will be done by calling this method on the Net::SIP::Simple::Call object \f(CW$self\fR. .ie n .IP "cancel ( %ARGS )" 4 .el .IP "cancel ( \f(CW%ARGS\fR )" 4 .IX Item "cancel ( %ARGS )" Closes a pending call by sending a \s-1CANCEL\s0 request. Returns true if call was pending and could be canceled. .Sp If \f(CW%ARGS\fR contains \fBcb_final\fR it will be used as a callback and invoked once it gets the response for the \s-1CANCEL\s0 (which might be a response packet or a timeout). The rest of \f(CW%ARGS\fR will be merged with the connection parameter and given as an argument to the \fBcb_final\fR callback (as hash reference). .ie n .IP "bye ( %ARGS )" 4 .el .IP "bye ( \f(CW%ARGS\fR )" 4 .IX Item "bye ( %ARGS )" Closes a call by sending a \s-1BYE\s0 request. If \f(CW%ARGS\fR contains \fBcb_final\fR it will be used as a callback and invoked once it gets the response for the \s-1BYE\s0 (which might be a response packet or a timeout). The rest of \f(CW%ARGS\fR will be merged with the connection parameter and given as an argument to the \fBcb_final\fR callback (as hash reference). .ie n .IP "request ( \s-1METHOD, BODY,\s0 %ARGS )" 4 .el .IP "request ( \s-1METHOD, BODY,\s0 \f(CW%ARGS\fR )" 4 .IX Item "request ( METHOD, BODY, %ARGS )" Will create a request with \s-1METHOD\s0 and \s-1BODY\s0 and wait for completion. If \f(CW%ARGS\fR contains \fBcb_final\fR it will be used as a callback and invoked once it gets the response for the request (or timeout). The rest of \f(CW%ARGS\fR will be used to create request (mostly for request header, see Net::SIP::Endpoint::new_request) .ie n .IP "dtmf ( \s-1EVENTS,\s0 %ARGS )" 4 .el .IP "dtmf ( \s-1EVENTS,\s0 \f(CW%ARGS\fR )" 4 .IX Item "dtmf ( EVENTS, %ARGS )" Sends \s-1DTMF\s0 (dial tones) events to peer according to \s-1RFC2833\s0 (e.g. as \s-1RTP\s0 events). .Sp \&\s-1EVENTS\s0 is a string with the characters 0\-9,A\-D,*,#. These will be send as \s-1DTMF.\s0 Any other characters in the string will lead to a pause in sending \s-1DTMF\s0 (e.g. \&\*(L"123\-\-#\*(R" will send \*(L"1\*(R",\*(L"2,\*(R",\*(L"3\*(R", then add to pauses and then send \*(L"#\*(R"). .Sp In \f(CW%ARGS\fR one can specify a \fBduration\fR in ms (default 100ms) and a callback \&\fBcb_final\fR which is invoked with first argument '\s-1OK\s0', when all events are send. If no \fBcb_final\fR callback is given the method will return only when all events are send. .Sp One can also overwrite the automatic detection of the \s-1DTMF\s0 method using \&\fBmethods\fR in \f(CW%ARGS\fR. Default is 'rfc2833,audio', with 'rfc2833' only one enforces the use of \s-1RTP\s0 events, and if the peer does not support it it will croak. Setting to 'audio' will not fail from the client side, but the peer might not look for \s-1DTMF\s0 inband data if it expects \s-1RTP\s0 events. .Sp Sending \s-1DTMF\s0 needs to be supported by the active \s-1RTP\s0 handler set with \&\fBinit_media\fR. All builtin handlers from Net::SIP::Simple::RTP are supported. If no \s-1RTP\s0 handler is set up or if the \s-1RTP\s0 handler does not support \s-1DTMF\s0 sending no \s-1DTMF\s0 will be received without any warning. .IP "receive ( \s-1ENDPOINT, CTX, ERROR, CODE, PACKET, LEG, FROM\s0 )" 4 .IX Item "receive ( ENDPOINT, CTX, ERROR, CODE, PACKET, LEG, FROM )" Will be called from the dispatcher on incoming packets. \s-1ENDPOINT\s0 is the Net::SIP::Endpoint object which manages the Net::SIP::Endpoint::Context \s-1CTX\s0 calling context for the current call. \s-1ERROR\s0 is an errno describing the error (and 0|undef if no error). \s-1CODE\s0 is the numerical code from the packet if a response packet was received. \s-1PACKET\s0 is the incoming packet, \&\s-1LEG\s0 the Net::SIP::Leg where it came in and \s-1FROM\s0 the \f(CW"ip:port"\fR of the sender. For more details see documentation to \fBset_callback\fR in Net::SIP::Endpoint::Context. .Sp If the incoming packet is a \s-1BYE\s0 or \s-1CANCEL\s0 request it will close the call and invoke the \fBrecv_bye\fR callback. .Sp If it is \s-1INVITE\s0 or \s-1ACK\s0 it will make sure that the \s-1RTP\s0 sockets are set up. If receiving an \s-1ACK\s0 to the current call it will invoke the \fBcb_established\fR callback and also the \fBinit_media\fR callback which cares about setting up the \s-1RTP\s0 connections (e.g produce and accept \s-1RTP\s0 traffic). .ie n .IP "set_param ( %ARGS )" 4 .el .IP "set_param ( \f(CW%ARGS\fR )" 4 .IX Item "set_param ( %ARGS )" Changes param like \fBinit_media\fR, \fBsdp_on_ack\fR on the current call. See the constructor. This is useful if call consists of multiple invites with different features. .ie n .IP "get_param ( @KEYS )" 4 .el .IP "get_param ( \f(CW@KEYS\fR )" 4 .IX Item "get_param ( @KEYS )" Returns values for parameter \f(CW@KEYS\fR, pendant to \fBset_param\fR If there is only one key it will return the value as scalar, on multiple keys it returns an array with all values.