Net::S...dpoint(3pm)

📦

version 0.840 · 6 versions

0.840 · ubuntu resolute, ubuntu stonking (latest)
0.838 · ubuntu questing
0.833 · ubuntu jammy
0.836 · ubuntu noble
0.835 · debian bookworm
0.838 · debian trixie

💖 Net::SIP::Endpoint(3pm) — the User Contributed Perl Documentation glow-up 💖

okay bestie, gather round, because we're about to get into Net::SIP::Endpoint and honestly? she's giving main character energy in the SIP world. ✨

🌸 NAME 🌸

Net::SIP::Endpoint — the Endpoint for SIP packets (UAC, UAS). yes, both. she contains multitudes. 💅

🦋 SYNOPSIS 🦋

my $disp = Net::SIP::Dispatcher->new(...);
my $ua = Net::SIP::Endpoint->new($disp);
$ua->register(
      from => 'sip:me@example.com',
      contact => 'sip:me@192.168.0.1',
      registrar => 'sip:192.168.0.10:5060'
);

look at that. dispatcher in, endpoint out, register call, slay. 🎀

💜 DESCRIPTION 💜

so this package implements a communication endpoint for SIP. usually that's a phone, but lowkey it can also be a stateful proxy — and the reason it can be a stateful proxy is that it retransmits packets itself. iconic behavior, no cap.

it gives you methods to send arbitrary requests, but also special ones like INVITE or REGISTER. together with Net::SIP::Endpoint::Context, it implements the behavior of the endpoint. they're a duo, fr fr. 🫶

for incoming requests, the endpoint usually talks to the upper layer, aka the application, which is the interface to the user. think: let it ring for incoming calls, create a response for call accepted if the user picks up the phone on an incoming call, etc. yes, it's the vibe bridge between the network and the human. 💖

✨ CONSTRUCTOR ✨

new ( DISPATCHER ) — creates a new endpoint and sets it as the receiver for incoming packets at the Net::SIP::Dispatcher DISPATCHER. the endpoint will use DISPATCHER for outgoing packets and will receive incoming packets from it. so basically DISPATCHER is her whole support system and we love that for her. 🌈

👑 METHODS 👑

🎀 `set_application ( APP )`

sets APP as the upper layer — like, the layer between the user and the endpoint object $self. APP is either an object which has a method receive or a callback usable by invoke_callback in Net::SIP::Util.

the callback will be invoked with the following arguments:

ENDPOINT — this is the endpoint itself, e.g. $self. hi bestie, it's you. 🙈
CTX — the Net::SIP::Endpoint::Context object for the current call.
REQUEST — the Net::SIP::Request which caused the invocation of the call, e.g. an INVITE on new calls, ACK if the peer established the call, BYE if a call gets closed by the peer, etc.
LEG — the Net::SIP::Leg object where the call came in. together with FROM, it's used to send the response packet back to the peer.
FROM — hash with information about the sender of the request (keys "proto", "addr", "host", "port" and "family"). all five, don't lose any. 💅

it will call into APP on various incoming requests, like:

💌 `INVITE`

in this case APP should ring the user, and while ringing, send "180 Ringing" responses back to the peer, using "ENDPOINT->new_response". after some time it should send a final response (like "200 Ok" if the user accepted the call). the drama of the ringing phase... we've all been there. 😭

💌 `ACK`

this is the sign that the peer established the call. APP should now expect to process incoming RTP data and send RTP data itself. we're live, babes. 🔥

💌 `CANCEL`, `BYE`

this informs APP that the call is closed. there's no need for the APP to send a response itself — this was already handled by the endpoint, because there's literally no choice of responses; it can hardly not accept a BYE. like, the BYE is happening whether you like it or not. 💀

💌 other requests

like OPTION,.. . these need to be fully handled by APP, e.g. send the appropriate response back using "ENDPOINT->new_response". your problem now, bestie. 🫶

🎀 `invite ( CTX, [ CALLBACK, BODY, %ARGS ] )`

creates a new INVITE request and delivers it to the peer. simply calls new_request with the method 'INVITE'. see that method for information for the arguments. yes queen, it's a lil shortcut and she's not sorry. ✨

🎀 `register ( %ARGS )`

registers the endpoint at a remote registrar. %ARGS needs to be filled as follows:

registrar — SIP URI of registrar, i.e. anything acceptable to sip_uri2parts from Net::SIP::Util. Mandatory.
from — the address to register at the registrar. Mandatory.
contact — the contact, under which "from" will be registered. Mandatory.
auth — authorization info, see method authorize in Net::SIP::Request for information about the format. Optional.
expires — expires time. Optional, defaults to 900.
callback — optional callback, e.g. called if requests come in from the peer on the call created for the registration. see invoke_callback in Net::SIP::Util for the format.

