.\" 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::Dispatcher 3pm"
.TH Net::SIP::Dispatcher 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::Dispatcher \- dispatch SIP packets between legs and endpoint
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $disp = Net::SIP::Dispatcher\->new( ... );
\&  $disp\->deliver( $request );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module dispatches Net::SIP::Packets between Net::SIP::Legs
and endpoints like Net::SIP::Endpoint, Net::SIP::Registrar and
Net::SIP::StatelessProxy.
.PP
It manages retransmission of outgoing packets and redelivery of responses
to incoming requests.
.PP
It is asssociated with an event handling like
Net::SIP::Dispatcher::Eventloop.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( \e@LEGS, \s-1EVENTLOOP,\s0 %ARGS )" 4
.el .IP "new ( \e@LEGS, \s-1EVENTLOOP,\s0 \f(CW%ARGS\fR )" 4
.IX Item "new ( @LEGS, EVENTLOOP, %ARGS )"
Creates a new dispatcher object.
.Sp
\&\f(CW@LEGS\fR is a list of legs or specification for legs. See \fBadd_leg\fR for
possible formats.
.Sp
\&\s-1EVENTLOOP\s0 is a eventloop which provides handling of events on file
descriptors and timers. If not given a new Net::SIP::Dispatcher::Eventloop
object will be created and used. See there how to define your own
event loop package.
.Sp
\&\f(CW%ARGS\fR are parameters for the behavior of the dispatcher:
.RS 4
.IP "outgoing_proxy" 8
.IX Item "outgoing_proxy"
Specifies \f(CW"ip:port"\fR of outgoing proxy, e.g the proxy which will
be used for all outgoing packets. A leg to reach this proxy need to exist.
.IP "do_retransmits" 8
.IX Item "do_retransmits"
If \s-1TRUE\s0 retransmits will be done according to \s-1RFC3261.\s0 If \s-1FALSE\s0 no
retransmits will be done, which is used in the case of stateless
proxies.
Defaults to \s-1TRUE.\s0
.Sp
This is the default for the delivery and can be overwritten in
sub \fBdeliver\fR.
.IP "domain2proxy" 8
.IX Item "domain2proxy"
Optional mapping between target \s-1SIP\s0 domain and proxy to use.
This is usually a hash of \f(CW\*(C`( domain, "ip_proxy:port_proxy" )\*(C'\fR
pairs. Special domain '*' can be used to specify a fallback
and '*.domain' to include not only the domain but the subdomains
too.
See sub \fBdeliver\fR for more details.
.IP "dnsresolv" 8
.IX Item "dnsresolv"
Optional function to be used for \s-1DNS\s0 resolving instead of Net::DNS. This is
intended for testing or for interfacing with own resolver code.
The function is called with \f(CW\*(C`(type,name,callback)\*(C'\fR and is expected to
invoke the callback with the answer. \f(CW\*(C`type\*(C'\fR can be \s-1SRV, A\s0 or \s-1AAAA\s0 and the
answer is expected to be a list consisting of \f(CW\*(C`[\*(AqSRV\*(Aq,prio,host,port]\*(C'\fR,
\&\f(CW\*(C`[\*(AqA\*(Aq,ip,host]\*(C'\fR and \f(CW\*(C`[\*(AqAAAA\*(Aq,ip,host]\*(C'\fR.
.RE
.RS 4
.Sp
The constructor will create a timer using the eventloop which
will regularly (each second) call \fBqueue_expire\fR.
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "set_receiver ( \s-1ENDPOINT\s0 )" 4
.IX Item "set_receiver ( ENDPOINT )"
This sets \s-1ENDPOINT\s0 as a receiver for incoming packets.
\&\s-1ENDPOINT\s0 is an object with a method \fBreceive\fR or
a callback usable by \fBinvoke_callback\fR in Net::SIP::Util.
.IP "add_leg ( \s-1LEG\s0 )" 4
.IX Item "add_leg ( LEG )"
Adds \s-1LEG\s0 as a leg to the dispatcher \f(CW$self\fR. \s-1LEG\s0 can be either
a Net::SIP::Leg object, a IO::Handle or a hash reference
which is usable in the constructor of Net::SIP::Leg.
.Sp
The leg will be added to the dispatchers eventloop for receiving
incoming packets.
.IP "remove_leg ( \s-1LEG\s0 )" 4
.IX Item "remove_leg ( LEG )"
Removes Net::SIP::Leg object \s-1LEG\s0 from the dispatcher.
.ie n .IP "get_legs ( %ARGS )" 4
.el .IP "get_legs ( \f(CW%ARGS\fR )" 4
.IX Item "get_legs ( %ARGS )"
Get a list of all Net::SIP::Leg objects matching the
criteria given by \f(CW%ARGS\fR. \f(CW%ARGS\fR can be a combination of:
.RS 4
.IP "addr" 8
.IX Item "addr"
Matches if given address matches the legs source address.
.IP "port" 8
.IX Item "port"
Matches if given port matches the legs source port.
.IP "proto" 8
.IX Item "proto"
Matches if given proto ('udp','tcp') matches the legs protocol.
.IP "sub" 8
.IX Item "sub"
Call given sub with the Net::SIP::Leg as argument. Matches if
the sub returns \s-1TRUE.\s0
.RE
.RS 4
.Sp
The leg matches \f(CW%ARGS\fR if the all conditions specified in \f(CW%ARGS\fR
match.
.RE
.IP "add_timer ( \s-1WHEN, CALLBACK,\s0 [ \s-1REPEAT\s0 ] )" 4
.IX Item "add_timer ( WHEN, CALLBACK, [ REPEAT ] )"
Adds a timer using the eventloop.
.Sp
\&\s-1WHEN\s0 is either an absolute or a relative time (what it is will
be decided based on the value of \s-1WHEN\s0). Absolute times will be
specified in time_t (seconds since 1970\-01\-01 00:00:00) and
relative time will be specified in seconds.
\&\s-1WHEN\s0 can be floating point to specify subseconds.
\&\s-1WHEN\s0 can be \f(CW0\fR to trigger the timer immediately.
.Sp
\&\s-1CALLBACK\s0 is a callback usable by \fBinvoke_callback\fR in Net::SIP::Util.
.Sp
\&\s-1REPEAT\s0 is the optional repeat interval for the timer.
.ie n .IP "deliver ( \s-1PACKET,\s0 %ARGS )" 4
.el .IP "deliver ( \s-1PACKET,\s0 \f(CW%ARGS\fR )" 4
.IX Item "deliver ( PACKET, %ARGS )"
Delivers \fBNet::SIP::Packet\fR \s-1PACKET.\s0
\&\f(CW%ARGS\fR can specify hints for delivery:
.RS 4
.IP "id" 8
.IX Item "id"
\&\s-1ID\s0 for packet, used in \fBcancel_delivery\fR. If not given the transaction
\&\s-1ID\s0 of \s-1PACKET\s0 given by method \fBtid\fR will be used.
.IP "callid" 8
.IX Item "callid"
Call-ID for packet, used in \fBcancel_delivery\fR to cancel all deliveries for
a specific call. If not given the Call-Id of \s-1PACKET\s0 given by method \fBcallid\fR
will be used.
.IP "callback" 8
.IX Item "callback"
callback which will be called on definite delivery of packet (only possible
for \s-1TCP\s0) or on definite failure. Callback will be invoked using \fBinvoke_callback\fR
from \fBNet::SIP::Util\fR with the additional argument of \f(CW$!\fR.
See sub \fBdeliver\fR in Net::SIP::Leg.
.IP "leg" 8
.IX Item "leg"
Specifies outgoing Net::SIP::Leg object. For responses created by the
endpoint the outgoing leg is usually known, because it's the same as the
incoming leg for the request.
.IP "dst_addr" 8
.IX Item "dst_addr"
Destination, i.e. where to deliver the packet.  This should be given as a hash
with the keys \f(CW\*(C`proto\*(C'\fR (udp|tcp|tls), \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`family\*(C'\fR.
This is necessary for responses, for requests it can be found out based on the
requests \s-1URI.\s0
.IP "do_retransmits" 8
.IX Item "do_retransmits"
Specifies if retransmits should be done according to \s-1RFC3261.\s0 This is
usually the case, except for stateless proxies. Overwrites the global parameter
with the same name from the constructor for the delivery of the
specific packet.
.RE
.RS 4
.Sp
Delivery of the packet itself will be handled in multiple steps (in the
code done mainly by sub \fB_\|_deliver\fR:
.IP "\(bu" 8
If a leg is specified it will be used for delivery. \fBdst_addr\fR needs to
be specified in this case too.
This is usually the case for locally generated responses.
.IP "\(bu" 8
Otherwise leg and dst_addr will be retrieved using \fBresolve_uri\fR.
See there.
.RE
.RS 4
.Sp
If the packets could be retransmitted appropriate setups
will be done. Retransmission will be done until final failure
or until \fBcancel_delivery\fR will be called for the packet, which
usually means, that the packet was successfully delivered because
a response to the packet was received.
.RE
.IP "resolve_uri ( \s-1URI, ADDR, LEGS, CALLBACK,\s0 [ \s-1ALLOWED_PROTO, ALLOWED_LEGS\s0 ] )" 4
.IX Item "resolve_uri ( URI, ADDR, LEGS, CALLBACK, [ ALLOWED_PROTO, ALLOWED_LEGS ] )"
Resolves \s-1URI\s0 to get the destination address and the outgoing leg.
\&\s-1ADDR\s0 and \s-1LEGS\s0 are references to lists which will get filled with
the computed values.
.Sp
If \s-1ALLOWED_PROTO\s0 is given it will be interpreted as a \e@list of protocols.
Only the protocols given in the list will be considered and the
it will try them in the order from the list, e.g. \f(CW\*(C`(\*(Aqtcp\*(Aq,\*(Aqudp\*(Aq)\*(C'\fR
means that tcp is tried first and only if there is no way to do tcp
it will try udp. Default is to first try udp and then tcp.
.Sp
If \s-1ALLOWED_LEGS\s0 is given it will be interpreted as a \e@list of Net::SIP::Leg
objects and only these legs are allowed.
.Sp
Because the method can be asynchronous (\s-1DNS\s0 lookups can be involved)
it will call \s-1CALLBACK\s0 once it is done. If no errors occurred
\&\s-1CALLBACK\s0 will be invoked without additional arguments, otherwise
with the errno as additional argument.
.Sp
Resolving will be done as follows:
.RS 4
.IP "\(bu" 8
If \fBdomain2proxy\fR is given it will try to get the dst_addr
from this, e.g. the address of the proxy responsable for the domain
(if any). From dst_addr it will then get the leg.
.IP "\(bu" 8
If still no dst_addr is known it will use \fBoutgoing_proxy\fR
as the dst_addr.
.IP "\(bu" 8
If still no dst_addr is known but the \s-1SIP\s0 domain is an
\&\s-1IP\s0 address this will be used as dst_addr.
.IP "\(bu" 8
The last effort will be made by looking up the \s-1SIP\s0 domain using
\&\s-1DNS\s0 with a partial implementation of \s-1RFC3263,\s0 e.g. it looks at
the \s-1DNS SRV\s0 records but not at \s-1NAPTR\s0 records.
.IP "\(bu" 8
For each destination address (e.g. proto,addr,port) the outgoing
leg will be computed.
This will be done in sub \fB_\|_find_leg4addr\fR by going through
all legs and checking, if the leg could deliver to this
address by calling \fBcan_deliver_to\fR on the leg (see Net::SIP::Leg).
.RE
.RS 4
.RE
.IP "cancel_delivery ( \s-1TYP\s0?,ID )" 4
.IX Item "cancel_delivery ( TYP?,ID )"
Cancels retransmission of packet with id \s-1ID.\s0 Called from endpoint
if response to packet came in, which means that the packet was
successfully delivered.
.Sp
If \s-1TYP\s0 given packets can be canceled by something else. \s-1TYP\s0 can be
\&\f(CW\*(C`callid\*(C'\fR, in which case all deliveries for a specific call will be
canceled. It can be \f(CW\*(C`id\*(C'\fR which will cancel the packet with id \s-1ID.\s0
Or it can be \f(CW\*(C`qentry\*(C'\fR in which case \s-1ID\s0 will be interpreted as
the Net::SIP::Dispatcher::Packet object in the queue and it will
cancel this packet.
.Sp
Will return true if the item was canceled, false if no such item
was found in delivery queue.
.IP "receive ( \s-1PACKET, LEG, FROM\s0 )" 4
.IX Item "receive ( PACKET, LEG, FROM )"
Called from the eventloop (e.g was setup as a callback) for
incoming packets. The new Net::SIP::Packet is \s-1PACKET,
LEG\s0 is the Net::SIP::Leg where the packet came in and
\&\s-1FROM\s0 is \f(CW"ip:port"\fR of the sender.
.IP "queue_expire ( [ \s-1NOW\s0 ] )" 4
.IX Item "queue_expire ( [ NOW ] )"
Expires retransmission queue, e.g. deletes packet where retransmissions
failed permanently (and calls appropriate callbacks) and initiates
pending retransmissions. Called from a timer setup in the constructor.