.\" 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::Leg 3pm"
.TH Net::SIP::Leg 3pm "2012-06-26" "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::Leg \- Wrapper around Socket for sending and receiving SIP packets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $leg = Net::SIP::Leg\->new( addr => \*(Aq192.168.0.2\*(Aq );
\&  $leg\->deliver( $packet, \*(Aq192.168.0.5:5060\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \fBLeg\fR wraps the socket which is used to send and receive packets.
It provides ways to strip \fBVia\fR header from incoming packets, to
add \fBVia\fR header to outgoing packets and to add \fBRecord-Route\fR header
while forwarding.
.PP
It's usually not used directly, but from Net::SIP::Dispatcher.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( %ARGS )" 4
.el .IP "new ( \f(CW%ARGS\fR )" 4
.IX Item "new ( %ARGS )"
The constructor creates a new object based on the hash \f(CW%ARGS\fR.
The following keys are used from \f(CW%ARGS:\fR
.RS 4
.IP "sock" 8
.IX Item "sock"
The socket as IO::Socket::INET object. \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`proto\*(C'\fR
will be determined from this object and not from \f(CW%ARGS\fR.
.IP "addr" 8
.IX Item "addr"
The local address of the socket. If this is given but no port it
will extract port from addr, if it's in the format \f(CW\*(C`host:port\*(C'\fR.
.IP "port" 8
.IX Item "port"
The port of the socket. Defaults to 5060.
.IP "proto" 8
.IX Item "proto"
The connection protocol, e.g. 'tcp' or 'udp'. Defaults to 'udp'.
.IP "contact" 8
.IX Item "contact"
Optional contact information which will be added as \fBRecord-route\fR header
to outgoing requests and used within Contact header for 200 Responses to 
\&\s-1INVITE\s0. If not given it will be created based on \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR
and \f(CW\*(C`proto\*(C'\fR.
.RE
.RS 4
.Sp
If no socket is given with \f(CW\*(C`sock\*(C'\fR it will be created based on \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR
and \f(CW\*(C`proto\*(C'\fR. If this fails the constructur will \f(CW\*(C`die()\*(C'\fR.
.Sp
The constructor will creeate a uniq branch tag for this leg.
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "forward_incoming ( \s-1PACKET\s0 )" 4
.IX Item "forward_incoming ( PACKET )"
Modifies the Net::SIP::Packet \s-1PACKET\s0 in-place for forwarding, e.g
strips top \fBVia\fR header in responses, adds \fBreceived\fR parameter to
top \fBVia\fR header in requests, handles the difference between forwarding
of requests to strict or loose routes and inserts \fBRecord-Route\fR
header in requests.
.IP "forward_outgoing ( \s-1PACKET\s0, \s-1LEG_IN\s0 )" 4
.IX Item "forward_outgoing ( PACKET, LEG_IN )"
Similar to \fBforward_incoming\fR, but will be called on the outgoing
leg. \s-1LEG_IN\s0 is the Net::SIP::Leg, where the packet came in (and where
\&\fBforward_incoming\fR was called). Will add \fBRecord-Route\fR header and
remove itself from \fBRoute\fR.
.IP "deliver ( \s-1PACKET\s0, \s-1ADDR\s0, [ \s-1CALLBACK\s0 ] )" 4
.IX Item "deliver ( PACKET, ADDR, [ CALLBACK ] )"
Delivers Net::SIP::Packet \s-1PACKET\s0 through the leg \f(CW$self\fR to \s-1ADDR\s0, which
is \f(CW"ip:port"\fR.
Usually this method will be call from within Net::SIP::Dispatcher.
.Sp
If the packet was received by the other end (which is
only possible to say if a reliable protocol, e.g. 'tcp' was used) it will
call \s-1CALLBACK\s0 if provided. See \fBinvoke_callback\fR in Net::SIP::Util for
the format of callbacks. If the packet could not be delivered \s-1CALLBACK\s0
will be invoked with the appropriate errno (\f(CW$!\fR).
.Sp
While delivering requests it adds a \fBVia\fR header.
.IP "receive" 4
.IX Item "receive"
Reads a packet from the socket and returns the Net::SIP::Packet \s-1PACKET\s0
and the senders \s-1ADDR\s0 as \f(CW"ip:port"\fR. If reading failed will return \f(CW\*(C`()\*(C'\fR.
.IP "check_via ( \s-1PACKET\s0 )" 4
.IX Item "check_via ( PACKET )"
Returns \s-1TRUE\s0 if the top \fBVia\fR header in the Net::SIP::Packet \s-1PACKET\s0 contains
the \fBbranch\fR\-tag from \f(CW$self\fR, otherwise \s-1FALSE\s0. Used to check if the response
came in through the same leg the response was send.
.IP "add_via ( \s-1PACKET\s0 )" 4
.IX Item "add_via ( PACKET )"
Adds itself to \s-1PACKET\s0 as \fBVia\fR header.
.IP "can_deliver_to ( ADDR|%SPEC )" 4
.IX Item "can_deliver_to ( ADDR|%SPEC )"
Returns \s-1TRUE\s0 if the leg can deliver address specified by \s-1ADDR\s0 or \f(CW%SPEC\fR.
\&\s-1ADDR\s0 is a hostname which can be prefixed by the protocol ( e.g. \f(CW\*(C`udp:host\*(C'\fR )
and postfixed by the port ( \f(CW\*(C`host:port\*(C'\fR, \f(CW\*(C`tcp:host:port\*(C'\fR,... ).
.Sp
If the caller has 'proto','addr' and 'port' already as separate items
it can call the method with \f(CW%SPEC\fR instead.
.Sp
Right now it has now way to check if the leg can deliver to a specific
host because it has no access to the routing information of the underlying
\&\s-1OS\s0, so that only proto will be checked.
.IP "fd" 4
.IX Item "fd"
Returns socket of leg. In some special environments (like tests) there might
be legs, which don't have a socket associated. In this case you need to call
\&\fBreceive\fR from Net::SIP::Dispatcher yourself, because it cannot be
called automatically once it receives data on the socket.
.IP "dump" 4
.IX Item "dump"
Returns string containing information about the leg.
Used for debugging.