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:

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.