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 anncouncement once connected
$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.
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.
- 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:
- 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.