/ 
Net-SIP-0.11
River stage one • 1 direct dependent • 1 total dependent
/ Net::SIP::Simple::Call

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.

%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 connection parameter as an argument (as hash reference).

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 ( CODE => response_code ) in case failures caused by an unsuccessful response.

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 ).

...

More parameters may be specified and are accessable 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 be invoking all callbacks which are stored as \@list in $self->{call_cleanup}.

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).

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.

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.

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.

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).

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).