RFC 3015
Megaco Protocol Version 1.0
🎀 RFC 3015: Megaco Protocol Version 1.0 🎀
okay bestie, let's start with the basics 💅 this is RFC 3015, called Megaco Protocol Version 1.0, and it's a Standards Track doc from November 2000 🦋 it was written in the Network Working Group, and it obsoletes RFC 2885 and RFC 2886, so those older versions are now replaced 🫶
the squad behind it:
- F. Cuervo, N. Greene, and A. Rayhan from Nortel Networks 💖
- C. Huitema from Microsoft Corporation 💜
- B. Rosen from Marconi 🌸
- J. Segers from Lucent Technologies ✨
they're a whole team of networking legends, no cap 👑
Status of This Memo ✨
okay so this doc is an Internet standards track protocol for the whole Internet community, and it's literally asking people to talk about it and suggest improvements 🗣️ if you want the official standardization state and status of this protocol, check the current edition of "Internet Official Protocol Standards" (STD 1) 📚 and yes, distribution of this memo is unlimited 🌈
Copyright Notice
copyright belongs to The Internet Society (2000), and all rights are reserved 🔒
Abstract
so the main idea 🧚 this document defines the protocol that elements use to talk to each other in a physically decomposed multimedia gateway. that means a Media Gateway and a Media Gateway Controller 🎧
it's common text with ITU-T Recommendation H.248, and it came from applying the changes in RFC 2886 to the text of RFC 2885 💅
and the protocol in here meets the requirements for a media gateway control protocol as laid out in RFC 2805 🍓 iconic, honestly 😭
Table of Contents 🧚
1. SCOPE........................................................ 6
2. REFERENCES................................................... 6
2.1 Normative references................................... 6
2.2 Informative references................................. 9
3. DEFINITIONS.................................................. 10
4. ABBREVIATIONS................................................ 11
5. CONVENTIONS.................................................. 11
6. CONNECTION MODEL............................................. 11
6.1 Contexts............................................... 14
6.1.1 Context Attributes and Descriptors........... 15
6.1.2 Creating, Deleting and Modifying Contexts.... 15
6.2 Terminations........................................... 15
6.2.1 Termination Dynamics......................... 16
6.2.2 TerminationIDs............................... 17
6.2.3 Packages..................................... 17
6.2.4 Termination Properties and Descriptors....... 18
6.2.5 Root Termination............................. 21
7. COMMANDS..................................................... 21
7.1 Descriptors............................................ 22
7.1.1 Specifying Parameters........................ 22
7.1.2 Modem Descriptor............................. 23
7.1.3 Multiplex Descriptor......................... 23
7.1.4 Media Descriptor............................. 24
7.1.5 Termination State Descriptor................. 24
7.1.6 Stream Descriptor............................ 25
7.1.7 LocalControl Descriptor...................... 26
7.1.8 Local and Remote Descriptors................. 27
7.1.9 Events Descriptor............................ 30
7.1.10 EventBuffer Descriptor...................... 32
7.1.11 Signals Descriptor.......................... 32
7.1.12 Audit Descriptor............................ 34
7.1.13 ServiceChange Descriptor.................... 35
7.1.14 DigitMap Descriptor......................... 36
7.1.15 Statistics Descriptor....................... 41
7.1.16 Packages Descriptor......................... 41
7.1.17 ObservedEvents Descriptor................... 42
7.1.18 Topology Descriptor........................ 42
7.2 Command Application Programming Interface.............. 45
7.2.1 Add.......................................... 46
7.2.2 Modify....................................... 47
7.2.3 Subtract..................................... 48
7.2.4 Move......................................... 49
7.2.5 AuditValue................................... 50
7.2.6 AuditCapabilities............................ 52
7.2.7 Notify....................................... 53
7.2.8 ServiceChange................................ 54
7.2.9 Manipulating and Auditing Context Attributes. 58
7.2.10 Generic Command Syntax...................... 58
7.3 Command Error Codes.................................... 58
8. TRANSACTIONS................................................. 60
8.1 Common Parameters...................................... 62
8.1.1 Transaction Identifiers...................... 62
8.1.2 Context Identifiers.......................... 62
8.2 Transaction Application Programming Interface.......... 63
8.2.1 TransactionRequest........................... 63
8.2.2 TransactionReply............................. 63
8.2.3 TransactionPending........................... 65
8.3 Messages............................................... 65
9. TRANSPORT.................................................... 65
9.1 Ordering of Commands................................... 66
9.2 Protection against Restart Avalanche................... 67
10. SECURITY CONSIDERATIONS..................................... 68
10.1 Protection of Protocol Connections.................... 68
10.2 Interim AH scheme..................................... 69
10.3 Protection of Media Connections....................... 70
11. MG-MGC CONTROL INTERFACE................................... 71
11.1 Multiple Virtual MGs.................................. 71
11.2 Cold Start............................................ 72
11.3 Negotiation of Protocol Version....................... 72
11.4 Failure of an MG...................................... 73
11.5 Failure of an MGC..................................... 74
12. PACKAGE DEFINITION.......................................... 75
12.1 Guidelines for defining packages...................... 75
12.1.1 Package..................................... 76
12.1.2 Properties.................................. 76
12.1.3 Events...................................... 77
12.1.4 Signals..................................... 77
12.1.5 Statistics.................................. 77
12.1.6 Procedures.................................. 78
12.2 Guidelines to defining Properties, Statistics and
Parameters to Events and Signals........................... 78
12.3 Lists................................................. 78
12.4 Identifiers........................................... 78
12.5 Package Registration.................................. 79
13. IANA CONSIDERATIONS........................................ 79
13.1 Packages.............................................. 79
13.2 Error Codes........................................... 79
13.3 ServiceChange Reasons................................. 80
ANNEX A: BINARY ENCODING OF THE PROTOCOL (NORMATIVE)............ 80
A.1 Coding of wildcards.................................... 81
A.2 ASN.1 syntax specification............................. 82
A.3 Digit maps and path names.............................. 99
ANNEX B TEXT ENCODING OF THE PROTOCOL (NORMATIVE)...............100
B.1 Coding of wildcards....................................100
B.2 ABNF specification.....................................100
ANNEX C TAGS FOR MEDIA STREAM PROPERTIES (NORMATIVE)............112
C.1 General Media Attributes...............................113
C.2 Mux Properties.........................................114
C.3 General bearer properties..............................115
C.4 General ATM properties.................................115
C.5 Frame Relay............................................118
C.6 IP.....................................................118
C.7 ATM AAL2...............................................119
C.8 ATM AAL1...............................................120
C.9 Bearer Capabilities....................................121
C.10 AAL5 Properties.......................................129
C.11 SDP Equivalents.......................................130
C.12 H.245.................................................131
ANNEX D TRANSPORT OVER IP (NORMATIVE)...........................131
D.1 Transport over IP/UDP using Application Level Framing..131
D.1.1 Providing At-Most-Once Functionality.........132
D.1.2 Transaction identifiers and three-way handshake
...................................................132
D.1.3 Computing retransmission timers..............133
D.1.4 Provisional responses........................134
D.1.5 Repeating Requests, Responses and
Acknowledgements...................................135
D.2 Using TCP..............................................136
D.2.1 Providing the At-Most-Once functionality.....137
D.2.2 Transaction identifiers and three way handshake
...................................................137
D.2.3 Computing retransmission timers..............137
D.2.4 Provisional responses........................137
D.2.5 Ordering of commands.........................138
ANNEX E BASIC PACKAGES (NORMATIVE)..............................138
E.1 Generic................................................138
E.1.1 Properties...................................138
E.1.2 Events.......................................138
E.1.3 Signals......................................140
E.1.4 Statistics...................................140
E.2 Base Root Package......................................140
E.2.1 Properties...................................140
E.2.2 Events.......................................142
E.2.3 Signals......................................142
E.2.4 Statistics...................................142
E.2.5 Procedures...................................142
E.3 Tone Generator Package.................................142
E.3.1 Properties...................................142
E.3.2 Events.......................................143
E.3.3 Signals......................................143
E.3.4 Statistics...................................143
E.3.5 Procedures...................................143 E.4 Tone Detection Package.................................144
E.4.1 Properties...................................144
E.4.2 Events.......................................144
E.4.3 Signals......................................146
E.4.4 Statistics...................................146
E.4.5 Procedures...................................146
E.5 Basic DTMF Generator Package...........................147
E.5.1 Properties...................................147
E.5.2 Events.......................................147
E.5.3 Signals......................................147
E.5.4 Statistics...................................148
E.5.5 Procedures...................................148
E.6 DTMF detection Package.................................148
E.6.1 Properties...................................149
E.6.2 Events.......................................149
E.6.3 Signals......................................150
E.6.4 Statistics...................................150
E.6.5 Procedures...................................150
E.7 Call Progress Tones Generator Package..................151
E.7.1 Properties...................................151
E.7.2 Events.......................................151
E.7.3 Signals......................................151
E.7.4 Statistics...................................152
E.7.5 Procedures...................................152
E.8 Call Progress Tones Detection Package..................152
E.8.1 Properties...................................152
E.8.2 Events.......................................153
E.8.3 Signals......................................153
E.8.4 Statistics...................................153
E.8.5 Procedures...................................153
E.9 Analog Line Supervision Package........................153
E.9.1 Properties...................................153
E.9.2 Events.......................................153
E.9.3 Signals......................................156
E.9.4 Statistics...................................157
E.9.5 Procedures...................................157
E.9.6 Error Code...................................157
E.10 Basic Continuity Package..............................157
E.10.1 Properties..................................157
E.10.2 Events......................................157
E.10.3 Signals.....................................158
E.10.4 Statistics..................................158
E.10.5 Procedures..................................159
E.11 Network Package.......................................159
E.11.1 Properties..................................159
E.11.2 Events......................................160
E.11.3 Signals.....................................161
E.11.4 Statistics..................................161
E.11.5 Procedures..................................162
E.12 RTP Package..........................................162
E.12.1 Properties..................................162
E.12.2 Events......................................162
E.12.3 Signals.....................................163
E.12.4 Statistics..................................163
E.12.5 Procedures..................................164
E.13 TDM Circuit Package...................................164
E.13.1 Properties..................................164
E.13.2 Events......................................165
E.13.3 Signals.....................................165
E.13.4 Statistics..................................165
E.13.5 Procedures..................................165
APPENDIX A EXAMPLE CALL FLOWS (INFORMATIVE).....................166
A.1 Residential Gateway to Residential Gateway Call........166
A.1.1 Programming Residential GW Analog Line
Terminations for Idle Behavior.....................166
A.1.2 Collecting Originator Digits and Initiating
Termination........................................168
AUTHORS ADDRESS.................................................178
FULL COPYRIGHT STATEMENT........................................1791. SCOPE ✨
Okay bestie, so this document is all about the protocol that gets used between the pieces of a physically decomposed multimedia gateway 🎀. The sub-components can be spread across more than one physical device, and from a system point of view that's literally no different from a monolithic gateway like the one described in H.246 💅. Iconic, right?
Now, what this doc does not do is explain how gateways, multipoint control units or interactive voice response units (IVRs) work 🙈. Instead it sets up a general framework that's suitable for all of these applications, so it's giving flexible and reusable ✨.
Packet network interfaces may include IP, ATM or possibly others 🌈. On the SCN side, the interfaces will support a variety of signalling systems, including tone signalling, ISDN, ISUP, QSIG, and GSM 📞. National variants of these signalling systems will be supported where applicable 🌸.
The protocol definition in this document is common text with ITU-T Recommendation H.248 🦋. It also meets the requirements documented in RFC 2805 💜.
2. REFERENCES 🧚
2.1 Normative references
ATM Forum (1994): "User-Network Interface, Version 4.0".
ITU-T Recommendation H.225.0: "Call Signalling Protocols and Media Stream Packetization for Packet Based Multimedia Communications Systems".
ITU-T Recommendation H.235: "Security and encryption for H-Series (H.323 and other H.245-based) multimedia terminals".
ITU-T Recommendation H.245: "Control Protocol for Multimedia Communication".
ITU-T Recommendation H.323: "Packet Based Multimedia Communication Systems".
ITU-T Recommendation I.363.1, "B-ISDN ATM Adaptation Layer specification: Type 1 AAL".
ITU-T Recommendation I.363.2, "B-ISDN ATM Adaptation Layer specification: Type 2 AAL".
ITU-T Recommendation I.363.5, "B-ISDN ATM Adaptation Layer specification: Type 5 AAL".
ITU-T Recommendation I.363.5, "B-ISDN ATM Adaptation Layer specification: Type 5 AAL".
ITU-T Recommendation I.366.1, "Segmentation and Reassembly Service Specific Convergence Sublayer for the AAL type 2".
ITU-T Recommendation I.366.2, "AAL type 2 service specific convergence sublayer for trunking".
ITU-T Recommendation I.371, "Traffic control and congestion control in B-ISDN".
ITU-T Recommendation Q.763, "Signalling System No. 7 - ISDN user part formats and codes".
ITU-T Recommendation Q.765, "Signalling System No. 7 - Application transport mechanism".
ITU-T Recommendation Q.931: "Digital Subscriber Signalling System No. 1 (DSS 1) - ISDN User-Network Interface Layer 3 Specification for Basic Call Control".
ITU-T Recommendation Q.2630.1, "AAL Type 2 Signalling Protocol (Capability Set 1)".
ITU-T Recommendation Q.2931, "Broadband Integrated Services Digital Network (B-ISDN) - Digital Subscriber Signalling System No. 2 (DSS 2) - User-Network Interface (UNI) - Layer 3 specification for basic call/connection control".
ITU-T Recommendation Q.2941.1, "Digital Subscriber Signalling System No. 2 - Generic Identifier Transport".
ITU-T Recommendation Q.2961, "Broadband integrated services digital network (B-ISDN) - Digital subscriber signalling system no.2 (DSS 2) - additional traffic parameters".
ITU-T Recommendation Q.2965.1, "Digital subscriber signalling system No. 2 _ Support of Quality of Service classes."
ITU-T Recommendation Q.2965.2, "Digital subscriber signalling system No. 2 _ Signalling of individual Quality of Service parameters."
ITU-T Recommendation Q.2961.2, "Digital subscriber signalling system No. 2 - Additional traffic parameters: Support of ATM transfer capability in the broadband bearer capability information element."
ITU-T Recommendation X.213, "Information technology - Open System Interconnection - Network service definition plus Amendment 1 (08/1997), Addition of the Internet protocol address format identifier".
ITU-T Recommendation V.76 (08/96), "Generic multiplexer using V.42 LAPM-based procedures".
ITU-T Recommendation X.680 (1997): "Information technology-Abstract Syntax Notation One (ASN.1): Specification of basic notation".
ITU-T Recommendation H.246 (1998), "Interworking of H-series multimedia terminals with H-series multimedia terminals and voice/voiceband terminals on GSTN and ISDN".
Rose, M. and D. Cass, "ISO Transport Service on top of the TCP, Version 3", RFC 1006, May 1987.
Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.
Handley, M. and V. Jacobson, "SDP: Session Description Protocol", RFC 2327, April 1998.
Kent, S. and R. Atkinson, "IP Authentication Header", RFC 2402, November 1998.
Kent, S. and R. Atkinson, "IP Encapsulating Security Payload (ESP)", RFC 2406, November 1998.
2.2 Informative references
ITU-T Recommendation E.180/Q.35 (1998): "Technical characteristics of tones for the telephone service".
CCITT Recommendation G.711 (1988), "Pulse Code Modulation (PCM) of voice frequencies".
ITU-T Recommendation H.221 (05/99), "Frame structure for a 64 to 1920 kbit/s channel in audiovisual teleservices".
ITU-T Recommendation H.223 (1996), "Multiplexing protocol for low bit rate multimedia communication".
Postel, J., "User Datagram Protocol", RFC 768, August 1980.
Postel, J., "Internet protocol", RFC 791, September 1981.
Postel, J., "TRANSMISSION CONTROL PROTOCOL", RFC 793, September 1981.
Simpson, W., "The Point-to-Point Protocol", RFC 1661, July 1994.
Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobson, "RTP: A Transport Protocol for Real-Time Applications", RFC 1889, January 1996.
Schulzrinne, H., "RTP Profile for Audio and Video Audio and Video Conferences with Minimal Control", RFC 1890, January 1996.
Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.
Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", RFC 2460, December 1998.
Handley, M., Schulzrinne, H., Schooler, E. and J. Rosenberg, "SIP: Session Initiation Protocol", RFC 2543, March 1999.
Greene, N., Ramalho, M. and B. Rosen, "Media Gateway control protocol architecture and requirements", RFC 2805, April 1999.
3. DEFINITIONS ✨
okay so before we dive into the connection model, we need the vocab 💅 these are the terms the whole doc leans on, so let's get them straight bestie 🫶
Access Gateway: a type of gateway that gives you a User to Network Interface (UNI) like ISDN 🔌
Descriptor: a syntactic element of the protocol that groups related properties 🎀 like, the properties of a media flow on the MG can be set by the MGC by slapping the right descriptor into a command. iconic 💜
Media Gateway (MG): the media gateway converts media from one type of network into the format another type of network needs 🦋 for example, a MG could terminate bearer channels from a switched circuit network (think DS0s) and media streams from a packet network (think RTP streams in an IP network) 🌊 it may handle audio, video and T.120 alone or in any combo, and it WILL be capable of full duplex media translations 😭 it can also play audio/video messages and do other IVR functions, or do media conferencing 🎧
Media Gateway Controller (MGC): controls the parts of the call state that pertain to connection control for media channels in a MG 🧚
Multipoint Control Unit (MCU): an entity that controls the setup and coordination of a multi-user conference, usually including processing of audio, video and data 🌈
Residential Gateway: a gateway that interworks an analogue line to a packet network 🏠 it typically has one or two analogue lines and lives at the customer premises 🍓
SCN FAS Signalling Gateway: this function holds the SCN Signalling Interface that terminates SS7, ISDN or other signalling links where the call control channel and bearer channels are collocated in the same physical span 🫧
SCN NFAS Signalling Gateway: this function holds the SCN Signalling Interface that terminates SS7 or other signalling links where the call control channels are separated from bearer channels 🙈
Stream: bidirectional media or control flow received or sent by a media gateway as part of a call or conference 🎶
Trunk: a communication channel between two switching systems, like a DS0 on a T1 or E1 line ☎️
Trunking Gateway: a gateway between an SCN network and a packet network that typically terminates a large number of digital circuits 🏢
4. ABBREVIATIONS 💖
okay this part is giving cheat sheet 📝 this recommendation defines the following terms (no cap, these are the acronyms you'll see everywhere):
ATM Asynchronous Transfer Mode
CAS Channel Associated Signalling
DTMF Dual Tone Multi-Frequency
FAS Facility Associated Signalling
GSM Global System for Mobile communications
GW GateWay
IANA Internet Assigned Numbers Authority
IP Internet Protocol
ISUP ISDN User Part
IVR Interactive Voice Response
MG Media Gateway
MGC Media Gateway Controller
NFAS Non-Facility Associated Signalling
PRI Primary Rate Interface
PSTN Public Switched Telephone Network
QoS Quality of Service
RTP Real-time Transport Protocol
SCN Switched Circuit Network
SG Signalling Gateway
SS7 Signalling System No. 75. CONVENTIONS 🌸
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119. the rules of the road, bestie 📜✨
6. CONNECTION MODEL 🦋
okay this is the main event, so get comfy 🛋️ the connection model describes the logical entities, or objects, inside the Media Gateway that the Media Gateway Controller can control 🎮 the two big abstractions here are Terminations and Contexts 💜
a Termination sources and/or sinks one or more streams 🌊 in a multimedia conference, a Termination can be multimedia and source or sink multiple media streams 🎥 the media stream parameters, plus modem and bearer parameters, are all encapsulated within the Termination 📦
+------------------------------------------------------+
|Media Gateway |
| +-------------------------------------------------+ |
| |Context +-------------+ | |
| | | Termination | | |
| | |-------------| | |
| | +-------------+ +->| SCN Bearer |<---+->
| | | Termination | +-----+ | | Channel | | |
| | |-------------| | |---+ +-------------+ | |
<-+--->| RTP Stream |---| * | | |
| | | | | |---+ +-------------+ | |
| | +-------------+ +-----+ | | Termination | | |
| | | |-------------| | |
| | +->| SCN Bearer |<---+->
| | | Channel | | |
| | +-------------+ | |
| +-------------------------------------------------+ |
| |
| |
| +------------------------------+ |
| |Context | |
| +-------------+ | +-------------+ | |
| | Termination | | +-----+ | Termination | | |
| |-------------| | | | |-------------| | |
<-+->| SCN Bearer | | | * |------| SCN Bearer |<---+->
| | Channel | | | | | Channel | | |
| +-------------+ | +-----+ +-------------+ | |
| +------------------------------+ |
| |
| |
| +-------------------------------------------------+ |
| |Context | |
| | +-------------+ +-------------+ | |
| | | Termination | +-----+ | Termination | | |
| | |-------------| | | |-------------| | |
<-+--->| SCN Bearer |---| * |------| SCN Bearer |<---+->
| | | Channel | | | | Channel | | |
| | +-------------+ +-----+ +-------------+ | |
| +-------------------------------------------------+ |
| ___________________________________________________ |
+------------------------------------------------------+
Figure 1: Example of H.248 Connection Modelso a Context is basically an association between a collection of Terminations 🫶 there's also a special one called the null Context, which holds every Termination that isn't associated with any other Termination 🌙 like, in a decomposed access gateway, all the idle lines are Terminations sitting in the null Context 😴
Figure 1 above is a visual of all this 🖼️ and the diagram gives a few examples, it's NOT meant to be an all-inclusive illustration 🙅♀️ the asterisk box in each Context stands for the logical association of Terminations that the Context implies ⭐
now the example below shows one way to pull off a call-waiting scenario in a decomposed access gateway 📞 it shows a Termination getting relocated between Contexts, which is literally the whole plot 🎬 Terminations T1 and T2 are in Context C1 on a two-way audio call 🎧 a second audio call is waiting for T1 from Termination T3, and T3 is alone in Context C2 🧍♀️ T1 accepts the call from T3 and places T2 on hold ⏸️ this action results in T1 moving into Context C2, as shown below 🦋
+------------------------------------------------------+
|Media Gateway |
| +-------------------------------------------------+ |
| |Context C1 | |
| | +-------------+ +-------------+ | |
| | | Term. T2 | +-----+ | Term. T1 | | |
| | |-------------| | | |-------------| | |
<-+--->| RTP Stream |---| * |------| SCN Bearer |<---+->
| | | | | | | Channel | | |
| | +-------------+ +-----+ +-------------+ | |
| +-------------------------------------------------+ |
| |
| +-------------------------------------------------+ |
| |Context C2 | |
| | +-------------+ | |
| | +-----+ | Term. T3 | | |
| | | | |-------------| | |
| | | * |------| SCN Bearer |<---+->
| | | | | Channel | | |
| | +-----+ +-------------+ | |
| +-------------------------------------------------+ |
+------------------------------------------------------+
Figure 2: Example Call Waiting Scenario / Alerting Applied to T1
+------------------------------------------------------+
|Media Gateway |
| +-------------------------------------------------+ |
| |Context C1 | |
| | +-------------+ | |
| | | Term. T2 | +-----+ | |
| | |-------------| | | | |
<-+--->| RTP Stream |---| * | | |
| | | | | | | |
| | +-------------+ +-----+ | |
| +-------------------------------------------------+ |
| |
| +-------------------------------------------------+ |
| |Context C2 | |
| | +-------------+ +-------------+ | |
| | | Term. T1 | +-----+ | Term. T3 | | |
| | |-------------| | | |-------------| | |
<-+--->| SCN Bearer |---| * |------| SCN Bearer |<---+->
| | | Channel | | | | Channel | | |
| | +-------------+ +-----+ +-------------+ | |
| +-------------------------------------------------+ |
+------------------------------------------------------+
Figure 3. Example Call Waiting Scenario / Answer by T16.1 Contexts 💖
okay so a Context is basically a group chat for Terminations 💬 it's an association between a bunch of Terminations, and it describes the topology (who hears/sees whom) and, if there are more than two Terminations in the mix, the media mixing and/or switching parameters too. main character energy 👑
there's also a super special one called the null Context 🧚. it holds Terminations that aren't hooked up to any other Termination. the vibe is that Terminations in the null Context can still have their parameters checked or changed, and they can have events detected on them. lowkey iconic ✨
generally speaking, an Add command is what puts Terminations into Contexts 🎀. if the MGC doesn't name a Context that already exists for the Termination to join, the MG makes a brand new one 🌸. a Termination can get kicked out of a Context with a Subtract command, or be moved from one Context to another with a Move command 🦋. the big rule here: a Termination SHALL exist in only one Context at a time. no double-dipping, bestie 🙅♀️
the max number of Terminations in a Context is a MG property 💅. media gateways that only do point-to-point might allow at most two Terminations per Context, while gateways that support multipoint conferences might allow three or more. it's giving "we fit as many as the party needs" 🎉
6.1.1 Context Attributes and Descriptors
okay so the attributes of Contexts are:
- ContextID 🆔
- the topology (who hears/sees whom). this describes the flow of media between the Terminations inside a Context 🌊. the mode of a Termination (
send/receive/_) is different, because that one describes the flow of media at the ingress/egress of the media gateway. not the same thing, iykyk 🙈 - the priority, which gives the MG info about how to handle precedence for a context ⭐. the MGC can also use priority to autonomously control traffic precedence in the MG in a smooth way in certain situations (for example a restart), when a ton of contexts need handling at the same time 🔥
- an indicator for an emergency call, so the MG can give it preferred handling 🚨💜
6.1.2 Creating, Deleting and Modifying Contexts
the protocol can (implicitly) create Contexts and modify the parameter values of existing ones 🪄. it also has commands to add Terminations to Contexts, subtract them, and move Terminations between Contexts 🫶. the cute part is that Contexts get deleted implicitly once the last remaining Termination is subtracted or moved out 💀 no cleanup needed, it just vanishes 🍓
6.2 Terminations 🦋
a Termination is a logical entity on a MG that sources and/or sinks media and/or control streams 🎧. it's described by a bunch of characterizing Properties, which are grouped into Descriptors that get included in commands 📦. every Termination has a unique identity (a TerminationID), and the MG assigns those when the Termination gets created 🪪
some Terminations represent physical entities, and those have a semi-permanent existence ⏳. like, a Termination representing a TDM channel might exist for as long as it's provisioned in the gateway. the ephemeral ones, like RTP flows, usually only exist for as long as they're being used 🌬️
ephemeral Terminations are created with an Add command and destroyed with a Subtract command 💫. physical Terminations are different: when one is Added to or Subtracted from a Context, it's taken from or returned to the null Context, respectively 🧚
Terminations can have signals applied to them 🔔. signals are MG-generated media streams like tones and announcements, plus line signals like hookswitch. Terminations can also be programmed to detect Events, and when those happen they can trigger notification messages to the MGC or action by the MG 🚨. statistics can be accumulated on a Termination too 📊. they get reported to the MGC when requested (using the AuditValue command, see section 7.2.5) and also when the Termination is taken out of the call it's in 📞
now the multiplexing situation is a whole thing 🧵. multimedia gateways may process multiplexed media streams. for example, Recommendation H.221 describes a frame structure for multiple media streams multiplexed on a bunch of digital 64 kbit/s channels 🎞️. here's how the connection model handles it: for every bearer channel carrying part of the multiplexed streams, there's a Termination 🛤️. the Terminations that source/sink the digital channels are connected to a separate Termination called the multiplexing Termination 🧩. that one describes the multiplex being used, like how the H.221 frames are carried over the digital channels 💜. the MuxDescriptor is used for this. if multiple media are carried, this Termination contains multiple StreamDescriptors, and those media streams can be associated with streams sourced/sunk by other Terminations in the Context 🫧
Terminations can also be created to represent multiplexed bearers, like an ATM AAL Type 2 bearer 🌈. when a new multiplexed bearer is needed, an ephemeral Termination gets created in a Context set up for that purpose 🌸. when that Termination is subtracted, the multiplexed bearer is destroyed 💥
6.2.1 Termination Dynamics
the protocol can create new Terminations and modify property values of existing ones ✨. those modifications can include adding or removing events and/or signals 🎀. the Termination properties, events and signals are described in the sections that follow 📖. the vibe here is ownership: an MGC can only release/modify terminations, and the resources they represent, that it previously seized (for example via the Add command) 🔐 not me reaching into someone else's stuff 🙅♀️
6.2.2 TerminationIDs 🪪
Terminations are referenced by a TerminationID, which is an arbitrary schema chosen by the MG 🧠. TerminationIDs of physical Terminations are provisioned in the Media Gateway 🔧. they're allowed to have structure too, like a TerminationID made of a trunk group and a trunk within that group 🚂
there's a wildcarding mechanism with two types of wildcards, ALL and CHOOSE 🃏. ALL is used to address multiple Terminations at once. CHOOSE tells a media gateway that it must select a Termination that satisfies the partially specified TerminationID 🎯. so an MGC can instruct an MG to choose a circuit within a trunk group, which is honestly so clean 🥹
when ALL is used in the TerminationID of a command, the effect is identical to repeating the command with each matching TerminationID 🔁. since each of those commands may generate a response, the whole response can get big 😭. if individual responses aren't required, you can request a wildcard response instead. then a single response comes back, containing the UNION of all the individual responses that would otherwise have been generated, with duplicate values suppressed 🧹. for example, say Termination Ta has properties p1=a, p2=b and Termination Tb has properties p2=c, p3=d. a UNION response would consist of a wildcarded TerminationId and the sequence of properties p1=a, p2=b,c and p3=d 🍰. wildcard responses can be especially useful in the Audit commands 🔍
the encoding of the wildcarding mechanism is detailed in Annexes A and B 📚
6.2.3 Packages 📦
different types of gateways can implement Terminations with really different characteristics 🌍. the protocol handles those variations by letting Terminations have optional Properties, Events, Signals and Statistics implemented by MGs 🧩
to get MG/MGC interoperability, those options are grouped into Packages, and a Termination realizes a set of them 🤝. more info on defining packages is in section 12 📝. an MGC can audit a Termination to find out which Packages it realizes 🔎
Properties, Events, Signals and Statistics defined in Packages, plus the parameters to them, are referenced by identifiers (Ids) 🏷️. those identifiers are scoped: for each package, PropertyIds, EventIds, SignalIds, StatisticsIds and ParameterIds each have their own unique name spaces, so the same identifier can be reused across them. two PropertyIds in different packages can even share an identifier, etc. 💅
6.2.4 Termination Properties and Descriptors ✨
okay so Terminations have properties 💅 and every single property gets its own unique PropertyID 🎀. Most of them come with default values, which are spelled out either in this standard, in a package (see Section 12), or through provisioning 🌸. Unless provisioning says otherwise, every descriptor except TerminationState and LocalControl defaults to empty/"no value" when a Termination is first created or goes back to the null Context 🙈. The default contents of those two exceptions are explained in sections 7.1.5 and 7.1.7 💖.
There's a bunch of common properties for Terminations and then some properties that are specific to media streams 🦋. The common ones are also called the termination state properties 🧚. For each media stream, you get local properties plus properties of the received and transmitted flows 🌈.
Properties that aren't part of the base protocol live in Packages 📦. They're referred to by a name made of the PackageName and a PropertyId, and most of them have default values described in the Package description 💜. Properties can be read-only or read/write 👀. You can audit what values a property is allowed to have, and you can audit its current value too ✨. For read/write properties, the MGC is the one who sets their values 👑. A property can also be declared as "Global", which means one single value is shared by all the terminations that realize the package 🔥. And to keep things tidy, related properties get grouped into descriptors 🎀.
When a Termination is Added to a Context, you can set its read/write properties by including the right descriptors as parameters to the Add command 🍓. Any property the command doesn't mention keeps its prior value, no drama 🫶. The same goes for the Modify command, which can change a property's value on a Termination that's already in a Context, and again, anything not mentioned in Modify keeps its prior value 💅. Properties can also change when a Termination gets moved from one Context to another, thanks to a Move command 🦋. And sometimes descriptors come back as output from a command 💌.
Here's the full menu of Descriptors and what each one does. Not every descriptor is legal as input or output for every command, so keep that in mind bestie 😭:
+------------------+-----------------------------------------------+
| Descriptor Name | Description |
|------------------|-----------------------------------------------|
| Modem | Identifies modem type and properties |
| | when applicable. |
| Mux | Describes multiplex type for multimedia |
| | terminations (e.g. H.221, H.223, H.225.0) |
| | and Terminations forming the input mux. |
| Media | A list of media stream specifications |
| | (see 7.1.4). |
| TerminationState | Properties of a Termination (which can be |
| | defined in Packages) that are not stream |
| | specific. |
| Stream | A list of remote/local/localControl |
| | descriptors for a single stream. |
| Local | Contains properties that specify the media |
| | flows that the MG receives from the remote |
| | entity. |
| Remote | Contains properties that specify the media |
| | flows that the MG sends to the remote entity. |
| LocalControl | Contains properties (which can be defined in |
| | packages) that are of interest between the MG |
| | and the MGC. |
| Events | Describes events to be detected by the MG and |
| | what to do when an event is detected. |
| EventBuffer | Describes events to be detected by the MG |
| | when Event Buffering is active. |
| Signals | Describes signals and/or actions to be |
| | applied (e.g. Busy Tone) to the Terminations. |
| Audit | In Audit commands, identifies which |
| | information is desired. |
| Packages | In AuditValue, returns a list of Packages |
| | realized by Termination. |
| DigitMap | Defines patterns against which sequences of a |
| | specified set of events are to be matched so |
| | they can be reported as a group rather than |
| | singly. |
| ServiceChange | In ServiceChange, what, why service change |
| | occurred, etc. |
| ObservedEvents | In Notify or AuditValue, report of events |
| | observed. |
| Statistics | In Subtract and Audit, Report of Statistics |
| | kept on a Termination. |
+------------------------------------------------------------------+6.2.5 Root Termination 🌳
Sometimes a command needs to talk about the entire gateway, not just one termination inside it 🏠. So there's a special TerminationID, "Root", that's reserved just for this 👑. Packages can be defined on Root, which means Root can have properties, events and statistics 📊. Signals aren't appropriate for Root though, so no signals there 🙅♀️. The root TerminationID is allowed to show up in these places:
- a Modify command, to change a property or set an event
- a Notify command, to report an event
- an AuditValue return, to examine the values of properties and statistics implemented on Root
- an AuditCapability, to find out which properties of Root are implemented
- a ServiceChange, to declare the gateway in or out of service
Any other use of the root TerminationID is an error 🚫. Don't do it, bestie 💀.
7. COMMANDS ✨
The protocol gives you commands for manipulating the two main logical entities in the connection model: Contexts and Terminations 🎀.
Commands give you control at the finest level of granularity the protocol supports 🔬. You can add Terminations to a Context, modify them, subtract them from a Context, and audit the properties of Contexts or Terminations 🧐. Commands give you complete control over the properties of Contexts and Terminations 💅. That includes choosing which events a Termination reports, which signals or actions get applied to it, and the topology of a Context (who hears or sees whom) 🦋.
Most commands are for the Media Gateway Controller, which acts as the command initiator controlling Media Gateways as command responders 🍓. The exceptions are the Notify and ServiceChange commands: Notify goes from Media Gateway to Media Gateway Controller, and ServiceChange can be sent by either entity 🫶. Here's a quick overview of the commands. They get explained in more detail in section 7.2 🌸.
- Add. The Add command adds a termination to a context. The Add command on the first Termination in a Context is used to create a Context 🌱.
- Modify. The Modify command modifies the properties, events and signals of a termination ✏️.
- Subtract. The Subtract command disconnects a Termination from its Context and returns statistics on the Termination's participation in the Context 📉. The Subtract command on the last Termination in a Context deletes the Context 🗑️.
- Move. The Move command atomically moves a Termination to another context 🚚.
- AuditValue. The AuditValue command returns the current state of properties, events, signals and statistics of Terminations 🔍.
- AuditCapabilities. The AuditCapabilities command returns all the possible values for Termination properties, events and signals allowed by the Media Gateway 📋.
- Notify. The Notify command allows the Media Gateway to inform the Media Gateway Controller of the occurrence of events in the Media Gateway 🔔.
- ServiceChange. The ServiceChange Command allows the Media Gateway to notify the Media Gateway Controller that a Termination or group of Terminations is about to be taken out of service or has just been returned to service 🛠️. ServiceChange is also used by the MG to announce its availability to an MGC (registration), and to notify the MGC of impending or completed restart of the MG 🔄. The MGC may announce a handover to the MG by sending it a ServiceChange command 🤝. The MGC may also use ServiceChange to instruct the MG to take a Termination or group of Terminations in or out of service 🚦.
These commands are detailed in sections 7.2.1 through 7.2.8 💖.
7.1 Descriptors 🎀
The parameters to a command are called Descriptors 📝. A Descriptor is made of a name and a list of items, and some items may have values 🧁. Lots of Commands share the same common Descriptors, and this subsection lists them all 💜. Descriptors can also come back as output from a command 🎁. When a descriptor's contents are returned, an empty descriptor shows up as just its name with no list after it 🫧. Any parameters that are specific to a particular Command type are described in the subsection for that Command 🌈.
7.1.1 Specifying Parameters 🎯
Command parameters are organized into a bunch of descriptors 🗂️. In general, the text format of a descriptor looks like this:
DescriptorName=<someID>{parm=value, parm=value_.}Parameters can be fully specified, over-specified or under-specified, so let's break it down 🧩:
- Fully specified parameters have a single, unambiguous value that the command initiator is telling the command responder to use for that parameter 🎯.
- Under-specified parameters use the
CHOOSEvalue, which lets the command responder pick any value it can support 🤷♀️. - Over-specified parameters have a list of potential values. The list order shows the command initiator's order of preference for selection, and the command responder picks one value from the offered list and sends that value back to the command initiator 🥇.
If a required descriptor other than the Audit descriptor is unspecified (meaning entirely absent) from a command, the previous values set in that descriptor for that termination, if any, are kept 🔒. A missing Audit descriptor is treated the same as an empty Audit Descriptor 🫙. How the MG handles unspecified parameters inside a descriptor depends on the descriptor, as the following sections explain 📖. Whenever a parameter is underspecified or overspecified, the descriptor containing the value the responder chose gets included as output from the command 🎀.
Each command says which TerminationId it operates on, and that TerminationId can be "wildcarded" 🃏. When a command's TerminationId is wildcarded, the effect shall be as if the command was repeated with each of the TerminationIds it matches 🪞.
7.1.2 Modem Descriptor 📠
The Modem descriptor specifies the modem type and any parameters needed for use in, for example, H.324 and text conversation 💬. It includes these modem types: V.18, V.22, V.22bis, V.32, V.32bis, V.34, V.90, V.91, Synchronous ISDN, and it leaves room for extensions 🔌. By default, no modem descriptor is present in a Termination 🙈.
7.1.3 Multiplex Descriptor ✨
okay so in multimedia calls, you've got a bunch of media streams riding on a bunch of bearers, and the number of bearers might not match the number of streams 🎀 the multiplex descriptor is the thing that links the media to the bearers, like a bestie introducing two people who need to meet 💖
the descriptor carries the multiplex type, which can be:
- H.221
- H.223,
- H.226,
- V.76,
- Possible Extensions
and then a set of TerminationIDs for the multiplexed inputs, listed in order 🦋 here's a cute example:
Mux = H.221{ MyT3/1/2, MyT3/2/13, MyT3/3/6, MyT3/21/22}7.1.4 Media Descriptor 💅
the Media Descriptor is where all the parameters for every media stream live 🌸 it's split into two descriptors: a Termination State Descriptor, which covers the termination properties that don't depend on any particular stream, and one or more Stream Descriptors, where each one describes a single media stream. it's giving organized 😭
a stream gets identified by a StreamID 🧚 the StreamID is how you link the streams in a Context that belong together. multiple streams exiting a termination shall be synchronized with each other 🫶 inside each Stream Descriptor, there are up to three subsidiary descriptors: LocalControl, Local, and Remote. the nesting looks like this:
Media Descriptor
TerminationStateDescriptor
Stream Descriptor
LocalControl Descriptor
Local Descriptor
Remote Descriptoras a little convenience, a LocalControl, Local, or Remote descriptor can sit directly in the Media Descriptor without an enclosing Stream descriptor 🍓 when that happens, the StreamID is assumed to be 1. main character energy for StreamID 1 🔥
7.1.5 Termination State Descriptor 👑
the Termination State Descriptor holds the ServiceStates property, the EventBufferControl property, and the termination properties (defined in Packages) that aren't stream specific 💜
ServiceStates describes the overall state of the termination, not a specific stream. a Termination can be in one of these states: "test", "out of service", or "in service" 🌈 "test" means the termination is being tested. "out of service" means it can't be used for traffic. "in service" means it can be used, or is being used, for normal traffic. and "in service" is the default, so that's the vibe unless something says otherwise ✨
property values can be simple (integer, string, or enumeration), or they can be underspecified, which means you supply more than one value and the MG gets to make a choice 💅 there are four flavors:
- Alternative Values: multiple values in a list, one of which must be selected
- Ranges: minimum and maximum values, any value between min and max must be selected, boundary values included
- Greater Than/Less Than: value must be greater/less than specified value
- CHOOSE Wildcard: the MG chooses from the allowed values for the property
the EventBufferControl property says whether events get buffered after an event in the Events Descriptor is detected, or processed right away 🙈 see section 7.1.9 for the deets.
7.1.6 Stream Descriptor 🦋
a Stream descriptor specifies the parameters of a single bi-directional stream 🎀 those parameters are structured into three descriptors: one with termination properties specific to a stream, and one each for the local and remote flows. the Stream Descriptor includes a StreamID that identifies the stream 💖
streams get created by specifying a new StreamID on one of the terminations in a Context ✨ and a stream gets deleted by setting empty Local and Remote descriptors for it, with ReserveGroup and ReserveValue in LocalControl set to "false" on all the terminations in the context that used to support that stream 😭 bye bye stream 👋
StreamIDs only have local significance between the MGC and the MG, and the MGC assigns them 🧚 within a context, the StreamID is how you tell which media flows are interconnected: streams with the same StreamID are connected 🫶
and if a termination gets moved from one context to another, the effect on the destination context is the same as if a brand new termination had been added with the same StreamIDs as the moved one 🌸 iconic consistency, honestly.
7.1.7 LocalControl Descriptor 💜
the LocalControl Descriptor holds the Mode property, the ReserveGroup and ReserveValue properties, and the termination properties (defined in Packages) that are stream specific and matter between the MG and the MGC 🌈 property values can be underspecified, same as in section 7.1.1 ✨
the allowed values for the mode property are send-only, receive-only, send/receive, inactive, and loop-back 🎀 "send" and "receive" are measured from the exterior of the context, so, for example, a stream set to mode=sendonly does not pass received media into the context 🙈 Signals and Events are not affected by mode, which is lowkey a relief 💅
the boolean Reserve properties, ReserveValue and ReserveGroup, on a Termination say what the MG is expected to do when it gets a local and/or remote descriptor 👑
if a Reserve property is True, the MG SHALL reserve resources for all of the alternatives in the local and/or remote descriptors that it currently has resources available for 🔥 it SHALL respond with the alternatives it reserved resources for. if it cannot not support any of the alternatives, it SHALL respond with a reply to the MGC that contains empty local and/or remote descriptors 💀
if a Reserve property is False, the MG SHALL choose one of the alternatives in the local descriptor (if present) and one of the alternatives in the remote descriptor (if present) 🦋 if the MG hasn't reserved resources for the selected alternative yet, it SHALL reserve them. if it already reserved resources for the Termination (because of an earlier exchange with ReserveValue and/or ReserveGroup equal to True), it SHALL release any excess resources it reserved before 🧚 then the MG shall send a reply to the MGC containing the alternatives it selected for the local and/or remote descriptor 💖 and if the MG doesn't have enough resources to support any of the alternatives, is SHALL respond with error 510 (insufficient resources) 😭
the default value of ReserveValue and ReserveGroup is False 🌸 more on how to use the two Reserve properties is in section 7.1.8 🫶
a new setting of the LocalControl Descriptor completely replaces the previous one in the MG 🍓 so if the MGC wants to keep any info from before, it has to include that info in the new setting again. and if it wants to delete some info, it just resends the descriptor (in a Modify command) with the unwanted stuff stripped out ✨ no drama, just a fresh start 💅
7.1.8 Local and Remote Descriptors ✨
okay so bestie, this is where the MGC (the Media Gateway Controller, the boss 👑) uses the Local and Remote descriptors to reserve and then commit MG resources for media decoding and encoding. It's for the given Stream(s) and Termination the descriptors apply to. 💅 The MG then sends them back in its response to show what it's actually ready to support. And here's the iconic part: if a property is mandatory but the MGC didn't include it (like the MGC only said "payload type" and didn't spell out the detailed video encoding stuff), the MG SHALL add those properties and their values to its response. Not me being dramatic, that's just the rule 😭
Quick vocab check 🧚: Local means media the MG receives, and Remote means media the MG sends. Easy to mix up, so keep that in your back pocket 🎀
When it's text encoded, the descriptors are session descriptions defined in SDP (RFC2327). 🌸 For session descriptions going from the MGC to the MG, a few exceptions to RFC 2327 syntax are allowed:
- the "s=", "t=" and "o=" lines are optional,
- CHOOSE is allowed in place of a single parameter value, and
- alternatives are allowed in place of a single parameter value.
When you pack multiple session descriptions into one descriptor, the "v=" lines are REQUIRED as delimiters. Otherwise they're optional in session descriptions sent to the MG. 🦋 And implementations SHALL accept session descriptions that are fully conformant to RFC2327, so the strict ones are always welcome at the party 🫶
When it's binary encoded, the descriptor is a group of properties (tag-value pairs) as specified in Annex C. Each group can hold the parameters of a session description. 🍓
Now the semantics. The spec has two parts: first, what the descriptor contents mean, and second, what actions the MG MUST take when it gets the Local and Remote descriptors. Those actions depend on the values of the ReserveValue and ReserveGroup properties of the LocalControl descriptor. Main character energy from LocalControl, honestly 👑
Either the Local or Remote descriptor (or both) can be:
- unspecified (i.e., absent),
- empty,
- underspecified through use of CHOOSE in a property value,
- fully specified, or
- overspecified through presentation of multiple groups of properties and possibly multiple property values in one or more of these groups.
When descriptors come from the MGC to the MG, they're interpreted using the rules in section 7.1.1, plus these extra clarifications 💖
(a) An unspecified Local or Remote descriptor counts as a missing mandatory parameter. The MG has to use whatever was last specified for that descriptor. If nothing was ever specified, the descriptor gets ignored in further processing of the command. 🙈
(b) An empty Local (Remote) descriptor in a message from the MGC means "please release any resources reserved for the media flow received (sent)." Bye bye resources 🦋
(c) If there are multiple groups of properties in a Local or Remote descriptor, or multiple values within a group, the order of preference is descending. So top of the list is the fave ✨
(d) Underspecified or overspecified properties in a group sent by the MGC are requests for the MG to choose one or more values it can support for each of those properties. For an overspecified property, the list of values is in descending order of preference. ngl this is giving "pick what you can handle, babe" 💅
Subject to the rules above, what happens next depends on the ReserveValue and ReserveGroup properties in LocalControl. 🌈
If ReserveGroup is true, the MG reserves the resources needed to support any of the requested property group alternatives it can currently support. If ReserveValue is true, the MG reserves the resources needed to support any of the requested property value alternatives it can currently support. 🔥
NOTE - If a Local or Remote descriptor has multiple groups of properties, and ReserveGroup is true, then the MG is asked to reserve resources so it can decode or encode the media stream according to any of the alternatives. For example, if the Local descriptor has two groups of properties, one for packetized G.711 A-law audio and the other for G.723.1 audio, the MG reserves resources so it can decode one audio stream encoded in either G.711 A-law format or G.723.1 format. The MG does NOT have to reserve resources to decode two audio streams at once, one in G.711 A-law and one in G.723.1. The intention for ReserveValue is analogous. 🎀
Now if ReserveGroup is true or ReserveValue is true, these rules apply 👑
- If the MG doesn't have enough resources to support all the alternatives the MGC requested in both Local and Remote, the MG should reserve resources to support at least one alternative each within Local and Remote. 🫶
- If the MG doesn't have enough resources to support at least one alternative within a Local (Remote) descriptor received from the MGC, it SHALL return an empty Local (Remote) in response. 💀
- In its response to the MGC, when the MGC included Local and Remote descriptors, the MG SHALL include Local and Remote descriptors for all groups of properties and property values it reserved resources for. If the MG can't support at least one of the alternatives within the Local (Remote) descriptor received from the MGC, it SHALL return an empty Local (Remote) descriptor. 🥺
- If the Mode property of the LocalControl descriptor is RecvOnly, SendRecv, or Loopback, the MG MUST be prepared to receive media encoded according to any of the alternatives included in its response to the MGC. 🦋
- If ReserveGroup is False and ReserveValue is false, then the MG SHOULD apply the following rules to resolve Local and Remote to a single alternative each:
- The MG chooses the first alternative in Local for which it can support at least one alternative in Remote.
- If the MG can't support at least one Local and one Remote alternative, it returns Error 510 (Insufficient Resources). 😭
- The MG returns its selected alternative in each of Local and Remote.
Last but definitely not least: a new setting of a Local or Remote Descriptor completely replaces the previous setting of that descriptor in the MG. 💅 So if the MGC wants to keep any old info, it has to include it again in the new setting. And if it wants to delete some info, it just resends the descriptor (in a Modify command) with the unwanted stuff stripped out. Clean slate energy ✨🧚
7.1.9 Events Descriptor ✨
okay bestie, the EventsDescriptor parameter is basically the MG's to-do list 💅 It holds a RequestIdentifier plus a list of events the Media Gateway is supposed to detect and report. The RequestIdentifier is the tag that links the request to any notifications it sets off, so everything stays organized 🫶 Examples of events are fax tones, continuity test results, and on-hook and off-hook transitions. literally so iconic 📞
Each event in the descriptor has an Event name, an optional streamID, an optional KeepActive flag, and optional parameters. The Event name is a Package Name (where the event is defined) plus an EventID. You can use the ALL wildcard for the EventID, which means every event from that package has to be detected 👑 The default streamID is 0, which means the event isn't tied to any particular media stream. Events can also have parameters, so one event description can mean a few slightly different things without you needing a zillion separate events 🌈 Any further event parameters are defined in the package itself.
If a digit map completion event is present or implied in the EventsDescriptor, the EventDM parameter carries either the name or the value of the associated digit map. See section 7.1.14 for the deets 🧚
When an event gets processed against an active Events descriptor and it's found in there ("recognized"), the default action is for the MG to send a Notify command to the MG 🔥 Notification can be deferred if the event gets absorbed into the current dial string of an active digit map (see section 7.1.14). Any other action is for further study 🙈 Also, event recognition might make active signals stop, or it might replace the current Events and/or Signals descriptor, as described at the end of this section.
If the value of EventBufferControl is LockStep, then once an event gets detected, normal event handling is paused 💖 Any event detected after that which shows up in the EventBuffer Descriptor gets added to the end of the EventBuffer (it's a FIFO queue), along with the time it was detected. The MG SHALL wait for a new EventsDescriptor to be loaded. A new one can get loaded either by receiving a command with a new EventsDescriptor, or by activating an embedded EventsDescriptor.
If EventBufferControl is Off, the MG just keeps going based on the active EventsDescriptor 🦋
If an embedded EventsDescriptor is being activated, the MG keeps processing events based on that newly activated one. (Note - for EventBuffer purposes, activating an embedded EventsDescriptor counts the same as getting a new EventsDescriptor. no cap 🧠)
When the MG gets a command with a new EventsDescriptor, there might already be some events sitting in its EventBuffer. The value of EventBufferControl decides what the MG does with those buffered events 👀
Case 1
If EventBufferControl is LockStep and the MG receives a new EventsDescriptor, it checks the FIFO EventBuffer and does the following:
- If the EventBuffer is empty, the MG waits for events to be detected based on the new EventsDescriptor.
- If the EventBuffer isn't empty, the MG works through the FIFO queue starting with the first event:
- a) If the event in the queue is one of the events listed in the new EventsDescriptor, the MG acts on it and removes it from the EventBuffer. The time stamp of the Notify SHALL be the time the event was actually detected. Then the MG waits for a new EventsDescriptor. While it's waiting, any detected events that show up in the
EventsBufferDescriptorget placed in the EventBuffer. When a new EventsDescriptor arrives, event processing starts over from step 1. - b) If the event isn't in the new EventsDescriptor, the MG SHALL discard the event and repeat from step 1.
- a) If the event in the queue is one of the events listed in the new EventsDescriptor, the MG acts on it and removes it from the EventBuffer. The time stamp of the Notify SHALL be the time the event was actually detected. Then the MG waits for a new EventsDescriptor. While it's waiting, any detected events that show up in the
Case 2
If EventBufferControl is Off and the MG receives a new EventsDescriptor, it processes new events using the new EventsDescriptor 💅
If the MG gets a command telling it to set EventBufferControl to Off, then all events in the EventBuffer SHALL be discarded. bye bye buffer 👋
The MG may report several events in a single Transaction, as long as that doesn't unnecessarily hold up the reporting of individual events ⭐
For the rules on transmitting the Notify command, check the appropriate annex for specific transport considerations 🎀
The default value of EventBufferControl is Off.
Note - Since the EventBufferControl property lives in the TerminationStateDescriptor, the MG might get a command that changes EventBufferControl without including an EventsDescriptor. 🙈
Normally, when an event is recognized, any active signals have to stop. When KeepActive is specified in the event, the MG SHALL NOT interrupt any signals that are active on the Termination where the event was detected. wait that's so cute, the signals just keep vibing 🌸
An event can include an Embedded Signals descriptor and/or an Embedded Events Descriptor, and if they're there, they replace the current Signals/Events descriptor once the event gets recognized 🌈 For example, you can say the dial-tone Signal should be generated when an off-hook Event is recognized, or that the dial-tone Signal should be stopped when a digit is recognized. A media gateway controller shall not send EventsDescriptors where an event is marked KeepActive and also contains an embedded SignalsDescriptor. that combo is a no-go 💀
Only one level of embedding is allowed. An embedded EventsDescriptor SHALL NOT contain another embedded EventsDescriptor. An embedded EventsDescriptor may contain an embedded SignalsDescriptor, though 🧚
An EventsDescriptor received by a media gateway replaces any previous Events Descriptor. Event notification that's already in progress has to finish, and events detected after the command containing the new EventsDescriptor executes get processed according to the new EventsDescriptor ✨
7.1.10 EventBuffer Descriptor 🦋
okay so the EventBuffer Descriptor is a list of events (with their parameters, if they have any) that the MG is asked to detect and buffer whenever EventBufferControl equals LockStep (see 7.1.9). it's giving buffer main character energy 💜
7.1.11 Signals Descriptor 🎀
A SignalsDescriptor is the parameter that holds the set of signals the Media Gateway is asked to apply to a Termination 🌸 It can contain a bunch of signals and/or sequential signal lists, and it's totally fine for it to contain zero of them. Support for sequential signal lists is optional, so keep that in mind 🙈
Signals are defined in packages, and each one gets named with a Package name (where the signal is defined) and a SignalID. No wildcard shall be used in the SignalID 🚫 Signals in a SignalsDescriptor can have an optional StreamID parameter (the default is 0, meaning it's not related to a particular media stream), an optional signal type (more on that below), an optional duration, and maybe some parameters defined in the package that defines the signal. This lets one signal have a little variation in meaning, so you don't need a huge pile of separate signals 💖
Last but not least, the optional parameter notifyCompletion lets an MGC say it wants to be notified when a signal finishes playing out ✨ The possible reasons are: the signal timed out, it got interrupted by an event, it was halted when a SignalsDescriptor got replaced, or it stopped or never started for other reasons. If notifyCompletion isn't included in a SignalsDescriptor, a notification only happens if the signal stopped or never started for other reasons. For any of this reporting to happen, the signal completion event (see section E.1.2) has to be enabled in the currently active Events Descriptor 🔥
The duration is an integer value expressed in hundredths of a second ⏱️
There are three types of signals:
- on/off - the signal lasts until it's turned off 🌙
- timeout - the signal lasts until it's turned off or a specific period of time elapses ⏳
- brief - the signal's duration is so short that it stops on its own unless a new signal comes along and makes it stop; no timeout value is needed 💨
If the signal type is specified in a SignalsDescriptor, it overrides the default signal type (see Section 12.1.4). And if a duration is specified for an on/off signal, it SHALL be ignored 🙅♀️
A sequential signal list has a signal list identifier, a sequence of signals to be played one after another, and a signal type 🧶 Only the trailing element of the sequence can be an on/off signal. If the trailing element is an on/off signal, the signal type of the sequential signal list shall be on/off as well. If the sequence contains timeout signals and the trailing element is not on/off, the type of the sequential signal list SHALL be set to timeout 🦋 The duration of a timeout-type sequential signal list is the sum of the durations of the signals it contains. If the sequence contains only brief signals, the type of the sequential signal list SHALL be set to brief 💫 When it gets played out, a signal list is treated as one single signal of its specified type.
Multiple signals and sequential signal lists in the same SignalsDescriptor shall be played at the same time 🎶
Signals are defined as proceeding from the termination toward the exterior of the Context, unless a package says otherwise 🧚 When the same Signal is applied to multiple Terminations within one Transaction, the MG should consider using the same resource to generate those Signals 🫶
Production of a Signal on a Termination gets stopped when a new SignalsDescriptor is applied, or when an Event is detected on that Termination (see section 7.1.9) 🛑
A new SignalsDescriptor replaces any existing SignalsDescriptor. Any signals applied to the Termination that aren't in the replacement descriptor shall be stopped, and new signals get applied, except in these cases 🌈
- Signals that are in the replacement descriptor and have the KeepActive flag SHALL be continued if they're currently playing and haven't already completed. (wait, the KeepActive flag keeps them alive, so cute 🥹)
- If a replacement signal descriptor has a signal that isn't currently playing but does have the KeepActive flag, that signal SHALL be ignored 🙈
- If the replacement descriptor has a sequential signal list with the same identifier as one in the existing descriptor, then:
- the signal type and sequence of signals in the sequential signal list in the replacement descriptor shall be ignored, and
- the playing of the signals in the sequential signal list in the existing descriptor shall not be interrupted 💅
7.1.12 Audit Descriptor
okay so the Audit Descriptor is the bit that tells the MG exactly what info you want audited 📋✨ it also gives you the list of descriptors to send back. bestie, audit can be used in any command to force a descriptor to come back even if it wasn't in the command at all, or if it had no underspecified parameters 🙈 the possible items are:
+----------------+
| Modem |
|----------------|
| Mux |
|----------------|
| Events |
|----------------|
| Media |
|----------------|
| Signals |
|----------------|
| ObservedEvents |
|----------------|
| DigitMap |
|----------------|
| Statistics |
|----------------|
| Packages |
|----------------|
| EventBuffer |
+----------------+and an empty audit is totally valid 💅 it just means nothing gets returned. this is super useful in Subtract when you want to stop statistics from coming back, especially with wildcards 🧚
7.1.13 ServiceChange Descriptor
the ServiceChangeDescriptor is giving organised 🎀 it holds these parameters:
- ServiceChangeMethod
- ServiceChangeReason
- ServiceChangeAddress
- ServiceChangeDelay
- ServiceChangeProfile
- ServiceChangeVersion
- ServiceChangeMGCId
- TimeStamp
- Extension.
for the full details, go check section 7.2.8 🦋
7.1.14 DigitMap Descriptor
7.1.14.1 DigitMap Definition, Creation, Modification and Deletion
okay the DigitMap is basically a dialing plan that lives inside the Media Gateway 📞💖 it's used to detect and report digit events that come in on a Termination. the DigitMap Descriptor carries a DigitMap name plus the DigitMap you want assigned 🌸 there are three ways to get one in place: the MG can have it preloaded by management action and then you reference it by name in an EventsDescriptor, you can define it dynamically and reference it by name later, or you can just put the actual digitmap right into the EventsDescriptor 💅 and here's the iconic part: a digit map completion event inside an Events Descriptor can refer by name to a DigitMap defined by a DigitMap Descriptor in the same command, no matter which order the descriptors were sent in ✨
DigitMaps defined in a DigitMapDescriptor can show up in any of the standard Termination manipulation Commands 🦋 once defined, a DigitMap can be used on every Termination matched by the (possibly wildcarded) TerminationID in such a command. DigitMaps defined on the root Termination are global and can be used on every Termination in the MG, as long as that same name hasn't been defined on the specific Termination 👑 when you define one dynamically in a DigitMap Descriptor:
- a brand new DigitMap is created by giving it a name that isn't defined yet. the value shall be present.
- updating an existing one means supplying a new value for a name that's already defined. Terminations that are already using it keep the old definition, but later EventsDescriptors that name it (including any in the same command as the DigitMap descriptor) get the new one 🔥
- deleting one means supplying an empty value for a name that's already defined. Terminations currently using it keep using the old definition 💀
7.1.14.2 DigitMap Timers
the collection of digits under a DigitMap can be protected by three timers, viz. a start timer (T), short timer (S), and long timer (L) ⏱️🍓
- the start timer (T) is used before any digits have been dialed.
- if the Media Gateway can tell that at least one more digit is needed for a digit string to match any of the allowed patterns in the digit map, then the interdigit timer value should be set to a long (L) duration (e.g. 16 seconds).
- if the digit string has matched one of the patterns in a digit map, but more digits could still come in and match a different pattern, then the MG must not report the match right away. instead it must apply the short timer (S) and wait for more digits 🙈
the timers are configurable parameters to a DigitMap. the Start timer starts at the beginning of every digit map use, but it can be overridden 🌈
7.1.14.3 DigitMap Syntax
the formal syntax for the digit map is described by the DigitMap rule in the formal syntax description of the protocol (see Annex A and Annex B) 📝 a DigitMap, according to this syntax, is either a string or a list of strings. each string in the list is an alternative event sequence, written either as a sequence of digit map symbols or as a regular expression of digit map symbols 🧚 those digit map symbols are the digits "0" through "9" and the letters "A" through a maximum value that depends on the signalling system, but never goes past "K". they line up with specified events inside a package that was designated in the Events Descriptor on the termination where the digit map is being applied. (the mapping between events and digit map symbols is defined in the documentation for packages tied to channel-associated signalling systems like DTMF, MF, or R2. the digits "0" through "9" MUST be mapped to the matching digit events in that signalling system. letters should be allocated in a logical way, so range notation is easy to use for alternative events 💜)
the letter "x" is the wildcard, meaning any event matching the symbols in the range "0"-"9" ✨ the string can also have explicit ranges and explicit sets of symbols, which are alternative events where any one of them satisfies that position in the digit map. and the dot symbol "." means zero or more repetitions of the event selector (event, range of events, set of alternative events, or wildcard) right before it 🫶 because of the third timing rule above, inter-event timing while matching a terminal dot symbol uses the short timer by default.
on top of the event symbols, the string can contain the "S" and "L" inter-event timing specifiers and the "Z" duration modifier. "S" and "L" tell the MG to use the short (S) timer or the long (L) timer for the events that follow, overriding the timing rules above 🎀 if an explicit timing specifier is in effect in one alternative sequence but no other candidate alternative has one, the timer value from that explicit specifier must be used. if every sequence with explicit timing controls gets dropped from the candidate set, timing goes back to the default rules. and if conflicting timing specifiers are in effect in different alternative sequences, the results are undefined 😭
a "Z" marks a long duration event. when you put it in front of the symbol(s) for the event(s) that satisfy a given digit position, that position only counts as satisfied if the duration of the event goes over the long-duration threshold 🦋 the value of that threshold is assumed to be provisioned in the MG.
7.1.14.4 DigitMap Completion Event
a digit map is active while the events descriptor that invoked it is active and it hasn't completed yet 💅 a digit map completes when:
- a timer has expired, or
- an alternative event sequence has been matched and no other alternative event sequence in the digit map could be matched by detecting one more event (unambiguous match), or
- an event has been detected so that a match to a complete alternative event sequence of the digit map becomes impossible, no matter what more events come in.
when it completes, a digit map completion event (as defined in the package that provides the events being mapped into the digit map) gets generated 🔥 at that point the digit map is deactivated. events that come after that in the package get processed according to whatever event processing mechanisms are currently active 🌸
7.1.14.5 DigitMap Procedures
until completion happens, successive events shall be processed by these rules 🧚
- the "current dial string", an internal variable, starts out empty. the set of candidate alternative event sequences includes all the alternatives in the digit map.
- at each step, a timer is set to wait for the next event, based either on the default timing rules above or on explicit timing from one or more alternative event sequences. if the timer expires and a member of the candidate set is fully satisfied, a timeout completion with full match gets reported. if the timer expires and part or none of any candidate alternative is satisfied, a timeout completion with partial match gets reported 🍓
- if an event is detected before the timer expires, it's mapped to a digit string symbol and provisionally added to the end of the current dial string. the duration of the event (long or not long) is noted if and only if it's relevant at the current symbol position (because at least one candidate alternative event sequence has the "Z" modifier at this position in the sequence) 💖
- the current dial string gets compared to the candidate alternative event sequences. if and only if a sequence expecting a long-duration event at this position is matched (meaning the event was long and met the spec for this position), then any alternative event sequences that don't specify a long duration event at this position are discarded, and the current dial string gets a "Z" inserted in front of the symbol for the latest event. any sequence expecting a long-duration event at this position but not matching the observed event is discarded from the candidate set. if alternative event sequences that don't specify a long duration event in the given position are still in the candidate set after those rules, the observed event duration is treated as irrelevant when assessing matches to them 🌈
- if exactly one candidate remains and it has been fully matched, a completion event gets generated, indicating an unambiguous match. if no candidates remain, the latest event is removed from the current dial string and a completion event is generated indicating full match if one of the candidates from the previous step was fully satisfied before the latest event was detected, or partial match otherwise. the event removed from the current dial string then gets reported according to the currently active event processing mechanisms 👑
- if no completion event comes out of step 5, processing goes back to step 2. 🔁
7.1.14.6 DigitMap Activation
a digit map gets activated whenever a new event descriptor is applied to the termination, or an embedded event descriptor is activated, and that event descriptor contains a digit map completion event which itself contains a digit map parameter 🦋 each new activation of a digit map begins at step 1 of the procedure above, with a clear current dial string. any previous contents of the current dial string from an earlier activation are lost 💀
7.1.14.7 Interaction of DigitMap and Event Processing
okay so while a digit map is activated, detection is switched on for all the events in the package that holds the digit map completion event 👀 Normal event behaviour keeps going for each event that gets detected (like signals stopping, unless the digit completion event has the KeepActive flag turned on) 💅 but with two twists:
- the events in that package, other than the completion event itself, are not individually notified, and
- an event that triggers a partial match completion event is not recognized, so it has no side effects until it gets reprocessed after the digit map completion event is recognized 🫶
it's giving "wait your turn" energy, honestly 🙈
7.1.14.8 Wildcards
bestie, listen up 🎀 if a package contains a digit map completion event, then an event specification made of the package name with a wildcarded ItemID (Property Name) will activate a digit map, as long as the event includes a digit map parameter. Whether or not a digit map gets activated, if the package also contains the digit events themselves, this form of event specification will cause the individual events to be reported to the MGC as they're detected ✨
7.1.14.9 Example
let's look at an example dial plan, because it's so pretty 🧚
+------------------------+------------------------------------------+
| 0 | Local operator |
|------------------------+------------------------------------------|
| 00 | Long distance operator |
|------------------------+------------------------------------------|
| xxxx | Local extension number (starts with 1-7) |
|------------------------+------------------------------------------|
| 8xxxxxxx | Local number |
|------------------------+------------------------------------------|
| #xxxxxxx | Off-site extension |
|------------------------+------------------------------------------|
| *xx | Star services |
|------------------------+------------------------------------------|
| 91xxxxxxxxxx | Long distance number |
|------------------------+------------------------------------------|
| 9011 + up to 15 digits | International number |
+------------------------+------------------------------------------+if the DTMF detection package described in Annex E (section E.6) is used to collect the dialled digits, then the dialling plan above results in this digit map 🍓
(0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.)7.1.15 Statistics Descriptor
the Statistics parameter gives you the scoop on the status and usage of a Termination while it exists inside a specific Context 📊 There's a set of standard statistics kept for each termination where it makes sense (number of octets sent and received, for example) 🦋 Which statistical properties get reported for a given Termination depends on the Packages it realizes. By default, statistics are reported when the Termination gets Subtracted from the Context. You can override that by including an empty AuditDescriptor in the Subtract command 💜 Statistics can also come back from the AuditValue command, or from any Add/Move/Modify command that uses the Audit descriptor. They're cumulative, so reporting them does not reset them, and they only get reset when a Termination is Subtracted from a Context 🌸
7.1.16 Packages Descriptor
this one is only used with the AuditValue command 💅 The PackageDescriptor returns a list of the Packages realized by the Termination.
7.1.17 ObservedEvents Descriptor
ObservedEvents is supplied with the Notify command to tell the MGC which event(s) were detected ✨ When it's used with the AuditValue command, the ObservedEventsDescriptor returns the events in the event buffer that haven't been Notified yet. ObservedEvents contains the RequestIdentifier of the EventsDescriptor that triggered the notification, the event(s) detected, and the detection time(s) ⏰ Detection times are reported with a precision of hundredths of a second, and time is expressed in UTC 🌈
7.1.18 Topology Descriptor 🦋
okay bestie, the topology descriptor is how you decide who can hear whose media inside a Context 🎀. Unlike the other descriptors, which live on a Termination, this one applies to the whole Context 👑. By default, every termination's transmission gets received by all the other terminations 💅. The Topology Descriptor is optional to implement, so it's totally your call 🫶.
The Topology Descriptor goes before the commands in an action 🧚. You can even have an action that's ONLY a Topology Descriptor, as long as the context it's talking about already exists 💖.
A topology descriptor is a sequence of triples shaped like (T1, T2, association) ✨. T1 and T2 point at Terminations within the Context, and they can use the ALL or CHOOSE wildcard 🌸. The association tells you how media flows between those two:
(T1, T2, isolate)means the Terminations matching T2 don't receive media from the Terminations matching T1, and vice versa 🙈.(T1, T2, oneway)means the Terminations matching T2 receive media from the Terminations matching T1, but not the other way around 💅. In this case, using the ALL wildcard so that some Termination matches both T1 and T2 is not allowed.(T1, T2, bothway)means the Terminations matching T2 receive media from the Terminations matching T1, and the reverse too 🔥. Wildcards are allowed to create Terminations that match both. But if a Termination matches both, no loopback gets introduced 🔁.
CHOOSE wildcards can be used in T1 and T2 as well, with a couple of rules 💀:
- the action (see section 8) holding the topology descriptor has an Add command with a CHOOSE wildcard in it;
- if a CHOOSE wildcard occurs in T1 or T2, then a partial name SHALL NOT be specified.
The CHOOSE wildcard in a topology descriptor matches the TerminationID that the MG assigns in the first Add command that uses a CHOOSE wildcard in the same action 🧚. An existing Termination that matches T1 or T2 in the Context where a Termination gets added is connected to the new one, as the topology descriptor says ✨. If a termination isn't mentioned in the Topology Descriptor, the default association is bothway. So if T3 is added to a context with T1 and T2 using (T3,T1,oneway), it'll be connected bothway to T2 💖.
The figure and table below show some examples of topology descriptors in actions 🌈. They assume the topology descriptors are applied in sequence.
+------------------+ +------------------+ +------------------+
| +----+ | | +----+ | | +----+ |
| | T2 | | | | T2 | | | | T2 | |
| +----+ | | +----+ | | +----+ |
| ^ ^ | | ^ | | ^ |
| | | | | | | | | |
| +--+ +--+ | | +---+ | | +--+ |
| | | | | | | | | |
| v v | | v | | | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
| | T1 |<-->| T3 | | | | T1 |<-->| T3 | | | | T1 |<-->| T3 | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
+------------------+ +------------------+ +------------------+
1. No Topology Desc. 2. T1, T2 Isolate 3. T3, T2 oneway
+------------------+ +------------------+ +------------------+
| +----+ | | +----+ | | +----+ |
| | T2 | | | | T2 | | | | T2 | |
| +----+ | | +----+ | | +----+ |
| | | | ^ | | ^ ^ |
| | | | | | | | | |
| +--+ | | +---+ | | +--+ +--+ |
| | | | | | | | | |
| v | | v | | v v |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
| | T1 |<-->| T3 | | | | T1 |<-->| T3 | | | | T1 |<-->| T3 | |
| +----+ +----+ | | +----+ +----+ | | +----+ +----+ |
+------------------+ +------------------+ +------------------+
4. T2, T3 oneway 5. T2, T3 bothway 6. T1, T2 bothway
Figure 4: A Sequence Of Example Topologies
+----------+--------------------------------------------------+
| Topology | Description |
|----------+--------------------------------------------------|
| 1 | No topology descriptors |
|----------+--------------------------------------------------|
| When no topology descriptors are included, all terminations |
| have a both way connection to all other terminations. |
|----------+--------------------------------------------------|
| 2 | T1, T2, Isolate |
|----------+--------------------------------------------------|
| Removes the connection between T1 and T2. |
| T3 has a both way connection with both T1 and T2. T1 and |
| T2 have bothway connection to T3. |
|----------+--------------------------------------------------|
| 3 | T3, T2, oneway |
|----------+--------------------------------------------------|
| A oneway connection from T3 to T2 (i.e. T2 receives media |
| flow from T3). A bothway connection between T1 and T3. |
|----------+--------------------------------------------------|
| 4 | T2, T3, oneway |
|----------+--------------------------------------------------|
| A oneway connection between T2 to T3. |
| T1 and T3 remain bothway connected |
|----------+--------------------------------------------------|
| 5 | T2, T3 bothway |
|----------+--------------------------------------------------|
| T2 is bothway connected to T3. This results in the same |
| as 2.
|----------+--------------------------------------------------|
| 6 | T1, T2 bothway (T2, T3 bothway and T1,T3 bothway |
| | may be implied or explicit). |
|----------+--------------------------------------------------|
| All terminations have a bothway connection to all other |
| terminations. |
|----------+--------------------------------------------------|
| A oneway connection must implemented in such a way that the |
| other Terminations in the Context are not aware of the |
| change in topology. |
+-------------------------------------------------------------|7.2 Command Application Programming Interface ✨
Here's an Application Programming Interface (API) that lays out the protocol's Commands 💅. It's there to show the Commands and their parameters, and it is not meant to pin down an implementation (like using blocking function calls, for example) 🙈. Input parameters go in parentheses after the command name, and return values go in front of the Command. This is just for description; the real Command syntax and encoding are in the later subsections 🌸. The order of parameters to commands isn't fixed, and descriptors can show up as parameters in any order. The descriptors SHALL be processed in the order in which they appear 🔥.
All parameters in square brackets ([. . . ]) are optional 💖.
7.2.1 Add 🎀
The Add Command adds a Termination to a Context ✨.
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Add( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)The TerminationID specifies the termination to be added to the Context 🧚. The Termination is either created, or taken from the null Context. For an existing Termination, the TerminationID would be specific. For a Termination that doesn't exist yet, the TerminationID is specified as CHOOSE in the command. The new TerminationID will be returned. Wildcards may be used in an Add, but that would be unusual 🙈. If the wildcard matches more than one TerminationID, all possible matches are attempted, with results reported for each one. The order of attempts when multiple TerminationIDs match is not specified.
The optional MediaDescriptor describes all media streams 🎧.
The optional ModemDescriptor and MuxDescriptor specify a modem and multiplexer, if applicable 📞. For convenience, if a Multiplex Descriptor is present in an Add command and lists any Terminations that aren't currently in the Context, those Terminations get added to the Context as if individual Add commands listing them had been invoked. If an error occurs on such an implied Add, error 471 - Implied Add for Multiplex failure shall be returned and further processing of the command shall cease 💀.
The EventsDescriptor parameter is optional. If it's present, it provides the list of events that should be detected on the Termination 👀.
The SignalsDescriptor parameter is optional. If it's present, it provides the list of signals that should be applied to the Termination ✨.
The DigitMapDescriptor parameter is optional. If it's present, it defines a DigitMap that may be used in an EventsDescriptor 🌸.
The AuditDescriptor is optional. If it's present, the command returns descriptors as specified in the AuditDescriptor 🫶.
All descriptors that can be modified could be returned by the MG if a parameter was underspecified or overspecified 🍓. ObservedEvents, Statistics, and Packages, and the EventBuffer Descriptors, are returned only if requested in the AuditDescriptor 🔍.
Add SHALL NOT be used on a Termination with a serviceState of "OutofService" 🚫.
7.2.2 Modify
okay so Modify is the command for tweaking a Termination that already exists 💅 It changes the properties of a Termination, and the syntax is giving full menu of optional descriptors 🎀
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Modify( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)The TerminationID may be specific if you only want to modify one Termination in the Context 🦋 Wildcards may be appropriate for some operations, and if the wildcard matches more than one TerminationID, every possible match gets attempted, with results reported for each one 🌸 The order of attempts when multiple TerminationIDs match is not specified. The CHOOSE option is an error, bestie, because Modify can only be used on Terminations that already exist 🙈
The remaining parameters are the same as the ones for Add, so you already know them. The possible return values are also the same as Add's 💖
7.2.3 Subtract
Subtract is the one that disconnects a Termination from its Context, and it hands back statistics about how the Termination took part in that Context 📊✨
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Subtract(TerminationID
[, AuditDescriptor]
)TerminationID in the input parameters is the Termination being subtracted 🧚 It can be specific, or it can be a wildcard that means all (or a set of related) Terminations in the Context of the Subtract Command get subtracted. If the wildcard matches more than one TerminationID, all possible matches are attempted, with results reported for each one 💜 The order of attempts when multiple TerminationIDs match is not specified.
Using CHOOSE in the TerminationID is an error, because Subtract can only be used on existing Terminations. Not it 🙅♀️
ALL may be used as the ContextID as well as the TerminationId in a Subtract. This is a whole vibe shift, because it deletes all contexts, deletes all ephemeral terminations, and sends all physical terminations back to the Null context 💀🔥
By default, the Statistics parameter is returned to report information collected on the Termination or Terminations named in the Command. The information reported applies to their existence in the Context they're being subtracted from 📈
The AuditDescriptor is optional. If you include it, the command returns descriptors as specified in the AuditDescriptor. The possible return values are the same as the ones for Add 🎀
When a provisioned Termination gets Subtracted from a context, its property values shall revert to:
Here's how that goes, in order:
- the default value, if one is specified for the property and it isn't overridden by provisioning,
- otherwise, the provisioned value.
7.2.4 Move
Move is the command that moves a Termination to another Context from its current Context, all in one atomic operation 🦋 It's the only command that refers to a Termination in a Context different from the one the command is applied to, so it's kind of the main character of this section 👑 The Move command shall not be used to move Terminations to or from the null Context, so don't even try 🙅♀️
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
Move( TerminationID
[, MediaDescriptor]
[, ModemDescriptor]
[, MuxDescriptor]
[, EventsDescriptor]
[, SignalsDescriptor]
[, DigitMapDescriptor]
[, AuditDescriptor]
)The TerminationID specifies the Termination to be moved. It may be wildcarded, but CHOOSE shall not be used in the TerminationID. If the wildcard matches more than one TerminationID, all possible matches are attempted, with results reported for each one 💖 The order of attempts when multiple TerminationIDs match is not specified. By convention, the Termination gets subtracted from its previous Context. The Context it's moving into is indicated by the target ContextId in the Action. If the last remaining Termination is moved out of a Context, the Context is deleted 🧹
The remaining descriptors are processed the same way they are in the Modify Command. The AuditDescriptor with the Statistics option, for example, would return statistics on the Termination just prior to the Move. The possible descriptors returned from Move are the same as for Add 🌈
Move SHALL NOT be used on a Termination with a serviceState of "OutofService". Not the vibe, periodt 😭
7.2.5 AuditValue
AuditValue is the command that returns the current values of properties, events, signals and statistics associated with Terminations 🔍✨
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,DigitMapDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
[,PackagesDescriptor]
AuditValue(TerminationID,
AuditDescriptor
)TerminationID may be specific or wildcarded. If the wildcard matches more than one TerminationID, all possible matches are attempted, with results reported for each one 🫶 The order of attempts when multiple TerminationIDs match is not specified. If a wildcarded response is requested, only one command return is generated, and its contents contain the union of the values of all Terminations matching the wildcard. This convention may reduce the volume of data required to audit a group of Terminations, which is honestly so smart 🧠 Use of CHOOSE is an error.
The appropriate descriptors, with the current values for the Termination, get returned from AuditValue. Values appearing in multiple instances of a descriptor are defined to be alternate values supported, with each parameter in a descriptor considered independent 🌸
ObservedEvents returns a list of events in the EventBuffer. If the ObservedEvents descriptor is audited while a DigitMap is active, the returned ObservedEvents descriptor also includes a digit map completion event that shows the current dial string but does not show a termination method 📞
EventBuffer returns the set of events and associated parameter values currently enabled in the EventBufferDescriptor. PackagesDescriptor returns a list of packages realized by the Termination. DigitMapDescriptor returns the name or value of the current DigitMap for the Termination. A DigitMap requested in an AuditValue command with TerminationID ALL returns all DigitMaps in the gateway 🗂️ Statistics returns the current values of all statistics being kept on the Termination.
Specifying an empty Audit Descriptor results in only the TerminationID being returned. This may be useful to get a list of TerminationIDs when used with a wildcard. Annexes A and B provide a special syntax for presenting such a list in condensed form, so the AuditValue command tag doesn't have to be repeated for each TerminationID 🍓
AuditValue results depend on the Context, viz. specific, null, or wildcarded. The TerminationID may be specific, or wildcarded. (Note that ContextID All does not include the null Context.) The following table shows other information that can be obtained with the Audit Command 💅
+-----------+---------------+--------------------------------------+
| ContextID | TerminationID | Information Obtained |
+-----------+---------------+--------------------------------------+
| Specific | wildcard | Audit of matching Terminations in a |
| | | Context |
+-----------+---------------+--------------------------------------+
| Specific | specific | Audit of a single Termination in a |
| | | Context |
+-----------+---------------+--------------------------------------+
| Null | Root | Audit of Media Gateway state and |
| | | events |
+-----------+---------------+--------------------------------------+
| Null | wildcard | Audit of all matching Terminations |
| | | in the Null Context |
+-----------+---------------+--------------------------------------+
| Null | specific | Audit of a single Termination |
| | | outside of any Context |
+-----------+---------------+--------------------------------------+
| All | wildcard | Audit of all matching Terminations |
| | | and the Context to which they are |
| | | associated
+-----------+---------------+--------------------------------------+
| All | Root | List of all ContextIds |
+-----------+---------------+--------------------------------------+7.2.6 AuditCapabilities
AuditCapabilities is the command that returns the possible values of properties, events, signals and statistics associated with Terminations 🌟 Think of it as the menu, while AuditValue is what's actually on the plate 🍽️
TerminationID
[,MediaDescriptor]
[,ModemDescriptor]
[,MuxDescriptor]
[,EventsDescriptor]
[,SignalsDescriptor]
[,ObservedEventsDescriptor]
[,EventBufferDescriptor]
[,StatisticsDescriptor]
AuditCapabilities(TerminationID,
AuditDescriptor
)The appropriate descriptors, with the possible values for the Termination, are returned from AuditCapabilities. Descriptors may be repeated where there are multiple possible values. If a wildcarded response is requested, only one command return is generated, with the contents containing the union of the values of all Terminations matching the wildcard. This convention may reduce the volume of data required to audit a group of Terminations 🧁
Interpretation of what capabilities are requested for various values of ContextID and TerminationID is the same as in AuditValue 🫧
The EventsDescriptor returns the list of possible events on the Termination, together with the list of all possible values for the EventsDescriptor Parameters. EventBufferDescriptor returns the same information as EventsDescriptor. The SignalsDescriptor returns the list of possible signals that could be applied to the Termination, together with the list of all possible values for the Signals Parameters. StatisticsDescriptor returns the names of the statistics being kept on the termination. ObservedEventsDescriptor returns the names of active events on the termination. DigitMap and Packages are not legal in AuditCapability 🚫💜
7.2.7 Notify 🔔
Okay bestie, Notify is how the Media Gateway tells the Media Gateway Controller that something just happened inside the gateway. Main character energy 💅
Notify(TerminationID,
ObservedEventsDescriptor,
[ErrorDescriptor]
)The TerminationID tells you which Termination is sending the Notify. It SHALL be a fully qualified name 🎀
The ObservedEventsDescriptor holds the RequestID and a list of events the Media Gateway detected, in the order they happened ⏱️ Each event comes with its own parameters and the time it was detected. Sending Notify commands with a RequestID equal to 0 is still for further study 🧐
Notify Commands with a RequestID not equal to 0 SHALL only happen when an event shows up that's specified by an Events Descriptor which is active on that termination. No random vibes, only the events that were actually asked for ✨
The RequestID returns the RequestID parameter of the EventsDescriptor that triggered the Notify. That's how the Notify gets matched back to the request that started it 🔗 The events in the list MUST have been requested through the triggering EventsDescriptor or an embedded events descriptor, unless the RequestID is 0 (which, again, is for further study) 💜
7.2.8 ServiceChange 🚦
The ServiceChange Command is the Media Gateway's way of telling the MGC that a Termination, or a group of them, is about to go out of service or just came back 🦋 The MGC can also say that Terminations SHALL go out of service or come back. The Media Gateway MAY tell the MGC that a Termination's capability has changed. And it lets an MGC hand control of a MG over to a different MGC, which is giving handoff drama 👑
TerminationID,
[ServiceChangeDescriptor]
ServiceChange(TerminationID,
ServiceChangeDescriptor
)The TerminationID says which Termination(s) are going out of or coming back into service. Wildcarding Termination names is allowed, but the CHOOSE mechanism SHALL NOT be used 🙅♀️ Using the "Root" TerminationID means the ServiceChange is about the whole Media Gateway 🌈
The ServiceChangeDescriptor has these parameters, as required:
ServiceChangeMethodServiceChangeReasonServiceChangeDelayServiceChangeAddressServiceChangeProfileServiceChangeVersionServiceChangeMgcIdTimeStamp
The ServiceChangeMethod says what kind of ServiceChange is happening, or already happened 🎯
- Graceful: the listed Terminations are going out of service after the
ServiceChangeDelay. Connections that already exist aren't affected yet, but the MGC SHOULD stop setting up new connections and SHOULD try to gently tear down existing ones on the affected Termination(s). The MG SHOULD set the termination's serviceState to "out of service" when theServiceChangeDelayexpires or the termination is removed from an active context, whichever comes first 🫶 - Forced: the listed Terminations went out of service abruptly, and any established connections on them were lost 💀 The MGC is in charge of cleaning up the context (if there is one) that the failed termination was attached to. At a minimum, the termination SHALL be subtracted from the context. The termination's serviceState SHOULD be "out of service".
- Restart: service is coming back on the listed Terminations once the
ServiceChangeDelayruns out. The serviceState SHOULD be set to "inService" when the delay expires 🌸 - Disconnected: always used with the Root TerminationID. It means the MG lost contact with the MGC, but the contact came back 🙈 Since the MG's state may have changed in the meantime, the MGC MAY want to use the Audit command to resync its state with the MG's.
- Handoff: when it's sent from the MGC to the MG, it means the MGC is going out of service and a new MGC association MUST be set up. When it's sent from the MG to the MGC, it means the MG is trying to set up a new association based on a Handoff it got from the MGC it used to be associated with 🦋
- Failover: sent from the MG to the MGC to say the primary MG is out of service and a secondary MG is taking over 🔄
- Another value whose meaning both the MG and the MGC understand 🤝
The ServiceChangeReason says why the ServiceChange has happened, or will happen. It's made of an alphanumeric token (IANA registered) and, optionally, an explanatory string 📝
The optional ServiceChangeAddress gives the address (like an IP port number for IP networks) to use for later communication. It can go in the input parameter descriptor or the returned result descriptor. ServiceChangeAddress and ServiceChangeMgcId MUST NOT both be present in the ServiceChangeDescriptor or the ServiceChangeResultDescriptor 🚫 The ServiceChangeAddress is used inside the association that's being negotiated right now, while the ServiceChangeMgcId is an alternate address where the MG should try to set up a different association 🗺️
The optional ServiceChangeDelay is measured in seconds. If the delay is missing or set to zero, the delay value SHOULD be treated as null ⏳ For a "graceful" ServiceChangeMethod, a null delay means the Media Gateway Controller should wait for existing connections to end naturally and should not set up new ones. For "graceful" only, a null delay means the MG MUST NOT set serviceState to "out of service" until the termination is in the null context 🫧
The optional ServiceChangeProfile says which Profile (if any) of the protocol is supported. It includes the version of that profile ✨
The optional ServiceChangeVersion carries the protocol version, and it's used when protocol version negotiation happens (see section 11.3) 🔢
The optional TimeStamp is the actual time as kept by the sender. The responder can use it to figure out how far its clock is from its correspondent's clock ⏰ TimeStamp is sent with a precision of hundredths of a second, and it's expressed in UTC 🌍
The optional Extension parameter MAY contain any value whose meaning the MG and MGC both understand 🧩
A ServiceChange Command that specifies "Root" for the TerminationID and a ServiceChangeMethod equal to Restart is a registration command. That's how a Media Gateway announces that it exists to the Media Gateway Controller 📣 The Media Gateway is expected to be set up with the name of one primary MGC and, optionally, some number of alternate MGCs. Acknowledging the ServiceChange Command finishes the registration process, except when the MGC has returned an alternative ServiceChangeMgcId, as described in the next paragraph. The MG MAY include the transport ServiceChangeAddress that the MGC should use to send messages, in the ServiceChangeAddress parameter of the input ServiceChangeDescriptor. The MG MAY specify an address in the ServiceChangeAddress parameter of the ServiceChange request, and the MGC MAY also do so in the ServiceChange reply. Either way, the recipient MUST use the supplied address as the destination for all later transaction requests within the association. At the same time, as section 9 explains, transaction replies and pending indications MUST be sent to the address the matching requests came from. This MUST be done even if it means extra messaging, because commands and responses cannot be packed together 📦 The TimeStamp parameter SHALL be sent with a registration command and its response 🫶
The Media Gateway Controller MAY return a ServiceChangeMgcId parameter. That describes the MGC the Media Gateway should preferably contact for further service. In this case, the Media Gateway SHALL reissue the ServiceChange command to the new MGC. The gateway specified in a ServiceChangeMgcId, if one is provided, SHALL be contacted before any further alternate MGCs 🏃♀️ When a HandOff message goes from MGC to MG, the ServiceChangeMgcId is the new MGC that will take over from the current one 👑
The return from ServiceChange is empty, except when the Root terminationID is used. In that case, it includes these parameters, as required:
ServiceChangeAddress, if the responding MGC wants to specify a new destination for messages from the MG for the rest of the association;ServiceChangeMgcId, if the responding MGC does not want to keep an association with the MG;ServiceChangeProfile, if the responder wants to negotiate the profile used for the association;ServiceChangeVersion, if the responder wants to negotiate the version of the protocol used for the association.
These ServiceChangeReasons are defined. This list MAY be extended through an IANA registration, as outlined in section 13.3 📚
900 Service Restored
901 Cold Boot
902 Warm Boot
903 MGC Directed Change
904 Termination malfunctioning
905 Termination taken out of service
906 Loss of lower layer connectivity (e.g. downstream sync)
907 Transmission Failure
908 MG Impending Failure
909 MGC Impending Failure
910 Media Capability Failure
911 Modem Capability Failure
912 Mux Capability Failure
913 Signal Capability Failure
914 Event Capability Failure
915 State Loss7.2.9 Manipulating and Auditing Context Attributes 🧠
Okay so, everything we've covered in the earlier sections is about Terminations. This section is about how contexts get changed and audited 💖
Commands are grouped into actions (see section 8). An action applies to one context. Besides commands, an action MAY also contain instructions for manipulating or auditing the context 🎀
An action request sent to a MG MAY ask for the attributes of a context to be audited. An action MAY also ask for the attributes of a context to be changed 🔍
The context properties that MAY be included in an action reply are used to send information back to the MGC. That can be info requested by an audit of context attributes, or details about what happened when a context was manipulated 📬
If an MG receives an action that contains both a request to audit context attributes and a request to manipulate those attributes, the response SHALL include the values of the attributes after the manipulation request has been processed 💅✨
7.2.10. Generic Command Syntax 💅
okay so the protocol can be encoded in a binary format or a text format 🎀 MGCs should support both encoding formats. MGs may support both formats.
The binary format's protocol syntax lives in Annex A. Annex C is where you'll find the encoding of the Local and Remote descriptors for the binary format 🦋
The complete ABNF for the text encoding is in Annex B, written per RFC2234 ✨ SDP is used to encode the Local and Remote Descriptors in the text encoding, as modified in section 7.1.8 💖
7.3. Command Error Codes 🚨
okay, errors are made of an IANA registered error code plus an explanatory string. Sending the explanatory string is optional. Implementations are encouraged to tack diagnostic information onto the end of the string 🧚
When a MG reports an error to a MGC, it does it inside an error descriptor. An error descriptor is an error code and, optionally, the associated explanatory string 🌸
The identified error codes are:
400 - Bad Request
401 - Protocol Error
402 - Unauthorized
403 - Syntax Error in Transaction
406 - Version Not Supported
410 - Incorrect identifier
411 - The transaction refers to an unknown ContextId
412 - No ContextIDs available
421 - Unknown action or illegal combination of actions
422 - Syntax Error in Action
430 - Unknown TerminationID
431 - No TerminationID matched a wildcard
432 - Out of TerminationIDs or No TerminationID available
433 - TerminationID is already in a Context
440 - Unsupported or unknown Package
441 - Missing RemoteDescriptor
442 - Syntax Error in Command
443 - Unsupported or Unknown Command
444 - Unsupported or Unknown Descriptor
445 - Unsupported or Unknown Property
446 - Unsupported or Unknown Parameter
447 - Descriptor not legal in this command
448 - Descriptor appears twice in a command
450 - No such property in this package
451 - No such event in this package
452 - No such signal in this package
453 - No such statistic in this package
454 - No such parameter value in this package
455 - Parameter illegal in this Descriptor
456 - Parameter or Property appears twice in this Descriptor
471 - Implied Add for Multiplex failure
500 - Internal Gateway Error
501 - Not Implemented
502 - Not ready.
503 - Service Unavailable
504 - Command Received from unauthorized entity
505 - Command Received before Restart Response
510 - Insufficient resources
512 - Media Gateway unequipped to detect requested Event
513 - Media Gateway unequipped to generate requested Signals
514 - Media Gateway cannot send the specified announcement
515 - Unsupported Media Type
517 - Unsupported or invalid mode
518 - Event buffer full
519 - Out of space to store digit map
520 - Media Gateway does not have a digit map
521 - Termination is "ServiceChangeing"
526 - Insufficient bandwidth
529 - Internal hardware failure
530 - Temporary Network failure
531 - Permanent Network failure
581 - Does Not Exist8. TRANSACTIONS ✨
MGCs and MGs chat through Commands, and those Commands get grouped into Transactions 💜 Each Transaction has its own TransactionID. Transactions are made of one or more Actions, and an Action is a series of Commands that stay inside a single Context. So usually each Action has a ContextID. There are two situations where an Action doesn't get a specific ContextID though: modifying a Termination outside of a Context, and when the controller asks the gateway to create a brand new Context 🙈 Here's the picture of how Transactions, Actions and Commands fit together:
+----------------------------------------------------------+
| Transaction x |
| +----------------------------------------------------+ |
| | Action 1 | |
| | +---------+ +---------+ +---------+ +---------+ | |
| | | Command | | Command | | Command | | Command | | |
| | | 1 | | 2 | | 3 | | 4 | | |
| | +---------+ +---------+ +---------+ +---------+ | |
| +----------------------------------------------------+ |
| |
| +----------------------------------------------------+ |
| | Action 2 | |
| | +---------+ | |
| | | Command | | |
| | | 1 | | |
| | +---------+ | |
| +----------------------------------------------------+ |
| |
| +----------------------------------------------------+ |
| | Action 3 | |
| | +---------+ +---------+ +---------+ | |
| | | Command | | Command | | Command | | |
| | | 1 | | 2 | | 3 | | |
| | +---------+ +---------+ +---------+ | |
| +----------------------------------------------------+ |
+----------------------------------------------------------+
Figure 5 Transactions, Actions and CommandsTransactions are sent as TransactionRequests. The responses to a TransactionRequest come back in a single reply, and there might be a few TransactionPending messages before it (see section 8.2.3) ✨
Transactions guarantee ordered Command processing 👑 So Commands inside a Transaction run one after another. But ordering of Transactions is not guaranteed, so they can run in any order, or all at once 🌈
If a Command fails, processing of the rest of the Commands in that Transaction stops right there 💀 If a Command has a wildcarded TerminationID, the Command gets tried against each actual TerminationID that matches the wildcard. The TransactionReply includes a response for every matching TerminationID, even if some of them errored out. But if any TerminationID matching the wildcard errors, the Commands after that wildcarded one are NOT attempted. (Okay, I'm not allowed to write that one in caps, so it's a lowercase "not" for me 😭) Anyway, the rule is: they don't get tried 🫶
Commands can be marked as "Optional", and that overrides the stopping behavior. If a Command marked "Optional" errors, the later Commands in the Transaction still get executed 🦋 And if any Command fails, the MG shall, as far as possible, restore the state that existed before it tried that Command, and only then carry on with the rest of the processing ✨
A TransactionReply has the results for every Command in the matching TransactionRequest. It carries return values for the Commands that worked, plus the Command and an error descriptor for any Command that failed 🎀 TransactionPending is how the sender periodically lets the receiver know a Transaction hasn't finished yet, but it's still actively being worked on 🧚
Applications SHOULD implement an application level timer per transaction. When that timer expires, it should trigger a retransmission of the request. Getting a Reply should cancel the timer. Getting Pending should restart the timer 🌸
8.1. Common Parameters 💖
8.1.1. Transaction Identifiers
Transactions get a TransactionID, which the sender assigns, and it has to be unique within the sender's scope 🦋 If a request is missing its TransactionID and the response has an error descriptor to say so, that response shall use TransactionID 0 in its TransactionReply 🍓
8.1.2. Context Identifiers
Contexts get a ContextID, which the Media Gateway assigns, and it has to be unique within the Media Gateway's scope ✨ The Media Gateway Controller shall use the ContextID the Media Gateway gave it in every later Transaction about that Context 💜 The protocol also has a special value the MGC can use when it's talking about a Termination that isn't attached to any Context right now, and that's the null ContextID 🌈
The CHOOSE wildcard is how the MGC asks the Media Gateway to create a new Context 👑 The MGC shall not use partially specified ContextIDs that contain the CHOOSE wildcard 🙈
The MGC may use the ALL wildcard to hit all Contexts on the MG. The null Context does not get included when ALL is used 🫶
8.2. Transaction Application Programming Interface 🧚
Here's an Application Programming Interface (API) that describes the protocol's Transactions. It's there to show the Transactions and their parameters. It is NOT meant to pin down an implementation (for example, using blocking function calls), so it's not telling you how to write the code 💅 It describes, at a very high level, the input parameters and return values the various Transactions are expected to use. The actual Transaction syntax and encodings get covered in later subsections 🌸
8.2.1. TransactionRequest
The sender invokes the TransactionRequest. There's one Transaction per request invocation 💖 A request has one or more Actions, and each Action names its target Context and has one or more Commands per Context ✨
TransactionRequest(TransactionId {
ContextID {Command _ Command},
. . .
ContextID {Command _ Command } })The TransactionID parameter must specify a value so the receiver's TransactionReply or TransactionPending can be correlated with it later 🎀
The ContextID parameter must specify a value that applies to all the Commands following it, up until either the next ContextID parameter or the end of the TransactionRequest, whichever comes first 🦋
The Command parameter stands for one of the Commands listed in the "Command Details" subsection titled "Application Programming Interface" 🌈
8.2.2 TransactionReply 📬
Okay so the receiver is the one who sends the TransactionReply 💌 There is exactly one reply per transaction, no more, no less. A reply can hold one or more Actions, and every single Action has to name its target Context plus one or more Responses for that Context 🎀
TransactionReply(TransactionID {
ContextID { Response _ Response },
. . .
ContextID { Response _ Response } })The TransactionID must match the TransactionID from the TransactionRequest it's answering. No mix-ups, bestie 🫶
The ContextID must specify a value that covers all the Responses for that action. It can be a specific ContextID or null 🧚
Each Response is a return value like the ones described in section 7.2, or an error descriptor if something went wrong while running the command 😭 Once a command fails, every command after it gets skipped, so no Responses get issued for those. Rip 💀
There is one exception to that. If a command was marked optional in the Transaction request and it throws an error, the transaction keeps going anyway 🙌 So the Reply can have Responses showing up after an Error. Iconic behaviour, honestly 💅
If the receiver hits an error while processing a ContextID, the Action response is just the context ID plus one error descriptor, 422 Syntax Error in Action 🙈
If the receiver hits an error so bad it can't figure out a legal Action at all, it sends back a TransactionReply with the TransactionID and one error descriptor, 422 Syntax Error in Action. If the end of an action can't be reliably figured out but at least one Action can still be parsed, the receiver processes those and then sends 422 Syntax Error in Action as the very last action of the transaction 🍓
If the receiver hits an error so bad it can't figure out a legal Transaction, it returns a TransactionReply with a null TransactionID and a single error descriptor, 403 Syntax Error in Transaction 😵💫
If the end of a transaction can't be reliably determined and one or more Actions can be parsed, the receiver processes them and then returns 403 Syntax Error in Transaction as the last action reply for the transaction. If no Actions can be parsed at all, 403 Syntax Error in Transaction is the only reply 🦋
If the terminationID can't be reliably determined, the receiver sends 442 Syntax Error in Command as the action reply 🌸
If the end of a command can't be reliably determined, the receiver returns 442 Syntax Error in Command as the reply to the last action it could parse ✨
8.2.3 TransactionPending ⏳
The receiver is the one who invokes the TransactionPending 📣 It basically says "hey, I'm actively working on this transaction, it's not done yet." It's there so the sender doesn't think the TransactionRequest got lost when the transaction is going to take a hot minute 🫠
TransactionPending(TransactionID { } )The TransactionID has to match the TransactionID of the corresponding TransactionRequest 💜
Now for the timers 🕰️ A property of root called normalMGExecutionTime can be set by the MGC, and it tells the MG the interval the MGC expects to get a response to any transaction from the MG within. Another property, normalMGCExecutionTime, is also settable by the MGC, and it indicates the interval the MG should expect a response to any transaction from the MGC within. (Yes, the original says "should expects", we love a typo but we keep it real 😂)
A sender might get more than one TransactionPending for a single command, and that's totally allowed 🦋 If a duplicate request shows up while the responder is still pending, the responder can either send a duplicate pending right away, or keep waiting until its timer goes off to send another Transaction Pending. Choice is yours, boo 💅
8.3 Messages 💌
You can bundle multiple Transactions together into one Message 📦 Every Message has a header, and the header includes the identity of the sender. The Message Identifier (MID) of a message gets set to a provisioned name for the entity sending it, like a domain address, domain name, or device name. Domain name is the suggested default 🌈
Every Message carries a Version Number that tells you which version of the protocol it follows. Versions are one or two digits long, and they start at version 1 for the present version of the protocol ⭐
The transactions inside a message get treated independently of each other. There's no implied order, and there's no application or protocol acknowledgement of a message at all 🙃
9. TRANSPORT 🚚
The transport mechanism should allow for reliable transport of transactions between an MGC and an MG 🫶 It has to stay independent of which commands are being sent, and it has to work for every application state. Several transports are defined for the protocol in normative Annexes to this document. Additional Transports can be defined as more annexes in later editions of this document, or in separate documents 🧚 For transporting the protocol over IP, MGCs shall implement both TCP and UDP/ALF, and an MG shall implement TCP or UDP/ALF or both 💖
The MG gets provisioned with a name or address (like a DNS name or IP address) for a primary MGC and zero or more secondary MGCs (see section 7.2.8). This is the address the MG uses to send messages to the MGC 📮 If TCP or UDP is the transport and the port for the initial ServiceChange request isn't otherwise known, that request should go to the default port number for the protocol. That port is 2944 for text-encoded operation or 2945 for binary-encoded operation, for either UDP or TCP 🔢 The MGC gets the message containing the ServiceChange request from the MG and can figure out the MG's address from it 🕵️♀️ As described in section 7.2.8, either the MG or the MGC may supply an address in the ServiceChangeAddress parameter, and subsequent transaction requests must be addressed to that address. Responses, though (including the response to the initial ServiceChange request), must always go back to the address that was the source of the corresponding request 🦋
9.1 Ordering of Commands 🔀
This document doesn't require the underlying transport protocol to guarantee that transactions sent to an entity arrive in sequence. Not guaranteeing order keeps things timely, but it comes with a few drawbacks. For example:
- Notify commands may be delayed and arrive at the MGC after a new command changing the EventsDescriptor has already been sent 😬
- If a new command is sent before a previous one is acknowledged, there's no guarantee the prior command will run before the new one 🫠
Media Gateway Controllers that want to guarantee consistent operation of the Media Gateway can use the following rules 💅 These rules apply to commands that are in different transactions. Commands inside the same transaction get executed in order (see section 8) ✨
- When a Media Gateway handles several Terminations, commands for the different Terminations may be sent in parallel. For example, this works in a model where each Termination (or group of Terminations) is controlled by its own process or its own thread 🧵
- On a Termination, there should normally be at most one outstanding command (Add or Modify or Move), unless the outstanding commands are in the same transaction. A Subtract command, however, may be issued at any time. Because of that, a Media Gateway may sometimes receive a Modify command that applies to a previously subtracted Termination. Those commands should be ignored, and an error code should be returned 🙈
- On a given Termination, there should normally be at most one outstanding Notify command at any time 🔔
- Sometimes an implicitly or explicitly wildcarded Subtract command that applies to a group of Terminations may step in front of a pending Add command. The Media Gateway Controller should individually delete all Terminations for which an Add command was pending at the time of the global Subtract command. Also, new Add commands for Terminations named by the wild-carding (or implied in a Multiplex descriptor) should not be sent until the wild-carded Subtract command is acknowledged 🧹
- AuditValue and AuditCapability aren't subject to any sequencing at all 🧘♀️
- ServiceChange shall always be the first command sent by a MG as defined by the restart procedure. Any other command or response must be delivered after this ServiceChange command 🚦
These rules don't affect the command responder, which should always respond to commands 🫶🌸
9.2 Protection against Restart Avalanche ✨
okay so picture this 😭 a whole bunch of Media Gateways get powered on at the SAME time and they ALL try to send a ServiceChange transaction at once. the Media Gateway Controller would be totally swamped 🫠 leading to message losses and network congestion right when everything is trying to come back online. not a vibe. so to stop these avalanches, the spec suggests the following behavior 💅
- when a Media Gateway is powered on, it should start a restart timer set to a random value, uniformly distributed between 0 and a maximum waiting delay (MWD). make sure the random number generation doesn't end up synchronized across multiple Media Gateways that use the same algorithm 🙈
- the Media Gateway should then wait for either the timer to end OR for a local user activity to be detected, like an off-hook transition on a residential Media Gateway 📞
- when the timer elapses, or when an activity is detected, the Media Gateway should initiate the restart procedure 🚀
the restart procedure is pretty simple. the MG has to guarantee that the first message the Media Gateway Controller sees from this MG is a ServiceChange message informing the Media Gateway Controller about the restart. main character energy ✨
Note - The value of MWD is a configuration parameter that depends on the type of the Media Gateway. The following reasoning may be used to determine the value of this delay on residential gateways.
okay so the math is lowkey iconic 🧮 Media Gateway Controllers are typically dimensioned to handle the peak hour traffic load, during which, on average, 10% of the lines will be busy, placing calls whose average duration is typically 3 minutes. the processing of a call typically involves 5 to 6 Media Gateway Controller transactions between each Media Gateway and the Media Gateway Controller. so the Media Gateway Controller is expected to handle 5 to 6 transactions for each Termination every 30 minutes on average, or, to put it otherwise, about one transaction per Termination every 5 to 6 minutes on average. this suggests that a reasonable value of MWD for a residential gateway would be 10 to 12 minutes. in the absence of explicit configuration, residential gateways should adopt a value of 600 seconds for MWD 🎀
the same reasoning suggests that the value of MWD should be much shorter for trunking gateways or for business gateways 🏢 because they handle a large number of Terminations, and because the usage rate of these Terminations is much higher than 10% during the peak busy hour, a typical value being 60%. these Terminations, during the peak hour, are expected to contribute about one transaction per minute to the Media Gateway Controller load 📈 a reasonable algorithm is to make the value of MWD per "trunk" Termination six times shorter than the MWD per residential gateway, and also inversely proportional to the number of Terminations that are being restarted. for example, MWD should be set to 2.5 seconds for a gateway that handles a T1 line, or to 60 milliseconds for a gateway that handles a T3 line 🦋
10. SECURITY CONSIDERATIONS 🔒
this section covers security when using the protocol in an IP environment 🫶
10.1 Protection of Protocol Connections
okay this part is serious bestie 🥺 a security mechanism is clearly needed to stop unauthorized entities from using the protocol defined in this document to set up unauthorized calls or to interfere with authorized calls 🚫 the security mechanism for the protocol when it's transported over IP networks is IPsec [RFC2401 to RFC2411].
the AH header [RFC2402] gives you data origin authentication, connectionless integrity and optional anti-replay protection of messages passed between the MG and the MGC. the ESP header [RFC2406] provides confidentiality of messages, if desired. for instance, the ESP encryption service should be requested if the session descriptions are used to carry session keys, as defined in SDP 🔐
implementations of the protocol defined in this document that use the ESP header SHALL comply with section 5 of [RFC2406], which defines a minimum set of algorithms for integrity checking and encryption. similarly, implementations that use the AH header SHALL comply with section 5 of [RFC2402], which defines a minimum set of algorithms for integrity checking using manual keys 💖
implementations SHOULD use IKE [RFC2409] to get more robust keying options 🗝️ implementations that employ IKE SHOULD support authentication with RSA signatures and RSA public key encryption 💅
10.2 Interim AH scheme
okay so here's the deployment problem 😩 implementation of IPsec requires that the AH or ESP header be inserted immediately after the IP header, and that can't be easily done at the application level. so this presents a deployment problem for the protocol defined in this document where the underlying network implementation does not support IPsec 🤷♀️
as an interim solution, an optional AH header is defined within the H.248 protocol header ✨ the header fields are exactly those of the SPI, SEQUENCE NUMBER and DATA fields as defined in [RFC2402]. the semantics of the header fields are the same as the "transport mode" of [RFC2402], except for the calculation of the Integrity Check value (ICV). in IPsec, the ICV is calculated over the entire IP packet, including the IP header. this prevents spoofing of the IP addresses 🙅♀️ to keep the same functionality, the ICV calculation should be performed across the entire transaction, prepended by a synthesized IP header consisting of a 32 bit source IP address, a 32 bit destination address and a 16 bit UDP destination port encoded as 10 hex digits. when the interim AH mechanism is employed when TCP is the transport Layer, the UDP Port above becomes the TCP port, and all other operations are the same 🔁
implementations of the H.248 protocol SHALL implement IPsec where the underlying operating system and the transport network support IPsec 🌐 implementations of the protocol using IPv4 SHALL implement the interim AH scheme. however, this interim scheme SHALL NOT be used when the underlying network layer supports IPsec. IPv6 implementations are assumed to support IPsec and SHALL NOT use the interim AH scheme 🧚
all implementations of the interim AH mechanism SHALL comply with section 5 of [RFC2402], which defines a minimum set of algorithms for integrity checking using manual keys 🔑
The interim AH interim scheme does not provide protection against eavesdropping, thus forbidding third parties from monitoring the connections set up by a given termination. Also, it does not provide protection against replay attacks. These procedures do not necessarily protect against denial of service attacks by misbehaving MGs or misbehaving MGCs. However, they will provide an identification of these misbehaving entities, which should then be deprived of their authorization through maintenance procedures. 🚨
10.3 Protection of Media Connections
the protocol lets the MGC give MGs "session keys" that can be used to encrypt the audio messages, which protects against eavesdropping 🎧
a specific problem of packet networks is "uncontrolled barge-in" 😱 this attack can be performed by directing media packets to the IP address and UDP port used by a connection. if no protection is implemented, the packets must be decompressed and the signals must be played on the "line side". yikes 💀
a basic protection against this attack is to only accept packets from known sources, checking for example that the IP source address and UDP source port match the values announced in the Remote Descriptor 🛡️ this has two inconveniences, though: it slows down connection establishment, and it can be fooled by source spoofing 🙃
- to enable the address-based protection, the MGC must obtain the remote session description of the egress MG and pass it to the ingress MG. this requires at least one network roundtrip, and leaves us with a dilemma: either allow the call to proceed without waiting for the round trip to complete and risk, for example, "clipping" a remote announcement, or wait for the full roundtrip and settle for slower call-set-up procedures 😬
- source spoofing is only effective if the attacker can obtain valid pairs of source destination addresses and ports, for example by listening to a fraction of the traffic. to fight source spoofing, one could try to control all access points to the network. but this is, in practice, very hard to achieve 🥲
an alternative to checking the source address is to encrypt and authenticate the packets, using a secret key that is conveyed during the call set-up procedure. this will not slow down the call set-up, and it provides strong protection against address spoofing 💜
11. MG-MGC CONTROL INTERFACE 🎀
the control association between MG and MGC is initiated at MG cold start and announced by a ServiceChange message, but it can be changed by subsequent events, such as failures or manual service events 🔄 while the protocol does not have an explicit mechanism to support multiple MGCs controlling a physical MG, it has been designed to support the multiple logical MGs (within a single physical MG) that can be associated with different MGCs 🧩
11.1 Multiple Virtual MGs
a physical Media Gateway may be partitioned into one or more Virtual MGs. a virtual MG consists of a set of statically partitioned physical Terminations and/or sets of ephemeral Terminations. a physical Termination is controlled by one MGC. the model does not require that other resources be statically allocated, just Terminations. the mechanism for allocating Terminations to virtual MGs is a management method outside the scope of the protocol. each of the virtual MGs appears to the MGC as a complete MG client 🍓
a physical MG may have only one network interface, which must be shared across virtual MGs. in such a case, the packet/cell side Termination is shared. it should be noted, however, that in use, such interfaces require an ephemeral instance of the Termination to be created per flow, so sharing the Termination is straightforward. this does lead to a complication, namely that the MG must always know which of its controlling MGCs should be notified if an event occurs on the interface 🤔
in normal operation, the Virtual MG will be instructed by the MGC to create network flows (if it is the originating side), or to expect flow requests (if it is the terminating side), and no confusion will arise ✅ however, if an unexpected event occurs, the Virtual MG must know what to do with respect to the physical resources it is controlling 😵💫
if recovering from the event requires manipulation of a physical interface's state, only one MGC should do so. these issues are resolved by allowing any of the MGCs to create EventsDescriptors to be notified of such events, but only one MGC can have read/write access to the physical interface properties. all other MGCs have read-only access. the management mechanism is used to designate which MGC has read/write capability, and that MGC is designated the Master MGC 👑
each virtual MG has its own Root Termination. in most cases, the values for the properties of the Root Termination are independently settable by each MGC. where there can only be one value, the parameter is read-only to all but the Master MGC 🌈
ServiceChange may only be applied to a Termination or set of Terminations partitioned to the Virtual MG, or created (in the case of ephemeral Terminations) by that Virtual MG 💅✨
11.2 Cold Start 🥶
okay so picture this: a Media Gateway (MG) just got turned on for the first time 🌸. Before it ever talks to anyone, a management mechanism outside this protocol has pre-provisioned it with a Primary MGC and, optionally, an ordered list of Secondary MGCs. That's its contact list, bestie 📇.
When the MG cold starts, it sends a ServiceChange command with the "Restart" method on the Root Termination to its Primary MGC. If the MGC accepts the MG, it sends back a Transaction Accept with ServiceChangeMgcId set to itself 🎀. But if the MG gets a ServiceChangeMgcId that isn't the MGC it originally contacted, it sends a ServiceChange to the MGC named in that field instead. It keeps doing this hop-hop-hop until it finds a controlling MGC that accepts its registration, or until it gives up and gets no reply 🦋.
If there's no reply from the Primary MGC or from a designated successor, the MG tries its pre-provisioned Secondary MGCs, in order 🔁. And if it still can't set up a control relationship with any MGC, it shall wait a random amount of time as described in section 9.2, then start contacting its primary and, if necessary, its secondary MGCs all over again 😭.
There's also a sneaky case to watch for. The reply to a ServiceChange with "Restart" could get lost, and then a command could show up at the MG before the ServiceChange response does 👀. In that situation the MG shall issue error 505 - Command Received before Restart Response 💀.
11.3 Negotiation of Protocol Version 🤝
the very first ServiceChange command from an MG shall include the protocol version it supports, carried in the ServiceChangeVersion parameter. When the MGC gets that, if it only supports a lower version, it shall send a ServiceChangeReply with the lower version. From then on, every message between the MG and the MGC shall follow the lower version 💅.
If the MG can't go along with that and it already has a transport connection to the MGC, it should close the connection. Either way, it should reject all later requests from the MGC with Error 406 Version Not supported 🙅♀️.
Now the other side of the coin: if the MGC supports a higher version than the MG but can still handle the lower version the MG proposed, it shall send a ServiceChangeReply with the lower version. Again, everything after that shall conform to the lower version 🌈. If the MGC can't manage that at all, it shall reject the association with Error 406 Version Not Supported ❌.
Version negotiation can also happen during "handoff" and "failover" ServiceChanges, so it's not a one-and-done thing ⭐.
When it comes to adding new versions of the protocol, there are a few rules you should follow:
- Existing protocol elements (that's procedures, parameters, descriptors, properties, and values) should not be changed, unless a protocol error needs fixing or the operation of the service being supported has to change.
- The semantics of a command, parameter, descriptor, property, or value should not be changed.
- Established rules for formatting and encoding messages and parameters should not be modified.
- When an information element becomes obsolete, it can be marked as not used. But its identifier gets marked as reserved, so nobody can reuse it in future versions 🔒.
11.4 Failure of an MG 🫠
if an MG fails but can still send a message to the MGC, it sends a ServiceChange with an appropriate method (graceful or forced) and names the Root TerminationID 🚨. Once it's back in service, it sends a ServiceChange with a "Restart" method 🔄.
Here's the redundant-failover situation: letting the MGC send duplicate messages to both MGs is how a pair of MGs that can do redundant failover of one of them actually works 👯. Only the Working MG shall accept or reject transactions 💜. When failover happens, the Primary MG sends a ServiceChange command with a "Failover" method and a "MG Impending Failure" reason. Then the MGC uses the secondary MG as the active one 🦸♀️. When the error condition gets repaired, the Working MG can send a "ServiceChange" with a "Restart" method 🥳.
11.5 Failure of an MGC 💔
if the MG notices that its controlling MGC has failed, it tries to contact the next MGC on its pre-provisioned list 📞. It starts at the beginning, with the Primary MGC, unless that's the one that just failed. In that case, it starts at its first Secondary MGC. It sends a ServiceChange message with a "Failover" method and a " MGC Impending Failure" reason 🚩.
Sometimes an MGC needs to shuffle its controlled MGs over to a different MGC, like during partial failure or manual maintenance 🛠️. To do that, it sends a ServiceChange method to the MG with a "HandOff" method, and puts its designated replacement in ServiceChangeMgcId 🎁. The MG should then send a ServiceChange message with a "Handoff" method and a "MGC directed change" reason to the designated MGC 📨. If it doesn't get a reply, or it doesn't see an Audit command afterwards, it should act as if its MGC failed and start contacting secondary MGCs 😰. And if it can't set up a control relationship with any MGC, it shall wait a random amount of time as described in section 9.2, then start contacting its primary and, if necessary, its secondary MGCs again ⏳.
No recommendation is made on how the MGCs involved in a Handoff keep their state information. That's out of scope for this recommendation 🙅. Still, the MGC and MG may take the following steps when a Handoff happens. When the MGC starts a HandOff, the handover should be transparent to Operations on the Media Gateway ✨. Transactions can run in any order, and they might already be in progress when the ServiceChange is executed 🌀. So commands in progress continue, transaction replies go to the new MGC (once a new control association is established), and the MG should expect outstanding transaction replies from the new MGC 📬. No new messages shall be sent to the new MGC until that control association exists 🚫. Repeated transaction requests shall be directed to the new MGC 🎯. And the MG shall maintain state on all terminations and contexts 🧠.
It's also possible for an MGC to be built so that a failed MGC gets replaced by a working one with the same identity. In that case, ServiceChangeMgcId would carry the previous value, and the MG shall behave as if the value had changed, sending a ServiceChange message as above 🪞.
Pairs of MGCs that can do redundant failover can tell their controlled MGs about the failover using the mechanism above 🫶.
12. PACKAGE DEFINITION 📦
the main way to extend the protocol is through Packages 🧩. Packages define extra Properties, Events, Signals, and Statistics that can show up on Terminations.
Packages defined by IETF will appear in separate RFCs 📜. Packages defined by ITU-T may show up in the relevant recommendations, for example as annexes 🌷.
- A public document, or a standard forum document that can be referenced as the document describing the package following the guideline above, should be specified.
- The document shall specify the version of the Package it describes.
- The document should be available on a public web server and should have a stable URL. The site should offer a way to leave comments, and appropriate responses should come back 💌.
12.1 Guidelines for defining packages 📝
Packages define Properties, Events, Signals, and Statistics ✨.
Packages may also define new error codes, following the guidelines in section 13.2. This is mostly a matter of documentary convenience: the package documentation gets submitted to IANA to support the error code registration. If a package is modified, there's no need to give IANA a new document reference for the error code, unless the description of the error code itself changed 🙌.
Names of all these defined constructs shall consist of the PackageID (which uniquely identifies the package) and the ID of the item (which uniquely identifies the item in that package) 🪪. In the text encoding, the two are separated by a forward slash (/). For example, togen/playtone is the text encoding for the play tone signal in the tone generation package 🎵.
A Package will contain the following sections:
12.1.1 Package 🎀
This is the overall description of the package. It specifies:
- Package Name: only descriptive,
- PackageID: Is an identifier
- Description:
- Version: A new version of a package can only add additional Properties, Events, Signals, Statistics and new possible values for an existing parameter described in the original package. No deletions or modifications shall be allowed. A version is an integer in the range from 1 to 99.
- Extends (Optional): A package may extend an existing package. The version of the original package must be specified. When a package extends another package it shall only add additional Properties, Events, Signals, Statistics and new possible values for an existing parameter described in the original package. An extended package shall not redefine or overload a name defined in the original package. Hence, if package B version 1 extends package A version 1, version 2 of B will not be able to extend the A version 2 if A version 2 defines a name already in B version 1. 🧐
12.1.2 Properties 💎
These are the Properties defined by the package. Each one specifies:
- Property Name: only descriptive.
- PropertyID: Is an identifier
- Description:
- Type: One of:
- String: UTF-8 string
- Integer: 4 byte signed integer
- Double: 8 byte signed integer
- Character: Unicode UTF-8 encoding of a single letter. Could be more than one octet.
- Enumeration: One of a list of possible unique values (See 12.3)
- Sub-list: A list of several values from a list
- Boolean
- Possible Values:
- Defined in: Which Megaco descriptor the property is defined in.
LocalControlis for stream dependent properties.TerminationStateis for stream independent properties. These are expected to be the most common cases, but it is possible for properties to be defined in other descriptors 🗂️. - Characteristics: Read / Write or both, and (optionally), global: Indicates whether a property is read-only, or read-write, and if it is global. If Global is omitted, the property is not global. If a property is declared as global, the value of the property is shared by all terminations realizing the package 🌍.
12.1.3 Events 🔔
These are the Events defined by the package. Each one specifies:
- Event name: only descriptive.
- EventID: Is an identifier
- Description:
- EventsDescriptor Parameters: Parameters used by the MGC to configure the event, and found in the EventsDescriptor. See section 12.2.
- ObservedEventsDescriptor Parameters: Parameters returned to the MGC in Notify requests and in replies to command requests from the MGC that audit ObservedEventsDescriptor, and found in the ObservedEventsDescriptor. See section 12.2. 👀
12.1.4 Signals ✨
okay bestie, every package has to list out its signals, and for each signal it spells out the following 💅
- Signals defined by the package, specifying:
- Signal Name: only descriptive. (just a label for humans 🎀)
- SignalID: Is an identifier. SignalID is used in a SignalsDescriptor 🔑
- Description
- SignalType: One of:
- OO (On/Off)
- TO (TimeOut)
- BR (Brief)
- Duration: in hundredths of seconds ⏱️
- Additional Parameters: See section 12.2
👀 Heads up on SignalType: it can be defined so that it depends on the value of one or more parameters. Signals that would be played with SignalType BR or TO should have a default duration. The package has to define that default duration and signalType, no skipping!
12.1.5 Statistics 📊
Statistics defined by the package, specifying:
- Statistic name: only descriptive. 🧁
- StatisticID: Is an identifier. StatisticID is used in a StatisticsDescriptor. 🔑
- Description
- Units: unit of measure, e.g. milliseconds, packets. 📏
12.1.6 Procedures 🗺️
Additional guidance on the use of the package. Basically, the bit where you explain how to actually use the thing 🫶
12.2 Guidelines to defining Properties, Statistics and Parameters to Events and Signals. 🎀
Okay, this is where we get into the nitty-gritty of Parameters. Each one gets:
- Parameter Name: only descriptive
- ParameterID: Is an identifier
- Type: One of:
- String: UTF-8 octet string
- Integer: 4 octet signed integer
- Double: 8 octet signed integer
- Character: Unicode UTF-8 encoding of a single letter. Could be more than one octet.
- Enumeration: One of a list of possible unique values (See 12.3)
- Sub-list: A list of several values from a list (not supported for statistics)
- Boolean
- Possible values:
- Description:
12.3 Lists 📝
Possible values for parameters can be enumerations, and enumerations can be defined in a list. It is recommended that the list be IANA registered, so packages that extend the list can be defined without worrying about conflicting names. Main character energy for avoiding name clashes 💜
12.4 Identifiers 🔖
Identifiers in text encoding shall be strings of up to 64 characters, containing no spaces, starting with an alphanumeric character and consisting of alphanumeric characters and / or digits, and possibly including the special character underscore ("_").
Identifiers in binary encoding are 2 octets long. ✌️
Both text and binary values shall be specified for each identifier, including identifiers used as values in enumerated types. No exceptions, not even for the enum cuties 🧚
12.5 Package Registration 🪪
A package can be registered with IANA for interoperability reasons. See section 13 for IANA considerations. 🌈
13. IANA CONSIDERATIONS 🏛️
13.1 Packages 📦
The following considerations SHALL be met to register a package with IANA:
- A unique string name, unique serial number and version number is registered for each package. The string name is used with text encoding. The serial number shall be used with binary encoding. Serial Numbers 60000-64565 are reserved for private use. Serial number 0 is reserved. 🔒
- A contact name, email and postal addresses for that contact shall be specified. The contact information shall be updated by the defining organization as necessary. 📬
- A reference to a document that describes the package, which should be public:
The document shall specify the version of the Package that it describes.
If the document is public, it should be located on a public web server and should have a stable URL. The site should provide a mechanism to provide comments and appropriate responses should be returned. 💬
- Packages registered by other than recognized standards bodies shall have a minimum package name length of 8 characters. 🎀
- All other package names are first come-first served if all other conditions are met. 🏃♀️💨
13.2 Error Codes 🚨
The following considerations SHALL be met to register an error code with IANA:
- An error number and a one line (80 character maximum) string is registered for each error. 🧾
- A complete description of the conditions under which the error is detected shall be included in a publicly available document. The description shall be sufficiently clear to differentiate the error from all other existing error codes. 🔍
- The document should be available on a public web server and should have a stable URL. 🌐
- Error numbers registered by recognized standards bodies shall have 3 or 4 character error numbers. 👑
- Error numbers registered by all other organizations or individuals shall have 4 character error numbers. 🌸
- An error number shall not be redefined, nor modified except by the organization or individual that originally defined it, or their successors or assigns. Hands off, that's their error number 🙅♀️
13.3 ServiceChange Reasons 🔁
The following considerations SHALL be met to register service change reason with IANA:
- A one phrase, 80-character maximum, unique reason code is registered for each reason. 🏷️
- A complete description of the conditions under which the reason is used is detected shall be included in a publicly available document. The description shall be sufficiently clear to differentiate the reason from all other existing reasons. 📖
- The document should be available on a public web server and should have a stable URL. 🦋
ANNEX A: BINARY ENCODING OF THE PROTOCOL (NORMATIVE) 🧬
This Annex specifies the syntax of messages using the notation defined in ASN.1 [ITU-T Recommendation X.680 (1997): Information Technology - Abstract Syntax Notation One (ASN.1) - Specification of basic notation.]. Messages shall be encoded for transmission by applying the basic encoding rules specified in [ITU-T Recommendation X.690(1994) Information Technology - ASN.1 Encoding Rules: Specification of Basic Encoding Rules (BER)]. 📜
A.1 Coding of wildcars 🃏
The use of wildcards ALL and CHOOSE is allowed in the protocol. This lets an MGC partially specify Termination IDs and lets the MG choose from the values that conform to the partial specification. Termination IDs may encode a hierarchy of names, and that hierarchy is provisioned. For instance, a TerminationID may consist of a trunk group, a trunk within the group and a circuit. Wildcarding must be possible at all levels. The following paragraphs explain how this is achieved. 🌳
The ASN.1 description uses octet strings of up to 8 octets in length for Termination IDs. This means that Termination IDs consist of at most 64 bits. A fully specified Termination ID may be preceded by a sequence of wildcarding fields. A wildcarding field is one octet in length. Bit 7 (the most significant bit) of this octet specifies what type of wildcarding is invoked: if the bit value equals 1, then the ALL wildcard is used; if the bit value if 0, then the CHOOSE wildcard is used. Bit 6 of the wildcarding field specifies whether the wildcarding pertains to one level in the hierarchical naming scheme (bit value 0) or to the level of the hierarchy specified in the wildcarding field plus all lower levels (bit value 1). Bits 0 through 5 of the wildcarding field specify the bit position in the Termination ID at which the starts. 🔢
We illustrate this scheme with some examples. In these examples, the most significant bit in a string of bits appears on the left hand side. 👀
Assume that Termination IDs are three octets long and that each octet represents a level in a hierarchical naming scheme. A valid Termination ID is
00000001 00011110 01010101.Addressing ALL names with prefix 00000001 00011110 is done as follows:
wildcarding field: 10000111
Termination ID: 00000001 00011110 xxxxxxxx.The values of the bits labeled "x" is irrelevant and shall be ignored by the receiver. 🫥
Indicating to the receiver that is must choose a name with 00011110 as the second octet is done as follows:
wildcarding fields: 00010111 followed by 00000111
Termination ID: xxxxxxxx 00011110 xxxxxxxx.The first wildcard field indicates a CHOOSE wildcard for the level in the naming hierarchy starting at bit 23, the highest level in our assumed naming scheme. The second wildcard field indicates a CHOOSE wildcard for the level in the naming hierarchy starting at bit 7, the lowest level in our assumed naming scheme. 🪜
Finally, a CHOOSE-wildcarded name with the highest level of the name equal to 00000001 is specified as follows:
wildcard field: 01001111
Termination ID: 0000001 xxxxxxxx xxxxxxxx .Bit value 1 at bit position 6 of the first octet of the wildcard field indicates that the wildcarding pertains to the specified level in the naming hierarchy and all lower levels. 💅
Context IDs may also be wildcarded. In the case of Context IDs, however, specifying partial names is not allowed. Context ID 0x0 SHALL be used to indicate the NULL Context, Context ID 0xFFFFFFFE SHALL be used to indicate a CHOOSE wildcard, and Context ID 0xFFFFFFFF SHALL be used to indicate an ALL wildcard. 🎯
TerminationID 0xFFFFFFFFFFFFFFFF SHALL be used to indicate the ROOT Termination. 🌟
A.2 ASN.1 syntax specification 🧩
This section contains the ASN.1 specification of the H.248 protocol syntax. 📐
NOTE - In case a transport mechanism is used that employs application level framing, the definition of Transaction below changes. Refer to the annex defining the transport mechanism for the definition that applies in that case. ⚠️
NOTE - The ASN.1 specification below contains a clause defining TerminationIDList as a sequence of TerminationIDs. The length of this sequence SHALL be one, except possibly when used in contextAuditResult. 🧐
MEDIA-GATEWAY-CONTROL DEFINITIONS AUTOMATIC TAGS::= BEGIN
MegacoMessage ::= SEQUENCE
{
authHeader AuthenticationHeader OPTIONAL,
mess Message
}
AuthenticationHeader ::= SEQUENCE
{
secParmIndex SecurityParmIndex,
seqNum SequenceNum,
ad AuthData
}
SecurityParmIndex ::= OCTET STRING(SIZE(4))
SequenceNum ::= OCTET STRING(SIZE(4))
AuthData ::= OCTET STRING (SIZE (12..32))
Message ::= SEQUENCE
{ version INTEGER(0..99),
-- The version of the protocol defined here is equal to 1.
mId MId, -- Name/address of message originator
messageBody CHOICE
{
messageError ErrorDescriptor,
transactions SEQUENCE OF Transaction
},
...
}
MId ::= CHOICE
{
ip4Address IP4Address,
ip6Address IP6Address,
domainName DomainName,
deviceName PathName,
mtpAddress OCTET STRING(SIZE(2)),
-- Addressing structure of mtpAddress:
-- 15 0
-- | PC | NI |
-- 14 bits 2 bits
...
}
DomainName ::= SEQUENCE
{
name IA5String,
-- The name starts with an alphanumeric digit followed by a
-- sequence of alphanumeric digits, hyphens and dots. No two
-- dots shall occur consecutively.
portNumber INTEGER(0..65535) OPTIONAL
}
{
address OCTET STRING (SIZE(4)),
portNumber INTEGER(0..65535) OPTIONAL
}
IP6Address ::= SEQUENCE
{
address OCTET STRING (SIZE(16)),
portNumber INTEGER(0..65535) OPTIONAL
}
PathName ::= IA5String(SIZE (1..64))
-- See section A.3okay bestie, the big ASN.1 module keeps going 💖 this is where the messages get their shape, and it's giving architecture 🦋
Transaction ::= CHOICE
{
transactionRequest TransactionRequest,
transactionPending TransactionPending,
transactionReply TransactionReply,
transactionResponseAck TransactionResponseAck,
-- use of response acks is dependent on underlying
transport
...
}
TransactionId ::= INTEGER(0..4294967295) -- 32 bit unsigned integer
TransactionRequest ::= SEQUENCE
{
transactionId TransactionId,
actions SEQUENCE OF ActionRequest,
...
}
TransactionPending ::= SEQUENCE
{
transactionId TransactionId,
...
}
TransactionReply ::= SEQUENCE
{
transactionId TransactionId,
immAckRequired NULL OPTIONAL, transactionResult
CHOICE
{
transactionError ErrorDescriptor,
actionReplies SEQUENCE OF ActionReply
},
...
}
TransactionResponseAck ::= SEQUENCE
{
firstAck TransactionId,
lastAck TransactionId OPTIONAL
}
ErrorDescriptor ::= SEQUENCE
{
errorCode ErrorCode,
errorText ErrorText OPTIONAL
}
ErrorCode ::= INTEGER(0..65535)
-- See section 13 for IANA considerations w.r.t. error codes
ErrorText ::= IA5String
ContextID ::= INTEGER(0..4294967295)
-- Context NULL Value: 0
-- Context CHOOSE Value: 429467294 (0xFFFFFFFE)
-- Context ALL Value: 4294967295 (0xFFFFFFFF)
ActionRequest ::= SEQUENCE
{
contextId ContextID,
contextRequest ContextRequest OPTIONAL,
contextAttrAuditReq ContextAttrAuditRequest OPTIONAL,
commandRequests SEQUENCE OF CommandRequest
}
ActionReply ::= SEQUENCE
{
contextId ContextID,
errorDescriptor ErrorDescriptor OPTIONAL,
contextReply ContextRequest OPTIONAL,
commandReply SEQUENCE OF CommandReply
}
ContextRequest ::= SEQUENCE
{
priority INTEGER(0..15) OPTIONAL,
emergency BOOLEAN OPTIONAL,
topologyReq SEQUENCE OF TopologyRequest OPTIONAL,
...
}
ContextAttrAuditRequest ::= SEQUENCE
{
topology NULL OPTIONAL,
emergency NULL OPTIONAL,
priority NULL OPTIONAL,
...
}
CommandRequest ::= SEQUENCE
{
command Command,
optional NULL OPTIONAL,
wildcardReturn NULL OPTIONAL,
...
}
Command ::= CHOICE
{
addReq AmmRequest,
moveReq AmmRequest,
modReq AmmRequest,
-- Add, Move, Modify requests have the same parameters
subtractReq SubtractRequest,
auditCapRequest AuditRequest,
auditValueRequest AuditRequest,
notifyReq NotifyRequest,
serviceChangeReq ServiceChangeRequest,
...
}
CommandReply ::= CHOICE
{
addReply AmmsReply,
moveReply AmmsReply,
modReply AmmsReply,
subtractReply AmmsReply,
-- Add, Move, Modify, Subtract replies have the same parameters
auditCapReply AuditReply,
auditValueReply AuditReply,
notifyReply NotifyReply,
serviceChangeReply ServiceChangeReply,
...
}
TopologyRequest ::= SEQUENCE
{
terminationFrom TerminationID,
terminationTo TerminationID,
topologyDirection ENUMERATED
{
bothway(0),
isolate(1),
oneway(2)
}
}
AmmRequest ::= SEQUENCE
{
terminationID TerminationIDList,
descriptors SEQUENCE OF AmmDescriptor,
-- At most one descriptor of each type (see AmmDescriptor)
-- allowed in the sequence.
...
}
AmmDescriptor ::= CHOICE
{
mediaDescriptor MediaDescriptor,
modemDescriptor ModemDescriptor,
muxDescriptor MuxDescriptor,
eventsDescriptor EventsDescriptor,
eventBufferDescriptor EventBufferDescriptor,
signalsDescriptor SignalsDescriptor,
digitMapDescriptor DigitMapDescriptor,
auditDescriptor AuditDescriptor,
...
}
AmmsReply ::= SEQUENCE
{
terminationID TerminationIDList,
terminationAudit TerminationAudit OPTIONAL,
...
}
SubtractRequest ::= SEQUENCE
{
terminationID TerminationIDList,
auditDescriptor AuditDescriptor OPTIONAL,
...
}
AuditRequest ::= SEQUENCE
{
terminationID TerminationID,
auditDescriptor AuditDescriptor,
...
}
AuditReply ::= SEQUENCE
{
terminationID TerminationID,
auditResult AuditResult,
...
}
AuditResult ::= CHOICE
{
contextAuditResult TerminationIDList,
terminationAuditResult TerminationAudit
}
TerminationAudit ::= SEQUENCE OF AuditReturnParameter
AuditReturnParameter ::= CHOICE
{
errorDescriptor ErrorDescriptor,
mediaDescriptor MediaDescriptor,
modemDescriptor ModemDescriptor,
muxDescriptor MuxDescriptor,
eventsDescriptor EventsDescriptor,
eventBufferDescriptor EventBufferDescriptor,
signalsDescriptor SignalsDescriptor,
digitMapDescriptor DigitMapDescriptor,
observedEventsDescriptor ObservedEventsDescriptor,
statisticsDescriptor StatisticsDescriptor,
packagesDescriptor PackagesDescriptor,
emptyDescriptors AuditDescriptor,
...
}
AuditDescriptor ::= SEQUENCE
{
auditToken BIT STRING
{
muxToken(0), modemToken(1), mediaToken(2),
eventsToken(3), signalsToken(4),
digitMapToken(5), statsToken(6),
observedEventsToken(7),
packagesToken(8), eventBufferToken(9)
} OPTIONAL,
...
}
NotifyRequest ::= SEQUENCE
{
terminationID TerminationIDList,
observedEventsDescriptor ObservedEventsDescriptor,
errorDescriptor ErrorDescriptor OPTIONAL,
...
}
NotifyReply ::= SEQUENCE
{
terminationID TerminationIDList OPTIONAL,
errorDescriptor ErrorDescriptor OPTIONAL,
...
}
ObservedEventsDescriptor ::= SEQUENCE
{
requestId RequestID,
observedEventLst SEQUENCE OF ObservedEvent
}
ObservedEvent ::= SEQUENCE
{
eventName EventName,
streamID StreamID OPTIONAL,
eventParList SEQUENCE OF EventParameter,
timeNotation TimeNotation OPTIONAL,
...
}
EventName ::= PkgdName
EventParameter ::= SEQUENCE
{
eventParameterName Name,
value Value
}
ServiceChangeRequest ::= SEQUENCE
{
terminationID TerminationIDList,
serviceChangeParms ServiceChangeParm,
...
}
ServiceChangeReply ::= SEQUENCE
{
terminationID TerminationIDList,
serviceChangeResult ServiceChangeResult,
...
}
-- For ServiceChangeResult, no parameters are mandatory. Hence the
-- distinction between ServiceChangeParm and ServiceChangeResParm.
ServiceChangeResult ::= CHOICE
{
errorDescriptor ErrorDescriptor,
serviceChangeResParms ServiceChangeResParm
}
WildcardField ::= OCTET STRING(SIZE(1))
TerminationID ::= SEQUENCE
{
wildcard SEQUENCE OF WildcardField,
id OCTET STRING(SIZE(1..8)),
...
}
-- See Section A.1 for explanation of wildcarding mechanism.
-- Termination ID 0xFFFFFFFFFFFFFFFF indicates the ROOT Termination.
TerminationIDList ::= SEQUENCE OF TerminationID
MediaDescriptor ::= SEQUENCE
{
termStateDescr TerminationStateDescriptor OPTIONAL,
streams CHOICE
{
oneStream StreamParms,
multiStream SEQUENCE OF StreamDescriptor
},
...
}
StreamDescriptor ::= SEQUENCE
{
streamID StreamID,
streamParms StreamParms
}
StreamParms ::= SEQUENCE
{
localControlDescriptor LocalControlDescriptor OPTIONAL,
localDescriptor LocalRemoteDescriptor OPTIONAL,
remoteDescriptor LocalRemoteDescriptor OPTIONAL,
...
}
LocalControlDescriptor ::= SEQUENCE
{
streamMode StreamMode OPTIONAL,
reserveValue BOOLEAN,
reserveGroup BOOLEAN,
propertyParms SEQUENCE OF PropertyParm,
...
}
StreamMode ::= ENUMERATED
{
sendOnly(0),
recvOnly(1),
sendRecv(2),
inactive(3),
loopBack(4),
...
}
-- In PropertyParm, value is a SEQUENCE OF octet string. When sent
-- by an MGC the interpretation is as follows:
-- empty sequence means CHOOSE
-- one element sequence specifies value
-- If the sublist field is not selected, a longer sequence means
-- "choose one of the values" (i.e. value1 OR value2 OR ...)
-- If the sublist field is selected,
-- a sequence with more than one element encodes the value of a
-- list-valued property (i.e. value1 AND value2 AND ...).
-- The relation field may only be selected if the value sequence
-- has length 1. It indicates that the MG has to choose a value
-- for the property. E.g., x > 3 (using the greaterThan
-- value for relation) instructs the MG to choose any value larger
-- than 3 for property x.
-- The range field may only be selected if the value sequence
-- has length 2. It indicates that the MG has to choose a value
-- in the range between the first octet in the value sequence and
-- the trailing octet in the value sequence, including the
-- boundary values.
-- When sent by the MG, only responses to an AuditCapability request
-- may contain multiple values, a range, or a relation field.
PropertyParm ::= SEQUENCE
{
name PkgdName,
value SEQUENCE OF OCTET STRING,
extraInfo CHOICE
{
relation Relation,
range BOOLEAN,
sublist BOOLEAN
} OPTIONAL,
...
}
Name ::= OCTET STRING(SIZE(2))
PkgdName ::= OCTET STRING(SIZE(4))
-- represents Package Name (2 octets) plus Property Name (2 octets)
-- To wildcard a package use 0xFFFF for first two octets, choose
-- is not allowed. To reference native property tag specified in
-- Annex C, use 0x0000 as first two octets.
-- Wildcarding of Package Name is permitted only if Property Name is
-- also wildcarded.
Relation ::= ENUMERATED
{
greaterThan(0),
smallerThan(1),
unequalTo(2),
...
}heads up 🙈 the comment onContextIDsays the CHOOSE value is429467294 (0xFFFFFFFE), but 0xFFFFFFFE is actually 4294967294 in decimal. the number is copied exactly as the original has it, so flag it when you're implementing 🫶
we're still in the thick of the spec, so stay tuned ✨
LocalRemoteDescriptor ::= SEQUENCE
{
propGrps SEQUENCE OF PropertyGroup,
...
}
PropertyGroup ::= SEQUENCE OF PropertyParm
TerminationStateDescriptor ::= SEQUENCE
{
propertyParms SEQUENCE OF PropertyParm,
eventBufferControl EventBufferControl OPTIONAL,
serviceState ServiceState OPTIONAL,
...
}
EventBufferControl ::= ENUMERATED
{
off(0),
lockStep(1),
...
}
ServiceState ::= ENUMERATED
{
test(0),
outOfSvc(1),
inSvc(2),
...
}
MuxDescriptor ::= SEQUENCE
{
muxType MuxType,
termList SEQUENCE OF TerminationID,
nonStandardData NonStandardData OPTIONAL,
...
}
MuxType ::= ENUMERATED
{
h221(0),
h223(1),
h226(2),
v76(3),
...
}
StreamID ::= INTEGER(0..65535) -- 16 bit unsigned integer
EventsDescriptor ::= SEQUENCE
{
requestID RequestID,
eventList SEQUENCE OF RequestedEvent,
...
}
RequestedEvent ::= SEQUENCE
{
pkgdName PkgdName,
streamID StreamID OPTIONAL,
eventAction RequestedActions OPTIONAL,
evParList SEQUENCE OF EventParameter,
...
}
RequestedActions ::= SEQUENCE
{
keepActive BOOLEAN,
eventDM EventDM OPTIONAL,
secondEvent SecondEventsDescriptor OPTIONAL,
signalsDescriptor SignalsDescriptor OPTIONAL,
...
}
EventDM ::= CHOICE
{ digitMapName DigitMapName,
digitMapValue DigitMapValue
}
SecondEventsDescriptor ::= SEQUENCE
{
requestID RequestID,
eventList SEQUENCE OF SecondRequestedEvent,
...
}
SecondRequestedEvent ::= SEQUENCE
{
pkgdName PkgdName,
streamID StreamID OPTIONAL,
eventAction SecondRequestedActions OPTIONAL,
evParList SEQUENCE OF EventParameter,
...
}
SecondRequestedActions ::= SEQUENCE
{
keepActive BOOLEAN,
eventDM EventDM OPTIONAL,
signalsDescriptor SignalsDescriptor OPTIONAL,
...
}
EventBufferDescriptor ::= SEQUENCE OF EventSpec
EventSpec ::= SEQUENCE
{
eventName EventName,
streamID StreamID OPTIONAL,
eventParList SEQUENCE OF EventParameter,
...
}
SignalsDescriptor ::= SEQUENCE OF SignalRequest
SignalRequest ::=CHOICE
{
signal Signal,
seqSigList SeqSigList,
...
}
SeqSigList ::= SEQUENCE
{
id INTEGER(0..65535),
signalList SEQUENCE OF Signal
}
Signal ::= SEQUENCE
{
signalName SignalName,
streamID StreamID OPTIONAL,
sigType SignalType OPTIONAL,
duration INTEGER (0..65535) OPTIONAL,
notifyCompletion NotifyCompletion OPTIONAL,
keepActive BOOLEAN OPTIONAL,
sigParList SEQUENCE OF SigParameter,
...
}
SignalType ::= ENUMERATED
{
brief(0),
onOff(1),
timeOut(2),
...
}
SignalName ::= PkgdName
NotifyCompletion ::= BIT STRING
{
onTimeOut(0), onInterruptByEvent(1),
onInterruptByNewSignalDescr(2), otherReason(3)
}
SigParameter ::= SEQUENCE
{
sigParameterName Name,
value Value
}
RequestID ::= INTEGER(0..4294967295) -- 32 bit unsigned integer
ModemDescriptor ::= SEQUENCE
{
mtl SEQUENCE OF ModemType,
mpl SEQUENCE OF PropertyParm,
nonStandardData NonStandardData OPTIONAL
}
ModemType ::= ENUMERATED
{
v18(0),
v22(1),
v22bis(2),
v32(3),
v32bis(4),
v34(5),
v90(6),
v91(7),
synchISDN(8),
...
}
DigitMapDescriptor ::= SEQUENCE
{
digitMapName DigitMapName OPTIONAL,
digitMapValue DigitMapValue OPTIONAL
}
DigitMapName ::= Name
DigitMapValue ::= SEQUENCE
{
startTimer INTEGER(0..99) OPTIONAL,
shortTimer INTEGER(0..99) OPTIONAL,
longTimer INTEGER(0..99) OPTIONAL,
digitMapBody IA5String,
-- See Section A.3 for explanation of digit map syntax
...
}
ServiceChangeParm ::= SEQUENCE
{
serviceChangeMethod ServiceChangeMethod,
serviceChangeAddress ServiceChangeAddress OPTIONAL,
serviceChangeVersion INTEGER(0..99) OPTIONAL,
serviceChangeProfile ServiceChangeProfile OPTIONAL,
serviceChangeReason Value,
serviceChangeDelay INTEGER(0..4294967295) OPTIONAL,
-- 32 bit unsigned integer
serviceChangeMgcId MId OPTIONAL,
timeStamp TimeNotation OPTIONAL,
nonStandardData NonStandardData OPTIONAL,
}
ServiceChangeAddress ::= CHOICE
{
portNumber INTEGER(0..65535), -- TCP/UDP port number
ip4Address IP4Address,
ip6Address IP6Address,
domainName DomainName,
deviceName PathName,
mtpAddress OCTET STRING(SIZE(2)),
...
}
ServiceChangeResParm ::= SEQUENCE
{
serviceChangeMgcId MId OPTIONAL,
serviceChangeAddress ServiceChangeAddress OPTIONAL,
serviceChangeVersion INTEGER(0..99) OPTIONAL,
serviceChangeProfile ServiceChangeProfile OPTIONAL,
...
}
ServiceChangeMethod ::= ENUMERATED
{
failover(0),
forced(1),
graceful(2),
restart(3),
disconnected(4),
handOff(5),
...
}
ServiceChangeProfile ::= SEQUENCE
{
profileName Name,
version INTEGER(0..99)
}
PackagesDescriptor ::= SEQUENCE OF PackagesItem
PackagesItem ::= SEQUENCE
{
packageName Name,
packageVersion INTEGER(0..99),
...
}
StatisticsDescriptor ::= SEQUENCE OF StatisticsParameter
StatisticsParameter ::= SEQUENCE
{
statName PkgdName,
statValue Value
}
NonStandardData ::= SEQUENCE
{
nonStandardIdentifier NonStandardIdentifier,
data OCTET STRING
}
NonStandardIdentifier ::= CHOICE
{
object OBJECT IDENTIFIER,
h221NonStandard H221NonStandard,
experimental IA5String(SIZE(8)),
-- first two characters should be "X-" or "X+"
...
}
H221NonStandard ::= SEQUENCE
{ t35CountryCode1 INTEGER(0..255),
t35CountryCode2 INTEGER(0..255), -- country, as per T.35
t35Extension INTEGER(0..255), -- assigned nationally
manufacturerCode INTEGER(0..65535), -- assigned nationally
...
}
TimeNotation ::= SEQUENCE
{
date IA5String(SIZE(8)), -- yyyymmdd format
time IA5String(SIZE(8)) -- hhmmssss format
}
Value ::= OCTET STRING
ENDA.3 Digit maps and path names ✨
okay so from a syntax point of view, digit maps are just strings with some extra rules slapped on 💅 The syntax of valid digit maps is specified in ABNF [RFC 2234]. The grammar in this section is only there for illustration 🧚 and if it ever disagrees with the definition of digitMap in Annex B, Annex B takes precedence 🙈
digitMap = (digitString / LWSP "(" LWSP digitStringList LWSP ")"
LWSP)
digitStringList = digitString *( LWSP "/" LWSP digitString )
digitString = 1*(digitStringElement)
digitStringElement = digitPosition [DOT]
digitPosition = digitMapLetter / digitMapRange
digitMapRange = ("x" / LWSP "[" LWSP digitLetter LWSP "]" LWSP)
digitLetter = *((DIGIT "-" DIGIT) /digitMapLetter)
digitMapLetter = DIGIT ;digits 0-9
/ %x41-4B / %x61-6B ;a-k and A-K
/ "L" / "S" ;Inter-event timers
;(long, short)
/ "Z" ;Long duration event
DOT = %x2E ; "."
LWSP = *(WSP / COMMENT / EOL)
WSP = SP / HTAB
COMMENT = ";" *(SafeChar / RestChar / WSP) EOL
EOL = (CR [LF]) / LF
SP = %x20
HTAB = %x09
CR = %x0D
LF = %x0A
SafeChar = DIGIT / ALPHA / "+" / "-" / "&" / "!" / "_" / "/" /
"'" / "?" / "@" / "^" / "`" / "~" / "*" / "$" / "\" /
"(" / ")" / "%" / "."
RestChar = ";" / "[" / "]" / "{" / "}" / ":" / "," / "#" /
"<" / ">" / "=" / %x22
DIGIT = %x30-39 ; digits 0 through 9
ALPHA = %x41-5A / %x61-7A ; A-Z, a-zA path name is also a string with syntactic restrictions on it 🦋 The ABNF production that defines it is copied over from Annex B.
PathName = NAME *(["/"] ["*"] ["@"] (ALPHA / DIGIT)) ["*"]
NAME = ALPHA *63(ALPHA / DIGIT / "_" )ANNEX B TEXT ENCODING OF THE PROTOCOL (NORMATIVE) 🌈
B.1 Coding of wildcards 🎀
bestie, in a text encoding the TerminationIDs can be pretty much anything 🍓 but if you pick your names judiciously, the wildcard character "" becomes way more useful 🧚 When it shows up, it will "match" every TerminationID that has the same characters before and after it (if that makes sense for the name). So if you had TerminationIDs R13/3/1, R13/3/2 and R13/3/3, the TerminationID R13/3/ would catch all three of them 🫶
There are some situations where ALL Terminations must be referred to. For that, the TerminationID "*" does the job, and it's literally called ALL 👑 And the CHOOSE TerminationID "$" is how you signal to the MG that it has to create an ephemeral Termination or select an idle physical Termination 🔥
B.2 ABNF specification 💜
the protocol syntax is written in ABNF according to RFC2234 ✨ Here's the whole vibe:
; Boolean values, indicated in the text as True and False, are
; encoded as "On" and "Off", respectively, in the ABNF.
megacoMessage = LWSP [authenticationHeader SEP ] message
authenticationHeader = AuthToken EQUAL SecurityParmIndex COLON
SequenceNum COLON AuthData
SecurityParmIndex = "0x" 8(HEXDIG)
SequenceNum = "0x" 8(HEXDIG)
AuthData = "0x" 24*64(HEXDIG)
message = MegacopToken SLASH Version SEP mId SEP messageBody
; The version of the protocol defined here is equal to 1.
messageBody = ( errorDescriptor / transactionList )
transactionList = 1*( transactionRequest / transactionReply /
transactionPending / transactionResponseAck )
;Use of response acks is dependent on underlying transport
transactionPending = PendingToken EQUAL TransactionID LBRKT RBRKT
transactionResponseAck = ResponseAckToken LBRKT transactionAck
*(COMMA transactionAck) RBRKT
transactionAck = transactionID / (transactionID "-" transactionID)
transactionRequest = TransToken EQUAL TransactionID LBRKT
actionRequest *(COMMA actionRequest) RBRKT
actionRequest = CtxToken EQUAL ContextID LBRKT ((
contextRequest [COMMA commandRequestList])
/ commandRequestList) RBRKT
contextRequest = ((contextProperties [COMMA contextAudit])
/ contextAudit)okay the grammar keeps going, so let's keep the rules exact 💅✨
contextProperties = contextProperty *(COMMA contextProperty)
; at-most-once
contextProperty = (topologyDescriptor / priority / EmergencyToken)
contextAudit = ContextAuditToken LBRKT
contextAuditProperties *(COMMA
contextAuditProperties) RBRKT
; at-most-once
contextAuditProperties = ( TopologyToken / EmergencyToken /
PriorityToken )
commandRequestList= ["O-"] commandRequest *(COMMA ["O-"]
commandRequest)
commandRequest = ( ammRequest / subtractRequest / auditRequest
/ notifyRequest / serviceChangeRequest)
transactionReply = ReplyToken EQUAL TransactionID LBRKT
[ ImmAckRequiredToken COMMA]
( errorDescriptor / actionReplyList ) RBRKT
actionReplyList = actionReply *(COMMA actionReply )
actionReply = CtxToken EQUAL ContextID LBRKT
( errorDescriptor / commandReply ) RBRKT
commandReply = (( contextProperties [COMMA commandReplyList] )
/ commandReplyList )
commandReplyList = commandReplys *(COMMA commandReplys )
commandReplys = (serviceChangeReply / auditReply / ammsReply
/ notifyReply )
;Add Move and Modify have the same request parameters
ammRequest = (AddToken / MoveToken / ModifyToken ) EQUAL
TerminationID [LBRKT ammParameter *(COMMA
ammParameter) RBRKT]
;at-most-once
ammParameter = (mediaDescriptor / modemDescriptor /
muxDescriptor / eventsDescriptor /
signalsDescriptor / digitMapDescriptor /
eventBufferDescriptor / auditDescriptor)
ammsReply = (AddToken / MoveToken / ModifyToken /
SubtractToken ) EQUAL TerminationID [ LBRKT
terminationAudit RBRKT ]
subtractRequest = ["W-"] SubtractToken EQUAL TerminationID
[ LBRKT auditDescriptor RBRKT]
auditRequest = ["W-"] (AuditValueToken / AuditCapToken )
EQUAL TerminationID LBRKT auditDescriptor RBRKT
auditReply = (AuditValueToken / AuditCapToken )
( contextTerminationAudit / auditOther)
auditOther = EQUAL TerminationID LBRKT
terminationAudit RBRKT
terminationAudit = auditReturnParameter *(COMMA
auditReturnParameter)
contextTerminationAudit = EQUAL CtxToken ( terminationIDList /
LBRKT errorDescriptor RBRKT )
auditReturnParameter = (mediaDescriptor / modemDescriptor /
muxDescriptor / eventsDescriptor /
signalsDescriptor / digitMapDescriptor /
observedEventsDescriptor / eventBufferDescriptor /
statisticsDescriptor / packagesDescriptor /
errorDescriptor / auditItem )
auditDescriptor = AuditToken LBRKT [ auditItem
*(COMMA auditItem) ] RBRKT
notifyRequest = NotifyToken EQUAL TerminationID
LBRKT ( observedEventsDescriptor
[ COMMA errorDescriptor ] ) RBRKT
notifyReply = NotifyToken EQUAL TerminationID
[ LBRKT errorDescriptor RBRKT ]
serviceChangeRequest = ServiceChangeToken EQUAL TerminationID
LBRKT serviceChangeDescriptor RBRKT
serviceChangeReply = ServiceChangeToken EQUAL TerminationID
[LBRKT (errorDescriptor /
serviceChangeReplyDescriptor) RBRKT]
errorDescriptor = ErrorToken EQUAL ErrorCode
LBRKT [quotedString] RBRKT
ErrorCode = 1*4(DIGIT) ; could be extended
TransactionID = UINT32
mId = (( domainAddress / domainName )
[":" portNumber]) / mtpAddress / deviceName
; ABNF allows two or more consecutive "." although it is meaningless
; in a domain name.
domainName = "<" (ALPHA / DIGIT) *63(ALPHA / DIGIT / "-" /
".") ">"
deviceName = pathNAME
;The values 0x0, 0xFFFFFFFE and 0xFFFFFFFF are reserved.
ContextID = (UINT32 / "*" / "-" / "$")
domainAddress = "[" (IPv4address / IPv6address) "]"
;RFC2373 contains the definition of IP6Addresses.
IPv6address = hexpart [ ":" IPv4address ]
IPv4address = V4hex DOT V4hex DOT V4hex DOT V4hex
V4hex = 1*3(DIGIT) ; "0".."225"
; this production, while occurring in RFC2373, is not referenced
; IPv6prefix = hexpart SLASH 1*2DIGIT
hexpart = hexseq "::" [ hexseq ] / "::" [ hexseq ] / hexseq
hexseq = hex4 *( ":" hex4)
hex4 = 1*4HEXDIG
portNumber = UINT16
; An mtp address is two octets long
mtpAddress = MTPToken LBRKT octetString RBRKT
terminationIDList = LBRKT TerminationID *(COMMA TerminationID)
RBRKT
; Total length of pathNAME must not exceed 64 chars.
pathNAME = ["*"] NAME *("/" / "*"/ ALPHA / DIGIT /"_" / "$" )
["@" pathDomainName ]
; ABNF allows two or more consecutive "." although it is meaningless
; in a path domain name.
pathDomainName = (ALPHA / DIGIT / "*" )
*63(ALPHA / DIGIT / "-" / "*" / ".")
TerminationID = "ROOT" / pathNAME / "$" / "*"
mediaDescriptor = MediaToken LBRKT mediaParm *(COMMA mediaParm)
RBRKT
; at-most-once per item
; and either streamParm or streamDescriptor but not both
mediaParm = (streamParm / streamDescriptor /
terminationStateDescriptor)
; at-most-once
streamParm = ( localDescriptor / remoteDescriptor /
localControlDescriptor )
streamDescriptor = StreamToken EQUAL StreamID LBRKT streamParm
*(COMMA streamParm) RBRKT
localControlDescriptor = LocalControlToken LBRKT localParm
*(COMMA localParm) RBRKT
; at-most-once per item
localParm = ( streamMode / propertyParm /
reservedValueMode
/ reservedGroupMode )
reservedValueMode = ReservedValueToken EQUAL ( "ON" / "OFF" )
reservedGroupMode = ReservedGroupToken EQUAL ( "ON" / "OFF" )
streamMode = ModeToken EQUAL streamModes
streamModes = (SendonlyToken / RecvonlyToken /
SendrecvToken /
InactiveToken / LoopbackToken )
propertyParm = pkgdName parmValue
parmValue = (EQUAL alternativeValue/ INEQUAL VALUE)
alternativeValue = ( VALUE
/ LSBRKT VALUE *(COMMA VALUE) RSBRKT
; sublist (i.e. A AND B AND ...)
/ LBRKT VALUE *(COMMA VALUE) RBRKT
; alternatives (i.e. A OR B OR ...)
/ LSBRKT VALUE COLON VALUE RSBRKT )
; range
INEQUAL = LWSP (">" / "<" / "#" ) LWSP
LSBRKT = LWSP "[" LWSP
RSBRKT = LWSP "]" LWSP
localDescriptor = LocalToken LBRKT octetString RBRKT
remoteDescriptor = RemoteToken LBRKT octetString RBRKT
eventBufferDescriptor= EventBufferToken LBRKT eventSpec
*( COMMA eventSpec ) RBRKT
eventSpec = pkgdName [ LBRKT eventSpecParameter
*(COMMA eventSpecParameter) RBRKT ]
eventSpecParameter = (eventStream / eventOther)
eventBufferControl = BufferToken EQUAL ( "OFF" / LockStepToken )
terminationStateDescriptor = TerminationStateToken LBRKT
terminationStateParm *( COMMA terminationStateParm )
RBRKT
; at-most-once per item
terminationStateParm =(propertyParm / serviceStates /
eventBufferControl )
serviceStates = ServiceStatesToken EQUAL ( TestToken /
OutOfSvcToken / InSvcToken )
muxDescriptor = MuxToken EQUAL MuxType terminationIDList
MuxType = ( H221Token / H223Token / H226Token /
V76Token / extensionParameter )
StreamID = UINT16
pkgdName = (PackageName SLASH ItemID) ;specific item
/ (PackageName SLASH "*") ;all events in package
/ ("*" SLASH "*") ; all events supported by the MG
PackageName = NAME
ItemID = NAME
eventsDescriptor = EventsToken EQUAL RequestID LBRKT
requestedEvent *( COMMA requestedEvent ) RBRKT
requestedEvent = pkgdName [ LBRKT eventParameter
*( COMMA eventParameter ) RBRKT ]
; at-most-once each of KeepActiveToken , eventDM and eventStream
;at most one of either embedWithSig or embedNoSig but not both
;KeepActiveToken and embedWithSig must not both be present
eventParameter = ( embedWithSig / embedNoSig / KeepActiveToken
/eventDM / eventStream / eventOther )
embedWithSig = EmbedToken LBRKT signalsDescriptor
[COMMA embedFirst ] RBRKT
embedNoSig = EmbedToken LBRKT embedFirst RBRKT
; at-most-once of each
embedFirst = EventsToken EQUAL RequestID LBRKT
secondRequestedEvent *(COMMA secondRequestedEvent) RBRKT
secondRequestedEvent = pkgdName [ LBRKT secondEventParameter
*( COMMA secondEventParameter ) RBRKT ]
; at-most-once each of embedSig , KeepActiveToken, eventDM or
; eventStream
; KeepActiveToken and embedSig must not both be present
secondEventParameter = ( EmbedSig / KeepActiveToken / eventDM /
eventStream / eventOther )
embedSig = EmbedToken LBRKT signalsDescriptor RBRKT
eventStream = StreamToken EQUAL StreamID
eventOther = eventParameterName parmValue
eventParameterName = NAME
eventDM = DigitMapToken ((EQUAL digitMapName ) /
(LBRKT digitMapValue RBRKT ))
signalsDescriptor = SignalsToken LBRKT [ signalParm
*(COMMA signalParm)] RBRKT
signalParm = signalList / signalRequest
signalRequest = signalName [ LBRKT sigParameter
*(COMMA sigParameter) RBRKT ]
signalList = SignalListToken EQUAL signalListId LBRKT
signalListParm *(COMMA signalListParm) RBRKT
signalListId = UINT16
;exactly once signalType, at most once duration and every signal
;parameter
signalListParm = signalRequest
signalName = pkgdName
;at-most-once sigStream, at-most-once sigSignalType,
;at-most-once sigDuration, every signalParameterName at most once
sigParameter = sigStream / sigSignalType / sigDuration / sigOther
/ notifyCompletion / KeepActiveToken
sigStream = StreamToken EQUAL StreamID
sigOther = sigParameterName parmValue
sigParameterName = NAME
sigSignalType = SignalTypeToken EQUAL signalType
signalType = (OnOffToken / TimeOutToken / BriefToken)
sigDuration = DurationToken EQUAL UINT16
notifyCompletion = NotifyCompletionToken EQUAL (LBRKT
notificationReason *(COMMA notificationReason) RBRKTmore grammar rules are coming up next, so stay tuned, bestie 🫶🎀
okay bestie, we're deep in the grammar now and it's giving ABC-vibes 🧚💖 the first bit is all about notifications and what they're reporting back. like, which event got observed, when it got buffered, and the little parameters riding along with it 🦋
notificationReason = ( TimeOutToken / InterruptByEventToken
/ InterruptByNewSignalsDescrToken
/ OtherReasonToken )
observedEventsDescriptor = ObservedEventsToken EQUAL RequestID
LBRKT observedEvent *(COMMA observedEvent) RBRKT
;time per event, because it might be buffered
observedEvent = [ TimeStamp LWSP COLON] LWSP
pkgdName [ LBRKT observedEventParameter
*(COMMA observedEventParameter) RBRKT ]
;at-most-once eventStream, every eventParameterName at most once
observedEventParameter = eventStream / eventOther
RequestID = UINT32
modemDescriptor = ModemToken (( EQUAL modemType) /
(LSBRKT modemType *(COMMA modemType) RSBRKT))
[ LBRKT NAME parmValue
*(COMMA NAME parmValue) RBRKT ]
; at-most-once
modemType = (V32bisToken / V22bisToken / V18Token /
V22Token / V32Token / V34Token / V90Token /
V91Token / SynchISDNToken / extensionParameter)next up is the digit map stuff, which is honestly my favourite ngl 🔥 it's how you tell the gateway what dial strings to expect, with little timers and letters doing their thing 🎀
digitMapDescriptor = DigitMapToken EQUAL
( ( LBRKT digitMapValue RBRKT )
/ (digitMapName [ LBRKT digitMapValue RBRKT ]) )
digitMapName = NAME
digitMapValue = ["T" COLON Timer COMMA] ["S" COLON Timer COMMA]
["L" COLON Timer COMMA] digitMap
Timer = 1*2DIGIT
digitMap =
digitString / LWSP "(" LWSP digitStringList LWSP ")" LWSP
digitStringList = digitString *( LWSP "|" LWSP digitString )
digitString = 1*(digitStringElement)
digitStringElement = digitPosition [DOT]
digitPosition = digitMapLetter / digitMapRange
digitMapRange = ("x" / LWSP "[" LWSP digitLetter LWSP "]" LWSP)
digitLetter = *((DIGIT "-" DIGIT ) / digitMapLetter)
digitMapLetter = DIGIT ;Basic event symbols
/ %x41-4B / %x61-6B ; a-k, A-K
/ "L" / "S" ;Inter-event timers (long, short)
/ "Z" ;Long duration modifierand now the audit items, which come with a little warning sticker attached 👀 ⭐
;at-most-once, and DigitMapToken and PackagesToken are not allowed
;in AuditCapabilities command
auditItem = ( MuxToken / ModemToken / MediaToken /
SignalsToken / EventBufferToken /
DigitMapToken / StatsToken / EventsToken /
ObservedEventsToken / PackagesToken )⚠️ bestie, read that comment twice: DigitMapToken and PackagesToken are not allowed inside an AuditCapabilities command. no exceptions 💅
next comes the ServiceChange family, which is basically the gateway announcing "hey, I'm going through something" and the other side replying with its own info 🌸
serviceChangeDescriptor = ServicesToken LBRKT serviceChangeParm
*(COMMA serviceChangeParm) RBRKT
serviceChangeParm = (serviceChangeMethod / serviceChangeReason /
serviceChangeDelay / serviceChangeAddress /
serviceChangeProfile / extension / TimeStamp /
serviceChangeMgcId / serviceChangeVersion )
serviceChangeReplyDescriptor = ServicesToken LBRKT
servChgReplyParm *(COMMA servChgReplyParm) RBRKT
;at-most-once. Version is REQUIRED on first ServiceChange response
servChgReplyParm = (serviceChangeAddress / serviceChangeMgcId /
serviceChangeProfile / serviceChangeVersion )
serviceChangeMethod = MethodToken EQUAL (FailoverToken /
ForcedToken / GracefulToken / RestartToken /
DisconnectedToken / HandOffToken /
extensionParameter)
serviceChangeReason = ReasonToken EQUAL VALUE
serviceChangeDelay = DelayToken EQUAL UINT32
serviceChangeAddress = ServiceChangeAddressToken EQUAL VALUE
serviceChangeMgcId = MgcIdToken EQUAL mId
serviceChangeProfile = ProfileToken EQUAL NAME SLASH Version
serviceChangeVersion = VersionToken EQUAL Version
extension = extensionParameter parmValueand then the packages, version numbers, and timestamps, which are giving very organised energy 🍓✨
packagesDescriptor = PackagesToken LBRKT packagesItem
*(COMMA packagesItem) RBRKT
Version = 1*2(DIGIT)
packagesItem = NAME "-" UINT16
TimeStamp = Date "T" Time ; per ISO 8601:1988
; Date = yyyymmdd
Date = 8(DIGIT)
; Time = hhmmssss
Time = 8(DIGIT)
statisticsDescriptor = StatsToken LBRKT statisticsParameter
*(COMMA statisticsParameter ) RBRKT
;at-most-once per item
statisticsParameter = pkgdName EQUAL VALUE
topologyDescriptor = TopologyToken LBRKT terminationA COMMA
terminationB COMMA topologyDirection RBRKT
terminationA = TerminationID
terminationB = TerminationID
topologyDirection = BothwayToken / IsolateToken / OnewayToken
priority = PriorityToken EQUAL UINT16
extensionParameter = "X" ("-" / "+") 1*6(ALPHA / DIGIT)now the SDP bit 🎀 this is where the octet strings get their escaping situation sorted, and the comments are literally telling you to be careful with CRLF, so pay attention 💜
; octetString is used to describe SDP defined in RFC2327.
; Caution should be taken if CRLF in RFC2327 is used.
; To be safe, use EOL in this ABNF.
; Whenever "}" appears in SDP, it is escaped by "\", e.g., "\}"
octetString = *(nonEscapeChar)
nonEscapeChar = ( "\}" / %x01-7C / %x7E-FF )
quotedString = DQUOTE 1*(SafeChar / RestChar/ WSP) DQUOTE
UINT16 = 1*5(DIGIT) ; %x0-FFFF
UINT32 = 1*10(DIGIT) ; %x0-FFFFFFFF
NAME = ALPHA *63(ALPHA / DIGIT / "_" )
VALUE = quotedString / 1*(SafeChar)
SafeChar = DIGIT / ALPHA / "+" / "-" / "&" /
"!" / "_" / "/" / "'" / "?" / "@" /
"^" / "`" / "~" / "*" / "$" / "\" /
"(" / ")" / "%" / "|" / "."and last but not least, the bottom-of-the-barrel character rules and whitespace, comments, and the RestChar crew 💅🫶
EQUAL = LWSP %x3D LWSP ; "="
COLON = %x3A ; ":"
LBRKT = LWSP %x7B LWSP ; "{"
RBRKT = LWSP %x7D LWSP ; "}"
COMMA = LWSP %x2C LWSP ; ","
DOT = %x2E ; "."
SLASH = %x2F ; "/"
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39 ; 0-9
DQUOTE = %x22 ; " (Double Quote)
HEXDIG = ( DIGIT / "A" / "B" / "C" / "D" / "E" / "F" )
SP = %x20 ; space
HTAB = %x09 ; horizontal tab
CR = %x0D ; Carriage return
LF = %x0A ; linefeed
LWSP = *( WSP / COMMENT / EOL )
EOL = (CR [LF] / LF )
WSP = SP / HTAB ; white space
SEP = ( WSP / EOL / COMMENT) LWSP
COMMENT = ";" *(SafeChar/ RestChar / WSP / %x22) EOL
RestChar = ";" / "[" / "]" / "{" / "}" / ":" / "," / "#"
/
"<" / ">" / "="that's the whole grammar wrapped up for this bit, bestie! 🌈✨
AddToken = ("Add" / "A")
AuditToken = ("Audit" / "AT")
AuditCapToken = ("AuditCapability" / "AC")
AuditValueToken = ("AuditValue" / "AV")
AuthToken = ("Authentication" / "AU")
BothwayToken = ("Bothway" / "BW")
BriefToken = ("Brief" / "BR")
BufferToken = ("Buffer" / "BF")
CtxToken = ("Context" / "C")
ContextAuditToken = ("ContextAudit" / "CA")
DigitMapToken = ("DigitMap" / "DM")
DisconnectedToken = ("Disconnected" / "DC")
DelayToken = ("Delay" / "DL")
DurationToken = ("Duration" / "DR")
EmbedToken = ("Embed" / "EB")
EmergencyToken = ("Emergency" / "EM")
ErrorToken = ("Error" / "ER")
EventBufferToken = ("EventBuffer" / "EB")
EventsToken = ("Events" / "E")
FailoverToken = ("Failover" / "FL")
ForcedToken = ("Forced" / "FO")
GracefulToken = ("Graceful" / "GR")
H221Token = ("H221" )
H223Token = ("H223" )
H226Token = ("H226" )
HandOffToken = ("HandOff" / "HO")
ImmAckRequiredToken = ("ImmAckRequired" / "IA")
InactiveToken = ("Inactive" / "IN")
IsolateToken = ("Isolate" / "IS")
InSvcToken = ("InService" / "IV")
InterruptByEventToken = ("IntByEvent" / "IBE")
InterruptByNewSignalsDescrToken
= ("IntBySigDescr" / "IBS")
KeepActiveToken = ("KeepActive" / "KA")
LocalToken = ("Local" / "L")
LocalControlToken = ("LocalControl" / "O")
LockStepToken = ("LockStep" / "SP")
LoopbackToken = ("Loopback" / "LB")
MediaToken = ("Media" / "M")
MegacopToken = ("MEGACO" / "!")
MethodToken = ("Method" / "MT")
MgcIdToken = ("MgcIdToTry" / "MG")
ModeToken = ("Mode" / "MO")
ModifyToken = ("Modify" / "MF")
ModemToken = ("Modem" / "MD")
MoveToken = ("Move" / "MV")
MTPToken = ("MTP")
MuxToken = ("Mux" / "MX")
NotifyToken = ("Notify" / "N")
NotifyCompletionToken = ("NotifyCompletion" / "NC")
ObservedEventsToken = ("ObservedEvents" / "OE")
OnewayToken = ("Oneway" / "OW")
OnOffToken = ("OnOff" / "OO")
OtherReasonToken = ("OtherReason" / "OR")
OutOfSvcToken = ("OutOfService" / "OS")
PackagesToken = ("Packages" / "PG")
PendingToken = ("Pending" / "PN")
PriorityToken = ("Priority" / "PR")
ProfileToken = ("Profile" / "PF")
ReasonToken = ("Reason" / "RE")
RecvonlyToken = ("ReceiveOnly" / "RC")
ReplyToken = ("Reply" / "P")
RestartToken = ("Restart" / "RS")
RemoteToken = ("Remote" / "R")
ReservedGroupToken = ("ReservedGroup" / "RG")
ReservedValueToken = ("ReservedValue" / "RV")
SendonlyToken = ("SendOnly" / "SO")
SendrecvToken = ("SendReceive" / "SR")
ServicesToken = ("Services" / "SV")
ServiceStatesToken = ("ServiceStates" / "SI")
ServiceChangeToken = ("ServiceChange" / "SC")
ServiceChangeAddressToken = ("ServiceChangeAddress" / "AD")
SignalListToken = ("SignalList" / "SL")
SignalsToken = ("Signals" / "SG")
SignalTypeToken = ("SignalType" / "SY")
StatsToken = ("Statistics" / "SA")
StreamToken = ("Stream" / "ST")
SubtractToken = ("Subtract" / "S")
SynchISDNToken = ("SynchISDN" / "SN")
TerminationStateToken = ("TerminationState" / "TS")
TestToken = ("Test" / "TE")
TimeOutToken = ("TimeOut" / "TO")
TopologyToken = ("Topology" / "TP")
TransToken = ("Transaction" / "T")
ResponseAckToken = ("TransactionResponseAck"/ "K")
V18Token = ("V18")
V22Token = ("V22")
V22bisToken = ("V22b")
V32Token = ("V32")
V32bisToken = ("V32b")
V34Token = ("V34")
V76Token = ("V76")
V90Token = ("V90")
V91Token = ("V91")
VersionToken = ("Version" / "V")ANNEX C TAGS FOR MEDIA STREAM PROPERTIES (NORMATIVE) ✨
okay, so this annex is where the media stream properties get their tag numbers 🏷️ When binary encoding is used, the parameters for Local and Remote descriptors are sent as tag-value pairs 🎀. This annex lists the property names (PropertyID), the tags (Property Tag), the type of each property (Type), and the values (Value) 💖. Here's the important bit: when the Value field has a reference in it, the value is "information" 🤓, and the reference is where the normative values live 📚. If a Value field doesn't have a reference, the values in that field can be considered "normative" 💅.
Tags are written as hexadecimal numbers in this annex 🌸. When an MGC sets the value of a property, it may underspecify the value using one of the mechanisms in section 7.1.1 🦋. For an "enumeration" type, the value is written as the number in brackets, like Send(0) or Receive(1) 🧚. And when a type is smaller than one octet, the value shall be stored in the low-order bits of an octet string of size 1 🫶.
C.1 General Media Attributes 🎀
Okay, here's the whole table of general media attributes. Some of the rows have notes, a reference to ITU-T, and a reference to RFC 1890, so read the little footnote-y lines too 👀.
+-------------------+------+-------------+---------------------------+
| PropertyID | Tag | Type | Value |
+-------------------+------+-------------+---------------------------+
| Media | 1001 | Enumeration | Audio(0), Video(1), |
| | | | Data(2) |
+-------------------+------+-------------+---------------------------+
| Transmission mode | 1002 | Enumeration | Send(0), Receive(1), |
| | | | Send&Receive(2) |
+-------------------+------+-------------+---------------------------+
| Number of | 1003 | Unsigned | 0-255 |
| Channels | | Integer | |
+-------------------+------+-------------+---------------------------+
| Sampling rate | 1004 | Unsigned | 0-2^32 |
| | | Integer | |
+-------------------+------+-------------+---------------------------+
| Bitrate | 1005 | Integer | (0..4294967295) |
| | | | Note - units of 100 bit/s |
+-------------------+------+-------------+---------------------------+
| ACodec | 1006 | Octet | Audio Codec Type |
| | | String | |
+-------------------+------+-------------+---------------------------+
| Reference: ITU-T Rec. Q.765 - Application transport mechanism. |
| Non-ITU codecs are defined with the appropriate standards |
| organisation under a defined Organizational Identitifier. |
+-------------------+------+-------------+---------------------------+
| Samplepp | 1007 | Unsigned | Maximum samples or frames |
| | | Integer | per packet: 0-65535 |
+-------------------+------+-------------+---------------------------+
| Silencesupp | 1008 | BOOLEAN | Silence Suppression: |
| | | | True/false |
+-------------------+------+-------------+---------------------------+
| Encrypttype | 1009 | Octet | Ref.: rec. H.245 |
| | | String | |
+-------------------+------+-------------+---------------------------+
| Encryptkey | 100A | Octet | SIZE(0..65535) |
| | | String | Encryption key |
+-------------------+------+-------------+---------------------------+
| Ref.: rec. H.235 |
+-------------------+------+-------------+---------------------------+
| Echocanc | 100B | Enumeration | Echo Canceller: Off(0), |
| | | | G.165(1), G168(2) |
+-------------------+------+-------------+---------------------------+
| Gain | 100C | Unsigned | Gain in db: 0-65535 |
| | | Integer | |
+-------------------+------+-------------+---------------------------+
| Jitterbuff | 100D | Unsigned | Jitter buffer size in ms: |
| | | Integer | 0-65535 |
+-------------------+------+-------------+---------------------------+
| PropDelay | 100E | Unsigned | Propagation Delay: |
| | | Integer | 0..65535 |
+-------------------+------+-------------+---------------------------+
| Maximum propagation delay in milliseconds for the bearer |
| connection between two media gateways. The maximum delay will be |
| dependent on the bearer technology. |
+-------------------+------+-------------+---------------------------+
|RTPpayload | 100F | integer | Payload type in RTP |
+-------------------+------+-------------+---------------------------+
| Profile for Audio and Video Conferences with Minimal Control |
| Ref.: RFC 1890 |
+--------------------------------------------------------------------+that's the whole table, bestie 💜 every tag number, type and value is exactly as written, so you can use it with zero guesswork ✨
C.2. Mux Properties ✨
okay bestie, this is the mux properties table 🎀 every property here has its own PropertyID, Tag, Type, and Value, and the Reference lines point at the ITU H.245 parameter structures. it's giving organized 💅
+-------------------+------+----------+------------------------------+
| PropertyID | Tag | Type | Value |
+-------------------+------+----------+------------------------------+
| H.221 | 2001 | Octet | Ref.: rec. H.245, |
| | | String | H222LogicalChannelParameters |
+-------------------+------+----------+------------------------------+
| H223 | 2002 | Octet | Ref.: rec. H.245, |
| | | String | H223LogicalChannelParameters |
+-------------------+------+----------+------------------------------+
| V76 | 2003 | Octet | Ref.: rec. H.245, |
| | | String | V76LogicalChannelParameters |
+-------------------+------+-------------+---------------------------+
| H2250 | 2004 | Octet | Ref.: rec. H.245, |
| | | String | H2250LogicalChannelParameters|
+-------------------+------+----------+------------------------------+C.3. General bearer properties 🦋
next up are the general bearer properties 🌸 Mediatx tells you the media transport type, and the list is TDM Circuit(0), ATM(1), FR(2), Ipv4(3), Ipv6(4), and then the ... tail, so it's open-ended ✨ BIR depends on the transport technology, and NSAP has its own reference to ITU X.213 Annex A 🧚
+-------------------+------+-------------+---------------------------+
| PropertyID | Tag | Type | Value |
+-------------------+------+-------------+---------------------------+
| Mediatx | 3001 | Enumeration | Media Transport Type: |
+-------------------+------+-------------+---------------------------+
| TDM Circuit(0), ATM(1), FR(2), Ipv4(3), Ipv6(4), ... |
+-------------------+------+-------------+---------------------------+
| BIR | 3002 | 4 OCTET | Value depends on transport|
| | | | technology |
+-------------------+------+-------------+---------------------------+
| NSAP | 3003 | 1-20 OCTETS | See NSAP: |
+-------------------+------+-------------+---------------------------+
| Reference: ITU X.213 Annex A |
+--------------------------------------------------------------------+C.4. General ATM properties 💜
and now the big one, the ATM properties 😭 there are a LOT of them, and each one is a whole vibe. AESA is the ATM End System Address (20 OCTETS), VPVC is the VPCI/VCI pair, and then it just keeps going: service categories, bearer class, transfer capability, clipping susceptibility, connection configuration, cell rates and burst sizes for both CLP=0 and CLP=0+1, best effort, tagging, frame discard, CDV, cell loss ratio, transit delay, QoS classes, and finally the AAL type 🔥 the QosClass table and the AALType values are spelled out inside the block so nothing gets lost, periodt 🫶
+------------------+---------+--------------+------------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+------------------+---------+--------------+------------------------+
| AESA | 4001 | 20 OCTETS | ATM End System Address |
+------------------+---------+--------------+------------------------+
| VPVC | 4002 | 2 x 16 bit | VPCI/VCI |
| | | integer | |
| Reference ITU-T Recommendation Q.2931 |
+------------------+---------+--------------+------------------------+
| SC | 4003 | Enumeration | Service Category |
| Reference: ATM Forum UNI 4.0: |
| CBR(0), nrt-VBR1(1), nrt-VBR2(2), nrt-VBR3(3), rt-VBR1(4), rt- |
| VBR2(5), rt-VBR3(6), UBR1(7), UBR2(8), ABR(9). |
+------------------+---------+--------------+------------------------+
| BCOB | 4004 | 5 bit integer Broadband Bearer Class |
| Reference: ITU Recommendation Q.2961.2 |
+------------------+---------+--------------+------------------------+
| BBTC | 4005 | 7 bit integer| Broadband Transfer |
| | | | Capability |
| Reference: ITU Recommendation Q.2961 |
+------------------+---------+--------------+------------------------+
| ATC | 4006 | Enumeration | I.371 ATM Traffic |
| | | | Capability |
| Reference: ITU Recommendation I.371: |
| DBR(0), SBR1(1), SBR2(2), SBR3(3), ABT/IT(4), ABT/DT(5), ABR(6) |
+------------------+---------+--------------+------------------------+
| STC | 4007 | 2 bits | Susceptibility to |
| | | | clipping |
| Reference: ITU Recommendation Q.2931 |
| 00 Susceptible |
| 01 Not-susceptible |
+------------------+---------+--------------+------------------------+
| UPCC | 4008 | 2 bits | User Plane Connection |
| | | | configuration: |
| Reference: ITU Recommendation Q.2931 |
| 00 Pt-to-pt, |
| 01 Pt-to-mpt |
+------------------+---------+--------------+------------------------+
| PCR0 | 4009 | 24 bit | Peak Cell Rate (For |
| | | integer | CLP=0) |
| Reference: ITU Recommendation Q.2931 |
+------------------+---------+--------------+------------------------+
| SCR0 | 400A | 24 bit | Sustainable Cell Rate |
| | | integer | (For CLP=0) |
| Reference: ITU Recommendation Q.2961 |
+------------------+---------+--------------+------------------------+
| MBS0 | 400B | 24 bit | Maximum Burst Size (For|
| | | integer | CLP=0) |
| Reference: ITU Recommendation Q.2961 |
+------------------+---------+--------------+------------------------+
| PCR1 | 400C | 24 bit | Peak Cell Rate (For |
| | | integer | CLP=0+1) |
| Reference: ITU Recommendation Q.2931 |
+------------------+---------+--------------+------------------------+
| SCR1 | 400D | 24 bit | Sustainable Cell Rate |
| | | integer | (For CLP=0+1) |
| Reference: ITU Recommendation Q.2961 |
+------------------+---------+--------------+------------------------+
| MBS1 | 400E | 24 bit | Maximum Burst Size (For|
| | | integer | CLP=0+1) |
| Reference: ITU Recommendation Q.2961 |
+------------------+---------+--------------+------------------------+
| BEI | 400F | Boolean | Best Effort Indicator |
| Reference: ATM Forum UNI 4.0: |
| 0 -- do not include BEI in ATM signalling |
| 1 -- include BEI in ATM signalling |
+------------------+---------+--------------+------------------------+
| TI | 4010 | Boolean | Tagging |
| Reference: ITU-T Recommendation Q.2961 |
| 0 -- tagging is not allowed |
| 1 -- tagging is requested |
+------------------+---------+--------------+------------------------+
| FD | 4011 | Boolean | Frame Discard |
| Reference: ATM Forum UNI 4.0: |
| 0 -- no frame discard is allowed |
| 1 -- frame discard is allowed |
+------------------+---------+--------------+------------------------+
| A2PCDV | 4012 | 24 bit | Acceptable 2-point CDV |
| | | integer | |
| Reference: ITU-T Recommendation Q.2965.2 |
+------------------+---------+--------------+------------------------+
| C2PCDV | 4013 | 24 bit | Cumulative 2-point CDV |
| | | integer | |
| Reference: ITU-T Recommendation Q.2965.2 |
+------------------+---------+--------------+------------------------+
| APPCDV | 4014 | 24 bit | Acceptable P-P CDV |
| | | integer | |
| Reference: ATM Forum UNI 4.0 |
+------------------+---------+--------------+------------------------+
| CPPCDV | 4015 | 24 bit | Cumulative P-P CDV |
| | | integer | |
| Reference: ATM Forum UNI 4.0 |
+------------------+---------+--------------+------------------------+
| ACLR | 4016 | 8 bit integer| Acceptable Cell Loss |
| | | | Ratio |
| Reference: ITU-T Recommendation Q.2965.2, ATM Forum UNI 4.0 |
+------------------+---------+--------------+------------------------+
| MEETD | 4017 | 16 bit | Maximum end-to-end |
| | | integer | transit delay |
| Reference: ITU-T Recommendation Q.2965.2, ATM Forum UNI 4.0 |
+------------------+---------+--------------+------------------------+
| CEETD | 4018 | 16 bit | Cumulative end-to-end |
| | | integer | transit delay |
| Reference: ITU-T Recommendation Q.2965.2, ATM Forum UNI 4.0 |
+------------------+---------+--------------+------------------------+
| QosClass | 4019 | Integer 0-5 | QOS Class |
| Reference: ITU-T Recommendation Q.2965.1 |
| Qos Class Meaning |
| --------- ------------------------------- |
| 0 Default QoS associated with the ATC |
| as defined in ITU Rec. Q.2961.2 |
| 1 Stringent |
| 2 Tolerant |
| 3 Bi-level |
| 4 Unbounded |
| 5 Stringent bi-level |
+------------------+---------+--------------+------------------------+
| AALType | 401A | 1 octet | AAL Type |
| Reference: ITU Recommendation Q.2931 |
| 00000000 AAL for voice |
| 00000001 AAL type 1 |
| 00000010 AAL type 2 |
| 00000011 AAL type 3/4 |
| 00000101 AAL type 5 |
| 00010000 user defined AAL |
+------------------+---------+--------------+------------------------+C.5 Frame Relay 🦋
okay so the Frame Relay properties are giving main character energy 💅 here's the whole table, bestie:
+-------------------+------+-------------+---------------------------+
| PropertyID | Tag | Type | Value |
+-------------------+------+-------------+---------------------------+
| DLCI | 5001 | Unsigned | Data link connection id |
| | | Integer | |
+-------------------+------+-------------+---------------------------+
| CID | 5002 | Unsigned | sub-channel id. |
| | | Integer | |
+-------------------+------+-------------+---------------------------+
| SID/Noiselevel | 5003 | Unsigned | silence insertion |
| | | Integer | descriptor |
+-------------------+------+-------------+---------------------------+
| Primary Payload |5004 | Unsigned | Primary Payload Type |
| Type | | Integer | Covers FAX and codecs |
+-------------------+------+-------------+---------------------------+so DLCI is tag 5001 and it's the data link connection id 🌸, CID is 5002 (sub-channel id, ngl so cute), SID/Noiselevel is 5003 for the silence insertion descriptor ✨, and Primary Payload Type is 5004, which covers FAX and codecs 🎀
C.6 IP 🌈
the IP properties are literally the building blocks of the whole vibe 🫶 here's the table:
+-------------------+------+-------------+---------------------------+
| PropertyID | Tag | Type | Value |
+-------------------+------+-------------+---------------------------+
| IPv4 | 6001 | 32 BITS | Ipv4Address|Ipv4Address: |
+-------------------+------+-------------+---------------------------+
| Reference: IETF RFC791 |
+-------------------+------+-------------+---------------------------+
| IPv6 | 6002 | 128 BITS | IPv6 Address: |
+-------------------+------+-------------+---------------------------+
| Reference: IETF RFC2460 |
+-------------------+------+-------------+---------------------------+
| Port | 6003 | Unsigned |0-65535 |
| | | Integer | |
+-------------------+------+-------------+---------------------------+
| Porttype | 6004 | enumerated | TCP(0), UDP(1), SCTP(2) |
+-------------------+------+-------------+---------------------------+so IPv4 is tag 6001 (32 bits, referenced to RFC791 🧚), IPv6 is 6002 (128 bits, referenced to RFC2460 💜), Port is 6003 and takes 0-65535 🍓, and Porttype is 6004 with TCP(0), UDP(1), SCTP(2) 👑 the way the numbering just goes 6001 → 6004 is so clean 😭
C.7 ATM AAL2 💖
ATM AAL2 is where things get a bit more layered, but we're going to slay it anyway 💅 here's the table:
+-----------+-------+-------------------------+----------------------+
| PropertyID| Tag n | Type | Value |
+-----------+-------+-------------------------+----------------------+
| AESA | 7001 | 20 OCTETS | AAL2 service endpoint |
| | | | address |
+-----------+-------+--------------------------+---------------------+
| as defined in Reference: ITU Recommendation Q.2630.1 |
| ESEA |
| NSEA |
+-----------+-------+-------------------------+----------------------+
| BIR |See C.3| 4 OCTETS | Served user |
| | | | reference |
+-----------+-------+-------------------------+----------------------+
| as defined in Reference: ITU Recommendation Q.2630.1 SUGR |
+-----------+-------+-------------------------+----------------------+
| ALC | 7002 | 12 OCTETS | AAL2 link |
| | | | characteristics |
+-----------+-------+-------------------------+----------------------+
| as defined in Reference: ITU Recommendation Q.2630.1 |
| max/average CPS-SDU bitrate, |
| max/average CPS-SDU size |
+-----------+-------+-------------------------+----------------------+
| SSCS | 7003 | I.366.2: | Service specific |
| | | audio (8 OCTETS) | convergence sublayer |
| | | multirate (3 OCTETS) | information |
| | | or I.366.1: | |
| | | SAR-assured (14 OCTETS)/| |
| | | unassured (7 OCTETS) | |
+-----------+-------+-------------------------+----------------------+
| as defined in Reference: Q.2630.1 and used in I.366.1 and I.366.2 |
| I.366.2: audio/multirate |
| I.366.1: SAR-assured/unassured |
+-----------+-------+-------------------------+----------------------+
| SUT | 7004 | 1..254 octets |Served user transport |
| | | | parameter |
+-----------+-------+-------------------------+----------------------+
| as defined in Reference: ITU Recommendation Q.2630.1 |
| TCI | 7005 |BOOLEAN | Test connection |
| | | | indicator |
+-----------+-------+-------------------------+----------------------+
| as defined in Reference: ITU Recommendation Q.2630.1 |
+-----------+-------+-------------------------+----------------------+
| Timer_CU | 7006 |32 bit integer | Timer-CU: |
+-----------+-------+-------------------------+----------------------+
| Milliseconds to hold partially filled cell before sending. |
+-----------+-------+-------------------------+----------------------+
| MaxCPSSDU | 7007 | 8 bit integer | Maximum Common Part |
| | | | Sublayer Service |
| | | | Data Unit |
+-----------+-------+-------------------------+----------------------+
| Ref.: rec. Q.2630.1 |
+-----------+-------+-------------------------+----------------------+
| CID | 7008 | 8 bits | subchannel id, 0-255 |
+-----------+-------+-------------------------+----------------------+
| Ref.: rec. I.363.2 |
+--------------------------------------------------------------------+the big picture: AESA is 7001 (20 octets, AAL2 service endpoint address), BIR points at C.3 and holds 4 octets of served user reference, ALC is 7002 with 12 octets of AAL2 link characteristics 🦋, SSCS is 7003 and comes in a few flavours (audio 8 octets, multirate 3 octets, or SAR-assured 14 octets / unassured 7 octets), SUT is 7004 with 1..254 octets of served user transport parameter, TCI is 7005 as a BOOLEAN test connection indicator, Timer_CU is 7006 as a 32 bit integer measured in milliseconds to hold a partially filled cell before sending ⏱️, MaxCPSSDU is 7007 as an 8 bit integer, and CID is 7008 as 8 bits, a subchannel id from 0-255 🌈
C.8 ATM AAL1 🎀
AAL1 has its own tags and subtypes, and it's giving detail 🤌 here's the table:
+----------------+---------+-----------------+-----------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+----------------+---------+-----------------+-----------------------+
| BIR | See | 29 OCTETS | GIT (Generic |
| | Table | | Identifier Transport) |
| | C.3 | | |
| Ref.: Recommendation Q.2941.1 |
+----------------+---------+-----------------+-----------------------+
| AAL1ST | 8001 | 1 OCTET | AAL1 Subtype: |
| Reference: ITU Recommendation Q.2931 |
| 00000000 Null |
| 00000001 voiceband signal transport on 64kbit/s |
| 00000010 circuit transport |
| 00000100 high-quality audio signal transport |
| 00000101 video signal transport |
+----------------+---------+-----------------+-----------------------+
| CBRR | 8002 | 1 OCTET | CBR Rate |
| Reference: ITU Recommendation Q.2931 |
| 00000001 64 kbit/s |
| 00000100 1544 kbit/s |
| 00000101 6312 kbit/s |
| 00000110 32064 kbit/s |
| 00000111 44736 kbit/s |
| 00001000 97728 kbit/s |
| 00010000 2048 kbit/s |
| 00010001 8448 kbit/s |
| 00010010 34368 kbit/s |
| 00010011 139264 kbit/s |
| 01000000 n x 64 kbit/s |
| 01000001 n * 8 kbit/s |
+----------------+---------+-----------------+-----------------------+
| MULT | See | | Multiplier, or n x |
| | Table | | 64k/8k/300 |
| | C.9 | | |
| Reference: ITU Recommendation Q.2931 |
+----------------+---------+-----------------+-----------------------+
| SCRI | 8003 | 1 OCTECT | Source Clock Frequency|
| | | | Recovery Method |
| Reference: ITU Recommendation Q.2931 |
| 00000000 NULL |
| 00000001 SRTS |
| 00000010 ACM |
+----------------+---------+-----------------+-----------------------+
| ECM | 8004 | 1 OCTECT | Error Correction |
| | | | Method |
| Reference: ITU Recommendation Q.2931 |
| 00000000 Null |
| 00000001 FEC-LOSS |
| 00000010 FEC-DELAY |
+----------------+---------+-----------------+-----------------------+
| SDTB | 8005 | 16 bit integer | Structured Data |
| | | | Transfer Blocksize |
| Reference: ITU Recommendation I.363.1 |
| Block size of SDT CBR service |
+----------------+---------+-----------------+-----------------------+
| PFCI | 8006 | 8 bit integer | Partially filled cells|
| | | | identifier |
| Reference: ITU Recommendation I.363.1 |
| 1-47 |
+--------------------------------------------------------------------+the headline stuff: BIR is referenced to Q.2941.1 and is 29 octets of GIT (Generic Identifier Transport) 💅, AAL1ST is 8001 (1 octet, AAL1 subtype, with null, voiceband signal transport on 64kbit/s, circuit transport, high-quality audio signal transport, and video signal transport as the values), CBRR is 8002 (1 octet, CBR rate, with the rates listed above, including n x 64 kbit/s and n * 8 kbit/s), MULT points at C.9 as a multiplier, or n x 64k/8k/300 🔥, SCRI is 8003 (1 octet, source clock frequency recovery method, NULL, SRTS, or ACM), ECM is 8004 (1 octet, error correction method, Null, FEC-LOSS, or FEC-DELAY), SDTB is 8005 (16 bit integer, structured data transfer blocksize, the block size of the SDT CBR service), and PFCI is 8006 (8 bit integer, partially filled cells identifier, valued 1-47) 🦋
C.9 Bearer Capabilities 🍓
last one, bestie 🫶 and it's a quick note:
The table entries referencing ITU-T Recommendation Q.931 refer to the encoding in the bearer capability information element of Q.931, not to the low layer information element.
so anything that points to Q.931 in these tables means the bearer capability information element encoding, not the low layer one 🧚 that's the whole tea ✨
okay bestie, these are the property tables in the Bearer Capabilities bit 🎀 Each row is a property with its ID, tag, type, and value, and the fancy bit-by-bit lists tell you exactly what every code means 💅
+----------------+---------+-----------------+-----------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+----------------+---------+-----------------+-----------------------+
| TMR | 9001 | 1 OCTET | Transmission Medium |
| | | | Requirement (Q.763) |
| Reference: ITU Recommendation Q.763 |
| Bit 8 7 6 5 4 3 2 1 |
| 00000000 - speech |
| 00000001 - spare |
| 00000010 - 64 kbit/s unrestricted |
| 00000011 - 3.1 kHz audio |
| 00000100 - reserved for alternate speech (service 2)/64 kbit/s |
| unrestricted (service 1) |
| 00000101 - reserved for alternate 64 kbit/s unrestricted |
| (service 1)/speech (service 2) |
| 00000110 - 64 kbit/s preferred |
| 00000111 - 2 x 64 kbit/s unrestricted |
| 00001000 - 384 kbit/s unrestricted |
| 00001001 - 1536 kbit/s unrestricted |
| 00001010 - 1920 kbit/s unrestricted |
| 00001011 through 00001111- spare |
| 00010000 - 3 x 64 kbit/s unrestricted |
| 00010001 - 4 x 64 kbit/s unrestricted |
| 00010010 - 5 x 64 kbit/s unrestricted |
| 00010011 spare |
| 00010100 - 7 x 64 kbit/s unrestricted |
| 00010101 - 8 x 64 kbit/s unrestricted |
| 00010110 - 9 x 64 kbit/s unrestricted |
| 00010111 - 10 x 64 kbit/s unrestricted |
| 00011000 - 11 x 64 kbit/s unrestricted |
| 00011001 - 12 x 64 kbit/s unrestricted |
| 00011010 - 13 x 64 kbit/s unrestricted |
| 00011011 - 14 x 64 kbit/s unrestricted |
| 00011100 - 15 x 64 kbit/s unrestricted |
| 00011101 - 16 x 64 kbit/s unrestricted |
| 00011110 - 17 x 64 kbit/s unrestricted |
| 00011111 - 18 x 64 kbit/s unrestricted |
| 00100000 - 19 x 64 kbit/s unrestricted |
| 00100001 - 20 x 64 kbit/s unrestricted |
| 00100010 - 21 x 64 kbit/s unrestricted |
| 00100011 - 22 x 64 kbit/s unrestricted |
| 00100100 - 23x 64 kbit/s unrestricted |
| 00100101 - spare |
| 00100110 - 25 x 64 kbit/s unrestricted |
| 00100111 - 26 x 64 kbit/s unrestricted |
| 00101000 - 27 x 64 kbit/s unrestricted |
| 00101001 - 28 x 64 kbit/s unrestricted |
| 00101010 - 29 x 64 kbit/s unrestricted |
| 00101011 through 11111111 Spare |
+----------------+---------+-----------------+-----------------------+
| TMRSR | 9002 | 1 OCTET | Transmission Medium |
| | | | Requirement Subrate |
| 0 - unspecified |
| 1 - 8kbit/s |
| 2 - 16kbit/s |
| 3 - 32kbit/s |
+----------------+---------+-----------------+-----------------------+
| Contcheck | 9003 | BOOLEAN | Continuity Check |
| Reference: ITU Recommendation Q.763 |
| 0 - Not required on this circuit |
| 1 - Required on this circuit |
+----------------+---------+-----------------+-----------------------+
| ITC | 9004 | 5 BITS | Information Transfer |
| | | | Capability |
| Reference: ITU Recommendation Q.763 |
| Bits 5 4 3 2 1 |
| 00000 - Speech |
| 01000 - Unrestricted digital information |
| 01001 - Restricted digital information |
| 10000 - 3.1 kHz audio |
| 10001 - Unrestricted digital information with |
| tones/announcements |
| 11000 - Video |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| TransMode | 9005 | 2 BITS | Transfer Mode |
| Reference: ITU Recommendation Q.931 |
| Bit 2 1 |
| 00 - Circuit mode |
| 10 - Packet mode |
+----------------+---------+-----------------+-----------------------+
| TransRate | 9006 | 5 BITS | Transfer Rate |
| Reference: ITU Recommendation Q.931 |
| Bit 5 4 3 2 1 |
| 00000 - This code shall be used for packet mode calls |
| 10000 - 64 kbit/s |
| 10001 - 2 x 64 kbit/s |
| 10011 -384 kbit/s |
| 10101 -1536 kbit/s |
| 10111 -1920 kbit/s |
| 11000 - Multirate (64 kbit/s base rate) |
+----------------+---------+-----------------+-----------------------+
| MULT | 9007 | 7 BITS | Rate Multiplier |
| Reference: ITU Recommendation Q.931 |
| Any value from 2 to n (maximum number of B-channels) |
+----------------+---------+-----------------+-----------------------+
| USI | 9008 | 5 BITS | User Information Layer|
| | | | 1 Protocol |
| Reference: ITU Recommendation Q.931 |
| Bits 5 4 3 2 1 |
| 00001 - CCITT standardized rate adaption V.110 and X.30. |
| 00010 - Recommendation G.711 u-law |
| 00011 - Recommendation G.711 A-law |
| 00100 - Recommendation G.721 32 kbit/s ADPCM and Recommendation |
| I.460. |
| 00101 - Recommendations H.221 and H.242 |
| 00110 - Recommendations H.223 and H.245 |
| 00111 - Non-ITU-T standardized rate adaption. |
| 01000 - ITU-T standardized rate adaption V.120. |
| 01001 - CCITT standardized rate adaption X.31 HDLC flag |
| stuffing. |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| syncasync | 9009 | BOOLEAN | Synchronous/ |
| | | | Asynchronous |
| Reference: ITU Recommendation Q.931 |
| 0 - Synchronous data |
| 1 - Asynchronous data |
+----------------+---------+-----------------+-----------------------+
| negotiation | 900A | BOOLEAN | Negotiation |
| Reference: ITU Recommendation Q.931 |
| 0 - In-band negotiation possible |
| 1 - In-band negotiation not possible |
+----------------+---------+-----------------+-----------------------+more of this table and its friends are coming up next, so stay tuned 🦋✨
Okay so this is where the Low Layer stuff gets extra 💅 Each tag below has a name, a hex code, a size, and a little list of what every value means, and the values are EXACTLY what the spec says, so no fudging 🫶
Here's the first batch, the rate and clocking ones 🧚
+----------------+---------+-----------------+-----------------------+
| Userrate | 900B | 5 BITS | User Rate |
| Reference: ITU Recommendation Q.931 |
| Bits 5 4 3 2 1 |
| 00000 - Rate is indicated by E-bits specified in Recommendation |
| I.460 or may be negotiated in-band |
| 00001 - 0.6 kbit/s Recommendations V.6 and X.1 |
| 00010 - 1.2 kbit/s Recommendation V.6 |
| 00011 - 2.4 kbit/s Recommendations V.6 and X.1 |
| 00100 - 3.6 kbit/s Recommendation V.6 |
| 00101 - 4.8 kbit/s Recommendations V.6 and X.1 |
| 00110 - 7.2 kbit/s Recommendation V.6 |
| 00111 - 8 kbit/s Recommendation I.460 |
| 01000 - 9.6 kbit/s Recommendations V.6 and X.1 |
| 01001 - 14.4 kbit/s Recommendation V.6 |
| 01010 - 16 kbit/s Recommendation I.460 |
| 01011 - 19.2 kbit/s Recommendation V.6 |
| 01100 - 32 kbit/s Recommendation I.460 |
| 01101 - 38.4 kbit/s Recommendation V.110 |
| 01110 - 48 kbit/s Recommendations V.6 and X.1 |
| 01111 - 56 kbit/s Recommendation V.6 |
| 10010 - 57.6 kbit/s Recommendation V.14 extended |
| 10011 - 28.8 kbit/s Recommendation V.110 |
| 10100 - 24 kbit/s Recommendation V.110 |
| 10101 - 0.1345 kbit/s Recommendation X.1 |
| 10110 - 0.100 kbit/s Recommendation X.1 |
| 10111 - 0.075/1.2 kbit/s Recommendations V.6 and X.1 |
| 11000 - 1.2/0.075 kbit/s Recommendations V.6 and X.1 |
| 11001 - 0.050 kbit/s Recommendations V.6 and X.1 |
| 11010 - 0.075 kbit/s Recommendations V.6 and X.1 |
| 11011 - 0.110 kbit/s Recommendations V.6 and X.1 |
| 11100 - 0.150 kbit/s Recommendations V.6 and X.1 |
| 11101 - 0.200 kbit/s Recommendations V.6 and X.1 |
| 11110 - 0.300 kbit/s Recommendations V.6 and X.1 |
| 11111 - 12 kbit/s Recommendation V.6 |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| INTRATE | 900C | 2 BITS | Intermediate Rate |
| Reference: ITU Recommendation Q.931 |
| Bit 2 1 |
| 00 - Not used |
| 01 - 8 kbit/s |
| 10 - 16 kbit/s |
| 11 - 32 kbit/s |
+----------------+---------+-----------------+-----------------------+
| nictx | 900D | BOOLEAN | Network Independent |
| | | | Clock (NIC) on |
| | | | transmission |
| Reference: ITU Recommendation Q.931 |
| 0 - Not required to send data with network independent clock |
| 1 - Required to send data with network independent clock |
+----------------+---------+-----------------+-----------------------+
| nicrx | 900E | BOOLEAN | Network independent |
| | | | clock (NIC) on |
| | | | reception |
| Reference: ITU Recommendation Q.931 |
| 0 - Cannot accept data with network independent clock (i.e. |
| sender does not support this optional procedure) |
| 1 - Can accept data with network independent clock (i.e. sender |
| does support this optional procedure) |
+----------------+---------+-----------------+-----------------------+
| flowconttx | 900F | BOOLEAN | Flow Control on |
| | | | transmission (Tx) |
| Reference: ITU Recommendation Q.931 |
| 0 - Not required to send data with flow control mechanism |
| 1 - Required to send data with flow control mechanism |
+----------------+---------+-----------------+-----------------------+
| flowcontrx | 9010 | BOOLEAN | Flow control on |
| | | | reception (Rx) |
| Reference: ITU Recommendation Q.931 |
| 0 - Cannot accept data with flow control mechanism (i.e. sender |
| does not support this optional procedure) |
| 1 - Can accept data with flow control mechanism (i.e. sender |
| does support this optional procedure) |
+----------------+---------+-----------------+-----------------------+
| rateadapthdr | 9011 | BOOLEAN | Rate adaption |
| | | | header/no header |
| Reference: ITU Recommendation Q.931 |
| 0 - Rate adaption header not included |
| 1 - Rate adaption header included |
+----------------+---------+-----------------+-----------------------+
| multiframe | 9012 | BOOLEAN | Multiple frame |
| | | | establishment support|
| | | | in data link |
| Reference: ITU Recommendation Q.931 |
| 0 - Multiple frame establishment not supported. Only UI frames |
| allowed. |
| 1 - Multiple frame establishment supported |
+----------------+---------+-----------------+-----------------------+
| OPMODE | 9013 | BOOLEAN | Mode of operation |
| Reference: ITU Recommendation Q.931 |
| 0 Bit transparent mode of operation |
| 1 Protocol sensitive mode of operation |
+----------------+---------+-----------------+-----------------------+
| llidnegot | 9014 | BOOLEAN | Logical link |
| | | | identifier negotiation|
| Reference: ITU Recommendation Q.931 |
| 0 Default, LLI = 256 only |
| 1 Full protocol negotiation |
+----------------+---------+-----------------+-----------------------+
| assign | 9015 | BOOLEAN | Assignor/assignee |
| Reference: ITU Recommendation Q.931 |
| 0 Message originator is "Default assignee" |
| 1 Message originator is "Assignor only" |
+----------------+---------+-----------------+-----------------------+
| inbandneg | 9016 | BOOLEAN | In-band/out-band |
| | | | negotiation |
| Reference: ITU Recommendation Q.931 |
| 0- Negotiation is done with USER INFORMATION messages on a |
| temporary signalling connection |
| 1- Negotiation is done in-band using logical link zero |
+----------------+---------+-----------------+-----------------------+
| stopbits | 9017 | 2 BITS | Number of stop bits |
| Reference: ITU Recommendation Q.931 |
| Bits 2 1 |
| 00 - Not used |
| 01 - 1 bit |
| 10 - 1.5 bits |
| 11 - 2 bits |
+----------------+---------+-----------------+-----------------------+
| databits | 9018 | 2 BIT | Number of data bits |
| | | | excluding parity Bit |
| | | | if present |
| Reference: ITU Recommendation Q.931 |
| Bit 2 1 |
| 00 - Not used |
| 01 - 5 bits |
| 10 - 7 bits |
| 11 - 8 bits |
+----------------+---------+-----------------+-----------------------+
| parity | 9019 | 3 BIT | Parity information |
| Reference: ITU Recommendation Q.931 |
| Bit 3 2 1 |
| 000 - Odd |
| 010 - Even |
| 011 - None |
| 100 - Forced to 0 |
| 101 - Forced to 1 |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| duplexmode | 901A | BOOLEAN | Mode duplex |
| Reference: ITU Recommendation Q.931 |
| 0 - Half duplex |
| 1 - Full duplex |
+----------------+---------+-----------------+-----------------------+
| modem | 901B | 6 BIT | Modem Type |
| Reference: ITU Recommendation Q.931 |
| Bits 6 5 4 3 2 1 |
| 00000 through 000101 National Use |
| 010001 - Recommendation V.21 |
| 010010 - Recommendation V.22 |
| 010011 - Recommendation V.22 bis |
| 010100 - Recommendation V.23 |
| 010101 - Recommendation V.26 |
| 011001 - Recommendation V.26 bis |
| 010111 - Recommendation V.26 ter |
| 011000 - Recommendation V.27 |
| 011001 - Recommendation V.27 bis |
| 011010 - Recommendation V.27 ter |
| 011011 - Recommendation V.29 |
| 011101 - Recommendation V.32 |
| 011110 - Recommendation V.34 |
| 100000 through 101111 National Use |
| 110000 through 111111 User Specified |
+----------------+---------+-----------------+-----------------------+That's the whole Q.931 tag set in this part, bestie 🦋 Every bit pattern is copied exactly as the spec wrote it, so if the table looks a little quirky (like V.26 bis and V.27 bis both sitting on 011001), that's the original being the original 🙈
Okay so the bearer capability stuff keeps going, and this next table is literally giving layer2 protocol vibes 🎀
+----------------+---------+-----------------+-----------------------+
| layer2prot | 901C 5 BIT | User information layer|
| | | 2 protocol |
| Reference: ITU Recommendation Q.931 |
| Bit 5 4 3 2 1 |
| 00010 - Recommendation Q.921/I.441 [3] |
| 00110 - Recommendation X.25 [5], link layer |
| 01100 - LAN logical link control (ISO/IEC 8802-2) |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| layer3prot | 901D | 5 BIT | User information layer|
| | | | 3 protocol |
| Reference: ITU Recommendation Q.931 |
| Bit 5 4 3 2 1 |
| 00010 - Recommendation Q.931/I.451 |
| 00110 - Recommendation X.25, packet layer |
| 01011 - ISO/IEC TR 9577 (Protocol identification in the network |
| layer) |
| All other values are reserved. |
+----------------+---------+-----------------+-----------------------+
| addlayer3prot | 901E | OCTET | Additional User |
| | | | Information layer 3 |
| | | | protocol |
| |
| Bits 4321
| 1100 1100 - Internet Protocol (RFC 791) (ISO/IEC TR 9577) |
| 1100 1111 - Point-to-point Protocol (RFC 1661) |
+----------------+---------+-----------------+-----------------------+
| DialledN | 901F | 30 OCTETS | Dialled Number |
+----------------+---------+-----------------+-----------------------+
| DiallingN | 9020 | 30 OCTETS | Dialling Number |
+----------------+---------+-----------------+-----------------------+
| ECHOCI | 9021 | Enumeration | Echo Control |
| | | | Information |
| echo canceler off (0), incoming echo canceler on (1), outgoing |
| echo canceler on (2), incoming and outgoing echo canceler on (3)|
+----------------+---------+-----------------+-----------------------+
| NCI | 9022 | 1 OCTET | Nature of Connection |
| | | | Indicators |
| Reference: ITU Recommendation Q.763 |
| Bits 8 7 6 5 4 3 2 1 |
| |
| Bits 2 1 Satellite Indicator |
| 0 0 no satellite circuit in the connection |
| 0 1 one satellite circuit in the connection |
| 1 0 two satellite circuits in the connection |
| 1 1 spare
| |
| Bits 4 3 Continuity check indicator |
| 0 0 continuity check not required |
| 0 1 continuity check required on this circuit |
| 1 0 continuity check performed on a previous circuit |
| 1 1 spare |
| |
| Bits 5 Echo control device indicator |
| 0 outgoing echo control device not included |
| 1 outgoing echo control device included |
| |
| Bits 8 7 6 Spare |
+--------------------------------------------------------------------+C.10 AAL5 Properties ✨
Next up is the AAL5 table, which has the forward and backward max CPCS-SDU sizes plus the SSCS bit that points you over to table C.7 💅
+----------------+---------+-----------------+-----------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+----------------+---------+-----------------+-----------------------+
| FMSDU | A001 | 32 bit integer | Forward Maximum CPCS-|
| | | | SDU Size: |
| Reference: ITU Recommendation Q.2931 |
| Maximum CPCS-SDU size sent in the direction from the calling |
| user to the called user. |
+----------------+---------+-----------------+-----------------------+
| BMSDU | A002 | 32 bit integer | Backwards Maximum |
| | | | CPCS-SDU Size |
| Reference: ITU Recommendation Q.2931 |
| Maximum CPCS-SDU size sent in the direction from the called user|
| to the calling user. |
+----------------+---------+-----------------+-----------------------+
| SSCS | See | See table C.7 | See table C.7 |
| | table | | |
| | C.7 | | |
| Additional values: |
| VPI/VCI |
+--------------------------------------------------------------------+C.11 SDP Equivalents 💜
This one is the SDP mapping, and every row points back to IETF RFC2327 for the full story 🌸
+----------------+---------+-----------------+-----------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+----------------+---------+-----------------+-----------------------+
| SDP_V | B001 | STRING | Protocol Version |
+----------------+---------+-----------------+-----------------------+
| SDP_O | B002 | STRING | Owner/creator and |
| | | | session ID |
+----------------+---------+-----------------+-----------------------+
| SDP_S | B003 | STRING | Sesson name |
+----------------+---------+-----------------+-----------------------+
| SDP_I | B004 | STRING | Session identifier |
+----------------+---------+-----------------+-----------------------+
| SDP_U | B005 | STRING | URI of descriptor |
+----------------+---------+-----------------+-----------------------+
| SDC_E | B006 | STRING | email address |
+----------------+---------+-----------------+-----------------------+
| SDP_P | B007 | STRING | phone number |
+----------------+---------+-----------------+-----------------------+
| SDP_C | B008 | STRING | Connection information|
+----------------+---------+-----------------+-----------------------+
| SDP_B | B009 | STRING | Bandwidth Information |
+----------------+---------+-----------------+-----------------------+
| SDP_Z | B00A | STRING | time zone adjustment |
+----------------+---------+-----------------+-----------------------+
| SDP_K | B00B | STRING | Encryption Key |
+----------------+---------+-----------------+-----------------------+
| SDP_A | B00C | STRING | Zero or more session |
+----------------+---------+-----------------+-----------------------+
| SDP_T | B00D | STRING | Active Session Time |
+----------------+---------+-----------------+-----------------------+
| SDP_R | B00E | STRING | Zero or more repeat |
+----------------+---------+-----------------+-----------------------+
| |
| Reference in all cases: IETF RFC2327, "Session Description |
| Protocol" |
+--------------------------------------------------------------------+C.12 H.245 🦋
Last table in this annex is H.245, where each property carries an octet string for the matching H.245 structure, and the reference is ITU-T Recommendation H.245 🫶
+----------------+---------+--------------+--------------------------+
| PropertyID | Property| Type | Value |
| | Tag | | |
+----------------+---------+--------------+--------------------------+
| OLC | C001 | octet string | The value of H.245 |
| | | | OpenLogicalChannel |
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| OLCack | C002 | octet string | The value of H.245 |
| | | | OpenLogicalChannelAck |
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| OLCcnf | C003 | octet string | The value of H.245 |
| | | | OpenLogicalChannelConfirm|
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| OLCrej | C004 | octet string | The value of H.245 |
| | | | OpenLogicalChannelReject |
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| CLC | C005 | octet string | The value of H.245 |
| | | | CloseLogicalChannel |
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| CLCack | C006 | octet string | The value of H.245 |
| | | | CloseLogicalChannelAck |
| | | | structure. |
+----------------+---------+--------------+--------------------------+
| Reference in all cases: ITU-T Recommendation H.245 |
+----------------+---------+--------------+--------------------------+ANNEX D TRANSPORT OVER IP (NORMATIVE) 🌈
D.1 Transport over IP/UDP using Application Level Framing 🧚
Okay bestie, this is the UDP part, and the vibe is that protocol messages from this document can ride over UDP 💖 When the peer doesn't give a port (that's the one in section 7.2.8), commands should be sent to the default port, which is 2944 for text-encoded operation or 2945 for binary-encoded operation. Responses must be sent back to the address and port that the matching commands came from 🫶
Implementors using IP/UDP with ALF should be aware of the restrictions of the MTU on the maximum message size 🙈
D.1.1 Providing At-Most-Once Functionality 🔁
Okay so messages are riding along on UDP 📦, which means they can get lost 😭. If there's no timely response, the commands just get repeated. The catch is that most commands aren't idempotent 🙈, so the MG's state would go totally unpredictable if, say, Add commands ran several times. The transmission procedures shall therefore provide an "At-Most-Once" functionality 💅.
Peer protocol entities are expected to keep a list in memory of the responses they sent to recent transactions, plus a list of the transactions that are currently outstanding 📝. When an incoming message shows up, its transaction identifier gets compared to the recent responses sent to the same MId 👀. If there's a match, the entity doesn't execute the transaction, it just repeats the response 🔁. If there's no match, the message gets checked against the outstanding transactions. A match there means it's a duplicate, so the entity doesn't execute it either (see section D.1.4 for procedures on sending TransactionPending) 🙅.
The procedure uses a long timer value, noted LONG-TIMER ⏳. The timer should be set larger than the maximum duration of a transaction. That duration should take into account the maximum number of repetitions, the maximum value of the repetition timer, and the maximum propagation delay of a packet in the network. A suggested value is 30 seconds ⭐.
The copy of the responses may be destroyed either LONG-TIMER seconds after the response is issued, or when the entity receives a confirmation that the response was received, through the "Response Acknowledgement parameter" 🫶. For transactions acknowledged through this parameter, the entity shall keep a copy of the transaction-id for LONG-TIMER seconds after the response is issued. That way it can detect and ignore duplicate copies of the transaction request that could be produced by the network 🕵️♀️.
D.1.2 Transaction identifiers and three-way handshake 🎀
D.1.2.1 Transaction identifiers 🔢
Transaction identifiers are 32 bit integer numbers ✨. A Media Gateway Controller can decide to use a specific number space for each of the MGs it manages, or use the same number space for all MGs that belong to some arbitrary group 🗂️. MGCs can also share the load of managing a large MG between several independent processes 🤝, and those processes will share the same transaction number space. There are a few ways to pull that off, like having a centralized allocation of transaction identifiers, or pre-allocating non-overlapping ranges of identifiers to different processes. Whatever the implementation, it shall guarantee that unique transaction identifiers are allocated to all transactions that originate from a logical MGC (identical mId) 🔐. MGs can simply detect duplicate transactions by looking at the transaction identifier and mId only 👑.
D.1.2.2 Three-way handshake 🤝
The TransactionResponse Acknowledgement parameter can be found in any message 💌. It carries a set of "confirmed transaction-id ranges". Entities may choose to delete the copies of the responses to transactions whose id is included in "confirmed transaction-id ranges" received in the transaction response messages. They should silently discard further commands when the transaction-id falls within these ranges 🤫.
The "confirmed transaction-id ranges" values shall not be used if more than LONG-TIMER seconds have elapsed since the MG issued its last response to that MGC, or when a MG resumes operation 🚫. In this situation, transactions should be accepted and processed, without any test on the transaction-id ✅.
Messages that carry the "Transaction Response Acknowledgement" parameter may be transmitted in any order 🔀. The entity shall retain the "confirmed transaction-id ranges" received for LONG-TIMER seconds ⏳.
In the binary encoding, if only the firstAck is present in a response acknowledgement (see Annex A.2), only one transaction is acknowledged 1️⃣. If both firstAck and lastAck are present, then the range of transactions from firstAck to lastAck is acknowledged. In the text encoding, a horizontal dash is used to indicate a range of transactions being acknowledged (see Annex B.2) ➖.
D.1.3 Computing retransmission timers ⏰
It is the responsibility of the requesting entity to provide suitable time outs for all outstanding transactions, and to retry transactions when time outs have been exceeded. Furthermore, when repeated transactions fail to be acknowledged, it's the requesting entity's job to seek redundant services and/or clear existing or pending connections 🧹. Implementations SHALL ensure that the algorithm used to calculate retransmission timing performs an exponentially increasing backoff of the retransmission timeout for each retransmission or repetition after the first one 📈.
The specification purposely avoids specifying any value for the retransmission timers 🤷♀️. These values are typically network dependent, so the retransmission timers should normally estimate the timer value by measuring the time spent between the sending of a command and the return of a response ⏱️.
Note - One possibility is to use the algorithm implemented in TCP-IP, which uses two variables:
- The average acknowledgement delay, AAD, estimated through an exponentially smoothed average of the observed delays.
- The average deviation, ADEV, estimated through an exponentially smoothed average of the absolute value of the difference between the observed delay and the current average. The retransmission timer, in TCP, is set to the sum of the average delay plus N times the average deviation. The maximum value of the timer should however be bounded for the protocol defined in this document, in order to guarantee that no repeated packet would be received by the gateways after
LONG-TIMERseconds. A suggested maximum value is 4 seconds 🌸.
After any retransmission, the entity SHOULD do the following:
- It should double the estimated value of the average delay, AAD
- It should compute a random value, uniformly distributed between 0.5 AAD and AAD
- It should set the retransmission timer to the sum of that random value and N times the average deviation.
This procedure has two effects. Because it includes an exponentially increasing component, it will automatically slow down the stream of messages in case of congestion 🐢. Because it includes a random component, it will break the potential synchronization between notifications triggered by the same external event 🎲.
D.1.4 Provisional responses 🧘♀️
Executing some transactions may require a long time ⌛. Long execution times may interact with the timer based retransmission procedure. This may result either in an inordinate number of retransmissions, or in timer values that become too long to be efficient 😵. Entities that can predict that a transaction will require a long execution time may send a provisional response, "Transaction Pending" 💜. They SHOULD send this response if they receive a repetition of a transaction that is still being executed.
Entities that receive a Transaction Pending shall switch to a different repetition timer for repeating requests 🔄. The root termination has a property (ProvisionalResponseTimerValue), which can be set to the requested maximum number of milliseconds between receipt of a command and transmission of the TransactionPending response ⏲️. Upon receipt of a final response following receipt of provisional responses, an immediate confirmation shall be sent, and normal repetition timers shall be used thereafter. An entity that sends a provisional response, SHALL include the immAckRequired field in the ensuing final response, indicating that an immediate confirmation is expected 💌. Receipt of a Transaction Pending after receipt of a reply shall be ignored 🙈.
D.1.5 Repeating Requests, Responses and Acknowledgements 🔁
okay so the protocol is built out of transactions 💌, and each one is a request plus a response, which people also call an acknowledgement. The messages ride on UDP, which means they can get lost along the way 😭. If you don't hear back in time, you just send it again. Entities are expected to keep a memory list of the responses they sent to recent transactions, meaning every response from the last LONG-TIMER seconds, plus a list of the transactions that are running right now ✨.
The repetition thing exists to protect against three kinds of problems:
- transmission errors, like when a packet gets lost because of line noise or a jammed queue 📉;
- component failure, like when an interface to an entity stops being available 🔌;
- entity failure, like when a whole entity goes down 💀.
Entities should be able to look back at their history and estimate how much packet loss is coming from transmission errors 📊. In a properly configured system that loss rate should stay super low, typically under 1%. If a Media Gateway Controller or a Media Gateway has to repeat one message more than a few times, it's very reasonable to assume something other than a transmission error is going on 🚩. Like, at a 1% loss rate, the chance that five tries in a row all fail is 1 in 100 billion, which should happen less than once every 10 days for an MGC handling 1 000 transactions per second. (The number of repeats that counts as excessive should actually depend on the current packet loss rate 🧠.) Also, the "suspicion threshold", which we're calling "Max1", is normally lower than the "disconnection threshold", and that one should be set to a bigger number 💅.
A classic retransmission algorithm would just count the successive repeats and decide the association is broken after an excessive number of retransmissions, typically somewhere between 7 and 11 times. But to handle a failover that might be undetected or already happening, this document tweaks the classic approach. If the Media Gateway gets a valid ServiceChange message announcing a failover, it starts sending its outstanding commands to that new MGC 🚀. Responses to commands still go back to the source address of the command 💖.
To adapt to network load automatically, this document uses exponentially increasing timers 📈. If the initial timer is 200 milliseconds, losing a fifth retransmission gets detected after about 6 seconds, which is honestly a pretty acceptable wait to spot a failover 👀. The repeats should keep going past that point, not only to ride out a temporary connectivity hiccup but also to give a failover some extra time to happen. Waiting a total of 30 seconds is probably fine 🕰️.
It's still really important that the maximum delay for retransmissions is bounded 🧱. Before any retransmission, the code checks that the time since the initial datagram was sent is no greater than T-MAX. If more than T-MAX has passed, the MG concludes the MGC has failed and starts its recovery process 🆘. The MG shall use a ServiceChange with ServiceChangeMethod set to Disconnected so the new MGC knows the MG lost one or more transactions 📣. T-MAX is tied to LONG-TIMER too: LONG-TIMER is T-MAX plus the maximum propagation delay in the network ⏱️.
D.2. Using TCP 🧵
Protocol messages defined in this document can be sent over TCP 🎀. When the other side doesn't specify a port (see section 7.2.8), commands should go to the default port. Here's the catch: the protocol treats messages as its unit of transfer, but TCP is stream-oriented 🌊. So TPKT, according to RFC1006, SHALL be used to mark where messages begin and end inside the TCP stream 🧩.
Even in a transaction-oriented protocol, transaction requests or responses can still get lost 🫠. Because of that, it's recommended that entities using TCP transport set up application level timers for each request and each response, kind of like the ones specified for application level framing over UDP ⏲️.
D.2.1 Providing the At-Most-Once functionality 🔒
Messages sent over TCP don't get lost in transport, but losing a transaction request or its reply can still happen in real implementations 😬. If there's no timely response, commands get repeated. The problem is that most commands aren't idempotent 🙅♀️. If Add commands ran several times, the MG's state could become totally unpredictable 🌀.
To guard against that, it's recommended that entities follow the procedures in section D.1.1 🛡️.
D.2.2 Transaction identifiers and three way handshake 🤝
For the same reasons, transaction replies can still be lost even with a reliable delivery protocol like TCP 🥲. It's recommended that entities follow the procedures in section D.1.2.2 ✅.
D.2.3 Computing retransmission timers ⏳
With reliable delivery, losing a transaction request or reply is expected to be very rare 🥳. So only simple timer mechanisms are required. Exponential back-off algorithms should not be necessary 🙅, although they could be used where the code for them is already needed anyway, like in an MGC, since MGCs must implement ALF/UDP as well as TCP 💪.
D.2.4 Provisional responses 💭
Same as with UDP, some transactions can take a really long time to execute 🐢. Entities that can predict a transaction will take a long time may send a provisional response, "Transaction Pending" 📨. They should send this when they get a repetition of a transaction that's still being executed 🔁.
Entities that receive a Transaction Pending shall switch to a longer repetition timer for that transaction 🕰️.
Entities shall retain Transactions and replies until they are confirmed 📦. The basic procedure from section D.1.4 should be followed, but simple timer values should be enough 😌. There's no need to send an immediate confirmation when a final response comes in 🙌.
D.2.5 Ordering of commands 📋
TCP gives you ordered delivery of transactions, so no special procedures are needed 🥇. But ALF/UDP is different: it lets the sending entity change how it behaves under congestion, and in particular it could reorder transactions when congestion shows up 🔀. TCP couldn't get those same results ✨.
ANNEX E BASIC PACKAGES (NORMATIVE) 🎁
This Annex has definitions for some packages you can use with the Megaco protocol 📚.
E.1. Generic 🧸
PackageID: g (0x0001)
Version: 1
Extends: None
Description: Generic package for commonly encountered items.E.1.1 Properties 🏷️
None
E.1.2 Events 🔔
Cause
-----
EventID: cause (0x0001)
Generic error event
ObservedEvents Descriptor Parameters:
General Cause
-------------
ParameterID: Generalcause (0x0001)
Description: This parameter groups the failures into six
groups, which the MGC may act upon.
Possible values: Enumerated,
"NR" Normal Release (0x0001)
"UR" Unavailable Resources (0x0002)
"FT" Failure, Temporary (0x0003)
"FP" Failure, Permanent (0x0004)
"IW" Interworking Error (0x0005)
"UN" Unsupported (0x0006)
Failure Cause
-------------
ParameterID: Failurecause (0x0002)
Description: The Release Cause is the value generated by the
Released equipment, i.e. a released network connection.
The concerned value is defined in the appropriate bearer
control protocol.
Possible Values: OCTET STRING
Signal Completion
-----------------
EventID: sc (0x0002)
Indicates termination of one or more signals for which the
notifyCompletion parameter was set to "ON". For further procedural
description, see sections 7.1.11, 7.1.17, and 7.2.7.
ObservedEvents Descriptor parameters:
Signal Identity
---------------
ParameterID: SigID (0x0001)
This parameter identifies the signals which have terminated.
Type: list
Possible values: a list of signals and/or sequential signal
lists which have terminated. A signal outside of a sequential
signal list shall be identified using the pkgdName syntax
without wildcarding. An individual signal inside of a
sequential signal list shall be identified using the sequential
signal list syntax with the correct signal list identifier,
enclosing the name of the specific signal which terminated in
pkgdName syntax.
Termination Method
------------------
ParameterID: Meth (0x0002)
Indicates the means by which the signal terminated.
Type: enumeration
Possible values:
"TO" (0x0001) Duration expired
"EV" (0x0002) Interrupted by event
"SD" (0x0003) Halted by new Signals Descriptor
"NC" (0x0004) Not completed, other causeQuick vibe check on that one: the Cause event is the generic error event 🚨, and Signal Completion tells you when signals with notifyCompletion set to "ON" have wrapped up 🏁. The procedure details live in sections 7.1.11, 7.1.17, and 7.2.7 📖.
E.1.3 Signals 📡
None
E.1.4 Statistics 📊
None
E.2. Base Root Package 🌳
Base Root Package
PackageID: root (0x0002)
Version: 1
Extends: None
Description: This package defines Gateway wide properties.This one holds the gateway-wide properties, the main character of the whole Gateway setup 👑.
E.2.1 Properties 🎛️
MaxNrOfContexts
---------------
PropertyID: maxNumberOfContexts (0x0001)
The value of this property gives the maximum number of contexts that
can exist at any time. The NULL context is not included in this
number.
Type: Double
Possible values: 1 and up
Defined in: TerminationState
MaxTerminationsPerContext
-------------------------
PropertyID: maxTerminationsPerContext (0x0002)
The maximum number of allowed terminations in a context, see section
6.1
Type: Integer
Possible Values: any integer
Defined In: TerminationState
normalMGExecutionTime
---------------------
PropertyId: normalMGExecutionTime (0x0003)
Settable by the MGC to indicate the interval within which the MGC
expects a response to any transaction from the MG (exclusive of
network delay)
Type: Integer
Possible Values: any integer, represents milliseconds
Defined in: TerminationState
normalMGCExecutionTime
----------------------
PropertyId: normalMGCExecutionTime (0x0004)
Settable by the MGC to indicate the interval within which the MG
should expects a response to any transaction from the MGC (exclusive
of network delay)
Type: Integer
Possible Values: any integer, represents milliseconds
Defined in: TerminationState
ProvisionalResponseTimerValue
-----------------------------
PropertyId: ProvisionalResponseTimerValue (0x0005)
Indicates the time within which to expect a Pending Response if a
Transaction cannot be completed. Initially set to
normalMGExecutionTime or normalMGCExecutionTime as appropriate, plus
network delay, but may be lowered.
Type: Integer
Possible Values: any integer, represents milliseconds
Defined in: TerminationStateSome highlights from these properties 💜: maxNumberOfContexts caps how many contexts can exist at once (the NULL context doesn't count) 🧮. maxTerminationsPerContext caps terminations per context, see section 6.1 🔢. normalMGExecutionTime is the MGC telling the MG how long to expect a response to a transaction, and normalMGCExecutionTime is the reverse direction 🔄. ProvisionalResponseTimerValue tells you how long to wait for a Pending Response when a transaction can't finish right away ⏰, and it starts at normalMGExecutionTime or normalMGCExecutionTime plus network delay, but it can be lowered 📉. Everything is in milliseconds, so bring your calculator 🧁.
E.2.2 Events 🔔
None
E.2.3 Signals 📡
None
E.2.4 Statistics 📊
None
E.2.5 Procedures 🛠️
None
E.3 Tone Generator Package 🎀
PackageID and friends live in this little block, so the vibe stays clean:
PackageID: tonegen (0x0003)
Version: 1
Extends: NoneDescription: okay so this package is where the audio tone signals live 🔊 It doesn't set any parameter values, because it's built to be extended ✨ Each tone is its own signal with a parameter called ind for the "interdigit" time delay, plus a tone id you can use with playtone. Keep a tone id consistent with any tone generation for that same tone, bestie 💅 And MGs are expected to be provisioned with the characteristics of the right tones for the country they're in 🌍
E.3.1 Properties
Nothing to see here! It's just None 🙈
E.3.2 Events
Also None 🌸
E.3.3 Signals
Play tone 🎶
SignalID: pt (0x0001)This one plays an audio tone over an audio channel, obsessed 🔥
Signal Type: Brief
Duration: ProvisionedAdditional Parameters:
Tone id list 📋
ParameterID: tl (0x0001)
Type: list of tone ids.This is the list of tones that get played in sequence. The list SHALL contain one or more tone ids. No empty lists, babe 🙅♀️
Inter signal duration ⏳
ParameterID: ind (0x0002)
Type: integer.This is the timeout between two consecutive tones, measured in milliseconds ⏱️
No tone ids are defined in this package. Packages that extend it can add possible values for tone id, plus their own individual tone signals 🧚
E.3.4 Statistics
None 🫶
E.3.5 Procedures
Still None! Nothing to do here 💜
E.4 Tone Detection Package 👂
PackageID: tonedet (0x0004)
Version: 1
Extends: NoneThis package defines the events for detecting audio tones 👂✨ Tones get picked out by name, which is their tone id. Same deal as before: MGs are expected to be provisioned with the characteristics of the appropriate tones for their country 🌏
It doesn't specify parameter values either, because it's also meant to be extendable 🦋
E.4.1 Properties
None 🌷
E.4.2 Events
Start tone detected 🟢
EventID: std, 0x0001This one catches the start of a tone. How positive the detection is depends on the implementation 🤷♀️
EventsDescriptor parameters:
Tone id list
ParameterID: tl (0x0001)
Type: list of tone idsThe only tone id defined in this package is the "wild card", which is * in text encoding and 0x0000 in binary. Extensions to this package would add more possible values for tone id. If tl is the "wild card", then any tone id gets detected 🌈
ObservedEventsDescriptor parameters:
Tone id
ParameterID: tid (0x0003)
Type: EnumerationThe only possible value in this package is "wildcard", as defined above. Extensions can add more values for tone id 💖
End tone detected 🔴
EventID: etd, 0x0002This one detects the end of a tone 🛑
EventDescriptor parameters:
Tone id list
ParameterID: tl (0x0001)
Type: enumeration or list of enumerated typesThis package doesn't specify any possible values here. Extensions would add possible values for tone id ✨
ObservedEventsDescriptor parameters:
Tone id
ParameterID: tid (0x0003)
Type: EnumerationThe only possible value in this package is "wildcard", as defined above. Extensions would add possible values for tone id 🫧
Duration
ParameterId: dur (0x0002)
Type: integer, in millisecondsThis parameter holds how long the tone lasted, from first detection until it stopped ⏳
Long tone detected 🫨
EventID: ltd, 0x0003This one detects that a tone has been playing for at least a certain amount of time 🕰️
EventDescriptor parameters:
Tone id list
ParameterID: tl (0x0001)
Type: enumeration or listThe only possible value is "wildcard", as defined above. Extensions would add possible values for tone id 🌸
Duration:
ParameterID: dur (0x0002)
Type: integer, duration to test againstPossible values are any legal integer, expressed in milliseconds 🔢
ObservedEventsDescriptor parameters:
Tone id
ParameterID: tid (0x0003)No possible values are specified in this package. Extensions would add possible values for tone id 🧚
E.4.3 Signals
None 🙌
E.4.4 Statistics
None 🌟
E.4.5 Procedures
None 💅
E.5 Basic DTMF Generator Package ☎️
PackageID: dg (0x0005)
Version: 1
Extends: tonegen version 1This package defines the basic DTMF tones as signals, and it extends the allowed values of parameter tl of playtone in tonegen 🎹✨
E.5.1 Properties
None 🌼
E.5.2 Events
None 🌷
E.5.3 Signals
dtmf character 0 0️⃣
SignalID: d0 (0x0010)This generates the DTMF 0 tone. The physical characteristics of DTMF 0 are defined in the gateway 🛠️
Signal Type: Brief
Duration: ProvisionedAdditional Parameters: none, None 🙈
Additional Values
d0 (0x0010) is defined as a toneid for playtone 🎵
The other DTMF characters are specified in exactly the same way. Here's a table with all of the signal names and signal IDs. Each DTMF character is defined as both a signal and a toneid, so it extends the basic tone generation package. Also, the DTMF SignalIds are different from the names used in a digit map, so don't mix them up 🫶
+------------------+-------------------+
| Signal Name | Signal ID/tone id |
+------------------+-------------------+
| dtmf character 0 | d0 (0x0010) |
| dtmf character 1 | d1 (0x0011) |
| dtmf character 2 | d2 (0x0012) |
| dtmf character 3 | d3 (0x0013) |
| dtmf character 4 | d4 (0x0014) |
| dtmf character 5 | d5 (0x0015) |
| dtmf character 6 | d6 (0x0016) |
| dtmf character 7 | d7 (0x0017) |
| dtmf character 8 | d8 (0x0018) |
| dtmf character 9 | d9 (0x0019) |
| dtmf character * | ds (0x0020) |
| dtmf character # | do (0x0021) |
| dtmf character A | da (0x001a) |
| dtmf character B | db (0x001b) |
| dtmf character C | dc (0x001c) |
| dtmf character D | dd (0x001d) |
+------------------+-------------------+E.5.4 Statistics
None 🌈
E.5.5 Procedures
None 💖
E.6 DTMF detection Package 🔍
PackageID: dd (0x0006)
Version: 1
Extends: tonedet version 1This package defines basic DTMF tone detection 📞 It extends the possible values of tone id in the "start tone detected", "end tone detected" and "long tone detected" events 🙌
The additional tone id values are all of the tone ids described in package dg, which is the basic DTMF generator package 💜
This table maps DTMF events to digit map symbols, as described in section 7.1.14 🗺️
+------+--------------+
| DTMF | Event Symbol |
+------+--------------+
| d0 | "0" |
| d1 | "1" |
| d2 | "2" |
| d3 | "3" |
| d4 | "4" |
| d5 | "5" |
| d6 | "6" |
| d7 | "7" |
| d8 | "8" |
| d9 | "9" |
| da | "A" or "a" |
| db | "B" or "b" |
| dc | "C" or "c" |
| dd | "D" or "d" |
| ds | "E" or "e" |
| do | "F" or "f" |
+------+--------------+E.6.1 Properties
None 🌷
E.6.2 Events
DTMF digits 🔢
EventIds are defined with the same names as the SignalIds in the table found in section E.5.3, so you already know them if you've been paying attention 🤓
DigitMap Completion Event 🏁
EventID: ce, 0x0001This gets generated when a digit map completes, as described in section 7.1.14 ✅
EventsDescriptor parameters: digit map processing only gets activated if a digit map parameter is present, which specifies a digit map by name or by value. Other parameters, like a KeepActive flag or embedded Events or Signals Descriptors, may also be present 🫧
ObservedEventsDescriptor parameters:
DigitString
ParameterID: ds (0x0001)
Type: string of digit map symbols (possibly empty) returned as a quotedString.
Possible values: a sequence of the characters "0" through "9", "A" through "F", and the long duration modifier "Z".This is the portion of the current dial string, as described in section 7.1.14, that matched part or all of an alternative event sequence in the digit map 📜
Termination Method
ParameterID: Meth (0x0003)
Type: enumeration
Possible values:
"UM" (0x0001) Unambiguous match
"PM" (0x0002) Partial match, completion by timer expiry
or unmatched event
"FM" (0x0003) Full match, completion by timer expiry
or unmatched eventThis tells you why the event was generated. Check the procedures in section 7.1.14 for the details 🕵️♀️
E.6.3 Signals
None 🫶
E.6.4 Statistics
None 🌸
E.6.5 Procedures
None 💅
E.7 Call Progress Tones Generator Package 📶
PackageID: cg, 0x0007
Version: 1
Extends: tonegen version 1This package defines the basic call progress tones as signals, and it extends the allowed values of the tl parameter of playtone in tonegen 🔔
E.7.1 Properties
None 🌼
E.7.2 Events
None 🌷
E.7.3 Signals
Dial Tone 📞
SignaID: dt (0x0030)This generates the dial tone. The physical characteristics of the dial tone are available in the gateway 🛠️
Signal Type: Timeout
Duration: ProvisionedAdditional Parameters: None 🙈
Additional Values
dt (0x0030) is defined as a tone id for playtoneThe other tones in this package are defined in exactly the same way. Here's a table with all of the signal names and signal IDs. Each tone is defined as both a signal and a toneid, so it extends the basic tone generation package 💖
+---------------------------+-------------------+
| Signal Name | Signal ID/tone id |
+---------------------------+-------------------+
| Dial Tone | dt (0x0030) |
| Ringing Tone | rt (0x0031) |
| Busy Tone | bt (0x0032) |
| Congestion Tone | ct (0x0033) |
| Special Information Tone | sit(0x0034) |
| Warning Tone | wt (0x0035) |
| Payphone Recognition Tone | pt (0x0036) |
| Call Waiting Tone | cw (0x0037) |
| Caller Waiting Tone | cr (0x0038) |
+---------------------------+-------------------+E.7.4 Statistics
None 🌈
E.7.5 Procedures
NOTE - The required set of tone ids corresponds to those defined in Recommendation E.180/Q.35 [ITU-T Recommendation E.180/Q.35 (1998)]. See E.180 for definition of the meanings of these tones. 📚🫶
E.8 Call Progress Tones Detection Package 🎀
PackageID: cd (0x0008)
Version: 1
Extends: tonedet version 1okay so this package is all about the basic call progress detection tones 📞 It extends the possible values of tone id in the "start tone detected", "end tone detected" and "long tone detected" events 💅
Additional values
tone id values get defined for start tone detected, end tone detected and long tone detected, using the same values as package cg (the call progress tones generation package) 🌸 The required set of tone ids matches Recommendation E.180/Q.35 [ITU-T Recommendation E.180/Q.35 (1998)]. Go check Recommendation E.180/Q.35 for what each tone actually means 🧚
E.8.1 Properties
none
E.8.2 Events
Events are defined the same way they are in the call progress tones generator package (cg), for the tones listed in the table of section E.7.3 ✨
E.8.3 Signals
none
E.8.4 Statistics
none
E.8.5 Procedures
none
E.9 Analog Line Supervision Package 📞
PackageID: al, 0x0009
Version: 1
Extends: NoneThis package defines events and signals for an analog line 🦋
E.9.1 Properties
None
E.9.2 Events
onhook
EventID: on (0x0004)Detects the handset going on hook 📴 Whenever an events descriptor gets activated that asks for monitoring of an on-hook event and the line is already on-hook, then the MG shall behave according to the setting of the "strict" parameter 🙈
EventDescriptor parameters
Strict Transition
ParameterID: strict (0x0001)
Type: enumeration
Possible values: "exact" (0x00), "state" (0x01), "failWrong" (0x02)- "exact" means only an actual hook state transition to on-hook gets recognized.
- "state" means the event gets recognized if the hook state transition is detected or if the hook state is already on-hook.
- "failWrong" means that if the hook state is already on-hook, the command fails and an error is reported.
ObservedEventsDescriptor parameters
Initial State
ParameterID: init (0x0002)
Type: BooleanPossible values:
- True means the event was reported because the line was already on-hook when the events descriptor containing this event got activated.
- False means the event represents an actual state transition to on-hook.
offhook
EventID: of (0x0005)Detects the handset going off hook 📲 Whenever an events descriptor gets activated that asks for monitoring of an off-hook event and the line is already off-hook, then the MG shall behave according to the setting of the "strict" parameter 💜
EventDescriptor parameters
Strict Transition
ParameterID: strict (0x0001)
Type: enumeration
Possible values: "exact" (0x00), "state" (0x01), "failWrong" (0x02)- "exact" means only an actual hook state transition to off-hook gets recognized.
- "state" means the event gets recognized if the hook state transition is detected or if the hook state is already off-hook.
- "failWrong" means that if the hook state is already off-hook, the command fails and an error is reported.
ObservedEventsDescriptor parameters
Initial State
ParameterID: init (0x0002)
Type: BooleanPossible values:
- True means the event was reported because the line was already off-hook when the events descriptor containing this event got activated.
- False means the event represents an actual state transition to off-hook.
flashhook
EventID: fl, 0x0006Detects handset flash ⚡ A flash happens when an onhook is followed by an offhook between a minimum and maximum duration 🌈
EventDescriptor parameters
Minimum duration
ParameterID: mindur (0x0004)
Type: integer in millisecondsDefault value is provisioned.
Maximum duration
ParameterID: maxdur (0x0005)
Type: integer in millisecondsDefault value is provisioned.
ObservedEventsDescriptor parameters
None
E.9.3 Signals
ring
SignalID: ri, 0x0002Applies ringing on the line 🔔
Signal Type: TimeOut
Duration: ProvisionedAdditional Parameters:
Cadence
ParameterID: cad (0x0006)Type: list of integers representing durations of alternating on and off segments, constituting a complete ringing cycle starting with an on. Units in milliseconds.
Default is fixed or provisioned. Restricted function MGs may ignore cadence values they are incapable of generating.
Frequency
ParameterID: freq (0x0007)Type: integer in Hz.
Default is fixed or provisioned. Restricted function MGs may ignore frequency values they are incapable of generating.
E.9.4 Statistics
None
E.9.5 Procedures
If the MGC sets an EventsDescriptor containing a hook state transition event (on-hook or off-hook) with the "strict" (0x0001) parameter set to "failWrong", and the hook state is already what the transition implies, the execution of the command containing that EventsDescriptor fails 🙅♀️ The MG SHALL include error code 540 "Unexpected initial hook state" in its response.
E.9.6 Error Code
This package defines a new error code:
540 - Unexpected initial hook stateThe procedure for using this code is given in section E.9.5 🫶
E.10 Basic Continuity Package 🔁
PackageID: ct (0x000a)
Version: 1
Extends: NoneThis package defines events and signals for continuity test. The continuity test includes provision of either a loopback or transceiver functionality 🍓
E.10.1 Properties
None
E.10.2 Events
Completion
EventID: cmp, 0x0005This event detects test completion of the continuity test ✅
EventDescriptor parameters
None
ObservedEventsDescriptor parameters
Result
ParameterID: res (0x0008)
Type: Enumeration
Possible values: success (0x0001), failure (0x0000)E.10.3 Signals
Continuity test
SignalID: ct (0x0003)Initiates sending of continuity test tone on the termination to which it is applied 🎶
Signal Type: TimeOutDefault value is provisioned.
Additional Parameters: None
Respond
SignalID: rsp (0x0004)This signal is used to respond to a continuity test. See section E.10.5 for further explanation 💬
Signal Type: On/OffDefault duration is provisioned.
Additional Parameters: None.
E.10.4 Statistics
None
E.10.5 Procedures
When a MGC wants to initiate a continuity test, it sends a command to the MG containing:
- a signals descriptor with the ct signal, and
- an events descriptor containing the cmp event.
Upon reception of a command containing the ct signal and cmp event, the MG initiates the continuity test tone for the specified termination. If the return tone is detected and any other required conditions are satisfied before the signal times out, the cmp event shall be generated with the value of the result parameter equal to success. In all other cases, the cmp event shall be generated with the value of the result parameter equal to failure 🎯
When a MGC wants the MG to respond to a continuity test, it sends a command to the MG containing a signals descriptor with the rsp signal. Upon reception of a command with the rsp signal, the MG either applies a loopback or (for 2-wire circuits) awaits reception of a continuity test tone. In the loopback case, any incoming information shall be reflected back as outgoing information. In the 2-wire case, any time the appropriate test tone is received, the appropriate response tone should be sent. The MGC determines when to remove the rsp signal ⏯️
When a continuity test is performed on a termination, no echo devices or codecs shall be active on that termination 🙅♀️
Performing voice path assurance as part of continuity testing is provisioned by bilateral agreement between network operators 🤝
E.11 Network Package 🌐
PackageID: nt (0x000b)
Version: 1
Extends: NoneThis package defines properties of network terminations, independent of network type 🛜
E.11.1 Properties
Maximum Jitter Buffer
PropertyID: jit (0x0007)This property puts a maximum size on the jitter buffer.
Type: integer in millisecondsPossible Values: This property is specified in milliseconds.
Defined In: LocalControlDescriptor
Characteristics: read/write
E.11.2 Events
network failure
EventID: netfail, 0x0005The termination generates this event upon detection of a failure due to external or internal network reasons 💀
EventDescriptor parameters
None
ObservedEventsDescriptor parameters
cause
ParameterID: cs (0x0001)
Type: String
Possible values: any text stringThis parameter may be included with the failure event to provide diagnostic information on the reason of failure 🔍
quality alert
EventID: qualert, 0x0006This property allows the MG to indicate a loss of quality of the network connection 📉 The MG may do this by measuring packet loss, interarrival jitter, and propagation delay, and then indicating the result as a percentage of quality loss.
EventDescriptor parameters
Threshold
ParameterId: th (0x0001)
Type: integerPossible Values: threshold for percent of quality loss measured, calculated based on a provisioned method, that could take into consideration packet loss, jitter, and delay for example. The event is triggered when the calculation exceeds the threshold.
ObservedEventsDescriptor parameters
Threshold
ParameterId: th (0x0001)
Type: integerPossible Values: percent of quality loss measured, calculated based on a provisioned method, that could take into consideration packet loss, jitter, and delay for example.
E.11.3 Signals
none
E.11.4 Statistics
Duration
StatisticsID: dur (0x0001)Description: Provides the duration of time the termination has been in the context ⏱️
Type: Double, in milliseconds.
Octets Sent
StatisticID: os (0x0002)Type: double
Possible Values: any 64 bit integer
Octets Received
StatisticID: or (0x0003)Type: double
Possible Values: any 64 bit integer
E.11.5 Procedures
none
E.12 RTP Package 🎶
PackageID: rtp (0x000c)
Version: 1
Extends: Network Package version 1This package supports packet based multimedia data transfer by means of the Real-time Transport Protocol (RTP) [RFC 1889] 🎧
E.12.1 Properties
None
E.12.2 Events
Payload Transition
EventID: pltrans, 0x0001This event detects and notifies when there is a transition of the RTP payload format from one format to another 🦋
EventDescriptor parameters
None
ObservedEventsDescriptor parameters
rtppayload
ParameterID: rtppltype, 0x01
Type: list of enumerated types.Possible values: The encoding method shall be specified by using one or several valid encoding names, as defined in the RTP AV Profile or registered with IANA 💖
E.12.3 Signals
None
E.12.4 Statistics ✨
Packets Sent 📦
StatisticID: ps (0x0004)
Type: double
Possible Values: any 64 bit integer
Packets Received 📥
StatisticID: pr (0x0005)
Type: double
Possible Values: any 64 bit integer
Packet Loss 📉
StatisticID: pl (0x0006)
This one tells you the current rate of packet loss on an RTP stream, as defined in IETF RFC 1889. It's expressed as a percentage: the number of packets lost in the interval between two reception reports, divided by the number of packets expected during that interval. Iconic math, honestly. 🧮
Type: double
Possible Values: a 32 bit whole number and a 32 bit fraction.
Jitter 🫨
StatisticID: jit (0x0007)
This requests the current value of the interarrival jitter on an RTP stream, as defined in IETF RFC 1889. Jitter measures how much the interarrival time varies for RTP data packets. It's the wobble, bestie. 🌊
Delay ⏱️
StatisticID:delay (0x0008)
Requests the current value of packet propagation delay, expressed in timestamp units. It's the same thing as average latency, so no need to overthink it 💅
E.12.5 Procedures
none
E.13 TDM Circuit Package 🎀
PackageID: tdmc (0x000d)
Version: 1
Extends: Network Package version 1This package is used to support TDM circuit terminations. Main character energy, literally. 👑
E.13.1 Properties
Echo Cancellation 🔇
PropertyID: ec (0x0008)
By default, the telephony gateways always perform echo cancellation. Lowkey though, some calls need it turned off, so that's what this is for. 🙈
Type: boolean
Possible Values: "on" (when the echo cancellation is requested) and "off" (when it is turned off.) The default is "on".
Defined In: LocalControlDescriptor
Characteristics: read/write
Gain Control 🔊
PropertyID: gain (0x000a)
Gain control is the usage of signal level adaptation and noise level reduction, which adapts the level of the signal. It's giving volume adjustment, but make it protocol. However, for things like modem calls, you'll want to turn this function off. 📞
Type: enumeration (integer)
Possible Values: The gain control parameter may either be specified as "automatic" (0xffffffff), or as an explicit number of decibels of gain (any other integer value). The default is provisioned in the MG.
Defined In: LocalControlDescriptor
Characteristics: read/write
E.13.2 Events
none
E.13.3 Signals
none
E.13.4 Statistics
None
E.13.5 Procedures
None
APPENDIX A EXAMPLE CALL FLOWS (INFORMATIVE) 🧚
All Megaco implementors must read the normative part of this document carefully before implementing from it. No one should use the examples in this section as stand-alone explanations of how to create protocol messages. Read the rules first, bestie, the examples are just vibes. 🫶
The examples in this section use SDP for encoding of the Local and Remote stream descriptors. SDP is defined in RFC 2327. If there is any discrepancy between the SDP in the examples and RFC 2327, the RFC should be consulted for correctness. Audio profiles used are those defined in RFC 1890, and others registered with IANA. For example, G.711 A-law is called PCMA in the SDP, and is assigned profile 0. G.723 is profile 4, and H263 is profile 34. See also:
http://www.isi.edu/in-notes/iana/assignments/rtp-parametersA.1 Residential Gateway to Residential Gateway Call 🏠
This example scenario shows how the elements of the protocol set up a Residential Gateway to Residential Gateway call over an IP-based network. For simplicity, it assumes that both Residential Gateways involved in the call are controlled by the same Media Gateway Controller. It's a cute little duo, no drama. 💖
A.1.1 Programming Residential GW Analog Line Terminations for Idle Behavior 📟
The following shows the API invocations from the Media Gateway Controller and Media Gateways that get the Terminations in this scenario programmed for idle behavior. Both the originating and terminating Media Gateways have idle AnalogLine Terminations programmed to look for call initiation events (i.e.-offhook) by using the Modify Command with the appropriate parameters. The null Context is used to indicate that the Terminations are not yet involved in a Context. The ROOT termination is used to indicate the entire MG instead of a termination within the MG. ✨
In this example, MG1 has the IP address 124.124.124.222, MG2 is 125.125.125.111, and the MGC is 123.123.123.4. The default Megaco port is 55555 for all three. 🌸
- An MG registers with an MGC using the ServiceChange command:
MG1 to MGC:
MEGACO/1 [124.124.124.222]
Transaction = 9998 {
Context = - {
ServiceChange = ROOT {Services {
Method=Restart,
ServiceChangeAddress=55555, Profile=ResGW/1}
}
}
}- The MGC sends a reply:
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Reply = 9998 {
Context = - {ServiceChange = ROOT {
Services {ServiceChangeAddress=55555, Profile=ResGW/1} } }
}- The MGC programs a Termination in the NULL context. The terminationId is A4444, the streamId is 1, and the requestId in the Events descriptor is 2222. The mId is the identifier of the sender of this message. In this case, it's the IP address and port [123.123.123.4]:55555. Mode for this stream is set to SendReceive. "al" is the analog line supervision package. 📞💕
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Transaction = 9999 {
Context = - {
Modify = A4444 {
Media { Stream = 1 {
LocalControl {
Mode = SendReceive,
tdmc/gain=2, ; in dB,
tdmc/ec=on
},
Local {
v=0
c=IN IP4 $
m=audio $ RTP/AVP 0
a=fmtp:PCMU VAD=X-NNVAD ; special voice activity
; detection algorithm
}
}
},
Events = 2222 {al/of}
}
}
}The dialplan script could have been loaded into the MG previously. Its function would be to wait for the OffHook, turn on dialtone, and start collecting DTMF digits. However, in this example, we use the digit map, which is put into place after the offhook is detected (step 5 below). 🔢
Note that the embedded EventsDescriptor could have been used to combine steps 3 and 4 with steps 8 and 9, eliminating steps 6 and 7. Big brain move, fr fr. 🧠
- The MG1 accepts the Modify with this reply:
MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Reply = 9999 {
Context = - {Modify = A4444}
}- A similar exchange happens between MG2 and the MGC, resulting in an idle Termination called A5555. 🦋
A.1.2. Collecting Originator Digits and Initiating Termination 📞✨
okay so this one picks up right where we left off 💅 it follows the originating side, where the Media Gateway Controller and MG1 work together to get the originating Termination A4444 through digit collection so it can start a connection to the terminating Media Gateway (MG2) 🦋
- MG1 detects an offhook event from User 1 and reports it to the Media Gateway Controller via the Notify Command. 📲
MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Transaction = 10000 {
Context = - {
Notify = A4444 {ObservedEvents =2222 {
19990729T22000000:al/of}}
}
}- And the Notify is acknowledged. 🫶
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Reply = 10000 {
Context = - {Notify = A4444}
}- The MGC Modifies the termination to play dial tone, to look for digits according to Dialplan0 and to look for the on-hook event now. 🎶 It's giving full control 👑
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Transaction = 10001 {
Context = - {
Modify = A4444 {
Events = 2223 {
al/on, dd/ce {DigitMap=Dialplan0}
},
Signals {cg/dt},
DigitMap= Dialplan0{
(0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.)}
}
}
}- And the Modify is acknowledged. ✅
MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Reply = 10001 {
Context = - {Modify = A4444}
}- Next, digits are accumulated by MG1 as they are dialed by User 1. Dialtone is stopped upon detection of the first digit. When an appropriate match is made of collected digits against the currently programmed Dialplan for A4444, another Notify is sent to the Media Gateway Controller. 🔢💖 the digits are literally being collected one by one, it's so cute
MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Transaction = 10002 {
Context = - {
Notify = A4444 {ObservedEvents =2223 {
19990729T22010001:dd/ce{ds="916135551212",Meth=FM}}}
}
}- And the Notify is acknowledged. 🌸
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Reply = 10002 {
Context = - {Notify = A4444}
}- The controller then analyses the digits and determines that a connection needs to be made from MG1 to MG2. Both the TDM termination A4444, and an RTP termination are added to a new context in MG1. Mode is ReceiveOnly since Remote descriptor values are not yet specified. Preferred codecs are in the MGC's preferred order of choice. 🧚 the controller is literally making the plan here, so iconic
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Transaction = 10003 {
Context = $ {
Add = A4444,
Add = $ {
Media {
Stream = 1 {
LocalControl {
Mode = ReceiveOnly,
nt/jit=40 ; in ms
},
Local {
v=0
c=IN IP4 $
m=audio $ RTP/AVP 4
a=ptime:30
v=0
c=IN IP4 $
m=audio $ RTP/AVP 0
}
}
}
}
}
}NOTE - The MGC states its preferred parameter values as a series of sdp blocks in Local. The MG fills in the Local Descriptor in the Reply. 📝 the MGC wants its choices heard first, then MG1 fills in the blanks, okay that's a power move 💅
- MG1 acknowledges the new Termination and fills in the Local IP address and UDP port. It also makes a choice for the codec based on the MGC preferences in Local. MG1 sets the RTP port to 2222. 🎀
MEGACO/1 [124.124.124.222]:55555
Reply = 10003 {
Context = 2000 {
Add = A4444,
Add=A4445{
Media {
Stream = 1 {
Local {
v=0
c=IN IP4 124.124.124.222
m=audio 2222 RTP/AVP 4
a=ptime:30
a=recvonly
} ; RTP profile for G.723 is 4
}
}
}
}
}- The MGC will now associate A5555 with a new Context on MG2, and establish an RTP Stream (i.e, A5556 will be assigned), SendReceive connection through to the originating user, User 1. The MGC also sets ring on A5555. 🔔 MG2 is about to be the main character 🌈
MGC to MG2:
MEGACO/1 [123.123.123.4]:55555
Transaction = 50003 {
Context = $ {
Add = A5555 { Media {
Stream = 1 {
LocalControl {Mode = SendReceive} }},
Events=1234{al/of},
Signals {al/ri}
},
Add = $ {Media {
Stream = 1 {
LocalControl {
Mode = SendReceive,
nt/jit=40 ; in ms
},
Local {
v=0
c=IN IP4 $
m=audio $ RTP/AVP 4
a=ptime:30
},
Remote {
v=0
c=IN IP4 124.124.124.222
m=audio 2222 RTP/AVP 4
a=ptime:30
} ; RTP profile for G.723 is 4
}
}
}
}
}- This is acknowledged. The stream port number is different from the control port number. In this case it is 1111 (in the SDP). ✨
MG2 to MGC:
MEGACO/1 [124.124.124.222]:55555
Reply = 50003 {
Context = 5000 {
Add = A5555,
Add = A5556{
Media {
Stream = 1 {
Local {
v=0
c=IN IP4 125.125.125.111
m=audio 1111 RTP/AVP 4
}
}
} ; RTP profile for G723 is 4
}
}
}- The above IPAddr and UDPport need to be given to MG1 now. 📮
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Transaction = 10005 {
Context = 2000 {
Modify = A4444 {
Signals {cg/rt}
},
Modify = A4445 {
Media {
Stream = 1 {
Remote {
v=0
c=IN IP4 125.125.125.111
m=audio 1111 RTP/AVP 4
}
} ; RTP profile for G723 is 4
}
}
}
}MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Reply = 10005 {
Context = 2000 {Modify = A4444, Modify = A4445}
}- The two gateways are now connected and User 1 hears the RingBack. The MG2 now waits until User2 picks up the receiver and then the two-way call is established. 📞🎶 the ringback is so dramatic, and then the vibe shifts to the two-way call
From MG2 to MGC:
MEGACO/1 [125.125.125.111]:55555
Transaction = 50005 {
Context = 5000 {
Notify = A5555 {ObservedEvents =1234 {
19990729T22020002:al/of}}
}
}From MGC to MG2:
MEGACO/1 [123.123.123.4]:55555
Reply = 50005 {
Context = - {Notify = A5555}
}From MGC to MG2:
MEGACO/1 [123.123.123.4]:55555
Transaction = 50006 {
Context = 5000 {
Modify = A5555 {
Events = 1235 {al/on},
Signals { } ; to turn off ringing
}
}
}From MG2 to MGC:
MEGACO/1 [125.125.125.111]:55555
Reply = 50006 {
Context = 5000 {Modify = A4445}
}- Change mode on MG1 to SendReceive, and stop the ringback. 🎧 MG1 is finally getting its voice back, bestie 🫶
MGC to MG1:
MEGACO/1 [123.123.123.4]:55555
Transaction = 10006 {
Context = 2000 {
Modify = A4445 {
Media {
Stream = 1 {
LocalControl {
Mode=SendReceive
}
}
}
},
Modify = A4444 {
Signals { }
}
}
}from MG1 to MGC:
MEGACO/1 [124.124.124.222]:55555
Reply = 10006 {
Context = 2000 {Modify = A4445, Modify = A4444}}- The MGC decides to Audit the RTP termination on MG2. 🔍👀
MEGACO/1 [123.123.123.4]:55555
Transaction = 50007 {
Context = - {AuditValue = A5556{
Audit{Media, DigitMap, Events, Signals, Packages, Statistics
}}
}
}- The MG2 replies. 🫧
MEGACO/1 [125.125.125.111]:55555
Reply = 50007 {
Context = - {
AuditValue = A5556 {
Media {
TerminationState { ServiceStates = InService,
Buffer = OFF },
Stream = 1 {
LocalControl { Mode = SendReceive,
nt/jit=40 },
Local {
v=0
c=IN IP4 125.125.125.111
m=audio 1111 RTP/AVP 4
a=ptime:30
},
Remote {
v=0
c=IN IP4 124.124.124.222
m=audio 2222 RTP/AVP 4
a=ptime:30
} } },
Events,
Signals,
DigitMap,
Packages {nt-1, rtp-1},
Statistics { rtp/ps=1200, ; packets sent
nt/os=62300, ; octets sent
rtp/pr=700, ; packets received
nt/or=45100, ; octets received
rtp/pl=0.2, ; % packet loss
rtp/jit=20,
rtp/delay=40 } ; avg latency
}
}
}- When the MGC receives an onhook signal from one of the MGs, it brings down the call. In this example, the user at MG2 hangs up first. 📴 bye bye, User 2 💀
From MG2 to MGC:
MEGACO/1 [125.125.125.111]:55555
Transaction = 50008 {
Context = 5000 {
Notify = A5555 {ObservedEvents =1235 {
19990729T24020002:al/on}
}
}
}From MGC to MG2:
MEGACO/1 [123.123.123.4]:55555
Reply = 50008 {
Context = - {Notify = A5555}
}- The MGC now sends both MGs a Subtract to take down the call. Only the subtracts to MG2 are shown here. Each termination has its own set of statistics that it gathers. An MGC may not need to request both to be returned. A5555 is a physical termination, and A5556 is an RTP termination. 🧹 everything gets cleaned up, no mess left behind
From MGC to MG2:
MEGACO/1 [123.123.123.4]:55555
Transaction = 50009 {
Context = 5000 {
Subtract = A5555 {Audit{Statistics}},
Subtract = A5556 {Audit{Statistics}}
}
}From MG2 to MGC:
MEGACO/1 [125.125.125.111]:55555
Reply = 50009 {
Context = 5000 {
Subtract = A5555 {
Statistics {
nt/os=45123, ; Octets Sent
nt/dur=40 ; in seconds
}
},
Subtract = A5556 {
Statistics {
rtp/ps=1245, ; packets sent
nt/os=62345, ; octets sent
rtp/pr=780, ; packets received
nt/or=45123, ; octets received
rtp/pl=10, ; % packets lost
rtp/jit=27,
rtp/delay=48 ; average latency
}
}
}
}- The MGC now sets up both MG1 and MG2 to be ready to detect the next off-hook event. See step 1. Note that this could be the default state of a termination in the null context, and if this were the case, no message need be sent from the MGC to the MG. Once a termination returns to the null context, it goes back to the default termination values for that termination. 🔄💜 and that's a wrap on the whole call flow, periodt 💅✨
Authors' Addresses 🎀
Fernando Cuervo
Nortel Networks
P.O. Box 3511, Station C
Ottawa, ON K1Y 4H7
Canada
E-mail: cuervo@nortelnetworks.com
Nancy Greene
Nortel Networks
P.O. Box 3511, Station C
Ottawa, ON K1Y 4H7
Canada
E-mail: ngreene@nortelnetworks.com
Christian Huitema*
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
USA
E-mail: huitema@microsoft.com
* The contribution of Christian Huitema was developed while he was
employed by Telcordia Technologies.
Abdallah Rayhan
Nortel Networks
P.O. Box 3511, Station C
Ottawa, ON K1Y 4H7
Canada
E-mail: arayhan@nortelnetworks.com
Brian Rosen
Marconi
1000 FORE Drive
Warrendale, PA 15086
USA
E-mail: brian.rosen@marconi.com
John Segers
Lucent Technologies, Room HE 303
Dept. Forward Looking Work
P.O. Box 18, 1270 AA Huizen
The Netherlands
E-mail: jsegers@lucent.comFull Copyright Statement ✨
okay so the legal part is lowkey important, so I'm keeping the actual words exact. no cap, you don't want to mess with this one 🫶
Copyright (C) The Internet Society (2000). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.the vibe is basically: you can copy it and share it, and you can make derivative works that explain it or help people implement it 🦋 but the document itself can't be edited (keep the notice, keep the Internet Society references), except for a few specific cases like standards development or translation. those permissions are forever, and the document comes "AS IS" with no warranties at all, so don't come crying to the IETF if something goes sideways 💀
Acknowledgement 🌸
funding for the RFC Editor function is currently provided by the Internet Society 💜 so, the people who keep the RFC series running are backed by the Internet Society right now 🧚
📦 where this page comes from
- ietf: rfc3015 2000-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms