NAME¶
Net::SIP::Simple::Call - call context for Net::SIP::Simple
SYNOPSIS¶
my $call = $simple->invite(...);
$call->reinvite(... );
$call->bye();
DESCRIPTION¶
This package manages the call context for Net::SIP::Simple, e.g. (re-)invites on
existing context etc.
CONSTRUCTOR¶
- new ( CONTROL, CTX, \%ARGS )
- Creates a new Net::SIP::Simple::Call object to control a call. Usually
called from invite in Net::SIP::Simple.
CONTROL is the Net::SIP::Simple object managing the calls.
CTX is either an existing Net::SIP::Endpoint::Context or the SIP 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 $call if called as "$call-"new>.
%ARGS 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 %ARGS:
- leg
- Which leg should be used for the call (default is first leg in
dispatcher).
- sdp_on_ack
- If given and TRUE it will not send the SDP body on INVITE request, but on
ACK. Mainly used for testing behavior of proxies in between the two
parties.
- init_media
- Callback used to initialize media for the connection, see method
rtp in Net::SIP::Simple and Net::SIP::Simple::RTP.
Callback will be invoked with the call $self and the connection parameter as
an argument (as hash reference).
- rtp_param
- Data for the codec used in the media specified by init_media and
for the initialization of the default SDP data. This is an array reference
"[pt,size,interval,name]" where pt is the payload type,
size is the size of the payload and interval the interval in
which the RTP packets will be send. name is optional and if given
rtpmap and ptime entries will be added to the SDP so that the name is
associated with the given payload type. The default is for PCMU/8000:
"[0,160,160/8000]".
- sdp
- Net::SIP::SDP object or argument for constructing this object. If not
given it will create an SDP body with one RTP audio connection unless it
got first SDP data from the peer in which case it simply matches
them.
- sdp_peer
- Holds the Net::SIP::SDP body send by the peer. Usually not set in the
constructor but can be accessed from callbacks.
- media_lsocks
- Contains a \@list of sockets for each media-line in the SDP. Each item in
this list is either a single socket (in case of port range 1) or a \@list
of sockets.
If sdp is provided this parameter has to be provided too, e.g. the
package will not allocate the sockets described in the SDP packet.
- media_ssocks
- Sockets used for sending RTP data. If not given the socket for sending RTP
is the same as for receiving RTP, unless asymetric_rtp is
specified.
- asymetric_rtp
- By default it will send the RTP data from the same port where it listens
for the data. If this option is TRUE it will allocate a different port for
receiving data. Mainly used for testing behavior of proxies in between the
two parties.
- recv_bye
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when the peer initiated the close of the connection using BYE or
CANCEL.
Argument for the callback will be a hash reference containing the connection
parameter.
- send_bye
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when the local side initiated the close of the connection using
BYE or CANCEL.
Argument for the callback will be a hash reference containing the connection
parameter merged with the parameter from the bye method.
- clear_sdp
- If TRUE 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 RTP instead of reusing the existing.
- cb_final
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received the final answer on locally created INVITE
requests (e.g. when it established the call by sending the ACK).
Callback will be invoked with "( STATUS, SELF, %INFO )" where
STATUS is either 'OK' or 'FAIL' ('OK' if final response meant success,
else 'FINAL'), and %INFO contains more information, like "( packet
=> packet )" for the packet containing the final answer or "(
code => response_code )" in case failures caused by an
unsuccessful response.
- cb_preliminary
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received a preliminary response on locally created
INVITE.
Callback will be invoked with "( SELF, CODE, RESPONSE )" where
CODE is the response code and RESPONSE the Net::SIP::Response packet.
- cb_established
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received the final answer on locally created INVITE
requests.
Callback will be invoked with "( 'OK', SELF )".
- cb_invite
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received an INVITE request
Callback will be invoked with "( SELF, REQUEST )" where REQUEST is
the Net::SIP::Request packet for the INVITE.
- cb_dtmf
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received an DTMF event.
Callback will be invoked with "( EVENT, DURATION )" where EVENT is
the event ([0-9A-D*#]) and DURATION the duration in ms.
Receiving DTMF needs to be supported by the active RTP handler set with
init_media. All builtin handlers from Net::SIP::Simple::RTP are
supported. If no RTP handler is set up or if the RTP handler does not
support DTMF sending no DTMF will be received without any warning.
- cb_notify
- Callback usable by invoke_callback in Net::SIP::Util which will be
invoked, when it received an NOTIFY request
Callback will be invoked with "( SELF, REQUEST )" where REQUEST is
the Net::SIP::Request packet for the NOTIFY.
- sip_header
- A reference to a hash with additional SIP headers for the INVITE
requests.
- call_on_hold
- This option causes the next SDP 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 set_param or within
reinvite each time the call should be put on hold.
- ...
- More parameters may be specified and are accessible from the callbacks.
For instance media_send_recv in Net::SIP::Simple::RTP uses a
parameter cb_rtp_done. See there.
METHODS¶
- cleanup
- Will be called to clean up the call. Necessary because callbacks etc can
cause cyclic references which need to be broken. Calls rtp_cleanup
too. Works by invoking all callbacks which are stored as \@list in
"$self->{call_cleanup}".
This will called automatically at a clean end of a call (e.g. on BYE or
CANCEL, 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.
- rtp_cleanup
- Cleanup of current RTP connection. Works be invoking all callbacks which
are stored as \@list in "$self->{rtp_cleanup}" (these
callbacks are inserted by Net::SIP::Simple::RTP etc).
- get_peer
- Returns peer of call, see peer in Net::SIP::Endpoint::Context.
- reinvite ( %ARGS )
- Creates a INVITE request which causes either the initial SDP session or an
update of the SDP session (reinvite). %ARGS will merged with the
connection parameter, see description on the constructor. Additionally
using resp40x an auth as a parameter here would make sense
if you want to habe full control about the authorization process.
Sets up callback for the connection, which will invoke cb_final once
the final response for the INVITE was received and init_media if
this response was successful.
If no cb_final 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 ring_time which specifies the time it will wait for a
final response. If no final response came in within this time it will send
a CANCEL request for this call to close it. In this case a callback
specified with cb_noanswer will be called after the CANCEL was
delivered (or delivery failed).
Returns the connection context as Net::SIP::Endpoint::Context object.
This method is called within invite in Net::SIP::Simple after
creating the new Net::SIP::Simple::Call object to create the first SDP
session. Changes on the SDP session will be done by calling this method on
the Net::SIP::Simple::Call object $self.
- cancel ( %ARGS )
- Closes a pending call by sending a CANCEL request. Returns true if call
was pending and could be canceled.
If %ARGS contains cb_final it will be used as a callback and invoked
once it gets the response for the CANCEL (which might be a response packet
or a timeout). The rest of %ARGS will be merged with the connection
parameter and given as an argument to the cb_final callback (as
hash reference).
- bye ( %ARGS )
- Closes a call by sending a BYE request. If %ARGS contains cb_final
it will be used as a callback and invoked once it gets the response for
the BYE (which might be a response packet or a timeout). The rest of %ARGS
will be merged with the connection parameter and given as an argument to
the cb_final callback (as hash reference).
- request ( METHOD, BODY, %ARGS )
- Will create a request with METHOD and BODY and wait for completion. If
%ARGS contains cb_final it will be used as a callback and invoked
once it gets the response for the request (or timeout). The rest of %ARGS
will be used to create request (mostly for request header, see
Net::SIP::Endpoint::new_request)
- dtmf ( EVENTS, %ARGS )
- Sends DTMF (dial tones) events to peer according to RFC2833 (e.g. as RTP
events).
EVENTS is a string with the characters 0-9,A-D,*,#. These will be send as
DTMF. Any other characters in the string will lead to a pause in sending
DTMF (e.g. "123--#" will send
"1","2,","3", then add to pauses and then
send "#").
In %ARGS one can specify a duration in ms (default 100ms) and a
callback cb_final which is invoked with first argument 'OK', when
all events are send. If no cb_final callback is given the method
will return only when all events are send.
One can also overwrite the automatic detection of the DTMF method using
methods in %ARGS. Default is 'rfc2833,audio', with 'rfc2833' only
one enforces the use of RTP 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 DTMF inband data if it expects RTP events.
Sending DTMF needs to be supported by the active RTP handler set with
init_media. All builtin handlers from Net::SIP::Simple::RTP are
supported. If no RTP handler is set up or if the RTP handler does not
support DTMF sending no DTMF will be received without any warning.
- receive ( ENDPOINT, CTX, ERROR, CODE, PACKET, LEG, FROM )
- Will be called from the dispatcher on incoming packets. ENDPOINT is the
Net::SIP::Endpoint object which manages the Net::SIP::Endpoint::Context
CTX calling context for the current call. ERROR is an errno describing the
error (and 0|undef if no error). CODE is the numerical code from the
packet if a response packet was received. PACKET is the incoming packet,
LEG the Net::SIP::Leg where it came in and FROM the "ip:port" of
the sender. For more details see documentation to set_callback in
Net::SIP::Endpoint::Context.
If the incoming packet is a BYE or CANCEL request it will close the call and
invoke the recv_bye callback.
If it is INVITE or ACK it will make sure that the RTP sockets are set up. If
receiving an ACK to the current call it will invoke the
cb_established callback and also the init_media callback
which cares about setting up the RTP connections (e.g produce and accept
RTP traffic).
- set_param ( %ARGS )
- Changes param like init_media, sdp_on_ack on the current
call. See the constructor. This is useful if call consists of multiple
invites with different features.
- get_param ( @KEYS )
- Returns values for parameter @KEYS, pendant to set_param If there
is only one key it will return the value as scalar, on multiple keys it
returns an array with all values.