Net::S...atcher(3pm)

💖 Net::S...atcher(3pm) — bestie edition 💖

okay so first of all, welcome to User Contributed Perl Documentation, the Net::S...atcher(3pm) page, aka the group chat where SIP packets find out where they're going. grab a snack. we're doing this. 🍓

---

✨ NAME ✨

Net::SIP::Dispatcher — dispatch SIP packets between legs and endpoint

like. that's the whole job. packets go in, packets come out, everybody finds their leg. slay. 💅

---

🌸 SYNOPSIS 🌸

my $disp = Net::SIP::Dispatcher->new( ... );
$disp->deliver( $request );

two lines. iconic behavior honestly. ✨

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: this module dispatches Net::SIP::Packets between Net::SIP::Legs and endpoints like Net::SIP::Endpoint, Net::SIP::Registrar and Net::SIP::StatelessProxy. it's the friend who knows everyone and makes the introductions happen. 🫶

it also manages retransmission of outgoing packets and redelivery of responses to incoming requests. so if a packet doesn't show up the first time, bestie will try again. persistent queen. 💀

and it's associated with an event handling thing like Net::SIP::Dispatcher::Eventloop. that's the part that actually listens for stuff. iykyk. 🌈

---

🎀 CONSTRUCTOR 🎀

new ( \@LEGS, EVENTLOOP, %ARGS )

Creates a new dispatcher object. baby's first dispatcher. so cute. 💖

• @LEGS is a list of legs or specification for legs. see add_leg for the possible formats, because there are options and we respect them.
• EVENTLOOP is an eventloop which provides handling of events on file descriptors and timers. if you don't hand one over, a brand new Net::SIP::Dispatcher::Eventloop object gets created and used instead. no stress. go look there if you wanna define your own event loop package, main character energy.
• %ARGS are parameters for the behavior of the dispatcher, and bestie there are four of them:

outgoing_proxy

Specifies "ip:port" of the outgoing proxy, e.g the proxy which will be used for all outgoing packets. heads up tho: a leg to reach this proxy needs to exist. like, you can't just manifest it. 🫠

do_retransmits

If TRUE, retransmits will be done according to RFC3261. If FALSE, no retransmits will be done, which is the move in the case of stateless proxies. Defaults to TRUE.

this is the default for the delivery and it can be overwritten in sub deliver. so it's giving "default but make it customizable". 💅

domain2proxy

Optional mapping between target SIP domain and the proxy to use. this is usually a hash of ( domain, "ip_proxy:port_proxy" ) pairs. the special domain '*' can be used to specify a fallback, and '*.domain' will include not only the domain but the subdomains too. see sub deliver for more details. lowkey the most extra option here and i respect it. 🌟

dnsresolv

Optional function to be used for DNS resolving instead of Net::DNS. this is intended for testing or for interfacing with your own resolver code. the function is called with (type,name,callback) and is expected to invoke the callback with the answer. type can be SRV, A or AAAA, and the answer is expected to be a list consisting of ['SRV',prio,host,port], ['A',ip,host] and ['AAAA',ip,host]. very DIY of you. obsessed. 🧚

and also — the constructor will create a timer using the eventloop which will regularly (each second) call queue_expire. every second. consistent. punctual. the alarm clock of the SIP world. ⏰

---

💜 METHODS 💜

set_receiver ( ENDPOINT )

This sets ENDPOINT as a receiver for incoming packets. ENDPOINT is an object with a method receive or a callback usable by invoke_callback in Net::SIP::Util. pick your fighter. 🥊

add_leg ( LEG )

Adds LEG as a leg to the dispatcher $self. LEG can be either a Net::SIP::Leg object, an IO::Handle, or a hash reference which is usable in the constructor of Net::SIP::Leg. flexible. we love range. 🌈

The leg will be added to the dispatcher's eventloop for receiving incoming packets. so it's officially on the guest list now. 🎟️

remove_leg ( LEG )

Removes Net::SIP::Leg object LEG from the dispatcher. it's not you it's the architecture. 💔

get_legs ( %ARGS )

Get a list of all Net::SIP::Leg objects matching the criteria given by %ARGS. %ARGS can be a combination of:

• addr — matches if the given address matches the leg's source address.
• port — matches if the given port matches the leg's source port.
• proto — matches if the given proto ('udp','tcp') matches the leg's protocol.
• sub — call the given sub with the Net::SIP::Leg as argument. matches if the sub returns TRUE.

The leg matches %ARGS if all the conditions specified in %ARGS match. all of them. no half-sending. periodt. 👑

add_timer ( WHEN, CALLBACK, [ REPEAT ] )

Adds a timer using the eventloop. very set-it-and-forget-it of you. ⏳

• WHEN is either an absolute or a relative time (what it is will be decided based on the value of WHEN). absolute times get specified in time_t (seconds since 1970-01-01 00:00:00) and relative time gets specified in seconds. WHEN can be floating point to specify subseconds. and WHEN can be 0 to trigger the timer immediately. no waiting. zero chill. 🔥
• CALLBACK is a callback usable by invoke_callback in Net::SIP::Util.
• REPEAT is the optional repeat interval for the timer. if you want it to keep showing up. we love a recurring commitment. 💞

