.\" 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::SocketPool 3pm"
.TH Net::SIP::SocketPool 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:::SocketPool \- manage sockets related to a leg
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $pool = Net::SIP::SocketPool\->new(...)
\&  $pool\->sendto($packet, [ip,port,family], \e&callback)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBSocketPool\fR manages a collection of sockets associated with a \fBLeg\fR. This is
usually an unconnected socket (i.e. \s-1UDP\s0 or \s-1TCP\s0 listen socket) and mayby some
connected sockets.
While in \s-1UDP\s0 a packet can be received and sent using an unconnected socket this
is not possible in \s-1TCP\s0 and therefore these connected socket have to be
maintained somehow. Also, it is expected in \s-1TCP\s0 that a response will be sent
back through the same \s-1TCP\s0 connection as the request came in, if possible.
.PP
\&\fBSocketPool\fR is usually not used directly but will be created when a new \fBLeg\fR
gets created.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new (\s-1PROTO, FD, DST, CONNECTED,\s0 [\s-1TLS\s0])" 4
.IX Item "new (PROTO, FD, DST, CONNECTED, [TLS])"
The constructer creates a new \fBSocketPool\fR for protocol \fB\s-1PROTO\s0\fR (\f(CW\*(C`udp\*(C'\fR,
\&\f(CW\*(C`tcp\*(C'\fR or \f(CW\*(C`tls\*(C'\fR) with \fB\s-1FD\s0\fR as the master socket.
If \fB\s-1CONNECTED\s0\fR is true this master socket is connected and \fB\s-1DST\s0\fR will in this
case be interpreted as the peer of the socket. But a connected master socket
makes only sense for \s-1UDP\s0 and only if the communication should be limited to
specific party, like an outgoing \s-1SIP\s0 proxy.
In the common case that \fB\s-1CONNECTED\s0\fR is false the optional \fB\s-1DST\s0\fR
given as \f(CW\*(C`[ip, port, family]\*(C'\fR will be interpreted as restriction for the
communication, i.e. it will be forced as destination in \fBsendto\fR no matter what
was given and it will be checked that any received data origin from the expected
peer \fB\s-1DST\s0\fR.
.Sp
With the optional \fB\s-1TLS\s0\fR argument a hash can be givevn wth arguments used in
creation of the IO::Socket::SSL objects when <\s-1PROTO\s0> is \f(CW\*(C`tls\*(C'\fR. This
typically includes location of the certificate and key with \f(CW\*(C`SSL_cert_file\*(C'\fR and
\&\f(CW\*(C`SSL_key_file\*(C'\fR. These arguments will be used for both server and client \s-1SSL\s0
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 \f(CW\*(C`verify_client\*(C'\fR in \fB\s-1TLS\s0\fR can be used to require
authentication with client certificates by the peer. It can be set to \f(CW0\fR for
no client certificates, \f(CW\*(C`\-1\*(C'\fR for optional and \f(CW1\fR for required client
certificates.
.SH "METHODS"
.IX Header "METHODS"
.IP "sendto(\s-1PKT, DST, CALLBACK\s0)" 4
.IX Item "sendto(PKT, DST, CALLBACK)"
This method is used indirectly from \fBLeg::deliver\fR to deliver a new packet to
its destinination.
.Sp
This will deliver the Net::SIP::Packet \fB\s-1PKT\s0\fR to the target \fB\s-1DST\s0\fR given as
hash with \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR, \f(CW\*(C`family\*(C'\fR and will invoke \fB\s-1CALLBACK\s0\fR when done.
Callback can be anything accepted by \fBinvoke_callback\fR from Net::SIP::Util.
.Sp
With \s-1TCP\s0 the \fBSocketPool\fR 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.
.Sp
With \s-1UDP\s0 instead it will just use the master socket for sending.
.IP "master" 4
.IX Item "master"
This will just return the \s-1FD\s0 for the master socket. This is used by \fBLeg\fR in
case the \fBSocketPool\fR was created outside the \fBLeg\fR.
.IP "attach_eventloop(\s-1LOOP, CALLBACK\s0)" 4
.IX Item "attach_eventloop(LOOP, CALLBACK)"
This attaches the \fBSocketPool\fR to a Net::SIP::Dispatcher::EventLoop object
so that it can be used for event based I/O. This attaches \fB\s-1CALLBACK\s0\fR as read
handler to the given \fB\s-1LOOP\s0\fR to handle new packets coming in through the sockets
inside the \fBSocketPool\fR. It will accept any callback suitable for
\&\fBinvoke_callback\fR and will invoke it with \f(CW\*(C`[PKT, FROM]\*(C'\fR where \fB\s-1PKT\s0\fR is
the freshly read Net::SIP::Packet and \fB\s-1FROM\s0\fR the origin of this packet as
hash.
This hash includes \f(CW\*(C`addr\*(C'\fR, \f(CW\*(C`port\*(C'\fR of the sender, \f(CW\*(C`family\*(C'\fR of the socket,
\&\f(CW\*(C`proto\*(C'\fR as the used protocol (i.e. 'udp', 'tcp' or 'tls') and \f(CW\*(C`socket\*(C'\fR 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.
.Sp
If \fB\s-1LOOP\s0\fR is undef it will just detach from the current loop.
.Sp
This function is used from inside Net::SIP::Dispatcher to attach a legs
sockets to the event loop and process incoming data.
.PP
Additionally to these methods the internal configuration can be adjusted with
\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`import\*(C'\fR:
.PP
.Vb 1
\&    use Net::SIP::SocketPool (MAX_SIP_HEADER => 2**14, ... );
.Ve
.PP
The following settings are possible this way:
.IP "\s-1MAX_SIP_HEADER\s0" 4
.IX Item "MAX_SIP_HEADER"
maximum size of \s-1SIP\s0 header, default \f(CW\*(C`2**14\*(C'\fR
.IP "\s-1MAX_SIP_BODY\s0" 4
.IX Item "MAX_SIP_BODY"
maximum size of \s-1SIP\s0 body, default \f(CW\*(C`2**16\*(C'\fR
.IP "\s-1MAX_TIDLIST\s0" 4
.IX Item "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.
.IP "\s-1MIN_EXPIRE, MAX_EXPIRE\s0" 4
.IX Item "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.
.IP "\s-1CONNECT_TIMEOUT\s0" 4
.IX Item "CONNECT_TIMEOUT"
The timeout used for establishing a \s-1TCP\s0 connection. Default to 10 (seconds).
.IP "\s-1TCP_READSIZE\s0" 4
.IX Item "TCP_READSIZE"
The amount of data it tries to read within a single sysread, default 2**16.