---
name: "Net::SIP::SocketPool"
section: "3pm"
platform: "linux"
package: "libnet-sip-perl"
version: "0.838-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Net::SIP::SocketPool"
---

# Net::SIP::SocketPool(3pm)

manage sockets related to a leg

## 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.