Provided by: libnet-sip-perl_0.812-1_all 
NAME
Net::SIP::Util - utility functions used by all of Net::SIP
SYNOPSIS
use Net::SIP::Util qw( create_rtp_sockets );
my ($port,@socks) = create_rtp_sockets( '192.168.0.10' ) or die;
DESCRIPTION
This package implements various utility function used within various Net::SIP packages and
partly usable for the user of Net::SIP too.
Each of this functions is exportable, but none is exported per default. All functions can
be exported at once with the import flag ":all".
SUBROUTINES
invoke_callback ( CALLBACK, @ARGS )
Invokes callback CALLBACK with additional args @ARGS. CALLBACK can be:
A code reference
In this case it will be called as "$CALLBACK->(@ARGS)" and return the return
value of this call.
A reference to a scalar
In this case the scalar will be set to $ARGS[0] and the rest of @ARGS will be
ignored. If no @ARGS are given the scalar will be set to TRUE. It will return
with the value of the scalar.
An object which has a method run
In this case it will call "$CALLBACK->run(@ARGS)" and return with the return
value of this call.
A reference to an array
The first element of the array will be interpreted as code reference, while
the rest as args, e.g. it will do:
my ($coderef,@cb_args) = @$CALLBACK;
return $coderef->( @cb_args, @ARGS );
A regular expression
In this case it will try to match all @ARGS against the regex. If anything
matches it will return TRUE, else FALSE.
laddr4dst(DST) -> SRC
This will try to find out which local IP address SRC is used for connections to target
DST. This will be done by creating a connected UDP socket to the target and using
getsockname to get the local IP address of this socket.
create_socket_to ( ADDR, [ PROTO ] )
Creates socket with protocol PROTO (default 'udp'). It will use "laddr4dst" to find
the appropriate local source IP address.
It will try to bind the socket to port 5060 (default SIP port). If this fails it will
try port 5062..5100 and if it cannot bind to any of these ports it will just use any
port which gets assigned by the OS.
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 about 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.
In scalar context it just returns the newly created socket. In array context it will
return the socket and the "ip:port" the created socket is bound to. If the creation
of the socket fails it will return "()" and set $!.
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 consists usually of a data socket on an
even port number and a control socket (RTCP) and the following port. It will try to
create these sockets. MINPORT is the minimal port number to use (default 2000),
MAXPORT the highest port (default MINPORT+10000), TRIES is the number of attempts it
makes to create such socket pairs and defaults to 1000.
RANGE is the number of consecutive ports it needs to allocate and defaults to 2 (e.g.
data and control socket).
Allocation will be done 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 the allocation fails after TRIES attempts were made it will return "()", otherwise
it will return an array with at first the starting port number 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 ","
the field name KEY need to be known.
KEY needs to be normalized already (lower case, no abbreviation).
Returns array with initial data (up to first delimiter) and the parameters as 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, e.g constructs header value for KEY from PREFIX
and %PARAMETER and returns value.
sip_uri2parts(URI) -> (DOMAIN, USER, PROTO, DATA, PARAM) | DOMAIN
Returns parts from 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 will default to
"sip".
DATA
The original full part before any parameter, i.e. the part containing the domain,
optional user and optional proto.
PARAM
A hash reference to any parameters following "data" as returned by
sip_hdrval2parts.
sip_parts2uri(DOMAIN, USER, PROTO, PARAM) -> URI
Returns URI from parts, i.e. the reverse to sip_uri2parts. For the meaning of the
parameters see there.
sip_uri2sockinfo(URI; OPAQUE) -> (PROTO, HOST, PORT, FAMILY)
This extracts information from URI which are needed for creating the socket: HOST is
the IP address or host name, PORT the port (undef if not given) and FAMILY 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 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 will expected to provided 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 user part case
sensitive, domain part case insensitive (does no DNS resolution) protocol and ports in
domain (assumes default ports for protocol if no port is given).
ip_string2parts(STR;OPAQUE) -> (HOST, PORT, FAMILY) | \%HASH
This will parse the given string STR and split it into the parts as follows:
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 and in this way no strict checking and no canonicalization is done.
If the function is called with a scalar context it will return the result as a hash
ref with the keys "host", "addr", "port", "family" where "addr" is only set if it is
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 string.
ip_sockaddr2parts(SOCKADDR, [FAMILY]) -> (IP, PORT, FAMILY)
This will return 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 with a scalar context it will return the result as a hash
ref as described for ip_string2parts.
ip_parts2sockaddr(IP, PORT, [FAMILY]) -> SOCKADDR
This will create 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 will return 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 will create 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 will convert the given IP address into a canonical form suitable for comparison.
hostname2ip(host, [FAMILY]) -> @IP
This will lookup the given name using getaddrinfo and return 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 this is an IP address.