megaco_udp(3)

💖 megaco_udp — the Erlang Module Definition you're about to be obsessed with 💖

okay so bestie, this is megaco_udp, a page from the Erlang Module Definition collection. It's the interface module for the UDP transport protocol for Megaco/H.248. Yes, we're doing telecom transport today, and yes, we're gonna slay it. 🦋

---

✨ DESCRIPTION ✨

This module contains the public interface to the UDP/IP version transport protocol for Megaco/H.248. That's the whole vibe. It's the front door, it's the bouncer, it's the group chat admin. 💅

---

🎀 DATA TYPES 🎀

counter()

counter() ::
          medGwyGatewayNumInMessages | medGwyGatewayNumInOctets |
          medGwyGatewayNumOutMessages | medGwyGatewayNumOutOctets |
          medGwyGatewayNumErrors.

Defines the different counters handled by this transport. Five of them, fr fr, and each one is a little number that snitches on your traffic. ✨

handle()

-opaque handle()

An opaque data type representing an UDP socket. It's opaque, which means don't peek under the hood, just trust the process. 👑

send_handle()

-opaque send_handle()

An opaque data type representing an UDP socket, used when sending. Same energy as handle(), different job — this one is specifically the sender's lil badge. 🫶

---

🔥 FUNCTIONS 🔥

block(Handle) -> ok

block(Handle) -> ok
    when Handle :: handle() | send_handle().

Stop receiving incoming messages on the socket. Like putting your phone on Do Not Disturb but for packets. 📵

close(Handle) -> ok

close(Handle) -> ok
    when Handle :: handle() | send_handle().

This function is used for closing an active UDP socket. Saying goodbye, closing the door, ending the era. 🚪✨

create_send_handle(Handle, Host, Port) -> send_handle()

create_send_handle(Handle, Host, Port) -> send_handle()
                            when
                                Handle :: handle(),
                                Host ::
                                    inet:ip4_address() |
inet:hostname(),
                                Port :: inet:port_number().

Creates a send handle from a transport handle. The send handle is intended to be used by megaco_udp:send_message/2. Yes, you build the sender from the handle first — it's giving "make the key before you drive the car." 🔑

get_stats() -> {ok, TotalStats} | {error, Reason}

get_stats() -> {ok, TotalStats} | {error, Reason}
                   when
                       TotalStats :: [{SH, [{Counter, integer()}]}],
                       SH :: send_handle(),
                       Counter :: counter(),
                       Reason :: term().

Get all counter values for all known connections. Full transparency, no secrets in this group chat. 👀

get_stats(SH) -> {ok, Stats} | {error, Reason}

get_stats(SH) -> {ok, Stats} | {error, Reason}
                   when
                       SH :: send_handle(),
                       Stats :: [{Counter, integer()}],
                       Counter :: counter(),
                       Reason :: term().

Get all counter values for a given handle. One handle, all its numbers. 💅

get_stats(SH, Counter) -> {ok, integer()} | {error, Reason}

get_stats(SH, Counter) -> {ok, integer()} | {error, Reason}
                   when
                       SH :: send_handle(),
                       Counter :: counter(),
                       Reason :: term().

Get the value of a specific counter. Cherry-picking one single stat, as you should. 🍓

open(TransportRef, Opts) -> {ok, Handle, ControlPid} | {error, Reason}

open(TransportRef, Opts) ->
              {ok, Handle, ControlPid} | {error, Reason}
              when
                  TransportRef :: pid(),
                  Opts ::
                      {inet_backend, default | inet | socket} |
                      {port, PortNum} |
                      {options, list()} |
                      {receive_handle, term()} |
                      {module, atom()},
                  PortNum :: inet:port_number(),
                  Handle :: handle(),
                  ControlPid :: pid(),
                  Reason :: term().

This function is used to open an UDP/IP socket. It's the opening-night moment. 🎬

Now the options, and bestie, listen, these matter:

module

The option makes it possible for the user to provide their own callback module. The functions receive_message/4 or process_received_message/4 of this module is called when a new message is received. Which one depends on the size of the message:

• small
  • receive_message
• large
  • process_received_message

Default value is megaco.

inet_backend

Choose the inet-backend.

This option make it possible to use a different inet-backend ('default', 'inet' or 'socket').

Default is default (system default).

reset_stats() -> megaco:void()

reset_stats() -> megaco:void().

Reset all counters for all UDP handles. Clean slate, new era, clear the chat. 🧼

reset_stats(SH) -> megaco:void()

reset_stats(SH) -> megaco:void()
    when SH :: send_handle().

Reset all counters for the given UDP handle. Just the one. 🎯

send_message(SH, Msg) -> ok

send_message(SH, Msg) -> ok
                      when
                          SH :: send_handle(),
                          Msg :: binary() | iolist().

Sends a message on a socket. The send handle is obtained by megaco_udp:create_send_handle/3. Increments the NumOutMessages and NumOutOctets counters if message successfully sent. In case of a failure to send, the NumErrors counter is not incremented. This is done elsewhere in the megaco app.

not me staring at that last sentence — yes, the error counter does not get bumped here, it happens somewhere else in the megaco app. Don't come for this function about it. 😭

socket(Handle) -> Socket

socket(Handle) -> Socket
                when
                    Handle :: handle() | send_handle(),
                    Socket :: inet:socket().

This function is used to convert a socket handle() to a inet socket(). Glow-up transformation, same soul, new format. 🦋

start_transport() -> {ok, TransportRef}

start_transport() -> {ok, TransportRef}
    when TransportRef :: pid().

This function is used for starting the UDP/IP transport service. Use exit(TransportRef, Reason) to stop the transport service.

the stop button is literally just exit(TransportRef, Reason). that's it. that's the whole off switch. 💀

unblock(Handle) -> ok

unblock(Handle) -> ok
    when Handle :: handle() | send_handle().

Starting to receive incoming messages from the socket again. DND is OFF, we're back, we're receiving, we're thriving. 🔔

upgrade_receive_handle(ControlPid, NewRecvHandle) -> ok

upgrade_receive_handle(ControlPid, NewRecvHandle) -> ok
                                when
                                    ControlPid :: pid(),
                                    NewRecvHandle :: term().

Update the receive handle of the control process (e.g. after having changed protocol version). It's giving "new protocol, new me." ✨

---

👑 SEE ALSO 👑

Nothing else listed here bestie — this page is standing on its own two feet, main character energy only. 💅

---

that's the whole page, no cap.

This one comes to you from Ericsson AB, shipping as part of megaco 4.9.2, and it lives at megaco_udp(3). Thanks for reading, bestie — go open a socket responsibly. 🎀💖🦋✨