Net::SIP:::SocketPool - manage sockets related to a leg
my $pool = Net::SIP::SocketPool->new(...)
$pool->sendto($packet, [ip,port,family], \&callback)
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.
is usually not used directly but will be created when a new
- 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.
- 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.
- This will just return the FD for the master socket. This is used by
Leg in case the SocketPool was created outside the
- 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:
- maximum size of SIP header, default "2**14"
- maximum size of SIP body, default "2**16"
- 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
- 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.
- The timeout used for establishing a TCP connection. Default to 10
- The amount of data it tries to read within a single sysread, default