megaco(3)

📦

version 29.0.6 · 2 versions

29.0.6 · nixos 26.05, nixpkgs unstable, ubuntu stonking (latest)
28.5.0.8 · alpine 3.24

, in nixos 26.05, nixpkgs unstable, ubuntu stonking

okay bestie, welcome to megaco(3) — that's the Erlang Module Definition, section 3, and it's literally the main API of the Megaco application. we're doing this in seven parts because it's a lot, but we're gonna get through it together. no cap. 💅

✨ NAME ✨

megaco — the main API of the Megaco application. that's it, that's the name. iykyk.

🌸 DESCRIPTION 🌸

Interface module for the Megaco application. it's the plug, the vibe, the whole point. periodt.

🦋 DATA TYPES 🦋

so this type is a basic lookup key — an atom — for info on an active connection. the value can be literally anything. no pressure. 💖

conn_info_item() ::
          control_pid | send_handle | local_mid | remote_mid |
          receive_handle | trans_id | max_trans_id | request_timer |
          long_request_timer | request_keep_alive_timeout |
          long_request_resend | reply_timer | call_proxy_gc_timeout |
          auto_ack | trans_ack | trans_ack_maxcount | trans_req |
          trans_req_maxcount | trans_req_maxsize | trans_timer |
          pending_timer | sent_pending_limit | recv_pending_limit |
          send_mod | encoding_mod | encoding_config | protocol_version |
          strict_version | reply_data | threaded | resend_indication |
          segment_reply_ind | segment_recv_timer | segment_send |
          max_pdu_size.

