Net::SIP::Util(3pm)

📦

version 0.840 · 6 versions

0.840 · ubuntu resolute, ubuntu stonking (latest)
0.838 · ubuntu questing
0.833 · ubuntu jammy
0.836 · ubuntu noble
0.835 · debian bookworm
0.838 · debian trixie

💖 Net::SIP::Util 💖

okay bestie, welcome to Net::SIP::Util — that's the 3pm page from the User Contributed Perl Documentation section of the manual. it's giving "utility closet of the whole Net::SIP house" and honestly? we're obsessed. 🧰✨

🌸 NAME 🌸

Net::SIP::Util — the utility functions used by all of Net::SIP. every single one. the whole squad relies on these. 👑

✨ SYNOPSIS ✨

like, here's the vibe in code form:

use Net::SIP::Util qw( create_rtp_sockets );
my ($port,@socks) = create_rtp_sockets( '192.168.0.10' ) or die;

see how we pull in just one function? that's the move. 💅

🦋 DESCRIPTION 🦋

so this package implements a whole bunch of utility functions that get used inside the various Net::SIP packages — and ngl, some of them are lowkey useful for you too, the actual user of Net::SIP. it's not <em>just</em> internal plumbing, bestie. 🫶

here's the important tea about importing:

every single one of these functions is exportable — you can absolutely grab them.
but none of them are exported by default. zero. nada. you have to ask. 🙈
wanna skip the asking and just take everything? pass the import flag :all and all the functions come to the party at once. 🎉

fr fr, don't assume they're just sitting in your namespace. they are not. you must import them, periodt.

and that's just part 1, bestie — there's more coming, so don't go anywhere. 🌈

✨ SUBROUTINES ✨

okay so bestie, these are the subroutines that make this whole module go brrr 💖 they're literally the backbone of everything, so let's get into it. no cap.

`invoke_callback ( CALLBACK, @ARGS )`

So you wanna call a callback? This one invokes CALLBACK and passes along any extra @ARGS you give it. And CALLBACK can be a whole bunch of things, bestie:

A code reference — it just does $CALLBACK->(@ARGS) and gives you back whatever that returns. periodt.
A reference to a scalar — it sets that scalar to $ARGS[0] and ignores the rest of @ARGS. If you don't give any @ARGS, it sets the scalar to TRUE. Then it returns the value of the scalar. slay.
An object which has a method run — it calls $CALLBACK->run(@ARGS) and returns whatever that gives back. iconic.
A reference to an array — the first element of the array is interpreted as a code reference, and the rest are args. So it basically does this:

my ($coderef,@cb_args) = @$CALLBACK;
return $coderef->( @cb_args, @ARGS );

A regular expression — it tries to match all @ARGS against the regex. If anything matches, you get TRUE, else FALSE. simple as that. 💅

`laddr4dst(DST) -> SRC`

This one figures out which local IP address (SRC) you'd use to connect to a target DST. How? By making a connected UDP socket to the target and then using getsockname to get the local IP of that socket. lowkey genius. 🧚

`create_socket_to ( ADDR, [ PROTO ] )`

Creates a socket with protocol PROTO (default is 'udp'). It uses laddr4dst to find the appropriate local source IP address. 🦋

It tries to bind the socket to port 5060 (the default SIP port). If that fails, it tries ports 5062..5100. And if it can't bind to any of those, it just uses any port the OS assigns. flexible much?

For multihomed hosts where several addresses are bound to the same interface, it will just use one of these addresses. If you need more control over the address the socket is bound to (and which will be used as the local IP in outgoing packets), you need to create the socket yourself. no biggie. 🙈

In scalar context it just returns the newly created socket. In array context it returns the socket and the "ip:port" the created socket is bound to. If the creation fails, it returns () and sets $!.

Example:

my ($sock,$ip_port) = create_socket_to ( '192.168.0.1' )
      or die $!;

`create_rtp_sockets ( LADDR, [ RANGE, MINPORT, MAXPORT, TRIES ] )`

