megaco(3erl)

📦

version 25.3.2.8 · 5 versions

💖 NAME 💖

megaco — Main API of the Megaco application. This is the megaco(3erl) page, Erlang Module Definition edition. Part 1 of 7, bestie, and we are keeping every single fact intact while making it sound like your group chat. 💅

✨ DESCRIPTION ✨

Interface module for the Megaco application.

That's the whole description, no cap — it's the interface module, and it's doing exactly what it says on the tin. ✨

🎀 DATA TYPES 🎀

okay so the type dictionary is huge and iconic, so here's the exact lineup:

megaco_mid() = ip4Address() | ip6Address() |
               domainName() | deviceName() |
               mtpAddress()
ip4Address() = #'IP4Address'{}
ip6Address() = #'IP6Address'{}
domainName() = #'DomainName'{}
deviceName() = pathName()
pathName()   = ia5String(1..64)
mtpAddress() = octetString(2..4)

action_request() = #'ActionRequest'{}
action_reply() = #'ActionReply'{}
error_desc() = #'ErrorDescriptor'{}
transaction_reply() = #'TransactionReply'{}
segment_no() = integer()

resend_indication() = flag | boolean()

property_parm() = #'PropertyParm'{}
property_group() = [property_parm()]
property_groups() = [property_group()]

sdp() = sdp_c() | sdp_o() | sdp_s() | sdp_i() | sdp_u() |
        sdp_e() | sdp_p() | sdp_b() | sdp_z() | sdp_k() |
        sdp_a() | sdp_a_rtpmap() | sdp_a_ptime() |
        sdp_t() | sdp_r() | sdp_m()
sdp_v() = #megaco_sdp_v{} (Protocol version)
sdp_o() = #megaco_sdp_o{} (Owner/creator and session identifier)
sdp_s() = #megaco_sdp_s{} (Session name)
sdp_i() = #megaco_sdp_i{} (Session information)
sdp_u() = #megaco_sdp_u{} (URI of description)
sdp_e() = #megaco_sdp_e{} (Email address)
sdp_p() = #megaco_sdp_p{} (Phone number)
sdp_c() = #megaco_sdp_c{} (Connection information)
sdp_b() = #megaco_sdp_b{} (Bandwidth information)
sdp_k() = #megaco_sdp_k{} (Encryption key)
sdp_a() = #megaco_sdp_a{} (Session attribute)
sdp_a_rtpmap() = #megaco_sdp_a_rtpmap{}
sdp_a_ptime() = #megaco_sdp_a_ptime{}
sdp_a_quality() = #megaco_sdp_a_quality{}
sdp_a_fmtp() = #megaco_sdp_a_fmtp{}
sdp_z() = #megaco_sdp_z{} (Time zone adjustment)
sdp_t() = #megaco_sdp_t{} (Time the session is active)
sdp_r() = #megaco_sdp_r{} (Repeat times)
sdp_m() = #megaco_sdp_m{} (Media name and transport address)
sdp_property_parm() = sdp() | property_parm()
sdp_property_group() = [sdp_property_parm()]
sdp_property_groups() = [sdp_property_group()]

megaco_timer() = infinity | integer() >= 0 | megaco_incr_timer()
megaco_incr_timer() = #megaco_incr_timer{}

The record megaco_incr_timer contains the following fields:

wait_for = integer() >= 0 — the actual timer time. ⏲️
factor = integer() >= 0 — the factor when calculating the new timer time (wait_for).
incr = integer() — the increment value when calculating the new timer time (wait_for). Note that this value can be negative and that a timer restart can therefore lead to a wait_for value of zero! It is up to the user to be aware of the consequences of a wait_for value of zero. 😭
max_retries = infinity | infinity_restartable | integer() >= 0 — the maximum number of repetitions of the timer.

There is a special case for this field. When the max_retries has the value infinity_restartable, it means that the timer is restartable as long as some external event occurs (e.g. receipt of a pending message for instance). But the timer will never be restarted "by itself", i.e. when the timer expires (whatever the timeout time), so does the timer. Whenever the timer is restarted, the timeout time will be calculated in the usual way! Also, as mentioned above, beware the consequences of setting the value to infinity if incr has been set to a negative value. 💀

🫶 EXPORTS 🫶

these are the exports, bestie. signatures stay exactly as they are, vibes are upgraded. 🌈

🌸 `start() -> ok | {error, Reason}`

Types:

Reason = term()

Starts the Megaco application.

