.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SIP::Leg 3pm"
.TH Net::SIP::Leg 3pm "2023-09-29" "perl v5.36.0" "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 object. \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR, \f(CW\*(C`family\*(C'\fR and \f(CW\*(C`proto\*(C'\fR
will be determined from this object and not from \f(CW%ARGS\fR.
This will be used to create the \fBSocketPool\fR object.
.IP "socketpool" 8
.IX Item "socketpool"
The socketpool as Net::SIP::SocketPool compatible object. This argument can
not be used together with \f(CW\*(C`sock\*(C'\fR. It will instead determine the master socket
by calling \fBmaster\fR on the given \fBSocketPool\fR object.
.IP "addr" 8
.IX Item "addr"
The local \s-1IP\s0 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 "host" 8
.IX Item "host"
The hostname matching \f(CW\*(C`addr\*(C'\fR. This is used to create default contact
information and the Via header. If not given defaults to the \s-1IP\s0 address.
Use of hostname instead of \s-1IP\s0 address is relevant for \s-1TLS\s0 where the
name is needed in validation of the peers certificate.
.IP "port" 8
.IX Item "port"
The port of the socket. Defaults to 5060.
.IP "family" 8
.IX Item "family"
The family of the socket. Will be determined from \f(CW\*(C`addr\*(C'\fR if omitted.
.IP "proto" 8
.IX Item "proto"
The connection protocol, e.g. 'udp', 'tcp' or 'tls'. Defaults to 'udp'.
.IP "dst" 8
.IX Item "dst"
The optional fixed target of the leg as hash with keys \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR
and \f(CW\*(C`family\*(C'\fR.
.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.
.IP "tls" 8
.IX Item "tls"
Optional arguments to be used in creating a \s-1TLS\s0 connection, as expected by
IO::Socket::SSL.
These are used for both incoming and outgoing \s-1TLS\s0 connection. Typically this
involves \f(CW\*(C`SSL_cert_file\*(C'\fR, \f(CW\*(C`SSL_key_file\*(C'\fR and \f(CW\*(C`SSL_ca_file\*(C'\fR or similar.
.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 create 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, LEG_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, ADDR,\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.
ADDR\s0 is a hash with the keys \f(CW\*(C`host\*(C'\fR, \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`family\*(C'\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(\s-1PACKET, FROM\s0)" 4
.IX Item "receive(PACKET, FROM)"
This is called from the dispatcher if the the Net::SIP::Packet \fB\s-1PACKET\s0\fR was
received from \fB\s-1FROM\s0\fR. \s-1FROM\s0 is given as hash with keys \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR,
\&\f(CW\*(C`family\*(C'\fR and \f(CW\*(C`proto\*(C'\fR.
This function might process the packet further or block it.
.Sp
It will return \f(CW\*(C`(PACKET, FROM)\*(C'\fR in the normal case or \f(CW\*(C`()\*(C'\fR if blocked.
.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 full or partial \s-1SIP URI.\s0
.Sp
If the caller has 'proto','addr','port' and 'family' 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 "match(%SPEC)" 4
.IX Item "match(%SPEC)"
This checks if the given \fB\s-1SPEC\s0\fR matches the leg. This is used from inside the
\&\fBget_legs\fR in Net::SIP::Dispatcher to get all legs matching specific
criteria. The \fB\s-1SPEC\s0\fR can contain the keys \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR and \f(CW\*(C`proto\*(C'\fR
which match the arguments given during construction of the leg or are obtained
from the legs socket.
Additionally \f(CW\*(C`sub\*(C'\fR can be used to specify a function which gets called with
the leg object and must return true on match only.
.Sp
The method returns true if there was a full match and false otherwise.
.IP "socketpool" 4
.IX Item "socketpool"
This returns the Net::SIP::SocketPool object associated with the leg.
.IP "laddr(\s-1LEVEL\s0)" 4
.IX Item "laddr(LEVEL)"
This will return the local address of the socket, either as address only
(\fB\s-1LEVEL\s0\fR is 0) or as \f(CW\*(C`ip:port\*(C'\fR (higher levels).
.IP "dump" 4
.IX Item "dump"
Returns string containing information about the leg.
Used for debugging.