.\" 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::NATHelper::Base 3pm"
.TH Net::SIP::NATHelper::Base 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::NATHelper::Base \- rewrite SDP and transport RTP for NAT
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module helps with doing \s-1NAT.\s0 It is implicitly used in \fBdo_nat\fR
from Net::SIP::StatelessProxy.
.PP
It cares about the rewriting the \s-1SDP\s0 bodies, forwarding \s-1RTP\s0 data for
active sessions and expiring sessions.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "new ( %ARGS )" 4
.el .IP "new ( \f(CW%ARGS\fR )" 4
.IX Item "new ( %ARGS )"
Creates a new object.
\&\f(CW%ARGS\fR can be of:
.RS 4
.IP "max_sockets N" 8
.IX Item "max_sockets N"
Restricts the maximum number of sockets allocated inside the object to N.
.IP "max_sockets_in_group N" 8
.IX Item "max_sockets_in_group N"
Restricts the maximum number of sockets allocated for a single socket group
(e.g. a single call to \fBget_rtp_sockets\fR) to N.
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "allocate_sockets ( \s-1NAT_BASIC,SIDE,ADDR,MEDIA\s0 )" 4
.IX Item "allocate_sockets ( NAT_BASIC,SIDE,ADDR,MEDIA )"
This is called to allocate new local sockets for \s-1MEDIA. MEDIA\s0
is a \e@list of specifications like you get from \fBget_media\fR
in Net::SIP::SDP. \s-1ADDR\s0 is the local address, where the sockets
should be allocated.
.Sp
\&\s-1NAT_BASIC\s0  consists of \f(CW\*(C`<[ CALLID, CSEQ, IDFROM, IDTO, URI_FROM, URI_TO ]\*(C'\fR>.
.Sp
\&\s-1IDFROM\s0 and \s-1IDTO\s0 represent the sides of the session, while \s-1SIDE\s0
helps to pick the right side for allocation, e.g. if \s-1SIDE\s0 is 0
the sockets will be allocated on the \s-1IDFROM\s0 side, if it is 1
it will be on the \s-1IDTO\s0 side. Thus for Requests \s-1SIDE\s0 will be 0,
while for responses it will be 1.
.Sp
\&\s-1CALLID\s0 and \s-1CSEQ\s0 are used to identify the \s-1SIP\s0 transaction, for which
the \s-1NAT\s0 will be done, while \s-1IDSIDE\s0 is either \s-1IDFROM\s0 or \s-1IDTO\s0 (see below)
depending on the side, where the packet came in.
.Sp
\&\s-1URI_FROM\s0 and \s-1URI_TO\s0 are primarily for information.
.Sp
The methode will return  the \e@list of new media in the format
needed by \fBreplace_media_listen\fR in Net::SIP::SDP, e.g tuples
of \f(CW\*(C`[ip,base_port]\*(C'\fR.
.Sp
If the allocation of sockets failed (because of resource constraints)
it will return undef. This will usually cause the caller do simply
not forward the packet and wait for the reetransmit (at least for \s-1UDP\s0).
.IP "activate_session ( \s-1NAT_BASIC\s0 ,[\e%PARAM] )" 4
.IX Item "activate_session ( NAT_BASIC ,[%PARAM] )"
\&\s-1NAT_BASIC\s0 is as described in \f(CW\*(C`allocate_sockets\*(C'\fR
Activates a session in the transaction defined by \s-1CALLID,CSEQ.\s0 This
will cause all sessions for older transactions in the same call (identified
by \s-1CALLID\s0) to shut down.
.Sp
\&\s-1IDFROM\s0 and \s-1IDTO\s0 represent the sides of the session, e.g. for the activation
to succeed there had to be an \fBallocate_sockets\fR call for each of these
sides.
.Sp
\&\s-1PARAM\s0 is an optional hash reference. If given it will be added as user
information to the new session and given back in the information hash
returned by close_session etc.
\&\s-1URI_FROM\s0 and \s-1URI_TO\s0 will be added to \s-1PARAM\s0 as \f(CW\*(C`uri_from\*(C'\fR and \f(CW\*(C`uri_to\*(C'\fR.
.Sp
The method returns two items: The first is information about the session
like returned in close_session, the second is a flag, which is true,
if the activation was for an already astablished session.
.Sp
The method is usually called whenever a \s-1SDP\s0 body is given and on \s-1ACK\s0 requests.
.IP "close_session ( \s-1NAT_BASIC\s0 )" 4
.IX Item "close_session ( NAT_BASIC )"
\&\s-1NAT_BASIC\s0 is as described before.
.Sp
This will cause the close of the session described by the arguments
(which have the same meaning like in \fBactivate_session\fR). Usually
called for \s-1BYE\s0 or \s-1CANCEL\s0 requests. For \s-1CANCEL\s0 it will be called with
\&\s-1CSEQ\s0 (because it should cancel a specific transaction) while for
\&\s-1BYE\s0 it will called with \s-1CSEQ\s0 undef, because it should end all sessions
in this call.
.Sp
It will return a list with infos about all closed sessions. Each of
these infos is a reference to a hash with the following items:
.RS 4
.IP "callid" 8
.IX Item "callid"
.PD 0
.IP "cseq" 8
.IX Item "cseq"
.IP "idfrom" 8
.IX Item "idfrom"
.IP "idto" 8
.IX Item "idto"
.IP "bytes_from \- number of bytes received on the 'from' side" 8
.IX Item "bytes_from - number of bytes received on the 'from' side"
.IP "bytes_to \- number of bytes received on the 'to' side" 8
.IX Item "bytes_to - number of bytes received on the 'to' side"
.ie n .IP "from \- space delimited list of ""ip:port/range"" for the media on the 'from' side" 8
.el .IP "from \- space delimited list of ``ip:port/range'' for the media on the 'from' side" 8
.IX Item "from - space delimited list of ip:port/range for the media on the 'from' side"
.IP "to \- same for the 'to' side" 8
.IX Item "to - same for the 'to' side"
.ie n .IP "created \- ""time_t"" when the session was created" 8
.el .IP "created \- \f(CWtime_t\fR when the session was created" 8
.IX Item "created - time_t when the session was created"
.RE
.RS 4
.PD
.Sp
Stateless proxies should forward the packet even if the session did
not exist, because the packet might be a retransmit referring to an
already closed session.
.RE
.ie n .IP "expire ( [ %ARGS ] )" 4
.el .IP "expire ( [ \f(CW%ARGS\fR ] )" 4
.IX Item "expire ( [ %ARGS ] )"
This causes the sessions and sockets to expire.
It will return a list with a hash for each expired session.
See close_session for details on the returned information.
.Sp
With \f(CW%ARGS\fR the behavior can be customized:
.RS 4
.IP "time" 8
.IX Item "time"
Current time, can be given to save system call for getting current time.
.IP "unused" 8
.IX Item "unused"
Expire time for unused sockets. Default ist 180, e.g. 3 minutes.
.IP "active" 8
.IX Item "active"
Expire time for active sessions. Default to 30 seconds. If no data
gets transferred through the session for \f(CW\*(C`active\*(C'\fR seconds the session
will be closed.
.IP "closed" 8
.IX Item "closed"
Expire time for closed sessions, i.e. the time after which the sockets from a
closed (replaced) session will be closed too. They are usually kept open a short
time in case packets are still in transit. Default to 1 second.
.RE
.RS 4
.RE
.IP "callbacks" 4
.IX Item "callbacks"
This will return a list (not a reference) of \f(CW\*(C`[cbid,fd,callback]\*(C'\fR pairs,
where fd is the file descriptor of the socket and callback is a callback
for \fBinvoke_callback\fR in Net::SIP::Util. cbid is a uniq id for each callback
so that one get compare the result from different calls to callbacks
and see, what changed.
.Sp
Each of these callbacks should be invoked once the file descriptor gets
readable and the callback will then forward the received packet to the
other side of the session.
.IP "sessions ( [ \s-1CALLBACK\s0 ] )" 4
.IX Item "sessions ( [ CALLBACK ] )"
This will call \s-1CALLBACK\s0 on all sessions and return an array containing
the results of the callbacks together. If no \s-1CALLBACK\s0 is given it will
return all session objects.
.Sp
To use this function you might need to know the interna of the session
objects (see source code), but in most cases it is enough to know, that
session objects have a method info_as_hash which will return infos
about the session as hash like described in close_session.
.ie n .IP "get_rtp_sockets ( \s-1NEW_ADDR,\s0 @MEDIA )" 4
.el .IP "get_rtp_sockets ( \s-1NEW_ADDR,\s0 \f(CW@MEDIA\fR )" 4
.IX Item "get_rtp_sockets ( NEW_ADDR, @MEDIA )"
Allocates sockets for on address \s-1NEW_ADDR\s0 for \f(CW@MEDIA\fR. \f(CW@MEDIA\fR is in
the format given by \fBget_media\fR in Net::SIP::SDP.
.Sp
Returns reference to array of allocated media, each item in the
array is \f(CW\*(C`[ ADDR,BASE_PORT,\e@SOCKS,\e@TARGETS ]\*(C'\fR, where \s-1ADDR\s0
is \s-1NEW_ADDR, BASE_PORT\s0 the base port for the allocated sockets,
\&\f(CW@SOCKS\fR the allocated sockets and \f(CW@TARGETS\fR the \f(CW\*(C`sockaddr\*(C'\fR of
the original targets, e.g. where it needs to forward the data
received on the sockets.
.Sp
If not all necssary sockets could be allocated it will allocate
none and return \f(CW\*(C`()\*(C'\fR.
.Sp
This method might be redefined to better control resource allocation
or to cache temporally unused resources together with unget_rtp_sockets.
.IP "unget_rtp_sockets ( \s-1NEW_MEDIA\s0 )" 4
.IX Item "unget_rtp_sockets ( NEW_MEDIA )"
Will take resources back. \s-1NEW_MEDIA\s0 is the result from \fBget_rtp_sockets\fR.
Returns nothing.
.Sp
Together with get_rtp_sockets it could be redefined to not destroy
resources but to cache them for future use.
.IP "dump" 4
.IX Item "dump"
This method is used for debugging only. It will return a string with information
about all calls within this nathelper and all sessions and allocated sockets within
the calls.
.IP "number_of_calls" 4
.IX Item "number_of_calls"
Returns the number of calls within the nathelper. This vaalue has not much
association with the result of \fBcallbacks\fR because there might be inactive
sockets (not yet or no longer in active session) which don't affect the
result of \fBcallbacks\fR.
.Sp
This value can be used to determine if \fBexpire\fR needs to be called at all.