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.

       create_socket_to ( ADDR, [ PROTO ] )
           Creates socket with protocol PROTO (default 'udp') on a local interface, from where
           ADDR is reachable.  This is done by first creating a UDP socket with target ADDR and
           using getsockname(2) to find out the local address of this socket. The newly created
           socket than will be bound to this 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 abbrevation).

           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 )
           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 domain part (including ports if any)
           user - The user part of the SIP address
           proto - The protocol, e.g. "sip" or "sips".
           data - The part before any parameter, includes SIP address
           param - A hash reference to any parameter, like in sip_hdrval2parts.
       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).