=head1 NAME

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

=head1 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 anncouncement once connected
  $ua->invite( 'you',
	init_media => $ua->rtp( 'send_recv', 'announcement.pcmu-8000' ),
	asymetric_rtp => 1,
  );

  # Mainloop
  $ua->loop;

=head1 DESCRIPTION

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

=head1 CONSTRUCTOR

=over 4

=item 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 B<cleanup> if you want it to go away.

%ARGS can be:

=over 8

=item outgoing_proxy|proxy

C<< "ip:port" >> of outgoing proxy. The necessary L<Net::SIP::Leg> to
the proxy will be created if no leg exists.

=item registrar

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

=item legs|leg

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

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

=item auth

Authorization data, see method B<authorize> in L<Net::SIP::Request> for details
about the format.

=item domain

Default domain for not fully qualified SIP addresses in C<from> and C<to> (method
B<invite>).

=item from

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

=item contact

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

=item 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
B<Allow>, B<Accept>, B<Accept-Encoding>, B<Accept-Language> and B<Supported>.

=item route

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

=item loop

Eventloop object for dispatcher, see L<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.

=item dispatcher

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

=item domain2proxy|d2p

Hash with mapping between domain and upstream proxy. See same key in the constructor
of L<Net::SIP::Dispatcher> for more details.

=back

=back

=head1 METHODS

=over 4

=item 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 B<new>).

=item error ( ERROR )

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

=item loop ( [ TIMEOUT, @STOPVAR ] )

Calls the event loops (key B<loop> in constructor> B<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 B<loop> in L<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.

=item add_timer ( WHEN, CALLBACK, [ REPEAT ] )

Calls same method from the L<Net::SIP::Dispatcher> object in C<$self>.
See there for details on arguments.

=item rtp ( METHOD,@ARGS )

Calls the method METHOD in L<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).

=item register ( %ARGS )

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

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

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

=item invite ( TO,%ARGS )

Invite party TO. Creates a new L<Net::SIP::Simple::Call> object with
TO and creates an INVITE request for this call using %ARGS.
See B<reinvite> in L<Net::SIP::Simple::Call> for more info on %ARGS.

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

=item listen ( %ARGS )

Sets up waiting on all legs in C<$self> for incoming calls, e.g. new INVITE
requests. All other incoming packets will be dropped.
If a call comes in a new L<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 B<loop>.

Special keys not described in L<Net::SIP::Simple::Call>:

=over 8

=item filter

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

=item cb_create

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

Must return TRUE or the call gets not answered.

=item 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 L<Net::SIP::Simple::Call> object as argument.

=item cb_cleanup

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

=back

=item create_registrar ( %ARGS )

Sets up a simple registrar using L<Net::SIP::Registrar>.
See there for the meaning of %ARGS.

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

=item create_stateless_proxy ( %ARGS )

Sets up a simple proxy using L<Net::SIP::StatelessProxy>.
See there for the meaning of %ARGS.

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

=item create_chain ( OBJECTS, %ARGS )

Sets up a chain using L<Net::SIP::ReceiveChain>.
See there for the meaning of OBJECT and %ARGS.

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

=back