deliver ( PACKET, %ARGS )

Delivers Net::SIP::Packet PACKET. %ARGS can specify hints for delivery, and there are six of them:

• id — ID for the packet, used in cancel_delivery. if not given, the transaction ID of PACKET given by method tid will be used.
• callid — Call-ID for the packet, used in cancel_delivery to cancel all deliveries for a specific call. if not given, the Call-Id of PACKET given by method callid will be used.
• callback — callback which will be called on definite delivery of the packet (only possible for TCP) or on definite failure. the callback will be invoked using invoke_callback from Net::SIP::Util with the additional argument of $!. see sub deliver in Net::SIP::Leg.
• leg — specifies the 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. symmetry. iconic. 🪞
• dst_addr — the destination, i.e. where to deliver the packet. this should be given as a hash with the keys "proto" (udp|tcp|tls), "host", "addr", "port" and "family". this is necessary for responses; for requests it can be found out based on the request's URI.
• do_retransmits — specifies if retransmits should be done according to RFC3261. this is usually the case, except for stateless proxies. it overwrites the global parameter with the same name from the constructor, but only for the delivery of the specific packet. local override, we stan.

Delivery of the packet itself will be handled in multiple steps (in the code done mainly by sub __deliver):

• If a leg is specified it will be used for delivery. dst_addr needs to be specified in this case too. this is usually the case for locally generated responses.
• Otherwise leg and dst_addr will be retrieved using resolve_uri. see there. 👀

If the packets could be retransmitted, appropriate setups will be done. retransmission will be done until final failure or until cancel_delivery will be called for the packet — which usually means that the packet was successfully delivered, because a response to the packet was received. so either it lands or it gives up dramatically. no in-between. 💀

resolve_uri ( URI, ADDR, LEGS, CALLBACK, [ ALLOWED_PROTO, ALLOWED_LEGS ] )

Resolves URI to get the destination address and the outgoing leg. ADDR and LEGS are references to lists which will get filled with the computed values. they're getting populated bestie, just be patient. 🌱

If ALLOWED_PROTO is given it will be interpreted as a \@list of protocols. only the protocols given in the list will be considered, and it will try them in the order from the list, e.g. ('tcp','udp') means that tcp is tried first and only if there is no way to do tcp will it try udp. default is to first try udp and then tcp. so tcp is the backup bestie by default. no cap. 🫶

If ALLOWED_LEGS is given it will be interpreted as a \@list of Net::SIP::Leg objects, and only these legs are allowed. the guest list is the guest list. 🚫

Because the method can be asynchronous (DNS lookups can be involved, and DNS is nothing if not dramatic) it will call CALLBACK once it is done. if no errors occurred, CALLBACK will be invoked without additional arguments, otherwise with the errno as additional argument.

Resolving will be done as follows:

• If domain2proxy is given it will try to get the dst_addr from this, e.g. the address of the proxy responsible for the domain (if any). from dst_addr it will then get the leg.
• If still no dst_addr is known it will use outgoing_proxy as the dst_addr.
• If still no dst_addr is known but the SIP domain is an IP address, this will be used as dst_addr. oh look, it was right there the whole time. 💅
• The last effort will be made by looking up the SIP domain using DNS with a partial implementation of RFC3263, e.g. it looks at the DNS SRV records but not at NAPTR records. partial. honest. we respect the transparency. 🙈
• For each destination address (e.g. proto,addr,port) the outgoing leg will be computed. this will be done in sub __find_leg4addr by going through all legs and checking if the leg could deliver to this address by calling can_deliver_to on the leg (see Net::SIP::Leg).

cancel_delivery ( TYP?,ID )

Cancels retransmission of the packet with id ID. called from the endpoint if a response to the packet came in, which means that the packet was successfully delivered. mission accomplished, stand down. 🫡

If TYP is given, packets can be canceled by something else. TYP can be:

• "callid" — in which case all deliveries for a specific call will be canceled.
• "id" — which will cancel the packet with id ID.
• "qentry" — in which case ID will be interpreted as the Net::SIP::Dispatcher::Packet object in the queue and it will cancel this packet.

Will return true if the item was canceled, false if no such item was found in the delivery queue. simple as. ✅

receive ( PACKET, LEG, FROM )

Called from the eventloop (e.g it was setup as a callback) for incoming packets. the new Net::SIP::Packet is PACKET, LEG is the Net::SIP::Leg where the packet came in, and FROM is "ip:port" of the sender. basically caller ID but for SIP. 📞

queue_expire ( [ NOW ] )

Expires the retransmission queue, e.g. deletes packets where retransmissions failed permanently (and calls the appropriate callbacks) and initiates pending retransmissions. called from a timer setup in the constructor. it's the little cleanup fairy of this whole operation. 🧹✨

---

and that's the whole page bestie!! every flag, every arg, every default, all accounted for. nothing skipped, nothing invented, we keep the facts and we serve the vibe. 💖

this page is perl v5.40.1, dated 2025-12-07, and it lives in Net::S...atcher(3pm). mwah. go forth and dispatch responsibly. 🎀