This tries to allocate sockets for RTP. RTP usually consists of a data socket on an even port number and a control socket (RTCP) on the following port. It will try to create these sockets. MINPORT is the minimal port number to use (default 2000), MAXPORT is the highest port (default MINPORT+10000), and TRIES is the number of attempts it makes to create such socket pairs, defaulting to 1000.

RANGE is the number of consecutive ports it needs to allocate and defaults to 2 (like data and control socket).

Allocation works by choosing a random even number between MINPORT and MAXPORT and then trying to allocate all the sockets on this and the following port numbers.

If allocation fails after TRIES attempts, it returns (). Otherwise it returns an array with the starting port number first, followed by all the allocated sockets.

Example:

my ($port,$rtp_sock,$rtcp_sock) = create_rtp_sockets( '192.168.0.10' )
      or die "allocation failed";

`sip_hdrval2parts ( KEY, VALUE )`

Interprets VALUE as a value for the SIP header field KEY and splits it into the parts (prefix, parameter). Because for most keys the delimiter is ";", but for some keys it's ",", the field name KEY needs to be known.

KEY needs to be normalized already (lower case, no abbreviation).

Returns an array with initial data (up to first delimiter) and the parameters as a hash.

Example for key 'to':

'"Silver; John" <silver@example.com>; tag=...; protocol=TCP'
-> ( '"Silver; John" <silver@example.com>', { tag => ..., protocol => 'TCP' } )

Example for key 'www-authenticate':

'Digest method="md5", qop="auth"'
-> ( 'Digest', { method => 'md5', qop => 'auth' } )

`sip_parts2hdrval ( KEY, PREFIX, \%PARAMETER )`

Inverse function to sip_hdrval2parts. It constructs a header value for KEY from PREFIX and %PARAMETER and returns the value. 🔄

`sip_uri2parts(URI) -> (DOMAIN, USER, PROTO, PARAM, DATA) | DOMAIN`

Returns parts from a URI. If called in scalar context it returns only the domain part. In array context it returns an array with the following values:

DOMAIN — The lower cased domain part as given in the URI, i.e. "host", "host:port", "[ipv6]:port" etc.
USER — The optional user part of the SIP address.
PROTO — The protocol, e.g. "sip" or "sips". If not explicitly given it defaults to "sip".
PARAM — A hash reference to any parameters following "data" as returned by sip_hdrval2parts.
DATA — The original full part before any parameter, i.e. the part containing the domain, optional user and optional proto.

`sip_parts2uri(DOMAIN, USER, PROTO, PARAM) -> URI`

Returns a URI from parts, i.e. the reverse of sip_uri2parts. For the meaning of the parameters, see there. 🔁

`sip_uri2sockinfo(URI; OPAQUE) -> (PROTO, HOST, PORT, FAMILY)`

This extracts information from a URI that's needed for creating the socket: HOST is the IP address or host name, PORT is the port (undef if not given), and FAMILY is the family, i.e. AF_INET, AF_INET6 or undef if HOST is not an IP address. PROTO will be set based on the SIP protocol and parameters, i.e. "tls" for "sips" URI, "tcp" or "udp" for "sip" URI with explicit "transport" parameter, and "undef" otherwise.

If OPAQUE is set, the host name is not required to be a valid name. See OPAQUE in "ip_string2parts" for more information. 💅

`sip_sockinfo2uri(PROTO, HOST, PORT, FAMILY) -> URI`

This is the reverse to sip_uri2sockinfo. See there for the meaning of the parameters.

If the first argument is a hash ref, it's expected to provide the arguments in the keys "proto", "host", "port" and "family". 🎀

`sip_uri_eq ( URI1, URI2 )`

Returns true if both URIs point to the same SIP address. This compares the user part case sensitively, the domain part case insensitively (it does no DNS resolution), protocol, and ports in the domain (it assumes default ports for the protocol if no port is given). 👑

`ip_string2parts(STR;OPAQUE) -> (HOST, PORT, FAMILY) | \%HASH`

