Net::SIP::Simple(3pm)

💖 NAME 💖

Net::SIP::Simple — the simple lil interface for using Net::SIP, bestie. It's from the User Contributed Perl Documentation, and yes she's iconic 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in one go, no cap:

use Net::SIP;

# create new agent
my $ua = Net::SIP::Simple->new(
      outgoing_proxy => '192.168.0.10',
      registrar => '192.168.0.10',
      domain => 'example.com',
      from => 'me',
      auth => [ 'me','secret' ],
);

# Register agent
$ua->register;

# Invite other party, send announcement once connected
my $call = $ua->invite( 'you',
      init_media => $ua->rtp( 'send_recv', 'announcement.pcmu-8000' ),
      asymetric_rtp => 1,
);

# Mainloop
$ua->loop;

like... that's IT. that's the whole SIP application. slay 🦋

---

🌸 DESCRIPTION 🌸

This package is a simple layer sitting on top of Net::SIP::Endpoint, Net::SIP::Registrar and Net::SIP::StatelessProxy. With her help you can write simple SIP applications in just a few lines of perl code. fr fr, a few. not a novel. not 4000 lines. a few. 👑

---

🎀 CONSTRUCTOR 🎀

new ( %ARGS )

Creates a new Net::SIP::Simple object. New bestie just dropped 💖

It will return the new object for further operations, but lowkey the object itself contains back references to itself in the form of callbacks into the eventloop and dispatcher. Which means... she will not self-destroy 😭 you have to call cleanup if you want her to actually go away. She's clingy, it's giving main character energy.

%ARGS can be:

• outgoing_proxy|proxy — "ip:port" of the outgoing proxy. The necessary Net::SIP::Leg to the proxy will be created if no leg exists.
• registrar — "ip:port" of the registrar. Used in method register if there is no other registrar given.
• legs|leg — a \@List of legs, or a single leg. A leg can be an existing Net::SIP::Leg (or derived) object, an IO::Handle (an existing socket), a hash reference which can be used in the constructor of Net::SIP::Leg, or a string of "proto:ip:port". In that last case, "proto" can be omitted (including the colon) and defaults to 'udp', and "port" can be omitted too (including the colon) defaulting to 5060.
• auth — Authorization data, see method authorize in Net::SIP::Request for details about the format.
• domain — Default domain for not fully qualified SIP addresses in "from" and "to" (method invite).
• from — SIP address of the local sender, either the full SIP address or only the part before \@, in which case domain has to be provided.
• contact — SIP address of the local sender, which should be used in the contact header of REGISTER and INVITE requests. If not given, from will be used.
• options — This is a hash reference containing headers (header-key, value) for replies to an OPTIONS request. If not given, or only partly given, defaults will be used for the headers Allow, Accept, Accept-Encoding, Accept-Language and Supported.
• route — Optional list of SIP routes which will be added to route requests.
• loop — Eventloop object for the dispatcher, see Net::SIP::Dispatcher::Eventloop. Usually not given, because the loop from the dispatcher will be used, but it can be given if no dispatcher was given.
• dispatcher — A Net::SIP::Dispatcher object. Usually not given and will be created, but sometimes one needs to share the same dispatcher between multiple Net::SIP::Simple objects.
• domain2proxy|d2p — Hash with mapping between domain and upstream proxy. See the same key in the constructor of Net::SIP::Dispatcher for more details.
• tls — Common TLS settings for all legs which will be created by this object. See "new" in Net::SIP::Leg for more details.

bestie, one of these is mandatory: either legs or outgoing_proxy has to be provided — you need at least one leg. no leg, no call, no vibe 💀

---

💅 METHODS 💅

cleanup

Cleans up the object, removes the legs it added from the dispatcher. The EventLoop will also be reset, but only if it was implicitly created inside this object. You need to call this if you want to destroy the object, because she will not self-destroy (see new). periodt.

error ( ERROR )

Either sets the current error (used internally) or returns the last error.

loop ( [ TIMEOUT, @STOPVAR ] )

Calls the event loop (key loop in constructor) > loop method. TIMEOUT is the timeout for the loop in seconds. If not given, it will not stop because of a timeout. @STOPVAR is a list of scalar references — the loop will stop if any of these references contains TRUE. See method loop in Net::SIP::Dispatcher::Eventloop for more details.

The order of TIMEOUT or the STOPVARs is insignificant, e.g. if it finds a reference it will use it as a stopvar, otherwise it's used as a timeout. She's flexible like that 💁

