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

NAME

       Net::SIP::Simple - Simple interface for using Net::SIP

SYNOPSIS

         use Net::SIP;

         # create new agent
         my $ua = Net::SIP::Simple->new(
               outgoing_proxy => '192.168.0.10',
               registrar => '192.168.0.10',
               domain => 'example.com',
               from => 'me',
               auth => [ 'me','secret' ],
         );

         # Register agent
         $ua->register;

         # Invite other party, send announcement once connected
         my $call = $ua->invite( 'you',
               init_media => $ua->rtp( 'send_recv', 'announcement.pcmu-8000' ),
               asymetric_rtp => 1,
         );

         # Mainloop
         $ua->loop;

DESCRIPTION

       This package implements a simple layer on top of Net::SIP::Endpoint, Net::SIP::Registrar
       and Net::SIP::StatelessProxy.  With the help of this package it is possible to write
       simple SIP applications with a few lines perl code.

CONSTRUCTOR

       new ( %ARGS )
           Creates new Net::SIP::Simple object.

           It will return the new object for further operations, but the object itself will
           contain back references to itself in the form of callbacks into the eventloop and
           dispatcher.  This means that that object will not self-destroy, but you need to call
           cleanup if you want it to go away.

           %ARGS can be:

           outgoing_proxy|proxy
                   "ip:port" of outgoing proxy. The necessary Net::SIP::Leg to the proxy will be
                   created if no leg exists.

           registrar
                   "ip:port" of registrar. Used in method register if there is no other registrar
                   given.

           legs|leg
                   \@List of legs or single leg. Leg can be an existing Net::SIP::Leg (or
                   derived) object, an IO::Handle (existing socket), a hash reference which can
                   be used in the constructor of Net::SIP::Leg or a string of "proto:ip:port".
                   In the latter case "proto" can be omitted (including the colon) and defaults
                   to 'udp' and "port" can be omitted to (including the colon) defaulting to
                   5060.

                   Either legs or outgoing_proxy has to be provided, e.g. it needs at least one
                   leg.

           auth    Authorization data, see method authorize in Net::SIP::Request for details
                   about the format.

           domain  Default domain for not fully qualified SIP addresses in "from" and "to"
                   (method invite).

           from    SIP address of local sender, either full SIP address or only part before \@,
                   in which case domain has to be provided.

           contact SIP address of local sender, which should be used in the contact header of
                   REGISTER and INVITE requests. If not given from will be used.

           options This is a hash reference containing headers (header-key,value) for replies to
                   an OPTIONS request. If not or only partly given defaults will be used for the
                   headers Allow, Accept, Accept-Encoding, Accept-Language and Supported.

           route   Optional list of SIP routes which will be added to route requests.

           loop    Eventloop object for dispatcher, see Net::SIP::Dispatcher::Eventloop. Usually
                   not given, because the loop from the dispatcher will be used, but can be given
                   if no dispatcher was given.

           dispatcher
                   Net::SIP::Dispatcher object. Usually not given and will be created, but
                   sometimes one need to share the same dispatcher between multiple
                   Net::SIP::Simple objects.

           domain2proxy|d2p
                   Hash with mapping between domain and upstream proxy. See same key in the
                   constructor of Net::SIP::Dispatcher for more details.

           tls     Common TLS settings for all legs which will be created by this object. See
                   "new" in Net::SIP::Leg for more details.