This parses the given string STR and splits it into parts like this:

IPv4, [IPv4]               -> (IPv4, undef, AF_INET)
IPv4:port, [IPv4]:port     -> (IPv4, port,  AF_INET)
IPv6, [IPv6]               -> (IPv6, undef, AF_INET6)
[IPv6]:port                -> (IPv6, port,  AF_INET6)
host, [host]               -> (host, undef, undef)
host:port, [host]:port     -> (host, port,  undef)

The IP address and host will be returned in a canonicalized way.

If this function is used to parse strings where the host part is not a real hostname but some identifier with more allowed characters than a hostname, then OPAQUE should be set. In this way no strict checking and no canonicalization is done.

If the function is called in scalar context it returns the result as a hash ref with the keys "host", "addr", "port", "family", where "addr" is only set if it's an IP address. ✨

`ip_parts2string(HOST, [ PORT, FAMILY, IPv6_BRCKT]) -> STR`

This is the reverse to ip_string2parts. If family is not given it will be determined by checking if ip_or_host contains ':' (i.e. IPv6 address):

(ip_or_host)              -> ip_or_host
(ipv4_or_host,port)       -> ipv4_or_host:port
(ipv6,port)               -> [ipv6]:port
(ipv6,undef,*,true)       -> [ipv6]

If the first argument is a hash ref, it will be treated as a hash ref as returned by ip_string2parts. In this case also "use_host" can be given, which prefers "host" to "addr" for stringification. Also, "default_port" can be used to give a port number which will be treated as default and omitted from the string. 🦋

`ip_sockaddr2parts(SOCKADDR, [FAMILY]) -> (IP, PORT, FAMILY)`

This returns the IP, PORT and FAMILY from a sockaddr_in or sockaddr_in6. If FAMILY is not given it will be determined based on the size of SOCKADDR.

If the function is called in scalar context it returns the result as a hash ref as described for ip_string2parts. 💖

`ip_parts2sockaddr(IP, PORT, [FAMILY]) -> SOCKADDR`

This creates a sockaddr_in or sockaddr_in6 from IP and PORT. FAMILY will be determined by checking the IP if not given.

If the first argument is a hash ref, it will be treated as a hash ref as returned by ip_sockaddr2parts. 🌸

`ip_sockaddr2string(SOCKADDR, [FAMILY]) -> STR`

This returns the STR from a sockaddr_in or sockaddr_in6, i.e. like combining ip_sockaddr2parts with ip_parts2string. If FAMILY is not given it will be determined based on the size of SOCKADDR. ✨

`ip_ptr(IP, [FAMILY]) -> PTR_NAME`

This creates the hostname used in reverse lookup of an IP address, i.e. "*.in-addr.arpa" or "*.ip6.arpa". If FAMILY is not given it will be determined based on the syntax of IP. 🔍

`ip_canonical(IP, [FAMILY]) -> IP`

This converts the given IP address into a canonical form suitable for comparison. 💅

`hostname2ip(host, [FAMILY]) -> @IP`

This looks up the given name using getaddrinfo and returns the IP addresses. If FAMILY is given, only addresses matching the family will be returned. 🌈

`ip_is_v4(IP) -> true|false`

This checks if the given IP address is a valid IPv4 address. ✅

`ip_is_v6(IP) -> true|false`

This checks if the given IP address is a valid IPv6 address. ✅

`ip_is_v46(IP) -> AF_INET|AF_INET6|undef`

This checks if the given IP address is a valid IPv4 or IPv6 address and returns the address family if it is an IP address. 👑

`CAN_IPV6([bool]) -> ipv6_available`

This checks if IPv6 is supported by Perl. You can also explicitly disable it by calling CAN_IPV6(0). 🧚

that's the whole vibe bestie 💖 this page was from perl v5.40.1, dated 2025-12-07, and it's for Net::SIP::Util(3pm). stay slaying ✨

📦 where this page comes from

ubuntu resolute: libnet-sip-perl 0.840-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnet-sip-perl 0.840-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms