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

📦
version 0.840 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

Net::S...::Call — bestie, this is the call context for Net::SIP::Simple. That's it, that's the whole vibe. Manual name is Net::S...::Call(3pm) from the User Contributed Perl Documentation, and yes she's iconic for it. 👑

✨ SYNOPSIS ✨

my $call = $simple->invite(...);
$call->reinvite(... );
$call->bye();

look at her go 🦋

🌸 DESCRIPTION 🌸

okay so this package is the one holding the call context for Net::SIP::Simple. it manages the whole situation — like (re-)invites on an already existing context, etc. it's giving backstage manager energy, fr fr. 💅

🎀 CONSTRUCTOR 🎀

new ( CONTROL, CTX, \%ARGS )

makes you a fresh lil Net::SIP::Simple::Call object so you can control a call. usually you don't call this yourself — invite in Net::SIP::Simple does it for you. 🫶

  • CONTROL — the Net::SIP::Simple object that's running the calls, aka the one in charge here.
  • CTX — this one's flexible, bestie. it's either an already-existing Net::SIP::Endpoint::Context, or the SIP address of the peer you're gonna contact in this call, or a hash that can be used to create the context. if the context isn't complete, the missing info gets pulled from $call when it's called as "$call-"new>. ✨
  • %ARGS — these describe how the call should behave, and they get saved into the object as the connection parameter. the options below all live in that connection parameter and can be passed in %ARGS:
  • leg — tells you which leg to use for the call. the default is just the first leg in the dispatcher. no cap.
  • sdp_on_ack — if you pass this and it's TRUE, it will not send the SDP body on the INVITE request, it sends it on the ACK instead. mostly used for testing how proxies behave between the two parties. lowkey a little sneaky. 🙈
  • init_media — a callback that initializes the media for the connection. see method rtp in Net::SIP::Simple and also Net::SIP::Simple::RTP.

the callback gets called with the call $self and the connection parameter as its arguments (as a hash reference).

  • rtp_param — data for the codec used in the media set up by init_media, plus for initializing the default SDP data. it's an array reference [pt,size,interval,name] where pt is the payload type, size is the size of the payload, and interval is the interval at which the RTP packets get sent. name is optional — if you give it, rtpmap and ptime entries get added to the SDP so the name gets associated with that payload type.

the default is for PCMU/8000: [0,160,160/8000]. an alternative could be, for example, [97,50,0.03,'iLBC/8000'] for iLBC. 🌈

  • sdp — a Net::SIP::SDP object, or the argument for constructing one. if you don't give it, it'll create an SDP body with one RTP audio connection — unless it already got first SDP data from the peer, in which case it just matches them. slay, adaptive. 💅
  • sdp_peer — holds the Net::SIP::SDP body sent by the peer. usually it's not set in the constructor, but you can get at it from callbacks.
  • media_lsocks — contains a \@list of sockets, one for each media-line in the SDP. every item in this list is either a single socket (when the port range is 1) or a \@list of sockets.
⚠️ if sdp is provided, this parameter has to be provided too. like, the package will not allocate the sockets described in the SDP packet. so bring your own, bestie.
  • media_ssocks — the sockets used for sending RTP data. if you don't give this, the socket for sending RTP is the same one used for receiving RTP — unless asymetric_rtp is specified.
  • asymetric_rtp — by default it sends the RTP data from the same port where it listens for data. if this option is TRUE it allocates a different port for receiving data. mostly used for testing how proxies behave between the two parties. 🧚
  • dtmf_methods — if a DTMF callback is specified, this is treated as the list of supported DTMF methods for receiving DTMF. if you don't give it, it defaults to 'rfc2833,audio'.
  • recv_bye — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when the peer initiated the close of the connection using BYE or CANCEL.

the argument for the callback will be a hash reference containing the connection parameter.

  • send_bye — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when the local side initiated the close of the connection using BYE or CANCEL.

the argument for the callback will be a hash reference containing the connection parameter merged with the parameter from the bye method.

  • clear_sdp — if TRUE, the keys media_lsocks, media_ssocks, sdp and sdp_peer get cleared on each new (re)INVITE request. so it'll allocate brand new sockets for RTP instead of reusing the existing ones. fresh start energy ✨
  • cb_final — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received the final answer on locally created INVITE requests (like, when it established the call by sending the ACK).