METHODS

       cleanup
           Cleans up object, removes legs it added from the dispatcher.  Needs to be called if
           you want to destroy the object, because it will not self-destroy (see new).

       error ( ERROR )
           Either sets current error (used internally) or returns last error.

       loop ( [ TIMEOUT, @STOPVAR ] )
           Calls the event loops (key loop in constructor> loop method.  TIMEOUT is the timeout
           for the loop in seconds. If not given it will not stop because of timeout. @STOPVAR is
           a list of scalar references, will stop the loop if any of these references contains
           TRUE.  See method loop in Net::SIP::Dispatcher::Eventloop for more details.

           The order of TIMEOUT or the STOPVARs is insignificant, e.g. if it finds a reference it
           will use it as stopvar, otherwise it's used as timeout.

       add_timer ( WHEN, CALLBACK, [ REPEAT ] )
           Calls same method from the Net::SIP::Dispatcher object in $self.  See there for
           details on arguments.

       rtp ( METHOD,@ARGS )
           Calls the method METHOD in Net::SIP::Simple::RTP with arguments @ARGS. Currently only
           does this and thus works as a shortcut.  In the future one might add more ways to find
           the right method for RTP handling (e.g. plugins or similar).

       register ( %ARGS )
           Registers the user agent. %ARGS can have the key registrar which has precedence over
           the same key in the constructor.  leg specifies the leg where the register request
           will be send through.  If not given it will pick the right leg.

           If cb_final is specified it is a callback usable by invoke_callback in Net::SIP::Util
           which will be called, once the registration is completed (e.g. it succeeded or
           failed). If no cb_final is specified the method will wait, until the registration is
           completed and return either the expires time given by the registrar or "()" if
           registration failed.

           All other keys, like contact, expires, resp40x, auth will be forwarded to method
           register in Net::SIP::Endpoint.  from and auth will be used from %ARGS or if not in
           %ARGS from the constructor.

       invite ( CTX,%ARGS )
           Creates a new call and invites peer.  Creates a new Net::SIP::Simple::Call object with
           context CTX and creates an INVITE request for this call using %ARGS.  See reinvite in
           Net::SIP::Simple::Call for more info on %ARGS.

           CTX can be address of peer or context hash containing the address.

           Returns with the newly created Net::SIP::Simple::Call object, which can later be used
           for reINVITEs or BYE etc.

           Note that in order to have any callbacks triggered by the invite working one needs to
           keep the returned caller object.

       listen ( %ARGS )
           Sets up waiting on all legs in $self for incoming calls, e.g. new INVITE requests. All
           other incoming packets will be dropped.  If a call comes in a new
           Net::SIP::Simple::Call object will be created using %ARGS.

           The method does not wait for the calls, its setting only the callback on the legs up.
           Thus it has to be followed by a call to loop.

           If %ARGS contain "auth_*" keys an Authorizer will be added before the listener.  See
           Net::SIP::Authorize for the keys, e.g. "auth_user2pass" will be forwarded as
           "user2pass" etc to the authorizer.

           Special keys not described in Net::SIP::Simple::Call:

           The returned object can be used together with other objects within "create_chain", but
           it should be used as the last object.

           filter  A callback usable by invoke_callback in Net::SIP::Util which gets called with
                   the value of the From header and the Net::SIP::Request object from the
                   incoming request.  If the callback returns TRUE the call gets accepted,
                   otherwise not.

           cb_create
                   Callback which will be called on accepting the call. Will be called with
                   "CALL,REQUEST,LEG,FROM" where CALL is the newly created Net::SIP::Simple::Call
                   object, REQUEST the creating Net::SIP::Request packet, LEG the incoming leg
                   and FROM the "ip:port" of the sender.

                   Must return TRUE or the call gets not answered.

           cb_established
                   Callback which will be called, after the call is established, e.g.  after
                   receiving the ACK from the peer. Will be invoked with 'OK' and the
                   Net::SIP::Simple::Call object as argument.

           cb_cleanup
                   Callback which will be called when the call gets closed to clean up allocated
                   resources. Will be invoked with the  Net::SIP::Simple::Call object as
                   argument.

       create_auth ( %ARGS )
           Sets up authorization.  See Net::SIP::Authorize for the meaning of %ARGS.  The
           returned object should be used together with other objects within "create_chain".

       create_registrar ( %ARGS )
           Sets up a simple registrar using Net::SIP::Registrar.  See there for the meaning of
           %ARGS.

           Like with listen you need to loop after calling this method, the method itself will
           not wait.

           Like with listen authorization can be added uses "auth_*" keys.

       create_stateless_proxy ( %ARGS )
           Sets up a simple proxy using Net::SIP::StatelessProxy.  See there for the meaning of
           %ARGS.

           Like with listen you need to loop after calling this method, the method itself will
           not wait.

           Like with listen authorization can be added uses "auth_*" keys.

       create_chain ( OBJECTS, %ARGS )
           Sets up a chain using Net::SIP::ReceiveChain.  See there for the meaning of OBJECT and
           %ARGS.

           Like with listen you need to loop after calling this method, the method itself will
           not wait.