all other keys will be used as header keys in generating the Net::SIP::Request object. 🦋

🎀 `new_request ( METHOD, CTX, [ CALLBACK, BODY, %ARGS ] )`

METHOD is the uppercase name of the method for which a request should be generated. it can also already be a Net::SIP::Request object, in which case no new request object will be generated, but the provided one delivered. flexible. we stan. 💅

CTX is either an existing Net::SIP::Endpoint::Context object or a hash reference which will be used to construct one. it contains information about "from" and "to", etc. see constructor in Net::SIP::Endpoint::Context for details. in case of a hash reference, auth and callid from ARGS will be used for the newly constructed context.

if it's an existing CTX, it has to be one which is already managed by this endpoint (e.g. one returned by this method). the endpoint will only manage CTX which it created itself, so that a context cannot be shared between multiple endpoints. possessive? maybe. correct? absolutely. 👑

CALLBACK is a callback usable by invoke_callback in Net::SIP::Util. if defined, it will be set up as the new default callback for the context.

BODY is a string or an object for the SIP body accepted by the constructor of Net::SIP::Request. see there. 📦

if a response object is given as resp40x in ARGS, it will be used to authorize the newly created request. 🔐

anything else in %ARGS will be used to construct the SIP header. see constructor in Net::SIP::Request.

it returns the Net::SIP::Endpoint::Context object for this request, which can then be used for further requests in the same call. keep it, you'll need it again bestie. 🎀

🎀 `cancel_invite ( CTX, REQUEST, CALLBACK )`

cancel the given request within the given context (e.g. send CANCEL request). if no REQUEST is given, it will cancel the most recent INVITE. returns the number of requests canceled, e.g. 0 or 1. math queen. ✨

CALLBACK will be used as the callback for the CANCEL request it sends using new_request.

🎀 `close_context ( CTX )`

delete Net::SIP::Endpoint::Context object CTX from the list of active calls. bye bye, you will not be missed (affectionate). 🦋

🎀 `receive ( PACKET, LEG, FROM )`

called from dispatcher on incoming packets.

PACKET is the incoming Net::SIP::Packet, LEG the Net::SIP::Leg where the packet came in, and FROM the hash with the sender info.

just forwards to receive_request or receive_response based on the type of packet. a lil traffic director, and she's good at it. 💅

🎀 `receive_response ( RESPONSE, LEG, FROM )`

handles incoming response packets. tries to find an active call based on the "Call-Id" header in the packet. if none was found, it will drop the packet, otherwise call handle_response on the call context object (Net::SIP::Endpoint::Context). no call id, no entry. rules are rules. 💀

🎀 `receive_request ( REQUEST, LEG, FROM )`

handles incoming requests.

if there's already a call context for this Call-Id in the request, it will use it; otherwise it will create a Net::SIP::Endpoint::Context object based on the information in the request ("from", "to", "contact",... ).

calls handle_request on the existing/new context object. 🫶

🎀 `new_response ( CTX, RESPONSE, LEG, ADDR )`

delivers Net::SIP::Response packet RESPONSE through the endpoint's dispatcher to ADDR (hash) using Net::SIP::Leg LEG. LEG and ADDR are usually the leg and the sender's address where the associated request came in. 📬

CTX is the context from the call where the associated request came in.

if the response is a 2xx response to a INVITE and no "contact" header is given as required from the RFC, it will add one based on the CTX. helpful icon behavior. ✨

ngl this whole module is giving "quietly does all the hard work while looking cute doing it". and that's the vibe check passed. 💖

and that's the whole page, bestie — brought to you by perl v5.40.1, dated 2025-12-07, from the User Contributed Perl Documentation collection. periodt. 💅🎀✨

📦 where this page comes from

ubuntu resolute: libnet-sip-perl 0.840-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnet-sip-perl 0.840-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Net::S...dpoint(3pm)

💖 Net::SIP::Endpoint(3pm) — the User Contributed Perl Documentation glow-up 💖

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

💜 DESCRIPTION 💜

✨ CONSTRUCTOR ✨

👑 METHODS 👑

🎀 set_application ( APP )

💌 INVITE

💌 ACK

💌 CANCEL, BYE

💌 other requests

🎀 invite ( CTX, [ CALLBACK, BODY, %ARGS ] )

🎀 register ( %ARGS )

🎀 new_request ( METHOD, CTX, [ CALLBACK, BODY, %ARGS ] )

🎀 cancel_invite ( CTX, REQUEST, CALLBACK )

🎀 close_context ( CTX )

🎀 receive ( PACKET, LEG, FROM )

🎀 receive_response ( RESPONSE, LEG, FROM )

🎀 receive_request ( REQUEST, LEG, FROM )

🎀 new_response ( CTX, RESPONSE, LEG, ADDR )