Net::SIP::Leg(3pm)

💖 Net::SIP::Leg 💖

okay bestie, welcome to Net::SIP::Leg — straight out of the User Contributed Perl Documentation collection. it's a wrapper around a Socket for sending and receiving SIP packets, and honestly? it's giving infrastructure queen. she's not the one you invite to the party, she's the one who runs the party. 🎀

---

✨ SYNOPSIS ✨

my $leg = Net::SIP::Leg->new( addr => '192.168.0.2' );
$leg->deliver( $packet, '192.168.0.5:5060' );

like. two lines. that's the whole vibe. slay. 💅

---

🦋 DESCRIPTION 🦋

so a Leg wraps the socket that's used to send and receive packets. that's the whole job description, but she does it so much:

• she strips the Via header off incoming packets
• she adds the Via header onto outgoing packets
• she adds the Record-Route header while forwarding

ngl you usually don't talk to her directly — she gets called from Net::SIP::Dispatcher. it's giving "I don't work with the public, I work with the manager." iykyk. 🙈

---

🌸 CONSTRUCTOR 🌸

new ( %ARGS )

the constructor makes you a brand new object based on the hash %ARGS. these are the keys she actually reads from %ARGS, and bestie, there are a lot of them, so buckle up:

• sock — the socket, as an IO::Socket object. addr, port, family and proto get determined from this object, not from %ARGS. this is what's used to create the SocketPool object. no cap.
• socketpool — the socketpool as a Net::SIP::SocketPool-compatible object. > ⚠️ you cannot use this argument together with sock. instead, it determines the master socket by calling master on the SocketPool object you hand it.
• addr — the local IP address of the socket. if you give this but no port, she'll extract the port from addr — but only if it's in the "host:port" format. 👑
• host — the hostname matching addr. this is used to create default contact info and the Via header. if you don't give it, it defaults to the IP address. why would you use a hostname instead of an IP? it's relevant for TLS, where the name is needed to validate the peer's certificate. so like, not optional energy if you're doing TLS. 🔥
• port — the port of the socket. defaults to 5060.
• family — the family of the socket. if omitted, it gets determined from addr.
• proto — the connection protocol, e.g. 'udp', 'tcp' or 'tls'. defaults to 'udp'.
• dst — the optional fixed target of the leg, as a hash with the keys host, addr, port and family.
• contact — optional contact information that gets added as a Record-route header to outgoing requests, and used inside the Contact header for 200 Responses to INVITE. if you don't give it, it gets created based on addr, port and proto.
• tls — optional arguments used when creating a TLS connection, exactly as expected by IO::Socket::SSL. these get used for both incoming and outgoing TLS connections. typically this involves SSL_cert_file, SSL_key_file and SSL_ca_file or similar. 🧚

if no socket is given via sock, one gets created based on addr, port and proto. and if that fails? the constructor will die(). 💀 dramatic but fair.

oh and — the constructor creates a uniq branch tag for this leg. remember that, it comes back later. ⭐

---

💅 METHODS 💅

• forward_incoming ( PACKET ) — modifies the Net::SIP::Packet PACKET in-place for forwarding. what does that mean? she strips the top Via header in responses, adds the received parameter to the top Via header in requests, handles the difference between forwarding requests to strict or loose routes, and inserts the Record-Route header in requests. multitasking icon behavior. 👑
• forward_outgoing ( PACKET, LEG_IN ) — similar to forward_incoming, but gets called on the outgoing leg. LEG_IN is the Net::SIP::Leg where the packet came in (aka where forward_incoming was called). she'll add the Record-Route header and remove herself from Route. self-removal? that's main character energy. 🫶
• deliver ( PACKET, ADDR, [ CALLBACK ] ) — delivers Net::SIP::Packet PACKET through the leg $self to ADDR. ADDR is a hash with the keys host, addr, port and family. usually this method gets called from within Net::SIP::Dispatcher. if the packet was received by the other end — which you can only actually know if a reliable protocol like 'tcp' was used — she'll call CALLBACK if you provided one. for the callback format, see invoke_callback in Net::SIP::Util. and if the packet could not be delivered, CALLBACK gets invoked with the appropriate errno ($!). while delivering requests, she adds a Via header. ✨
• receive(PACKET, FROM) — called from the dispatcher when the Net::SIP::Packet PACKET was received from FROM. FROM is given as a hash with the keys addr, port, family and proto. this function might process the packet further, or just block it. she returns (PACKET, FROM) in the normal case, or () if blocked. sometimes the answer is just silence bestie 😭
• check_via ( PACKET ) — returns TRUE if the top Via header in the Net::SIP::Packet PACKET contains the branch-tag from $self, otherwise FALSE. this is used to check whether the response came in through the same leg the response was sent through. (there's the uniq branch tag from the constructor! told you she'd come back 🎀)
• add_via ( PACKET ) — adds itself to PACKET as the Via header. insert yourself into the conversation, queen.
• can_deliver_to ( ADDR|%SPEC ) — returns TRUE if the leg can deliver to the address specified by ADDR or %SPEC. ADDR is a full or partial SIP URI. if the caller already has 'proto', 'addr', 'port' and 'family' as separate items, it can call the method with %SPEC instead.

🫠 right now she has no way to check if the leg can deliver to a specific host, because she has no access to the routing information of the underlying OS. so only proto gets checked. that's a real limitation, not a cute quirk.

• match(%SPEC) — checks if the given SPEC matches the leg. this is used from inside get_legs in Net::SIP::Dispatcher to grab all the legs matching specific criteria. the SPEC can contain the keys addr, port and proto, which match the arguments given during construction of the leg or are obtained from the leg's socket. additionally, sub can be used to specify a function which gets called with the leg object and must return true on match only. the method returns true on a full match and false otherwise. vibe check complete. 💖
• socketpool — returns the Net::SIP::SocketPool object associated with the leg.
• laddr(LEVEL) — returns the local address of the socket, either as just the address (LEVEL is 0) or as "ip:port" (higher levels). lowkey level up behavior. 🌈
• dump — returns a string containing information about the leg. used for debugging. the "tell me everything" method, we love her. 🔥

---

🌟 SEE ALSO 🌟

(no SEE ALSO section in this page, bestie — she keeps her circle small 🦋)

---

perl v5.40.1 · 2025-12-07 · that's the version and the date this page was generated, and honestly? a whole mood. go forth and forward those packets, angel. 💜✨