Users may either explicitly be registered with megaco:start_user/2 and/or be statically configured by setting the application environment variable 'users' to a list of {UserMid, Config} tuples. See the function megaco:start_user/2 for details. 👑

🌸 `stop() -> ok | {error, Reason}`

Types:

Reason = term()

Stops the Megaco application. bye bestie 👋

🌸 `start_user(UserMid, Config) -> ok | {error, Reason}`

Types:

UserMid = megaco_mid()
Config = [{user_info_item(), user_info_value()}]
Reason = term()

Initial configuration of a user.

Requires the megaco application to be started. A user is either a Media Gateway (MG) or a Media Gateway Controller (MGC). One Erlang node may host many users.

A user is identified by its UserMid, which must be a legal Megaco MID.

Config is a list of {Item, Value} tuples. See megaco:user_info/2 about which items and values that are valid. 🫶

🌸 `stop_user(UserMid) -> ok | {error, Reason}`

Types:

UserMid = megaco_mid()
Reason = term()

Delete the configuration of a user.

Requires that the user does not have any active connection. 🔌

🌸 `user_info(UserMid) -> [{Item, Value}]`

🌸 `user_info(UserMid, Item) -> Value | exit(Reason)`

Types:

Handle = user_info_handle()
UserMid = megaco_mid()
Item = user_info_item()
Value = user_info_value()
Reason = term()

Lookup user information.

The following Items are valid:

connections — lists all active connections for this user. Returns a list of megaco_conn_handle records.
receive_handle — construct a megaco_receive_handle record from user config.
trans_id — current transaction id. A positive integer or the atom undefined_serial (in case no messages has been sent).
min_trans_id — first trans id. A positive integer, defaults to 1.
max_trans_id — last trans id. A positive integer or infinity, defaults to infinity.
request_timer — wait for reply. The timer is cancelled when a reply is received. When a pending message is received, the timer is cancelled and the long_request_timer is started instead (see below). No resends will be performed from this point (since we now know that the other side has received the request). When the timer reaches an intermediate expire, the request is resent and the timer is restarted. When the timer reaches the final expire, either the function megaco:call will return with {error, timeout} or the callback function handle_trans_reply will be called with UserReply = {error, timeout} (if megaco:cast was used). A Megaco Timer (see explanation above), defaults to #megaco_incr_timer{}. 💅
long_request_timer — wait for reply after having received a pending message. When the timer reaches an intermediate expire, the timer is restarted. When a pending message is received, and the long_request_timer is not "on its final leg", the timer will be restarted, and, if long_request_resend = true, the request will be re-sent. A Megaco Timer (see explanation above), defaults to 60 seconds. ⏳
long_request_resend — this option indicates whether the request should be resent until the reply is received, even though a pending message has been received. Normally, after a pending message has been received, the request is not resent (since a pending message is an indication that the request has been received). But since the reply (to the request) can be lost, this behaviour has its values. It is of course pointless to set this value to true unless the long_request_timer (see above) is also set to an incremental timer (#megaco_incr_timer{}). A boolean, defaults to false. 🙈
reply_timer — wait for an ack. When a request is received, some info related to the reply is stored internally (e.g. the binary of the reply). This info will live until either an ack is received or this timer expires. For instance, if the same request is received again (e.g. a request with the same transaction id), the (stored) reply will be (re-)sent automatically by megaco. If the timer is of type #megaco_incr_timer{}, then for each intermediate timeout, the reply will be resent (this is valid until the ack is received or the timer expires). A Megaco Timer (see explanation above), defaults to 30000. 🎀
request_keep_alive_timeout — specifies the timeout time for the request-keep-alive timer. This timer is started when the first reply to an asynchronous request (issued using the megaco:cast/3 function) arrives. As long as this timer is running, replies will be delivered via the handle_trans_reply/4,5 callback function, with their "arrival number" (see UserReply of the handle_trans_reply/4,5 callback function). Replies arriving after the timer has expired, will be delivered using the handle_unexpected_trans/3,4 callback function. The timeout time can have the values: plain | integer() >= 0. 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 is started to handle all replies. When the reply has been received and delivered to the user, the proxy process continue to exist for as long as this option specifies. Any received messages, is passed on to the user via the handle_unexpected_trans callback function. The timeout time is in milliseconds. A value of 0 (zero) means that the proxy process will exit directly after the reply has been delivered. An integer >= 0, defaults to 5000 (= 5 seconds). ⭐
auto_ack — automatic send transaction ack when the transaction reply has been received (see trans_ack below). This is used for three-way-handshake. A 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 will be sent immediately. If trans_ack is true, then ack's will instead be 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). 💅