.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "2023-09-29" "perl v5.36.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.