Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::SIP::Util(3)     User Contributed Perl Documentation    Net::SIP::Util(3)

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, PARAM, DATA)	| 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".

	   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 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.

perl v5.32.1			  2020-05-28		     Net::SIP::Util(3)

NAME | SYNOPSIS | DESCRIPTION | SUBROUTINES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::SIP::Util&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help