NAME

       Net::SIP:::SocketPool - manage sockets related to a leg

SYNOPSIS

         my $pool = Net::SIP::SocketPool->new(...)
         $pool->sendto($packet, [ip,port,family], \&callback)

DESCRIPTION

       SocketPool manages a collection of sockets associated with a Leg. This is usually an unconnected socket
       (i.e. UDP or TCP listen socket) and mayby some connected sockets.  While in UDP a packet can be received
       and sent using an unconnected socket this is not possible in TCP and therefore these connected socket
       have to be maintained somehow. Also, it is expected in TCP that a response will be sent back through the
       same TCP connection as the request came in, if possible.

       SocketPool is usually not used directly but will be created when a new Leg gets created.

CONSTRUCTOR

       new (PROTO, FD, DST, CONNECTED, [TLS])
           The  constructer  creates  a new SocketPool for protocol PROTO ("udp", "tcp" or "tls") with FD as the
           master socket.  If CONNECTED is true this master socket is connected and DST will  in  this  case  be
           interpreted  as  the  peer  of the socket. But a connected master socket makes only sense for UDP and
           only if the communication should be limited to specific party, like an outgoing SIP  proxy.   In  the
           common  case  that  CONNECTED  is  false  the  optional  DST  given  as  "[ip, port, family]" will be
           interpreted as restriction for the communication, i.e. it will be forced as destination in sendto  no
           matter  what  was  given  and it will be checked that any received data origin from the expected peer
           DST.

           With the optional TLS argument  a  hash  can  be  givevn  wth  arguments  used  in  creation  of  the
           IO::Socket::SSL  objects  when  <PROTO> is "tls". This typically includes location of the certificate
           and key with "SSL_cert_file" and "SSL_key_file". These arguments will be used  for  both  server  and
           client  SSL sockets which also means that the certificate configured as server certificates will also
           be used as client certificates if the peer requires authentication  with  client  certificates.   The
           special  argument  "verify_client"  in  TLS  can  be  used  to  require  authentication  with  client
           certificates by the peer. It can be set to 0 for no client certificates, "-1" for optional and 1  for
           required client certificates.

METHODS

       sendto(PKT, DST, CALLBACK)
           This method is used indirectly from Leg::deliver to deliver a new packet to its destinination.

           This  will  deliver  the  Net::SIP::Packet  PKT  to the target DST given as hash with "addr", "port",
           "family" and will invoke CALLBACK when done.  Callback can be anything  accepted  by  invoke_callback
           from Net::SIP::Util.

           With  TCP  the  SocketPool  will  try to find an existing connected socket to the target first before
           creating a new one. For response packets it will prefer the socket where the request packet came  in,
           if possible.

           With UDP instead it will just use the master socket for sending.

       master
           This  will  just  return the FD for the master socket. This is used by Leg in case the SocketPool was
           created outside the Leg.

       attach_eventloop(LOOP, CALLBACK)
           This attaches the SocketPool to a Net::SIP::Dispatcher::EventLoop object so that it can be  used  for
           event  based  I/O.  This  attaches  CALLBACK  as read handler to the given LOOP to handle new packets
           coming in through the sockets inside the  SocketPool.  It  will  accept  any  callback  suitable  for
           invoke_callback  and will invoke it with "[PKT, FROM]" where PKT is the freshly read Net::SIP::Packet
           and FROM the origin of this packet as hash.   This  hash  includes  "addr",  "port"  of  the  sender,
           "family"  of  the  socket, "proto" as the used protocol (i.e. 'udp', 'tcp' or 'tls') and "socket" for
           the local socket object where the packet was received on.  This socket is  either  an  IO::Socket  or
           IO::Socket::SSL  object  and is only intended for passive use, for example to extract the certificate
           send by the peer.

           If LOOP is undef it will just detach from the current loop.

           This function is used from inside Net::SIP::Dispatcher to attach a legs sockets to the event loop and
           process incoming data.

       Additionally to these methods the internal configuration can be adjusted with "use" or "import":

           use Net::SIP::SocketPool (MAX_SIP_HEADER => 2**14, ... );

       The following settings are possible this way:

       MAX_SIP_HEADER
           maximum size of SIP header, default "2**14"

       MAX_SIP_BODY
           maximum size of SIP body, default "2**16"

       MAX_TIDLIST
           This is maximum size of remembered incoming requests per socket. These requests need to be remembered
           so that outgoing responses can be sent back through the same connection as the request came in.  This
           defaults to 30.

       MIN_EXPIRE, MAX_EXPIRE
           The minimal time for socket expiration and the maximum time. These default to 15 and  120  (seconds).
           The  exact  time  for  expiration  depends on the number of sockets in the socketgroup, i.e. the more
           sockets the shorter the expiration timeout.

       CONNECT_TIMEOUT
           The timeout used for establishing a TCP connection. Default to 10 (seconds).

       TCP_READSIZE
           The amount of data it tries to read within a single sysread, default 2**16.

perl v5.36.0                                       2023-09-29                          Net::SIP::SocketPool(3pm)