.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SIP::Simple 3pm"
.TH Net::SIP::Simple 3pm "2023-09-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SIP::Simple \- Simple interface for using Net::SIP
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::SIP;
\&
\&  # create new agent
\&  my $ua = Net::SIP::Simple\->new(
\&        outgoing_proxy => \*(Aq192.168.0.10\*(Aq,
\&        registrar => \*(Aq192.168.0.10\*(Aq,
\&        domain => \*(Aqexample.com\*(Aq,
\&        from => \*(Aqme\*(Aq,
\&        auth => [ \*(Aqme\*(Aq,\*(Aqsecret\*(Aq ],
\&  );
\&
\&  # Register agent
\&  $ua\->register;
\&
\&  # Invite other party, send announcement once connected
\&  my $call = $ua\->invite( \*(Aqyou\*(Aq,
\&        init_media => $ua\->rtp( \*(Aqsend_recv\*(Aq, \*(Aqannouncement.pcmu\-8000\*(Aq ),
\&        asymetric_rtp => 1,
\&  );
\&
\&  # Mainloop
\&  $ua\->loop;
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1SIP\s0 applications
with a few lines perl code.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( %ARGS )" 4
.el .IP "new ( \f(CW%ARGS\fR )" 4
.IX Item "new ( %ARGS )"
Creates new Net::SIP::Simple object.
.Sp
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 \fBcleanup\fR if you want it to go away.
.Sp
\&\f(CW%ARGS\fR can be:
.RS 4
.IP "outgoing_proxy|proxy" 8
.IX Item "outgoing_proxy|proxy"
\&\f(CW"ip:port"\fR of outgoing proxy. The necessary Net::SIP::Leg to
the proxy will be created if no leg exists.
.IP "registrar" 8
.IX Item "registrar"
\&\f(CW"ip:port"\fR of registrar. Used in method \fBregister\fR if there is no
other registrar given.
.IP "legs|leg" 8
.IX Item "legs|leg"
\&\e@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 \f(CW"proto:ip:port"\fR.
In the latter case \f(CW\*(C`proto\*(C'\fR can be omitted (including the colon) and defaults
to 'udp' and \f(CW\*(C`port\*(C'\fR can be omitted to (including the colon) defaulting to 5060.
.Sp
Either \fBlegs\fR or \fBoutgoing_proxy\fR has to be provided, e.g. it needs at least one
leg.
.IP "auth" 8
.IX Item "auth"
Authorization data, see method \fBauthorize\fR in Net::SIP::Request for details
about the format.
.IP "domain" 8
.IX Item "domain"
Default domain for not fully qualified \s-1SIP\s0 addresses in \f(CW\*(C`from\*(C'\fR and \f(CW\*(C`to\*(C'\fR (method
\&\fBinvite\fR).
.IP "from" 8
.IX Item "from"
\&\s-1SIP\s0 address of local sender, either full \s-1SIP\s0 address or only part before \e@, in which
case \fBdomain\fR has to be provided.
.IP "contact" 8
.IX Item "contact"
\&\s-1SIP\s0 address of local sender, which should be used in the contact header of \s-1REGISTER\s0
and \s-1INVITE\s0 requests. If not given \fBfrom\fR will be used.
.IP "options" 8
.IX Item "options"
This is a hash reference containing headers (header\-key,value) for replies to an
\&\s-1OPTIONS\s0 request. If not or only partly given defaults will be used for the headers
\&\fBAllow\fR, \fBAccept\fR, \fBAccept-Encoding\fR, \fBAccept-Language\fR and \fBSupported\fR.
.IP "route" 8
.IX Item "route"
Optional list of \s-1SIP\s0 routes which will be added to route requests.
.IP "loop" 8
.IX Item "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.
.IP "dispatcher" 8
.IX Item "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.
.IP "domain2proxy|d2p" 8
.IX Item "domain2proxy|d2p"
Hash with mapping between domain and upstream proxy. See same key in the constructor
of Net::SIP::Dispatcher for more details.
.IP "tls" 8
.IX Item "tls"
Common \s-1TLS\s0 settings for all legs which will be created by this object. See
\&\f(CW\*(C`new\*(C'\fR in Net::SIP::Leg for more details.
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "cleanup" 4
.IX 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 \fBnew\fR).
.IP "error ( \s-1ERROR\s0 )" 4
.IX Item "error ( ERROR )"
Either sets current error (used internally) or returns last error.
.ie n .IP "loop ( [ \s-1TIMEOUT,\s0 @STOPVAR ] )" 4
.el .IP "loop ( [ \s-1TIMEOUT,\s0 \f(CW@STOPVAR\fR ] )" 4
.IX Item "loop ( [ TIMEOUT, @STOPVAR ] )"
Calls the event loops (key \fBloop\fR in constructor> \fBloop\fR method.
\&\s-1TIMEOUT\s0 is the timeout for the loop in seconds. If not given it will
not stop because of timeout. \f(CW@STOPVAR\fR is a list of scalar references,
will stop the loop if any of these references contains \s-1TRUE.\s0
See method \fBloop\fR in Net::SIP::Dispatcher::Eventloop for more
details.
.Sp
The order of \s-1TIMEOUT\s0 or the STOPVARs is insignificant, e.g. if it
finds a reference it will use it as stopvar, otherwise it's used as
timeout.
.IP "add_timer ( \s-1WHEN, CALLBACK,\s0 [ \s-1REPEAT\s0 ] )" 4
.IX Item "add_timer ( WHEN, CALLBACK, [ REPEAT ] )"
Calls same method from the Net::SIP::Dispatcher object in \f(CW$self\fR.
See there for details on arguments.
.IP "rtp ( \s-1METHOD\s0,@ARGS )" 4
.IX Item "rtp ( METHOD,@ARGS )"
Calls the method \s-1METHOD\s0 in Net::SIP::Simple::RTP with arguments
\&\f(CW@ARGS\fR. Currently only does this and thus works as a shortcut.
In the future one might add more ways to find the right method
for \s-1RTP\s0 handling (e.g. plugins or similar).
.ie n .IP "register ( %ARGS )" 4
.el .IP "register ( \f(CW%ARGS\fR )" 4
.IX Item "register ( %ARGS )"
Registers the user agent. \f(CW%ARGS\fR can have the key \fBregistrar\fR which
has precedence over the same key in the constructor.
\&\fBleg\fR specifies the leg where the register request will be send through.
If not given it will pick the right leg.
.Sp
If \fBcb_final\fR is specified it is a callback usable by \fBinvoke_callback\fR
in Net::SIP::Util which will be called, once the registration is
completed (e.g. it succeeded or failed). If no \fBcb_final\fR is specified
the method will wait, until the registration is completed and return
either the expires time given by the registrar or \f(CW\*(C`()\*(C'\fR if registration
failed.
.Sp
All other keys, like \fBcontact\fR, \fBexpires\fR, \fBresp40x\fR, \fBauth\fR
will be forwarded to method \fBregister\fR in Net::SIP::Endpoint.
\&\fBfrom\fR and \fBauth\fR will be used from \f(CW%ARGS\fR or if not in \f(CW%ARGS\fR from
the constructor.
.IP "invite ( \s-1CTX\s0,%ARGS )" 4
.IX Item "invite ( CTX,%ARGS )"
Creates a new call and invites peer.
Creates a new Net::SIP::Simple::Call object with context \s-1CTX\s0
and creates an \s-1INVITE\s0 request for this call using \f(CW%ARGS\fR.
See \fBreinvite\fR in Net::SIP::Simple::Call for more info on \f(CW%ARGS\fR.
.Sp
\&\s-1CTX\s0 can be address of peer or context hash containing the address.
.Sp
Returns with the newly created Net::SIP::Simple::Call object,
which can later be used for reINVITEs or \s-1BYE\s0 etc.
.Sp
Note that in order to have any callbacks triggered by the invite working
one needs to keep the returned caller object.
.ie n .IP "listen ( %ARGS )" 4
.el .IP "listen ( \f(CW%ARGS\fR )" 4
.IX Item "listen ( %ARGS )"
Sets up waiting on all legs in \f(CW$self\fR for incoming calls, e.g. new \s-1INVITE\s0
requests. All other incoming packets will be dropped.
If a call comes in a new Net::SIP::Simple::Call object will
be created using \f(CW%ARGS\fR.
.Sp
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 \fBloop\fR.
.Sp
If \f(CW%ARGS\fR contain \f(CW\*(C`auth_*\*(C'\fR keys an Authorizer will be added before the listener.
See Net::SIP::Authorize for the keys, e.g. \f(CW\*(C`auth_user2pass\*(C'\fR will be
forwarded as \f(CW\*(C`user2pass\*(C'\fR etc to the authorizer.
.Sp
Special keys not described in Net::SIP::Simple::Call:
.Sp
The returned object can be used together with other objects
within \f(CW\*(C`create_chain\*(C'\fR, but it should be used as the last object.
.RS 4
.IP "filter" 8
.IX Item "filter"
A callback usable by \fBinvoke_callback\fR in Net::SIP::Util which gets
called with the value of the \fBFrom\fR header and the Net::SIP::Request
object from the incoming request.
If the callback returns \s-1TRUE\s0 the call gets accepted, otherwise not.
.IP "cb_create" 8
.IX Item "cb_create"
Callback which will be called on accepting the call. Will be called
with \f(CW\*(C`CALL,REQUEST,LEG,FROM\*(C'\fR where \s-1CALL\s0 is the newly created
Net::SIP::Simple::Call object, \s-1REQUEST\s0 the creating Net::SIP::Request
packet, \s-1LEG\s0 the incoming leg and \s-1FROM\s0 the \f(CW"ip:port"\fR of the sender.
.Sp
Must return \s-1TRUE\s0 or the call gets not answered.
.IP "cb_established" 8
.IX Item "cb_established"
Callback which will be called, after the call is established, e.g.
after receiving the \s-1ACK\s0 from the peer. Will be invoked with '\s-1OK\s0'
and the Net::SIP::Simple::Call object as argument.
.IP "cb_cleanup" 8
.IX Item "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.
.RE
.RS 4
.RE
.ie n .IP "create_auth ( %ARGS )" 4
.el .IP "create_auth ( \f(CW%ARGS\fR )" 4
.IX Item "create_auth ( %ARGS )"
Sets up authorization.
See Net::SIP::Authorize for the meaning of \f(CW%ARGS\fR.
The returned object should be used together with other objects
within \f(CW\*(C`create_chain\*(C'\fR.
.ie n .IP "create_registrar ( %ARGS )" 4
.el .IP "create_registrar ( \f(CW%ARGS\fR )" 4
.IX Item "create_registrar ( %ARGS )"
Sets up a simple registrar using Net::SIP::Registrar.
See there for the meaning of \f(CW%ARGS\fR.
.Sp
Like with \fBlisten\fR you need to \fBloop\fR after calling this
method, the method itself will not wait.
.Sp
Like with \fBlisten\fR authorization can be added uses \f(CW\*(C`auth_*\*(C'\fR keys.
.ie n .IP "create_stateless_proxy ( %ARGS )" 4
.el .IP "create_stateless_proxy ( \f(CW%ARGS\fR )" 4
.IX Item "create_stateless_proxy ( %ARGS )"
Sets up a simple proxy using Net::SIP::StatelessProxy.
See there for the meaning of \f(CW%ARGS\fR.
.Sp
Like with \fBlisten\fR you need to \fBloop\fR after calling this
method, the method itself will not wait.
.Sp
Like with \fBlisten\fR authorization can be added uses \f(CW\*(C`auth_*\*(C'\fR keys.
.ie n .IP "create_chain ( \s-1OBJECTS,\s0 %ARGS )" 4
.el .IP "create_chain ( \s-1OBJECTS,\s0 \f(CW%ARGS\fR )" 4
.IX Item "create_chain ( OBJECTS, %ARGS )"
Sets up a chain using Net::SIP::ReceiveChain.
See there for the meaning of \s-1OBJECT\s0 and \f(CW%ARGS\fR.
.Sp
Like with \fBlisten\fR you need to \fBloop\fR after calling this
method, the method itself will not wait.