control_pid — the pid of the process that's controlling a connection. like, the main character of that conn. 👑
- Value type: pid()
send_handle — an opaque send handle — its insides are a secret between the send module and itself. 🤫
- Value type: send_handle/0
local_mid — the local mid — that's the connection's own mid, the one it was born with. 💅
- Value type: mid/0
remote_mid — the remote mid — the other side's mid. the one you're talking to. 📞
- Value type: mid/0
receive_handle — constructs a megaco_receive_handle record. fancy. ✨
- Value type: receive_handle/0
trans_id — the next transaction id. but heads up: transaction ids are (currently) kept per user, so you can't be 100% sure that the value you get back will actually be used for a transaction on this connection — especially if a user has several connections, which is totally not unlikely. 🙈
- Value type: transaction_id/0 | undefined_serial
max_trans_id — the last transaction id. like, the final boss of transaction ids. 🏁
- Value type: transaction_id/0 | infinity
request_timer — wait for reply, bestie. when a reply comes in, the timer gets cancelled. when a pending message arrives, the timer is cancelled and the long_request_timer takes over (see below). no resends from that point because we now know the other side got the request. when the timer hits an intermediate expire, the request is resent and the timer restarts. when it hits the final expire, either megaco:call returns {error, timeout} or the handle_trans_reply callback is called with UserReply = {error, timeout} (if you used megaco:cast).
- Value type: megaco_timer/0
- Defaults to #megaco_incr_timer{}.
long_request_timer — wait for reply after you've already gotten a pending message. when the timer hits an intermediate expire, the timer restarts. when a pending message comes in and the long_request_timer isn't "on its final leg", the timer restarts, and if long_request_resend = true, the request gets re-sent. 🔁
- Value type: megaco_timer/0
- Defaults to 60 seconds.
request_keep_alive_timeout — sets the timeout for the request-keep-alive timer. this timer starts when the first reply to an async request (sent with megaco:cast/3) shows up. while it's running, replies go to the handle_trans_reply/4,5 callback with their "arrival number" (check UserReply in that callback). replies that arrive after the timer expires go to handle_unexpected_trans/3,4 instead. 🕰️
- Value type: plain | non_neg_integer()
- Defaults to plain.
long_request_resend — this option says whether the request should be resent until the reply arrives, even if a pending message was already received. normally, after a pending message, we don't resend (because pending means they got it). but the reply can still get lost, so this behavior has its moments. and like, it's pointless to set this to true unless long_request_timer (see above) is also an incremental timer (#megaco_incr_timer{}). 🤷
- Value type: boolean()
- Defaults to false.
reply_timer — wait for an ack. when a request comes in, some reply info gets stored internally (like the reply binary). that info sticks around until an ack arrives or this timer expires. so if the same request shows up again (same transaction id, say), megaco will automatically (re-)send the stored reply. if the timer is a #megaco_incr_timer{}, then for each intermediate timeout, the reply gets resent (until the ack arrives or the timer expires). 🔄
- Value type: megaco_timer/0
- Defaults to 30000.
call_proxy_gc_timeout — timeout for the call proxy. when you send a request with call/3, a proxy process starts to handle all the replies. after the reply is received and delivered, the proxy hangs around for as long as this option says. any messages it gets go to the user via handle_unexpected_trans. the timeout is in milliseconds. a value of 0 means the proxy exits right after delivering the reply. bye bestie 👋
- Value type: non_neg_integer()
- Defaults to 5000 (= 5 seconds).
auto_ack — automatically send a transaction ack when the transaction reply is received (see trans_ack below). this is for the three-way-handshake. 🤝
- Value type: boolean()
- Defaults to false.
trans_ack — should acks be accumulated or not? this only matters if auto_ack is true. if auto_ack is true and trans_ack is false, acks go out immediately. if trans_ack is true, acks go to the transaction sender process for accumulation and later sending (see trans_ack_maxcount, trans_req_maxcount, trans_req_maxsize, trans_ack_maxcount, and trans_timer). also check out "transaction sender" for more. 📦
- Value type: boolean()
- Defaults to false.
trans_ack_maxcount — max number of accumulated acks. the transaction sender will hold at most this many (if it's started and set to accumulate acks). check "transaction sender" for more. 🔢
- Value type: non_neg_integer()
- Defaults to 10.
trans_req — should requests be accumulated or not? if trans_req is false, requests go out immediately, each in its own message. if trans_req is true, requests go to the transaction sender for accumulation and later sending (see trans_ack_maxcount, trans_req_maxcount, trans_req_maxsize, trans_ack_maxcount, and trans_timer). check "transaction sender" for more. 📨
- Value type: boolean()
- Defaults to false.
trans_req_maxcount — max number of accumulated requests. the transaction sender will hold at most this many (if started and configured to accumulate requests). check "transaction sender" for more. 🗂️
- Value type: non_neg_integer()
- Defaults to 10.
trans_req_maxsize — max size of the accumulated requests. the transaction sender will hold at most this much (if started and configured to accumulate requests). check "transaction sender" for more. 📏
- Value type: non_neg_integer()
- Defaults to 2048.
trans_timer — transaction sender timeout. it does two things. first, if it's 0, transactions are not accumulated (so the transaction sender process isn't even started). second, if it's greater than 0 and either (auto_ack and trans_ack are true) or trans_req is true, the transaction sender starts and transactions get accumulated (depending on auto_ack, trans_ack, and trans_req) for later sending. check "transaction sender" for more. ⏲️
- Value type: non_neg_integer()
- Defaults to 0.
pending_timer — automatically send a transaction pending if the timer expires before a transaction reply is sent. this is also called the provisional response timer. ⏳
- Value type: megaco_timer/0
- Defaults to 30000 (= 30 seconds).
sent_pending_limit — sent pending limit (check the MGOriginatedPendingLimit and MGCOriginatedPendingLimit in the megaco root package). this says how many pending messages can be sent for a given received transaction request. if you go over the limit, the transaction is aborted (see handle_trans_request_abort) and an error message is sent to the other side. note: this does not affect the actual sending of pending transactions. that's either implicit (like when a re-sent transaction request comes in for a request already being processed) or controlled by pending_timer, see above. 🚫

that's part 1, bestie! part 2 is on its way, don't go anywhere 💖

Value type: pos_integer() | infinity

Defaults to infinity.

Okay bestie, that was the tail end of the last field, now let's keep it moving! 💅

recv_pending_limit — Receive pending limit (see the MGOriginatedPendingLimit and the MGCOriginatedPendingLimit of the megaco root package). This parameter specifies how many pending messages that can be received (for a sent transaction request). When the limit is exceeded, the transaction is considered lost, and an error returned to the user (through the call-back function handle_trans_reply). 😭

Value type: pos_integer() | infinity

Defaults to: infinity.

send_mod — Send callback module which exports send_message/2. The function SendMod:send_message(SendHandle, Binary) is invoked when the bytes needs to be transmitted to the remote user. 💌

Value type: module().

Defaults to: megaco_tcp.

encoding_mod — Encoding callback module which exports encode_message/2 and decode_message/2. The function EncodingMod:encode_message(EncodingConfig, MegacoMessage) is invoked whenever a 'MegacoMessage' record needs to be translated into an Erlang binary. The function EncodingMod:decode_message(EncodingConfig, Binary) is invoked whenever an Erlang binary needs to be translated into a 'MegacoMessage' record. ✨

Value type: module().

Defaults to: megaco_pretty_text_encoder.

encoding_config — Encoding module config.

Value type: loist(). (yes, that's spelled loist() in the original, no cap)

Defaults to: [].

protocol_version — Actual protocol version.

Value type: protocol_version/0

Defaults to: 1.

strict_version — Strict version control, i.e. when a message is received, verify that the version is that which was negotiated. 👑

Value type: boolean()

Defaults to: true.

reply_data — Default reply data.

Value type: term()

Defaults to: undefined.

threaded — If a received message contains several transaction requests, this option indicates whether the requests should be handled sequentially in the same process (false), or if each request should be handled by its own process (true i.e. a separate process is spawned for each request). 🧵

Value type: boolean()

Defaults to: false.

resend_indication — This option indicates whether the transport module should be told if a message send is a resend or not.

If false, megaco messages are sent using the send_message/2 function.

If true, megaco message re-sends are made using the resend_message function. The initial message send is still done using the send_message function.

The special value flag instead indicates that the function send_message/3 shall be used. 🚩

Value type: flag | boolean()

Defaults to: false.

segment_reply_ind — This option specifies if the user shall be notified of received segment replies or not.

See handle_segment_reply callback function for more information.

Value type: boolean()

Defaults to: false.

segment_recv_timer — This timer is started when the segment indicated by the segmentation complete token (e.g. the last of the segment which makes up the reply) is received, but all segments has not yet been received. ⏳

When the timer finally expires, a "megaco segments not received" (459) error message is sent to the other side and the user is notified with a segment timeout UserReply in either the handle_trans_reply callback function or the return value of the call/2 function.

Value type: megaco_timer/0

Defaults to: 10000 (= 10 seconds).

segment_send — Shall outgoing messages be segmented or not.

Value type: none | pos_integer() | infinity

none — Do not segment outgoing reply messages. This is useful when either it is known that messages are never too large or that the transport protocol can handle such things on its own (e.g. TCP or SCTP).
pos_integer/0 — Outgoing reply messages will be segmented as needed (see max_pdu_size below). This value, K, indicate the outstanding window, i.e. how many segments can be outstanding (not acknowledged) at any given time.
infinity — Outgoing reply messages will be segmented as needed (see max_pdu_size below). Segment messages are sent all at once (i.e. no acknowledgement awaited before sending the next segment).

Defaults to: none.

max_pdu_size — Max message size. If the encoded message (PDU) exceeds this size, the message should be segmented, and then encoded. 📦

Value type: infinity | pos_integer()

Defaults to: infinity.

And now, bestie, let's get into the type aliases! These are like the little building blocks, iykyk. 💖

counter() — medGwyGatewayNumTimerRecovery | medGwyGatewayNumErrors.
counter_value() — non_neg_integer().
digit_map_event() — megaco_digit_map:event().
digit_map_kind() — megaco_digit_map:kind().
digit_map_letter() — megaco_digit_map:letter().
digit_map_value() — megaco_digit_map:value().
error_desc() — megaco_encoder:error_desc().
global_counter() — medGwyGatewayNumErrors.
megaco_message() — megaco_encoder:megaco_message().
megaco_timer() — megaco_user:megaco_timer().
mid() — The Megaco Identifier. 🆔

mid() ::
          {ip4Address, megaco_encoder:ip4Address()} |
          {ip6Address, megaco_encoder:ip6Address()} |
          {domainName, megaco_encoder:domainName()} |
          {deviceName, megaco_encoder:deviceName()} |
          {mtpAddress, megaco_encoder:mtpAddress()}.

property_group() — megaco_sdp:property_group().
property_groups() — megaco_sdp:property_groups().
property_parm() — megaco_sdp:property_parm().
protocol_version() — megaco_encoder:protocol_version().
receive_handle() — megaco_user:receive_handle().
sdp() — megaco_sdp:sdp().
sdp_property_group() — megaco_sdp:sdp_property_group().
sdp_property_groups() — megaco_sdp:sdp_property_groups().
sdp_property_parm() — megaco_sdp:sdp_property_parm().
segment_no() — megaco_encoder:segment_no().
send_handle() — Opaque send handle whose contents is internal for the send module. May be any term.

Value type: term().

system_info_item() — System info items. 🛠️

system_info_item() ::
          text_config | connections | users | n_active_requests |
          n_active_replies | n_active_connections | reply_counters |
          pending_counters.

text_config — The text encoding config.

Value type: term()

connections — Lists all active connections. Returns a list of megaco_conn_handle records.

Value type: [conn_handle/0]

users — Lists all active users.

Value type: [mid/0]

n_active_requests — Returns number of requests that has originated from this Erlang node and still are active (and therefore consumes system resources).

Value type: non_neg_integer()

n_active_replies — Returns the number of replies that has originated from this Erlang node and still are active (and therefore consumes system resources).

Value type: non_neg_integer()

n_active_connections — Returns the number of active connections.

Value type: non_neg_integer()

reply_counters — Returns a list of the reply counters.

Value type: {conn_handle/0, transaction_id/0, [non_neg_integer()]}

pending_counters — Returns a list of the receive and sent pending counters.

Value type: {recv | sent, [{transaction_id/0, [non_neg_integer()]}]}

trace_data() — The trace data passed to the trace handler fun (in the second argument) and returned by same. For instance this could be a file descriptor, that the trace handler fun can use to print the event to a file. 📝

Value type: term().

trace_event() — The trace event generated by dbg.

Value type: term().

trace_handler() — The trace handler fun is used to "process" each trace event (for instance print to file or to stdout after formating). 🎀

trace_handler() ::
          fun((trace_event(), trace_data()) -> trace_data()).

trace_level() — How much trace events should be produced. min (=0) means no trace events are produced, which is the default.

Value type: min | max | 0..100.

transaction_id() — pos_integer().
transaction_reply() — megaco_encoder:transaction_reply().
user_info_item() —

user_info_item() ::
          connections | receive_handle | trans_id | min_trans_id |
          max_trans_id | request_timer | long_request_timer |
          long_request_resend | reply_timer |
          request_keep_alive_timeout | call_proxy_gc_timeout |
          auto_ack | trans_ack | trans_ack_maxcount | trans_req |
          trans_req_maxcount | trans_req_maxsize | trans_timer |
          pending_timer | sent_pending_limit | recv_pending_limit |
          send_mod | encoding_mod | encoding_config | protocol_version |
          strict_version | reply_data | user_mod | user_args |
          threaded | resend_indication | segment_reply_ind |
          segment_recv_timer | segment_send | max_pdu_size.

connections — Lists all active connections for this user. Returns a list of megaco_conn_handle records.

Value type: [conn_handle/0]

receive_handle — Construct a receive_handle from user config.

Value type: receive_handle/0

trans_id — Current transaction id.

Value type: transaction_id/0 | undefined_serial

min_trans_id — First transaction id.

Value type: transaction_id/0

Defaults to: 1.

max_trans_id — Last transaction id.

Value type: transaction_id/0 | infinity

Defaults to: infinity.

request_timer — Wait for reply.

The timer is cancelled when a reply is received.

When a pending message comes in, the timer gets cancelled and long_request_timer takes over instead (peep below 👇). From that point on there are no resends, periodt — because now we know the other side got the request. 🫶

When the timer hits an intermediate expire, the request gets resent and the timer restarts. 🔁

When the timer hits the final expire, it's one of two things: either megaco:call returns with {error, timeout}, or the callback function handle_trans_reply gets called with UserReply = {error, timeout} (that's the case if you used megaco:cast). 💀

Value type: megaco_timer/0

Defaults to #megaco_incr_timer{}.

long_request_timer — The wait-for-reply clock after you've already received a pending message. 🕰️

When the timer reaches an intermediate expire, the timer is simply restarted.

When a pending message arrives and the long_request_timer is not "on its final leg", the timer restarts, and, if long_request_resend = true, the request gets re-sent. ✨

Value type: megaco_timer/0

Defaults to 60000 (= 60 seconds).

long_request_resend — Whether the request should be re-sent until the reply shows up, even though a pending message already landed. 👀

Normally, once a pending message has been received, the request is not resent (because a pending message is basically the other side saying "yeah I got it"). But since the reply (to that request) can totally get lost, this behaviour does have its values.

It is of course pointless to set this value to true unless long_request_timer (see above) is also set to an incremental timer (#megaco_incr_timer{}).

Value type: boolean()

Defaults to false.

reply_timer — Wait for an ack. 🤝

When a request comes in, some info related to the reply is stored internally (e.g. the binary of the reply). This info lives until either an ack is received or this timer expires. So for instance, if the same request shows up again (e.g. a request with the same transaction id), the (stored) reply gets (re-)sent automatically by megaco. no cap.

If the timer is of type #megaco_incr_timer{}, then for every intermediate timeout, the reply gets resent (this holds until the ack is received or the timer expires).

Value type: megaco_timer/0

Defaults to 30 seconds.

request_keep_alive_timeout — The timeout time for the request-keep-alive timer. 💖

This timer kicks off when the first reply to an asynchronous request (one issued with the megaco:cast/3 function) arrives. As long as this timer is running, replies get delivered via the handle_trans_reply/4,5 callback function, together with their "arrival number" (see UserReply of the handle_trans_reply/4,5 callback function).

Replies that show up after the timer has expired get delivered using the handle_unexpected_trans/3,4 callback function instead. 😭

Value type: plain | non_neg_integer()

Defaults to plain.

call_proxy_gc_timeout — Timeout time for the call proxy. 🧹

When a request is sent using the call/3 function, a proxy process starts up to handle all the replies. Once the reply has been received and delivered to the user, that proxy process keeps existing for as long as this option says. Any messages it receives in that window get passed on to the user via the handle_unexpected_trans callback function.

The timeout time is in milliseconds. A value of 0 (zero) means the proxy process exits directly right after the reply has been delivered.

Value type: pos_integer()

Defaults to 5000 (= 5 seconds).

auto_ack — Automatic send transaction ack once the transaction reply has been received (see trans_ack below). 🎀

This is what's used for the three-way-handshake.

Value type: boolean()

Defaults to false.

trans_ack — Shall ack's be accumulated or not. 🤔

This property is only valid if auto_ack is true.

If auto_ack is true, then if trans_ack is false, ack's get sent immediately. If trans_ack is true, then ack's instead get sent to the transaction sender process for accumulation and later sending (see trans_ack_maxcount, trans_req_maxcount, trans_req_maxsize, trans_ack_maxcount and trans_timer).