Provided by: libnet-sip-perl_0.812-1_all bug

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     Specifies 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]". An alternative would be for example
                   "[97,50,0.03,'iLBC/8000']" for iLBC.

           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.

           dtmf_methods
                   If a DTMF callback is specified this is treated as a list of supported DTMF
                   methods for receiving DTMF. If not given it defaults to 'rfc2833,audio'.

           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.