.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::SIP::Util 3pm"
.TH Net::SIP::Util 3pm "2010-02-02" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SIP::Util \- utility functions used by all of Net::SIP
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::SIP::Util qw( create_rtp_sockets );
\&  my ($port,@socks) = create_rtp_sockets( \*(Aq192.168.0.10\*(Aq ) or die;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package implements various utility function used within various
Net::SIP packages and partly usable for the user of Net::SIP too.
.PP
Each of this functions is exportable, but none is exported per default.
All functions can be exported at once with the import flag \f(CW\*(C`:all\*(C'\fR.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.ie n .IP "invoke_callback ( \s-1CALLBACK\s0, @ARGS )" 4
.el .IP "invoke_callback ( \s-1CALLBACK\s0, \f(CW@ARGS\fR )" 4
.IX Item "invoke_callback ( CALLBACK, @ARGS )"
Invokes callback \s-1CALLBACK\s0 with additional args \f(CW@ARGS\fR.
\&\s-1CALLBACK\s0 can be:
.RS 4
.IP "A code reference" 8
.IX Item "A code reference"
In this case it will be called as \f(CW\*(C`$CALLBACK\->(@ARGS)\*(C'\fR
and return the return value of this call.
.IP "A reference to a scalar" 8
.IX Item "A reference to a scalar"
In this case the scalar will be set to \f(CW$ARGS[0]\fR and
the rest of \f(CW@ARGS\fR will be ignored. If no \f(CW@ARGS\fR are given the
scalar will be set to \s-1TRUE\s0.
It will return with the value of the scalar.
.IP "An object which has a method \fBrun\fR" 8
.IX Item "An object which has a method run"
In this case it will call \f(CW\*(C`$CALLBACK\->run(@ARGS)\*(C'\fR
and return with the return value of this call.
.IP "A reference to an array" 8
.IX Item "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:
.Sp
.Vb 2
\&  my ($coderef,@cb_args) = @$CALLBACK;
\&  return $coderef\->( @cb_args, @ARGS );
.Ve
.IP "A regular expression" 8
.IX Item "A regular expression"
In this case it will try to match all \f(CW@ARGS\fR against the regex.
If anything matches it will return \s-1TRUE\s0, else \s-1FALSE\s0.
.RE
.RS 4
.RE
.IP "create_socket_to ( \s-1ADDR\s0, [ \s-1PROTO\s0 ] )" 4
.IX Item "create_socket_to ( ADDR, [ PROTO ] )"
Creates socket with protocol \s-1PROTO\s0 (default 'udp') on a local interface,
from where \s-1ADDR\s0 is reachable.
This is done by first creating a \s-1UDP\s0 socket with target
\&\s-1ADDR\s0 and using \fIgetsockname\fR\|(2) to find out the local address of this
socket. The newly created socket than will be bound to this address.
.Sp
It will try to bind the socket to port 5060 (default \s-1SIP\s0 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 \s-1OS\s0.
.Sp
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 \s-1IP\s0 in outgoing packets) you need to create the
socket yourself.
.Sp
In scalar context it just returns the newly created socket.
In array context it will return the socket and the \f(CW"ip:port"\fR
the created socket is bound to.
If the creation of the socket fails it will return \f(CW\*(C`()\*(C'\fR and set \f(CW$!\fR.
.Sp
Example:
.Sp
.Vb 2
\&  my ($sock,$ip_port) = create_socket_to ( \*(Aq192.168.0.1\*(Aq )
\&        or die $!;
.Ve
.IP "create_rtp_sockets ( \s-1LADDR\s0, [ \s-1RANGE\s0, \s-1MINPORT\s0, \s-1MAXPORT\s0, \s-1TRIES\s0 ] )" 4
.IX Item "create_rtp_sockets ( LADDR, [ RANGE, MINPORT, MAXPORT, TRIES ] )"
This tries to allocate sockets for \s-1RTP\s0. \s-1RTP\s0 consists usually of a data
socket on an even port number and a control socket (\s-1RTCP\s0) and the following
port. It will try to create these sockets. \s-1MINPORT\s0 is the minimal
port number to use (default 2000), \s-1MAXPORT\s0 the highest port (default
\&\s-1MINPORT+10000\s0), \s-1TRIES\s0 is the number of attempts it makes to create such
socket pairs and defaults to 1000.
.Sp
\&\s-1RANGE\s0 is the number of consecutive ports it needs to allocate and
defaults to 2 (e.g. data and control socket).
.Sp
Allocation will be done by choosing a random even number between \s-1MINPORT\s0
and \s-1MAXPORT\s0 and then trying to allocate all the sockets on this and
the following port numbers.
.Sp
If the allocation fails after \s-1TRIES\s0 attempts were made it will return \f(CW\*(C`()\*(C'\fR,
otherwise it will return an array with at first the starting port number
followed by all the allocated sockets.
.Sp
Example:
.Sp
.Vb 2
\&  my ($port,$rtp_sock,$rtcp_sock) = create_rtp_sockets( \*(Aq192.168.0.10\*(Aq )
\&        or die "allocation failed";
.Ve
.IP "sip_hdrval2parts ( \s-1KEY\s0, \s-1VALUE\s0 )" 4
.IX Item "sip_hdrval2parts ( KEY, VALUE )"
Interprets \s-1VALUE\s0 as a value for the \s-1SIP\s0 header field \s-1KEY\s0 and splits
it into the parts (prefix, parameter). Because for most keys the
delimiter is \f(CW\*(C`;\*(C'\fR, but for some keys \f(CW\*(C`,\*(C'\fR the field name \s-1KEY\s0 need to
be known.
.Sp
\&\s-1KEY\s0 needs to be normalized already (lower case, no abbrevation).
.Sp
Returns array with initial data (up to first delimiter) and
the parameters as hash.
.Sp
Example for key 'to':
.Sp
.Vb 2
\&  \*(Aq"Silver; John" <silver@example.com>; tag=...; protocol=TCP\*(Aq
\&  \-> ( \*(Aq"Silver; John" <silver@example.com>\*(Aq, { tag => ..., protocol => \*(AqTCP\*(Aq } )
.Ve
.Sp
Example for key 'www\-authenticate':
.Sp
.Vb 2
\&  \*(AqDigest method="md5", qop="auth"\*(Aq
\&  \-> ( \*(AqDigest\*(Aq, { method => \*(Aqmd5\*(Aq, qop => \*(Aqauth\*(Aq } )
.Ve
.IP "sip_parts2hdrval ( \s-1KEY\s0, \s-1PREFIX\s0, \e%PARAMETER )" 4
.IX Item "sip_parts2hdrval ( KEY, PREFIX, %PARAMETER )"
Inverse function to \fBsip_hdrval2parts\fR, e.g constructs header value for \s-1KEY\s0 from
\&\s-1PREFIX\s0 and \f(CW%PARAMETER\fR and returns value.
.IP "sip_uri2parts ( \s-1URI\s0 )" 4
.IX Item "sip_uri2parts ( URI )"
Returns parts from \s-1URI\s0. If called in scalar context it returns only the domain
part. In array context it returns an array with the following values:
.RS 4
.IP "domain \- The domain part (including ports if any)" 4
.IX Item "domain - The domain part (including ports if any)"
.PD 0
.IP "user \- The user part of the \s-1SIP\s0 address" 4
.IX Item "user - The user part of the SIP address"
.ie n .IP "proto \- The protocol, e.g. ""sip"" or ""sips""." 4
.el .IP "proto \- The protocol, e.g. ``sip'' or ``sips''." 4
.IX Item "proto - The protocol, e.g. sip or sips."
.IP "data \- The part before any parameter, includes \s-1SIP\s0 address" 4
.IX Item "data - The part before any parameter, includes SIP address"
.IP "param \- A hash reference to any parameter, like in \fBsip_hdrval2parts\fR." 4
.IX Item "param - A hash reference to any parameter, like in sip_hdrval2parts."
.RE
.RS 4
.RE
.IP "sip_uri_eq ( \s-1URI1\s0, \s-1URI2\s0 )" 4
.IX Item "sip_uri_eq ( URI1, URI2 )"
.PD
Returns true if both URIs point to the same \s-1SIP\s0 address.
This compares user part case sensitive, domain part case insensitive (does
no \s-1DNS\s0 resolution) protocol and ports in domain (assumes default ports
for protocol if no port is given).