the callback gets invoked with ( STATUS, SELF, %INFO ) where STATUS is either 'OK' or 'FAIL' ('OK' if the final response meant success, else 'FINAL'), and %INFO contains more info — like ( packet => packet ) for the packet containing the final answer, or ( code => response_code ) in case of failures caused by an unsuccessful response.

  • cb_preliminary — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received a preliminary response on a locally created INVITE.

the callback gets invoked with ( SELF, CODE, RESPONSE ) where CODE is the response code and RESPONSE is the Net::SIP::Response packet.

  • cb_established — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received the final answer on locally created INVITE requests.

the callback gets invoked with ( 'OK', SELF ). periodt. 💅

  • cb_invite — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received an INVITE request.

the callback gets invoked with ( SELF, REQUEST ) where REQUEST is the Net::SIP::Request packet for the INVITE. if it returns a Net::SIP::Packet, that gets used as the response — otherwise a default response with code 200 gets created. easy. 🎀

  • cb_dtmf — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received a DTMF event.

the callback gets invoked with ( EVENT, DURATION ) where EVENT is the event ([0-9A-D*#]) and DURATION is the duration in ms.

receiving DTMF needs to be supported by the active RTP handler set with init_media. all builtin handlers from Net::SIP::Simple::RTP are supported. but if no RTP handler is set up, or if the RTP handler doesn't support DTMF sending, no DTMF will be received — and there's no warning at all. 😭 silent treatment fr fr.
  • cb_notify — a callback usable by invoke_callback in Net::SIP::Util. it gets invoked when it received a NOTIFY request.

the callback gets invoked with ( SELF, REQUEST ) where REQUEST is the Net::SIP::Request packet for the NOTIFY.

  • sip_header — a reference to a hash with extra SIP headers for the INVITE requests. 🌸
  • call_on_hold — this option makes the next SDP have 0.0.0.0 as its address, which puts this side of the call on hold (it will not receive data). it's a one-shot option, bestie — so it needs to be set with set_param or within reinvite each time the call should be put on hold. no set-and-forget here. 🙈
  • ... — more parameters can be specified and they're accessible from the callbacks. for instance, media_send_recv in Net::SIP::Simple::RTP uses a parameter cb_rtp_done. go look over there, iykyk. 👑

💖 METHODS 💖

okay bestie, here's where the actual doing happens. every method, every arg, no skipping, we go 💅

🧹 cleanup

this one gets called to clean up the call. why does that even matter? because callbacks and stuff can create cyclic references, and those bad boys need to be broken or they'll haunt your memory forever 😭. it calls rtp_cleanup too, obviously.

how does it work? it invokes all the callbacks that are stored as \@list in $self->{call_cleanup}. cute, right?

it gets called automatically at a clean end of a call — like on BYE or CANCEL, whether you issued it locally or your peer sent it over 🫶. but if the end is not clean and you wanna destroy the call all messy and unhinged, you gotta call this method manually. no cap.

🧼 rtp_cleanup

cleanup of the current RTP connection ✨. works by invoking all the callbacks stored as \@list in $self->{rtp_cleanup} — and btw those callbacks get inserted by Net::SIP::Simple::RTP and friends. iykyk.

👀 get_peer

returns the peer of the call. that's it, that's the method. for the full lore see peer in Net::SIP::Endpoint::Context.

📨 reinvite ( %ARGS )

creates an INVITE request which either kicks off the initial SDP session or updates an existing SDP session (aka a reinvite, hence the name bestie). %ARGS gets merged with the connection parameter — see the constructor description for that whole situation.

bonus tip from the source: also using resp40x as an auth parameter here would make sense if you want to have full control over the authorization process. main character energy fr.

it sets up a callback for the connection, which will invoke cb_final once the final response for the INVITE was received, and init_media if that response was successful 🔥.

if no cb_final callback was given, it will wait in the event loop until a final response was received. only in this case will it also use the param ring_time, which specifies the time it'll wait for that final response. and if no final response came in within that time? it sends a CANCEL request for this call to close it 🚫. in that case, a callback specified with cb_noanswer will be called after the CANCEL was delivered (or delivery failed).

returns the connection context as a Net::SIP::Endpoint::Context object.

also, for the record: this method is called within invite in Net::SIP::Simple after creating the new Net::SIP::Simple::Call object, to create the first SDP session. changes to the SDP session will be done by calling this method on the Net::SIP::Simple::Call object $self 💜.

❌ cancel ( %ARGS )

closes a pending call by sending a CANCEL request. returns true if the call was pending and could be canceled, false if not, simple as that 🌸.

if %ARGS contains cb_final, it'll be used as a callback and invoked once it gets the response for the CANCEL — and that response might be a response packet or a timeout, so prepare yourself 😭. the rest of %ARGS gets merged with the connection parameter and handed to the cb_final callback as an argument (as a hash reference).

👋 bye ( %ARGS )

closes a call by sending a BYE request. if %ARGS contains cb_final, it'll be used as a callback and invoked once it gets the response for the BYE — again, that could be a response packet or a timeout 🕐. the rest of %ARGS gets merged with the connection parameter and given as an argument to the cb_final callback (as a hash reference). same energy as cancel, different request. slay.

📮 request ( METHOD, BODY, %ARGS )

will create a request with METHOD and BODY, then wait for completion ⏳. if %ARGS contains cb_final, it'll be used as a callback and invoked once it gets the response for the request (or a timeout). the rest of %ARGS will be used to create the request — mostly for the request header, see Net::SIP::Endpoint::new_request for the details bestie.

🔢 dtmf ( EVENTS, %ARGS )

sends DTMF (dial tones 💅) events to the peer according to RFC2833 — like, as RTP events, iconic.

EVENTS is a string with the characters 0-9,A-D,*,#. those will be sent as DTMF. any other characters in the string lead to a pause in sending DTMF. for example, "123--#" will send "1", "2,", "3", then add to pauses, and then send "#" 🎀.

in %ARGS you can specify a duration in ms (default 100ms) and a callback cb_final, which is invoked with first argument 'OK' when all events are sent. if no cb_final callback is given, the method will only return when all events are sent.

you can also overwrite the automatic detection of the DTMF method using methods in %ARGS. default is 'rfc2833,audio'. with 'rfc2833' only, one enforces the use of RTP events — and if the peer does not support it, it will croak 💀. setting it to 'audio' will not fail from the client side, but the peer might not look for DTMF inband data if it expects RTP events. messy, we know.

⚠️ sending DTMF needs to be supported by the active RTP handler set with init_media. all builtin handlers from Net::SIP::Simple::RTP are supported. but if no RTP handler is set up, or if the RTP handler does not support DTMF sending, no DTMF will be received — without any warning. like, silence. nothing. 🙈

📥 receive ( ENDPOINT, CTX, ERROR, CODE, PACKET, LEG, FROM )

this one gets called from the dispatcher on incoming packets 📬. here's the whole cast:

  • ENDPOINT — the Net::SIP::Endpoint object which manages the Net::SIP::Endpoint::Context CTX calling context for the current call.
  • ERROR — an errno describing the error (and 0|undef if there's no error).
  • CODE — the numerical code from the packet, if a response packet was received.
  • PACKET — the incoming packet.
  • LEG — the Net::SIP::Leg where it came in.
  • FROM — the "ip:port" of the sender.

for more details see the documentation to set_callback in Net::SIP::Endpoint::Context 👑

and what does it do with all that? if the incoming packet is a BYE or CANCEL request, it will close the call and invoke the recv_bye callback.

if it's INVITE or ACK, it will make sure that the RTP sockets are set up 🧦. and if it's receiving an ACK to the current call, it will invoke the cb_established callback and also the init_media callback, which cares about setting up the RTP connections (e.g. produce and accept RTP traffic). it's giving setup era ✨.

🎛️ set_param ( %ARGS )

changes params like init_media, sdp_on_ack on the current call. see the constructor for what those are. this is super useful if the call consists of multiple invites with different features — vibe shift mid-call, we love to see it.

🔍 get_param ( @KEYS )

returns values for the parameter @KEYS, the pendant to set_param 🫶. if there's only one key, it'll return the value as a scalar; on multiple keys it returns an array with all the values. depending on how many keys you asked for, bestie.

and that's the whole page 💖✨ you now officially know Net::SIP::Simple::Call better than most people know themselves. go forth and handle those calls, icon 👑🌈

this little manual page is from perl v5.40.1, dated 2025-12-07 — shoutout to the perl crew for keeping the docs alive, mwah 💋

📦 where this page comes from