add_timer ( WHEN, CALLBACK, [ REPEAT ] )

Calls the same method from the Net::SIP::Dispatcher object in $self. See there for details on the arguments.

rtp ( METHOD,@ARGS )

Calls the method METHOD in Net::SIP::Simple::RTP with arguments @ARGS. Currently it only does this and thus works as a shortcut. In the future one might add more ways to find the right method for RTP handling (e.g. plugins or similar).

register ( %ARGS )

Registers the user agent. %ARGS can have the key registrar which has precedence over the same key in the constructor. leg specifies the leg where the register request will be sent through. If not given, it will pick the right leg. she's got good taste, she'll find it ✨

If cb_final is specified it is a callback usable by invoke_callback in Net::SIP::Util which will be called once the registration is completed (e.g. it succeeded or failed). If no cb_final is specified, the method will wait until the registration is completed and return either the expires time given by the registrar or "()" if registration failed.

All other keys, like contact, expires, resp40x, auth, will be forwarded to method register in Net::SIP::Endpoint. from and auth will be used from %ARGS or, if not in %ARGS, from the constructor.

invite ( CTX,%ARGS )

Creates a new call and invites the peer. Creates a new Net::SIP::Simple::Call object with context CTX and creates an INVITE request for this call using %ARGS. See reinvite in Net::SIP::Simple::Call for more info on %ARGS.

CTX can be the address of the peer or a context hash containing the address.

Returns the newly created Net::SIP::Simple::Call object, which can later be used for reINVITEs or BYE etc.

⚠️ note that in order to have any callbacks triggered by the invite working, you need to keep the returned caller object. don't let her go, bestie 😭

listen ( %ARGS )

Sets up waiting on all legs in $self for incoming calls, e.g. new INVITE requests. All other incoming packets will be dropped. If a call comes in, a new Net::SIP::Simple::Call object will be created using %ARGS.

The method does not wait for the calls — it's only setting the callback on the legs up. Thus it has to be followed by a call to loop. no cap, you literally have to loop after.

If %ARGS contain "auth_*" keys an Authorizer will be added before the listener. See Net::SIP::Authorize for the keys, e.g. "auth_user2pass" will be forwarded as "user2pass" etc to the authorizer.

Special keys not described in Net::SIP::Simple::Call:

The returned object can be used together with other objects within "create_chain", but it should be used as the last object.

• filter — A callback usable by invoke_callback in Net::SIP::Util which gets called with the value of the From header and the Net::SIP::Request object from the incoming request. If the callback returns TRUE the call gets accepted, otherwise not.
• cb_create — Callback which will be called on accepting the call. Will be called with "CALL,REQUEST,LEG,FROM" where CALL is the newly created Net::SIP::Simple::Call object, REQUEST the creating Net::SIP::Request packet, LEG the incoming leg and FROM the "ip:port" of the sender. Must return TRUE or the call gets not answered. 🫶
• cb_established — Callback which will be called after the call is established, e.g. after receiving the ACK from the peer. Will be invoked with 'OK' and the Net::SIP::Simple::Call object as argument.
• cb_cleanup — Callback which will be called when the call gets closed, to clean up allocated resources. Will be invoked with the Net::SIP::Simple::Call object as argument.

create_auth ( %ARGS )

Sets up authorization. See Net::SIP::Authorize for the meaning of %ARGS. The returned object should be used together with other objects within "create_chain".

create_registrar ( %ARGS )

Sets up a simple registrar using Net::SIP::Registrar. See there for the meaning of %ARGS.

Like with listen, you need to loop after calling this method — the method itself will not wait.

Like with listen, authorization can be added using "auth_*" keys.

create_stateless_proxy ( %ARGS )

Sets up a simple proxy using Net::SIP::StatelessProxy. See there for the meaning of %ARGS.

Like with listen, you need to loop after calling this method — the method itself will not wait.

Like with listen, authorization can be added using "auth_*" keys.

create_chain ( OBJECTS, %ARGS )

Sets up a chain using Net::SIP::ReceiveChain. See there for the meaning of OBJECT and %ARGS.

Like with listen, you need to loop after calling this method — the method itself will not wait.

---

and that's the whole page, bestie 🦋

this was pulled from the perl v5.40.1 docs, dated 2025-12-07, straight out of the User Contributed Perl Documentation, page Net::SIP::Simple(3pm). go forth and make calls, you've got this 💜✨