.\" 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::Registrar 3pm"
.TH Net::SIP::Registrar 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::Registrar \- Endpoint for registering SIP clients
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  my $reg = Net::SIP::Registrar\->new(
\&        dispatcher => $dispatcher,
\&        min_expires => 10,
\&        max_expires => 60,
\&        domains => [ \*(Aqexample.com\*(Aq,\*(Aqexample.org\*(Aq ],
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package implements a simple \s-1SIP\s0 registrar. In the current implementation
registry information are only kept in memory, e.g. they are not preserved over
restarts.
.PP
The implementation itself does not checking if the \s-1UAC\s0 is authorized to 
register the given address. This can be done with using an appropriate 
Authorize Module inside a ReceiveChain in front of the registrar.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( %ARGS )" 4
.el .IP "new ( \f(CW%ARGS\fR )" 4
.IX Item "new ( %ARGS )"
This creates a new registar object, \f(CW%ARGS\fR can have the following keys:
.RS 4
.IP "dispatcher" 8
.IX Item "dispatcher"
Net::SIP::Dispatcher object manging the registar. Mandatory.
.IP "max_expires" 8
.IX Item "max_expires"
Maximum expires time accepted. If the client requests a larger
expires value it will be capped at \fBmax_expires\fR
Defaults to 300.
.IP "min_expires" 8
.IX Item "min_expires"
Minimum expires value. If the client requests a smaller value
the registrar will return a response of \f(CW\*(C`423 Interval too brief\*(C'\fR.
Defaults to 30.
.IP "domains or domain" 8
.IX Item "domains or domain"
Either string or reference to list of strings containing the names
of the domains the registrar is responsable for. If not given the
registrar accepts everything.
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "receive ( \s-1PACKET,LEG,FROM\s0 )" 4
.IX Item "receive ( PACKET,LEG,FROM )"
\&\s-1PACKET\s0 is the incoming packet,
\&\s-1LEG\s0 is the Net::SIP::Leg where the packet arrived and \s-1FROM\s0
is the \f(CW"ip:port"\fR of the sender. Responses will be send
back to the sender through the same leg.
.Sp
Called from the managing Net::SIP::Dispatcher object if a new
packet arrives. Will return \f(CW\*(C`()\*(C'\fR and ignore the packet if it's
not a \s-1REGISTER\s0 request or if it is not responsable for the domain
given in the \f(CW\*(C`From\*(C'\fR heeader of the \s-1REGISTER\s0 request.
.Sp
If it is responsable for the packet it will create a response
and return the code of the response. Responses are either
\&\f(CW\*(C`423 Interval too brief\*(C'\fR if the request expires time
is too small, or \f(CW\*(C`200 Ok\*(C'\fR if the expires time is 0 (e.g. the
client should be unregistered) or greater or equal \fBmin_expires\fR.
.Sp
In case of a successful response it will also update the internal
registry information.
.IP "query ( \s-1ADDR\s0 )" 4
.IX Item "query ( ADDR )"
Search for \s-1ADDR\s0 (which has format \f(CW\*(C`proto:user@domain\*(C'\fR)
in the registry. Returns \f(CW@List\fR of all sip or sips contacts
for \s-1ADDR.\s0
.IP "expire" 4
.IX Item "expire"
Removes all expired entries from the internal registry.
Called whenever the registry information gets updated from
sub \fBreceive\fR.