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.