NAME¶
Net::SIP::NATHelper::Base - rewrite SDP and transport RTP for NAT
DESCRIPTION¶
This module helps with doing NAT. It is implicitly used in
do_nat from
Net::SIP::StatelessProxy.
It cares about the rewriting the SDP bodies, forwarding RTP data for active
sessions and expiring sessions.
CONSTRUCTOR¶
- new ( %ARGS )
- Creates a new object. %ARGS can be of:
- max_sockets N
- Restricts the maximum number of sockets allocated inside the object to
N.
- max_sockets_in_group N
- Restricts the maximum number of sockets allocated for a single socket
group (e.g. a single call to get_rtp_sockets) to N.
METHODS¶
- allocate_sockets ( CALLID,CSEQ,IDFROM,IDTO,SIDE,ADDR,MEDIA )
- This is called to allocate new local sockets for MEDIA. MEDIA is a \@list
of specifications like you get from get_media in Net::SIP::SDP.
ADDR is the local address, where the sockets should be allocated.
IDFROM and IDTO represent the sides of the session, while SIDE helps to pick
the right side for allocation, e.g. if SIDE is 0 the sockets will be
allocated on the IDFROM side, if it is 1 it will be on the IDTO side. Thus
for Requests SIDE will be 0, while for responses it will be 1.
CALLID and CSEQ are used to identify the SIP transaction, for which the NAT
will be done, while IDSIDE is either IDFROM or IDTO (see below) depending
on the side, where the packet came in.
The methode will return the \@list of new media in the format needed by
replace_media_listen in Net::SIP::SDP, e.g tuples of
"[ip,base_port]".
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 UDP).
- activate_session ( CALLID,CSEQ,IDFROM,IDTO,[\%PARAM] )
- Activates a session in the transaction defined by CALLID,CSEQ. This will
cause all sessions for older transactions in the same call (identified by
CALLID) to shut down.
IDFROM and IDTO represent the sides of the session, e.g. for the activation
to succeed there had to be an allocate_sockets call for each of
these sides.
PARAM 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.
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.
The method is usually called whenever a SDP body is given and on ACK
requests.
- close_session ( CALLID,CSEQ,IDFROM,IDTO )
- This will cause the close of the session described by the arguments (which
have the same meaning like in activate_session). Usually called for
BYE or CANCEL requests. For CANCEL it will be called with CSEQ (because it
should cancel a specific transaction) while for BYE it will called with
CSEQ undef, because it should end all sessions in this call.
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:
- callid
- cseq
- idfrom
- idto
- bytes_from - number of bytes received on the 'from' side
- bytes_to - number of bytes received on the 'to' side
- from - space delimited list of "ip:port/range" for the media on
the 'from' side
- to - same for the 'to' side
- created - "time_t" when the session was created
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.
- 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.
With %ARGS the behavior can be customized:
- time
- Current time, can be given to save system call for getting current
time.
- unused
- Expire time for unused sockets. Default ist 180, e.g. 3 minutes.
- active
- Expire time for active sessions. Default to 30 seconds. If no data gets
transferred through the session for "active" seconds the session
will be closed.
- callbacks
- This will return a list (not a reference) of
"[cbid,fd,callback]" pairs, where fd is the file descriptor of
the socket and callback is a callback for invoke_callback 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.
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.
- sessions ( [ CALLBACK ] )
- This will call CALLBACK on all sessions and return an array containing the
results of the callbacks together. If no CALLBACK is given it will return
all session objects.
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.
- get_rtp_sockets ( NEW_ADDR, @MEDIA )
- Allocates sockets for on address NEW_ADDR for @MEDIA. @MEDIA is in the
format given by get_media in Net::SIP::SDP.
Returns reference to array of allocated media, each item in the array is
"[ ADDR,BASE_PORT,\@SOCKS,\@TARGETS ]", where ADDR is NEW_ADDR,
BASE_PORT the base port for the allocated sockets, @SOCKS the allocated
sockets and @TARGETS the "sockaddr_in" of the original targets,
e.g. where it needs to forward the data received on the sockets.
If not all necssary sockets could be allocated it will allocate none and
return "()".
This method might be redefined to better control resource allocation or to
cache temporally unused resources together with unget_rtp_sockets.
- unget_rtp_sockets ( NEW_MEDIA )
- Will take resources back. NEW_MEDIA is the result from
get_rtp_sockets. Returns nothing.
Together with get_rtp_sockets it could be redefined to not destroy resources
but to cache them for future use.
- 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.
- number_of_calls
- Returns the number of calls within the nathelper. This vaalue has not much
association with the result of callbacks because there might be
inactive sockets (not yet or no longer in active session) which don't
affect the result of callbacks.
This value can be used to determine if expire needs to be called at
all.