From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/megaco/doc/standard/H.248.1-Corr1-200403.doc | Bin 0 -> 296448 bytes .../doc/standard/draft-ietf-megaco-h248v2-04.txt | 12079 +++++++++++++++++++ .../doc/standard/implementors_guide_v10-13.pdf | Bin 0 -> 219014 bytes lib/megaco/doc/standard/rfc2327.txt | 2355 ++++ lib/megaco/doc/standard/rfc3266.txt | 283 + lib/megaco/doc/standard/rfc3525.txt | 11931 ++++++++++++++++++ lib/megaco/doc/standard/rfc4234.txt | 899 ++ lib/megaco/doc/standard/rfc4566.txt | 2747 +++++ 8 files changed, 30294 insertions(+) create mode 100644 lib/megaco/doc/standard/H.248.1-Corr1-200403.doc create mode 100644 lib/megaco/doc/standard/draft-ietf-megaco-h248v2-04.txt create mode 100644 lib/megaco/doc/standard/implementors_guide_v10-13.pdf create mode 100644 lib/megaco/doc/standard/rfc2327.txt create mode 100644 lib/megaco/doc/standard/rfc3266.txt create mode 100644 lib/megaco/doc/standard/rfc3525.txt create mode 100644 lib/megaco/doc/standard/rfc4234.txt create mode 100644 lib/megaco/doc/standard/rfc4566.txt (limited to 'lib/megaco/doc/standard') diff --git a/lib/megaco/doc/standard/H.248.1-Corr1-200403.doc b/lib/megaco/doc/standard/H.248.1-Corr1-200403.doc new file mode 100644 index 0000000000..39ef6e4efa Binary files /dev/null and b/lib/megaco/doc/standard/H.248.1-Corr1-200403.doc differ diff --git a/lib/megaco/doc/standard/draft-ietf-megaco-h248v2-04.txt b/lib/megaco/doc/standard/draft-ietf-megaco-h248v2-04.txt new file mode 100644 index 0000000000..abb1df8988 --- /dev/null +++ b/lib/megaco/doc/standard/draft-ietf-megaco-h248v2-04.txt @@ -0,0 +1,12079 @@ + + + Media Gateway Control (megaco) C. Groves, M. Pantaleo + Internet Draft LM Ericsson + Document: draft-ietf-megaco-h248v2-04.txt T. Anderson + Expires: October 2003 Lucent Technologies + T. Taylor + Nortel Networks + (Editors) + April 2003 + + + The Megaco/H.248 Gateway Control Protocol, version 2 + + Status of this Memo + + This document is an Internet-Draft and is in full conformance with + all provisions of Section 10 of RFC2026. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + Abstract + + This document describes the second version of the general-purpose + gateway control protocol standardized as Megaco in the IETF and as + Recommendation H.248 (now H.248.1) in the ITU-T. It is common text + with Recommendation H.248.1 (05/02), published by the ITU-T. Megaco + v2 includes the corrections to RFC 3015 which resulted in RFC xxxx + [draft-ietf-megaco-3015corr-02.txt], plus the following new + capabilities: + + - ability to audit specific properties, events, signals and + statistics + - use of serviceChange to indicate that capabilities have changed in + the Media Gateway + - playing a signal on the Root Termination + - limiting the number of repetitions of transaction pending + - allowing topology to be set per stream + - ability to audit context properties + + + Groves et al Expires - October 2003 [Page 1] + Megaco Protocol version 2 April 2003 + + + - new Nx64K multiplex type + - provision for digit buffering when a digit map completes. + + In addition, the use of the Modem Descriptor was deprecated. + + A detailed list of changes from draft-ietf-megaco-3015corr- + 02.txt/H.248.1 (03/02) to this document is given in Appendix II at + the end of this document. + + Conventions used in this document + + 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 RFC-2119. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 2] + Megaco Protocol version 2 April 2003 + + + Table of Contents + + 1 SCOPE.................................................6 + + 2 REFERENCES............................................6 + 2.1 Normative references..................................7 + 2.2 Informative references................................9 + + 3 DEFINITIONS..........................................10 + + 4 ABBREVIATIONS........................................11 + + 5 A NOTE ON CONVENTIONS................................12 + + 6 CONNECTION MODEL.....................................12 + 6.1 Contexts.............................................15 + 6.1.1 Context attributes and descriptors...................16 + 6.1.2 Creating, deleting and modifying Contexts............16 + 6.2 Terminations.........................................16 + 6.2.1 Termination dynamics.................................20 + 6.2.2 TerminationIDs.......................................20 + 6.2.3 Packages.............................................21 + 6.2.4 Termination properties and descriptors...............22 + 6.2.5 Root Termination.....................................24 + + 7 COMMANDS.............................................25 + 7.1 Descriptors..........................................26 + 7.1.1 Specifying parameters................................26 + 7.1.2 Modem descriptor.....................................27 + 7.1.3 Multiplex descriptor.................................27 + 7.1.4 Media descriptor.....................................28 + 7.1.5 TerminationState descriptor..........................28 + 7.1.6 Stream descriptor....................................29 + 7.1.7 LocalControl descriptor..............................30 + 7.1.8 Local and Remote descriptors.........................31 + 7.1.9 Events descriptor....................................34 + 7.1.10 EventBuffer descriptor...............................37 + 7.1.11 Signals descriptor...................................37 + 7.1.12 Audit descriptor.....................................39 + 7.1.13 ServiceChange descriptor.............................40 + 7.1.14 DigitMap descriptor..................................40 + 7.1.14.1 DigitMap definition, creation, modification and + deletion.........................................40 + 7.1.14.2 DigitMap Timers......................................41 + 7.1.14.3 DigitMap Syntax......................................41 + 7.1.14.4 DigitMap Completion Event............................42 + 7.1.14.5 DigitMap Procedures..................................43 + 7.1.14.6 DigitMap Activation..................................45 + 7.1.14.7 Interaction Of DigitMap and Event Processing.........45 + + + Groves et al Expires - October 2003 [Page 3] + Megaco Protocol version 2 April 2003 + + + 7.1.14.8 Wildcards............................................46 + 7.1.14.9 Example..............................................46 + 7.1.15 Statistics descriptor................................47 + 7.1.16 Packages descriptor..................................47 + 7.1.17 ObservedEvents descriptor............................47 + 7.1.18 Topology descriptor..................................47 + 7.1.19 Error Descriptor.....................................51 + + 7.2 Command Application Programming Interface............51 + 7.2.1 Add..................................................52 + 7.2.2 Modify...............................................53 + 7.2.3 Subtract.............................................54 + 7.2.4 Move.................................................56 + 7.2.5 AuditValue...........................................57 + 7.2.6 AuditCapabilities....................................60 + 7.2.7 Notify...............................................62 + 7.2.8 ServiceChange........................................63 + 7.2.9 Manipulating and Auditing Context Attributes.........68 + 7.2.10 Generic Command Syntax...............................69 + + 8 TRANSACTIONS.........................................69 + 8.1 Common parameters....................................71 + 8.1.1 Transaction Identifiers..............................71 + 8.1.2 Context Identifiers..................................71 + 8.2 Transaction Application Programming Interface........71 + 8.2.1 TransactionRequest...................................72 + 8.2.2 TransactionReply.....................................72 + 8.2.3 TransactionPending...................................74 + 8.3 Messages.............................................75 + + 9 TRANSPORT............................................75 + 9.1 Ordering of Commands.................................76 + 9.2 Protection against Restart Avalanche.................77 + + 10 SECURITY CONSIDERATIONS..............................78 + 10.1 Protection of Protocol Connections...................79 + 10.2 Interim AH scheme....................................79 + 10.3 Protection of Media Connections......................80 + + 11 MG-MGC CONTROL INTERFACE.............................81 + 11.1 Multiple Virtual MGs.................................81 + 11.2 Cold start...........................................82 + 11.3 Negotiation of protocol version......................82 + 11.4 Failure of a MG......................................83 + 11.5 Failure of an MGC....................................84 + + 12 PACKAGE DEFINITION...................................85 + 12.1 Guidelines for defining packages.....................85 + 12.1.1 Package..............................................86 + + + Groves et al Expires - October 2003 [Page 4] + Megaco Protocol version 2 April 2003 + + + 12.1.2 Properties...........................................87 + 12.1.3 Events...............................................88 + 12.1.4 Signals..............................................88 + 12.1.5 Statistics...........................................89 + 12.1.6 Procedures...........................................89 + 12.2 Guidelines to defining Parameters to Events and + Signals..........................................89 + 12.3 Lists................................................90 + 12.4 Identifiers..........................................90 + 12.5 Package registration.................................91 + + 13 PROFILE DEFINITION...................................91 + + 14 IANA CONSIDERATIONS..................................92 + 14.1 Packages.............................................92 + 14.2 Error codes..........................................93 + 14.3 ServiceChange reasons................................93 + 14.4 Profiles.............................................94 + + ANNEX A BINARY ENCODING OF THE PROTOCOL......................95 + A.1 Coding of wildcards..................................95 + A.2 ASN.1 syntax specification...........................96 + + ANNEX B TEXT ENCODING OF THE PROTOCOL.......................120 + B.1 Coding of wildcards.................................120 + B.2 ABNF specification..................................120 + B.4 Hexadecimal octet sequence..........................137 + + ANNEX C TAGS FOR MEDIA STREAM PROPERTIES....................138 + C.1 General media attributes............................138 + C.2 Mux properties......................................140 + C.3 General bearer properties...........................140 + C.4 General ATM properties..............................141 + C.5 Frame Relay.........................................145 + C.6 IP 146 + C.7 ATM AAL2............................................146 + C.8 ATM AAL1............................................148 + C.9 Bearer capabilities.................................150 + C.10 AAL5 properties.....................................161 + C.11 SDP equivalents.....................................162 + C.12 H.245...............................................164 + + ANNEX D TRANSPORT OVER IP...................................165 + D.1 Transport over IP/UDP using Application Level Framing + (ALF)............................................165 + D.1.1 Providing At-Most-Once functionality................165 + D.1.2 Transaction identifiers and three-way handshake.....166 + D.1.2.1 Transaction identifiers.............................166 + D.1.2.2 Three-way handshake.................................166 + + + Groves et al Expires - October 2003 [Page 5] + Megaco Protocol version 2 April 2003 + + + D.1.3 Computing retransmission timers.....................167 + D.1.4 Provisional responses...............................168 + D.1.5 Repeating Requests, Responses and Acknowledgements..168 + D.2 Using TCP...........................................170 + D.2.1 Providing the At-Most-Once functionality............170 + D.2.2 Transaction identifiers and three-way handshake.....170 + D.2.3 Computing retransmission timers.....................170 + D.2.4 Provisional responses...............................171 + D.2.5 Ordering of commands................................171 + + ANNEX E BASIC PACKAGES......................................172 + E.1 Generic.............................................172 + E.2 Base Root Package...................................174 + E.3 Tone Generator Package..............................178 + E.4 Tone Detection Package..............................179 + E.5 Basic DTMF Generator Package........................182 + E.6 DTMF detection Package..............................184 + E.7 Call Progress Tones Generator Package...............186 + E.8 Call Progress Tones Detection Package...............187 + E.9 Analog Line Supervision Package.....................188 + E.10 Basic Continuity Package............................192 + E.11 Network Package.....................................195 + E.12 RTP Package.........................................197 + E.13 TDM Circuit Package.................................199 + + APPENDIX I Example Call Flows..................................201 + I.1 Residential Gateway to Residential Gateway Call.....201 + I.1.1 Programming Residential GW Analog Line Terminations + for Idle Behaviour..............................201 + I.1.2 Collecting Originator Digits and Initiating Termination + .................................................203 + + APPENDIX II CHANGES FROM RFC XXXX [draft-ietf-megaco-3015corr + -02.txt].........................................213 + + INTELLECTUAL PROPERTY RIGHTS....................................217 + Acknowledgments.................................................218 + Authors' Addresses..............................................219 + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 6] + Megaco Protocol version 2 April 2003 + + + 1 SCOPE + + This document defines the protocols used between elements of a + physically decomposed multimedia gateway. There are no functional + differences from a system view between a decomposed gateway, with + distributed sub-components potentially on more than one physical + device, and a monolithic gateway such as described in Recommendation + H.246. This document does not define how gateways, multipoint control + units or interactive voice response units (IVRs) work. Instead it + creates a general framework that is suitable for these applications. + + Packet network interfaces may include IP, ATM or possibly others. The + interfaces will support a variety of Switched Circuit Network (SCN) + signalling systems, including tone signalling, ISDN, ISUP, QSIG and + GSM. National variants of these signalling systems will be supported + where applicable. + + Products claiming compliance with Version 1 of H.248.1 shall comply + with all of the mandatory requirements of H.248.1 originally approved + in 06/2000 and reissued in 03/2002. H.248.1 (03/2002) is common text + with RFC xxxx [draft-ietf-megaco-3015corr-03.txt]. + + Products claiming compliance with Version 2 of H.248.1 shall comply + with all of the mandatory requirements of H.248.1 approved on + 05/2002. H.248.1 (05/2002) is common text with this document. + + Products shall indicate the version of the protocol in use by using + ServiceChangeVersion as æ1Æ to refer to RFC xxxx/H.248.1 (03/2002) + and æ2Æ to refer to this specification/H.248.1 (05/2002). + + + 2 REFERENCES + + The following ITU-T Recommendations and other references contain + provisions which, through reference in this text, constitute + provisions of this Recommendation. At the time of publication, the + editions indicated were valid. All Recommendations and other + references are subject to revision; all users of this Recommendation + are therefore encouraged to investigate the possibility of applying + the most recent edition of the Recommendations and other references + listed below. A list of the currently valid ITU-T Recommendations is + regularly published. + + 2.1 Normative references + + - ITU-T Recommendation H.225.0 (2000), Call signalling protocols and + media stream packetization for packet-based multimedia + communication systems. + + + + Groves et al Expires - October 2003 [Page 7] + Megaco Protocol version 2 April 2003 + + + - ITU-T Recommendation H.235 (1998), Security and encryption for H- + Series (H.323 and other H.245-based) multimedia terminals. + + - ITU-T Recommendation H.245 (1998), Control protocol for multimedia + communication. + + - 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. + + - ITU-T Recommendation H.248.4 (2000), Transport over Stream Control + Transmission Protocol (SCTP). + + - ITU-T Recommendation H.248.5 (2000), Transport over ATM. + + - ITU-T Recommendation H.248.8 (2002), H.248 Error Codes and Service + Change Reasons. + + - ITU-T Recommendation H.323 (1999), Packet-based multimedia + communication systems. + + - ITU-T Recommendation I.363.1 (1996), B-ISDN ATM adaptation layer + (AAL) specification: Type 1 AAL. + + - ITU-T Recommendation I.363.2 (1997), B-ISDN ATM adaptation layer + (AAL) specification: Type 2 AAL. + + - ITU-T Recommendation I.363.5 (1996), B-ISDN ATM adaptation layer + (AAL) specification: Type 5 AAL. + + - ITU-T Recommendation I.366.1 (1998), Segmentation and Reassembly + Service Specific Convergence Sublayer for the AAL type 2. + + - ITU-T Recommendation I.366.2 (1999), AAL type 2 service specific + convergence sublayer for trunking. + + - ITU-T Recommendation I.371 (2000), Traffic control and congestion + control in B-ISDN. + + - ITU-T Recommendation Q.763 (1999), Signalling System No. 7 - ISDN + user part formats and codes. + + - ITU-T Recommendation Q.765.5 (2001), Application transport + mechanism - Bearer independent call control (BICC). + + - ITU-T Recommendation Q.931 (1998), ISDN user-network interface + layer 3 specification for basic call control. + + + + + Groves et al Expires - October 2003 [Page 8] + Megaco Protocol version 2 April 2003 + + + - ITU-T Recommendation Q.2630.1 (1999), AAL type 2 signalling + protocol (Capability Set 1). + + - ITU-T Recommendation Q.2931 (1995), Digital Subscriber Signalling + System No. 2 (DSS2) - User-Network Interface (UNI) Layer 3 + specification for basic call/connection control. + + - ITU-T Recommendation Q.2941.1 (1997), Digital Subscriber + Signalling System No. 2 - Generic identifier transport. + + - ITU-T Recommendation Q.2961.1 (1995), Additional signalling + capabilities to support traffic parameters for the tagging option + and the sustainable call note parameter set. + + - ITU-T Recommendation Q.2961.2 (1997), Additional traffic + parameters: Support of ATM transfer capability in the broadband + bearer capability information element. + + - ITU-T Recommendation Q.2965.1 (1999), Digital subscriber + signalling system No. 2 - Support of Quality of Service classes. + + - ITU-T Recommendation Q.2965.2 (1999), Digital subscriber + signalling system No. 2 - Signalling of individual Quality of + Service parameters. + + - ITU-T Recommendation V.76 (1996), Generic multiplexer using V.42 + LAPM-based procedures. + + - ITU-T Recommendation X.213 (1995), Information technology - Open + Systems Interconnection - Network service definition plus + Amendment 1 (1997), Addition of the Internet protocol address + format identifier. + + - ITU-T Recommendation X.680 (1997), Information technology - + Abstract Syntax Notation One (ASN.1): Specification of basic + notation. + + - ITU-T Recommendation X.690 (1997), Information Technology - ASN.1 + Encoding Rules: Specification of Basic Encoding Rules (BER), + Canonical Encoding Rules (CER) and Distinguished Encoding Rules + (DER). + + - ATM Forum (1996), ATM User-Network Interface (UNI) Signalling + Specification - Version 4.0. + + - RFC 1006, ISO Transport Service on top of the TCP, Version 3. + + - RFC 2026, The Internet Standards Process -- Revision 3. + + + + Groves et al Expires - October 2003 [Page 9] + Megaco Protocol version 2 April 2003 + + + - RFC 2119, Key words for use in RFCs to Indicate Requirement + Levels. + + - RFC 2234, Augmented BNF for Syntax Specifications: ABNF. + + - RFC 2327, SDP: Session Description Protocol. + + - RFC 2402, IP Authentication Header. + + - RFC 2406, IP Encapsulating Security Payload (ESP). + + 2.2 Informative references + + - ITU-T Recommendation E.180/Q.35 (1998), Technical characteristics + of tones for the telephone service. + + - ITU-T Recommendation G.711 (1988), Pulse Code Modulation (PCM) of + voice frequencies. + + - ITU-T Recommendation H.221 (1999), 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. + + - ITU-T Recommendation H.226 (1998), Channel aggregation protocol + for multilink operation on circuit-switched networks. + + - ITU-T Recommendation Q.724 (1998), Signalling procedures. + + - ITU-T Recommendation Q.764 (1999), Signalling system No. 7 - ISDN + user part signalling procedures. + + - ITU-T Recommendation Q.1902.4 (2001), Bearer independent call + control protocol - Basic call procedures. + + - RFC 768, User Datagram Protocol. + + - RFC 791, Internet protocol. + + - RFC 793, Transmission control protocol. + + - RFC 1661, The Point-to-Point Protocol (PPP). + + - RFC 1889, RTP: A Transport Protocol for Real-Time Applications. + + - RFC 1890, RTP Profile for Audio and Video Conferences with Minimal + Control. + + + + Groves et al Expires - October 2003 [Page 10] + Megaco Protocol version 2 April 2003 + + + - RFC 2401, Security Architecture for the Internet Protocol. + + - RFC 2543, SIP: Session Initiation Protocol. + + - RFC 2460, Internet Protocol, Version 6 (IPv6) Specification. + + - RFC 2805, Media Gateway Control Protocol Architecture and + Requirements. + + + 3 DEFINITIONS + + This document defines the following terms: + + Access gateway: + A type of gateway that provides a User-Network Interface (UNI) such + as ISDN. + + Descriptor: + A syntactic element of the protocol that groups related properties. + For instance, the properties of a media flow on the MG can be set by + the MGC by including the appropriate descriptor in a command. + + Media Gateway (MG): + The media gateway converts media provided in one type of network to + the format required in another type of network. For example, a MG + could terminate bearer channels from a switched circuit network (e.g. + DS0s) and media streams from a packet network (e.g. RTP streams in an + IP network). This gateway may be capable of processing audio, video + and T.120 alone or in any combination, and will be capable of full + duplex media translations. The MG may also play audio/video messages + and perform other IVR functions, or may perform 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 that typically includes processing of audio, video and + data. + + Residential gateway: + A gateway that interworks an analogue line to a packet network. A + residential gateway typically contains one or two analogue lines and + is located at the customer premises. + + + + + + Groves et al Expires - October 2003 [Page 11] + Megaco Protocol version 2 April 2003 + + + SCN FAS signalling gateway: + This function contains 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 contains 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/sent by a media gateway + as part of a call or conference. + + Trunk: + A communication channel between two switching systems such as a DS0 + on a T1 or E1 line. + + Trunking gateway: + A gateway between SCN network and packet network that typically + terminates a large number of digital circuits. + + + 4 ABBREVIATIONS + + This document uses the following abbreviations: + + ALF Application Layer Framing + + 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 (superseded by Internet + Corporation for Assigned Names and Numbers (ICANN)) + + IP Internet Protocol + + ISUP ISDN User Part + + IVR Interactive Voice Response + + + Groves et al Expires - October 2003 [Page 12] + Megaco Protocol version 2 April 2003 + + + 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. 7 + + + 5 A NOTE ON CONVENTIONS + + According to ITU-T practice, "SHOULD" refers to a suggested but + optional feature or procedure. "SHOULD" as used by the ITU-T is thus + a weaker requirement level than in IETF practice as defined in RFC + 2119 and cited at the beginning of this document. In view of this + difference, the present document calls out all instances of "SHOULD" + for review and replacement by "suggested" where that appears to be + the intent. + + 6 CONNECTION MODEL + + The connection model for the protocol describes the logical entities, + or objects, within the Media Gateway that can be controlled by the + Media Gateway Controller. The main abstractions used in the + connection model are Terminations and Contexts. + + A Termination sources and/or sinks one or more streams. In a + multimedia conference, a Termination can be multimedia and sources or + sinks multiple media streams. The media stream parameters, as well as + bearer parameters are encapsulated within the Termination. + + A Context is an association between a collection of Terminations. + There is a special type of Context, the null Context, which contains + all Terminations that are not associated to any other Termination. + For instance, in a decomposed access gateway, all idle lines are + represented by Terminations in the null Context. + + + + Groves et al Expires - October 2003 [Page 13] + Megaco Protocol version 2 April 2003 + + + Following is a graphical depiction of these concepts. The diagram of + Figure 1 gives several examples and is not meant to be an all- + inclusive illustration. The asterisk box in each of the Contexts + represents the logical association of Terminations implied by the + Context. + + +------------------------------------------------------+ + |Media Gateway | + | +-------------------------------------------------+ | + | |Context +-------------+ | | + | | | Termination | | | + | | |-------------| | | + | | +-------------+ +->| SCN Bearer |<---+-> + | | | Termination | +-----+ | | Channel | | | + | | |-------------| | |---+ +-------------+ | | + <-+--->| RTP Stream |---| * | | | + | | | | | |---+ +-------------+ | | + | | +-------------+ +-----+ | | Termination | | | + | | | |-------------| | | + | | +->| SCN Bearer |<---+-> + | | | Channel | | | + | | +-------------+ | | + | +-------------------------------------------------+ | + | | + | | + | +------------------------------+ | + | (NULL Context) |Context | | + | +-------------+ | +-------------+ | | + | | Termination | | +-----+ | Termination | | | + | |-------------| | | | |-------------| | | + | | SCN Bearer | | | * |------| SCN Bearer |<---+-> + | | Channel | | | | | Channel | | | + | +-------------+ | +-----+ +-------------+ | | + | +------------------------------+ | + | | + | | + | +-------------------------------------------------+ | + | |Context | | + | | +-------------+ +-------------+ | | + | | | Termination | +-----+ | Termination | | | + | | |-------------| | | |-------------| | | + <-+--->| SCN Bearer |---| * |------| SCN Bearer |<---+-> + | | | Channel | | | | Channel | | | + | | +-------------+ +-----+ +-------------+ | | + | +-------------------------------------------------+ | + | ___________________________________________________ | + +------------------------------------------------------+ + + Figure 1: Examples of Megaco/H.248 Connection Model + + + Groves et al Expires - October 2003 [Page 14] + Megaco Protocol version 2 April 2003 + + + + + The example in Figure 2 shows an example of one way to accomplish a + call-waiting scenario in a decomposed access gateway, illustrating + the relocation of a Termination between Contexts. Terminations T1 and + T2 belong to Context C1 in a two-way audio call. A second audio call + is waiting for T1 from Termination T3. T3 is alone in Context C2. T1 + accepts the call from T3, placing T2 on hold. This action results in + T1 moving into Context C2, as shown in Figure 3. + + +------------------------------------------------------+ + |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 |---| * | | | + | | | | | | | | + | | +-------------+ +-----+ | | + | +-------------------------------------------------+ | + | | + | +-------------------------------------------------+ | + + + Groves et al Expires - October 2003 [Page 15] + Megaco Protocol version 2 April 2003 + + + | |Context C2 | | + | | +-------------+ +-------------+ | | + | | | Term. T1 | +-----+ | Term. T3 | | | + | | |-------------| | | |-------------| | | + <-+--->| SCN Bearer |---| * |------| SCN Bearer |<---+-> + | | | Channel | | | | Channel | | | + | | +-------------+ +-----+ +-------------+ | | + | +-------------------------------------------------+ | + +------------------------------------------------------+ + + Figure 3. Example Call Waiting Scenario / Answer by T1 + + + + 6.1 Contexts + + A Context is an association between a number of Terminations. The + Context describes the topology (who hears/sees whom) and the media + mixing and/or switching parameters if more than two Terminations are + involved in the association. + + There is a special Context called the null Context. It contains + Terminations that are not associated to any other Termination. + Terminations in the null Context can have their parameters examined + or modified, and may have events detected on them. + + In general, an Add command is used to add Terminations to Contexts. + If the MGC does not specify an existing Context to which the + Termination is to be added, the MG creates a new Context. A + Termination may be removed from a Context with a Subtract command, + and a Termination may be moved from one Context to another with a + Move command. A Termination SHALL exist in only one Context at a + time. + + The maximum number of Terminations in a Context is a MG property. + Media gateways that offer only point-to-point connectivity might + allow at most two Terminations per Context. Media gateways that + support multipoint conferences might allow three or more Terminations + per Context. + + 6.1.1 Context attributes and descriptors + + The attributes of Contexts are: + + - ContextID. + + - The topology (who hears/sees whom). + + + + + Groves et al Expires - October 2003 [Page 16] + Megaco Protocol version 2 April 2003 + + + The topology of a Context describes the flow of media between the + Terminations within a Context. In contrast, the mode of a + Termination (send/receive/...) describes the flow of the media at + the ingress/egress of the media gateway. + + - The priority is used for a Context in order to provide the MG with + information about a certain precedence handling for a Context. The + MGC can also use the priority to control autonomously the traffic + precedence in the MG in a smooth way in certain situations (e.g. + restart), when a lot of Contexts must be handled simultaneously. + Priority 0 is the lowest priority and a priority of 15 is the + highest priority. + + - An indicator for an emergency call is also provided to allow a + preference handling in the MG. + + 6.1.2 Creating, deleting and modifying Contexts + + The protocol can be used to (implicitly) create Contexts and modify + the parameter values of existing Contexts. The protocol has commands + to add Terminations to Contexts, subtract them from Contexts, and to + move Terminations between Contexts. Contexts are deleted implicitly + when the last remaining Termination is subtracted or moved out. + + 6.2 Terminations + + A Termination is a logical entity on a MG that sources and/or sinks + media and/or control streams. A Termination is described by a number + of characterizing Properties, which are grouped in a set of + Descriptors that are included in commands. Terminations have unique + identities (TerminationIDs), assigned by the MG at the time of their + creation. + + Terminations representing physical entities have a semi-permanent + existence. For example, a Termination representing a TDM channel + might exist for as long as it is provisioned in the gateway. + Terminations representing ephemeral information flows, such as RTP + flows, would usually exist only for the duration of their use. + + Ephemeral Terminations are created by means of an Add command. They + are destroyed by means of a Subtract command. In contrast, when a + physical Termination is Added to or Subtracted from a Context, it is + taken from or to the null Context, respectively. + + Terminations may have signals applied to them (see 7.1.11). + Terminations may be programmed to detect Events, the occurrence of + which can trigger notification messages to the MGC, or action by the + MG. Statistics may be accumulated on a Termination. Statistics are + + + + Groves et al Expires - October 2003 [Page 17] + Megaco Protocol version 2 April 2003 + + + reported to the MGC upon request (by means of the AuditValue command, + see 7.2.5) and when the Termination is subtracted from a context. + + Multimedia gateways may process multiplexed media streams. For + example, Recommendation H.221 describes a frame structure for + multiple media streams multiplexed on a number of digital 64 kbit/s + channels. Such a case is handled in the connection model in the + following way. For every bearer channel that carries part of the + multiplexed streams, there is a physical or ephemeral "bearer + Termination". The bearer Terminations that source/sink the digital + channels are connected to a separate Termination called the + "multiplexing Termination". The multiplexing termination is an + ephemeral termination representing a frame-oriented session. The + MultiplexDescriptor for this Termination describes the multiplex used + (e.g. H.221 for an H.320 session) and indicates the order in which + the contained digital channels are assembled into a frame. + + Multiplexing terminations may be cascades (e.g., H.226 multiplex of + digital channels feeding into a H.223 multiplex supporting an H.324 + session). + + The individual media streams carried in the session are described by + StreamDescriptors on the multiplexing Termination. These media + streams can be associated with streams sourced/sunk by Terminations + in the Context other than the bearer Terminations supporting the + multiplexing Termination. Each bearer Termination supports only a + single data stream. These data streams do not appear explicitly as + streams on the multiplexing Termination and they are hidden from the + rest of the context. + + Figures 4, 5, 6, and 6a illustrate typical applications of the + multiplexing termination and Multiplex Descriptor. + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 18] + Megaco Protocol version 2 April 2003 + + + +-----------------------------------+ + | Context +-------+ | + +----+ | | | + Circuit 1 -|--| TC1|---------+ Tmux | | + | +----+ (Str 1) | | Audio +-----+ + | | | +-----*-----+ |----- + | +----+ | H.22x | Stream 1 | | + Circuit 2 -|--| TC2|---------+ multi-| | TR1 | + | +----+ (Str 1) | plex | |(RTP)| + | | | | Video | | + | +----+ | +-----*-----+ |----- + Circuit 3 -|--| TC3|---------+ | Stream 2 | | + / +----+ (Str 1) | | +-----+ + / | +-------+ | + / +-----------------\-----------------+ + Audio, video, and control \ + signals are carried in frames Tmux is an ephemeral with two + spanning the circuits. explicit Stream Descriptors + and a Multiplex Descriptor. + + Figure 4: Multiplexed Termination Scenario - Circuit to Packet + (Asterisks * denote the centre of the context) + + + + Context + +--------------------------------------+ + | +-------+ +-------+ | + +----+ | | | | +----+ + Circuit 1 ----| TC1|---+ Tmux1 | Audio | Tmux2 +---| TC4|--- + +----+ | +---*----+ | +----+ + | | | Str 1 | | | + +----+ | H.22x | | H.22x | +----+ + Circuit 2 ----| TC2|---+ multi-| | multi-+---| TC5|--- + +----+ | plex | | plex | +----+ + | | | Video | | | + +----+ | +---*----+ | +----+ + Circuit 3 ----| TC3|---+ | Str 2 | +---| TC6|--- + +----+ | | | | +----+ + | +-------+ +-------+ | + +-----------------\-----/--------------+ + \ / + Tmux1 and Tmux2 are ephemerals each with two + . explicit Stream Descriptors and a Multiplex Descriptor. + + Figure 5: Multiplexed Termination Scenario - Circuit to Circuit + (Asterisks * denote the centre of the context) + + + + + Groves et al Expires - October 2003 [Page 19] + Megaco Protocol version 2 April 2003 + + + + +-----------------------------------+ + | Context +-------+ | + +----+ | | | + Circuit 1 -|--| TC1|---------+ Tmux | | + | +----+ (Str 1) | | Audio +-----+ + | | | +-----*-----+ TR1 |----- + | +----+ | H.22x | Stream 1 |(RTP)| + Circuit 2 -|--| TC2|---------+ multi-| +-----+ + | +----+ (Str 1) | plex | | + | | | | Video +-----+ + | +----+ | +-----*-----+ TR2 |----- + Circuit 3 -|--| TC3|---------+ | Stream 2 |(RTP)| + / +----+ (Str 1) | | +-----+ + / | +-------+ | + / +-----------------\-----------------+ + Audio, video, and control \ + signals are carried in frames Tmux is an ephemeral with two + spanning the circuits. explicit Stream Descriptors + and a Multiplex Descriptor. + + Figure 6: Multiplexed Termination Scenario - Single to Multiple + Terminations + (Asterisks * denote the centre of the context) + + + + + Context + +---------------------------------------------+ + | +-------+ +-------+ | + Cct 1 +----+ | | | | Audio +-----+ + ----| TC1|---+ Tmux1 | | Tmux2 +-----*-----| TR1 |----- + +----+ | | | | Stream 1 |(RTP)| + | | | Data | | +-----+ + Cct 2 +----+ | H.226 +-------+ H.223 | | + ----| TC2|---+ multi-|(Str 1)| multi-| Control +-----+ + +----+ | plex | | plex +-----*-----+ Tctl|----- + | | | | | Stream 3 +-----+ + Cct 3 +----+ | | | | | + ----| TC3|---+ | | | +-----+ + +----+ | | | +-----*-----+ TR2 |----- + | +-------+ | | Video |(RTP)| + | +-------+ Stream 2 +-----+ + | | + +---------------------------------------------+ + Tmux1 has a Multiplex Descriptor and a single data stream. + Tmux2 has a Multiplex Descriptor with a single bearer and + three explicit Stream Descriptors. + + + Groves et al Expires - October 2003 [Page 20] + Megaco Protocol version 2 April 2003 + + + + Figure 6a: Multiplexed Termination Scenario - Cascaded Multiplexes + (Asterisks * denote the centre of the context) + Note: this figure does not appear in Rec. H.248.1. + + ---- + + Unlike the multiplexing terminations described in the previous + paragraphs, multiplexed bearer terminations, which represent + multiplexed bearers such as ATM AAL Type 2 bearers, carry no media + streams. They are present strictly for the purpose of modeling the + creation and destruction of the actual bearer. When a new + multiplexed bearer is to be created, an ephemeral Termination is + created in a Context established for this purpose. When the + Termination is subtracted, the multiplexed bearer is destroyed. + + 6.2.1 Termination dynamics + + The protocol can be used to create new Terminations and to modify + property values of existing Terminations. These modifications include + the possibility of adding or removing events and/or signals. The + Termination properties, and events and signals are described in the + ensuing subclauses. An MGC can only release/modify Terminations and + the resources that the Termination represents, which it has + previously seized via e.g. the Add command. + + 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. The TerminationIDs may be chosen to have structure. For + instance, a TerminationID may consist of trunk group and a trunk + within the group. + + A wildcarding mechanism using two types of wildcards can be used with + TerminationIDs. The two wildcards are ALL and CHOOSE. The former is + used to address multiple Terminations at once, while the latter is + used to indicate to a media gateway that it must select a Termination + satisfying the partially specified TerminationID. This allows, for + instance, that a MGC instructs a MG to choose a circuit within a + trunk group. + + When ALL is used in the TerminationID of a command, the effect is + identical to repeating the command with each of the matching + TerminationIDs. The use of ALL does not address the ROOT termination. + Since each of these commands may generate a response, the size of the + entire response may be large. If individual responses are not + + + Groves et al Expires - October 2003 [Page 21] + Megaco Protocol version 2 April 2003 + + + required, a wildcard response may be requested. In such a case, a + single response is generated, which contains the UNION of all of the + individual responses which otherwise would have been generated, with + duplicate values suppressed. For instance, given a Termination Ta + with properties p1=a, p2=b and Termination Tb with 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 + response may be particularly 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 may implement Terminations that have + widely differing characteristics. Variations in Terminations are + accommodated in the protocol by allowing Terminations to have + optional Properties, Events, Signals and Statistics implemented by + MGs. + + In order to achieve MG/MGC interoperability, such options are grouped + into Packages, and typically a Termination realizes a set of such + Packages. More information on definition of packages can be found in + clause 12. An MGC can audit a Termination to determine which Packages + it realizes. + + Properties, Events, Signals and Statistics defined in Packages, as + well as parameters to them, are referenced by identifiers (Ids). + Identifiers are scoped. For each package, PropertyIds, EventIds, + SignalIds, StatisticsIds and ParameterIds have unique name spaces and + the same identifier may be used in each of them. Two PropertyIds in + different packages may also have the same identifier, etc. + + To support a particular package the MG must support all properties, + signals, events and statistics defined in a package. It must also + support all Signal and Event parameters. The MG may support a subset + of the values listed in a package for a particular Property or + Parameter. + + When packages are extended, the properties, events, signals and + statistics defined in the base package can be referred to using + either the extended package name or the base package name. For + example, if Package A defines event e1, and Package B extends Package + A, then B/e1 is an event for a termination implementing Package B. By + definition, the MG MUST also implement the base Package, but it is + optional to publish the base package as an allowed interface. If it + does publish A, then A would be reported on the Package Descriptor + in AuditValue as well as B, and event A/e1 would be available on a + termination. If the MG does not publish A, then only B/e1 would be + + + Groves et al Expires - October 2003 [Page 22] + Megaco Protocol version 2 April 2003 + + + available. If published through AuditValue, A/e1 and B/e1 are the + same event. + + For improved interoperability and backward compatibility, an MG MAY + publish all Packages supported by its Terminations, including base + Packages from which extended Packages are derived. An exception to + this is in cases where the base packages are expressly "Designed to + be extended only". + + 6.2.4 Termination properties and descriptors + + Terminations have properties. The properties have unique PropertyIDs. + Most properties have default values, which are explicitly defined in + this protocol specification or in a package (see clause 12) or set by + provisioning. If not provisioned otherwise, the properties in all + descriptors except TerminationState and LocalControl default to + empty/"no value" when a Termination is first created or returned to + the null Context. The default contents of the two exceptions are + described in 7.1.5 and 7.1.7. + + The provisioning of a property value in the MG will override any + default value, be it supplied in this protocol specification or in a + package. Therefore if it is essential for the MGC to have full + control over the property values of a Termination, it SHOULD supply + explicit values when ADDing the Termination to a Context. + Alternatively, for a physical Termination the MGC can determine any + provisioned property values by auditing the Termination while it is + in the NULL Context. + + There are a number of common properties for Terminations and + properties specific to media streams. The common properties are also + called the Termination state properties. For each media stream, there + are local properties and properties of the received and transmitted + flows. + + Properties not included in the base protocol are defined in Packages. + These properties are referred to by a name consisting of the + PackageName and a PropertyId. Most properties have default values + described in the Package description. Properties may be read-only or + read/write. The possible values of a property may be audited, as can + their current values. For properties that are read/write, the MGC can + set their values. A property may be declared as "Global" which has a + single value shared by all Terminations realizing the package. + Related properties are grouped into descriptors for convenience. + + When a Termination is added to a Context, the value of its read/write + properties can be set by including the appropriate descriptors as + parameters to the Add command. Similarly, a property of a Termination + in a Context may have its value changed by the Modify command. + + + Groves et al Expires - October 2003 [Page 23] + Megaco Protocol version 2 April 2003 + + + Properties may also have their values changed when a Termination is + moved from one Context to another as a result of a Move command. In + some cases, descriptors are returned as output from a command. + + In general, if a Descriptor is completely omitted from one of the + aforementioned Commands, the properties in that Descriptor retain + their prior values for the Termination(s) upon which the Command + acts. On the other hand, if some read/write properties are omitted + from a Descriptor in a Command (i.e., the Descriptor is only + partially specified), those properties will be reset to their default + values for the Termination(s) upon which the Command acts, unless the + package specifies other behavior. For more details, see clause 7.1 + dealing with the individual Descriptors. + + The following table lists all of the possible descriptors and their + use. Not all descriptors are legal as input or output parameters to + every command. + + 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. + + + + Groves et al Expires - October 2003 [Page 24] + Megaco Protocol version 2 April 2003 + + + Descriptor name Description + + 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 (see 7.1.11) applied to + 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. + + Topology Specifies flow directions between Terminations + in a Context. + + Error Contains an error code and optionally error + text; it may occur in command replies and in + Notify requests. + + (*) ModemDescriptor has been deprecated in Megaco v2/H.248.1 + (05/2002). + + + + 6.2.5 Root Termination + + Occasionally, a command must refer to the gateway as an entity in + itself, rather than a Termination within it. A special TerminationID, + "Root" is reserved for this purpose. Packages may be defined on Root. + + + Groves et al Expires - October 2003 [Page 25] + Megaco Protocol version 2 April 2003 + + + Root thus may have properties, events, signals and statistics. + Accordingly, the root TerminationID may appear in: + + - a Modify command - to change a property, send a signal 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 determine what 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. Error code 410 - + "Incorrect identifier" shall be returned in these cases. + + + 7 COMMANDS + + The protocol provides commands for manipulating the logical entities + of the protocol connection model, Contexts and Terminations. Commands + provide control at the finest level of granularity supported by the + protocol. For example, Commands exist to add Terminations to a + Context, modify Terminations, subtract Terminations from a Context, + and audit properties of Contexts or Terminations. Commands provide + for complete control of the properties of Contexts and Terminations. + This includes specifying which events a Termination is to report, + which signals/actions are to be applied to a Termination and + specifying the topology of a Context (who hears/sees whom). + + Most commands are for the specific use of the Media Gateway + Controller as command initiator in controlling Media Gateways as + command responders. The exceptions are the Notify and ServiceChange + commands: Notify is sent from Media Gateway to Media Gateway + Controller, and ServiceChange may be sent by either entity. Below is + an overview of the commands; they are explained in more detail in + 7.2. + + 1) 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. + + 2) Modify: The Modify command modifies the properties, events and + signals of a Termination. + + + + + Groves et al Expires - October 2003 [Page 26] + Megaco Protocol version 2 April 2003 + + + 3) 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. + + 4) Move: The Move command atomically moves a Termination to another + Context. + + 5) AuditValue: The AuditValue command returns the current state of + properties, events, signals and statistics of Terminations. + + 6) AuditCapabilities: The AuditCapabilities command returns all the + possible values for Termination properties, events and signals + allowed by the Media Gateway. + + 7) Notify: The Notify command allows the Media Gateway to inform the + Media Gateway Controller of the occurrence of events in the Media + Gateway. + + 8) 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 a 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 7.2.1 through 7.2.8. + + 7.1 Descriptors + + The parameters to a command are termed Descriptors. A descriptor + consists of a name and a list of items. Some items may have values. + Many Commands share common descriptors. This subclause enumerates + these descriptors. Descriptors may be returned as output from a + command. In any such return of descriptor contents, an empty + descriptor is represented by its name unaccompanied by any list. + Parameters and parameter usage specific to a given Command type are + described in the subclause that describes the Command. + + 7.1.1 Specifying parameters + + Command parameters are structured into a number of descriptors. In + general, the text format of descriptors is + DescriptorName={parm=value, parm=value, ...}. + + Parameters may be fully specified, overspecified or underspecified: + + + Groves et al Expires - October 2003 [Page 27] + Megaco Protocol version 2 April 2003 + + + 1) Fully specified parameters have a single, unambiguous value that + the command initiator is instructing the command responder to use + for the specified parameter. + + 2) Underspecified parameters, using the CHOOSE value, allow the + command responder to choose any value it can support. + + 3) Overspecified parameters have a list of potential values. The list + order specifies the command initiator's order of preference of + selection. The command responder chooses one value from the + offered list and returns that value to the command initiator. + + If a required descriptor other than the Audit descriptor is + unspecified (i.e. entirely absent) from a command, the previous + values set in that descriptor for that Termination, if any, are + retained. In commands other than Subtract, a missing Audit descriptor + is equivalent to an empty Audit descriptor. The Behaviour of the MG + with respect to unspecified parameters within a descriptor varies + with the descriptor concerned, as indicated in succeeding subclauses. + Whenever a parameter is underspecified or overspecified, the + descriptor containing the value chosen by the responder is included + as output from the command. + + Each command specifies the TerminationId the command operates on. + This TerminationId may be "wildcarded". When the TerminationId of a + command is wildcarded, the effect shall be as if the command was + repeated with each of the TerminationIds matched. + + 7.1.2 Modem descriptor + + The Modem descriptor specifies the modem type and parameters, if any, + required for use in e.g. H.324 and text conversation. The descriptor + includes the following modem types: V.18, V.22, V.22 bis, V.32, V.32 + bis, V.34, V.90, V.91, Synchronous ISDN, and allows for extensions. + By default, no Modem descriptor is present in a Termination. + + Use of the ModemDescriptor is deprecated in Megaco v2/H.248.1 + (05/2002) and subsequent versions. This means that the + ModemDescriptor shall not be included as part of transmitted content + and if received shall either be ignored or processed at the option of + the implementation. Modem type is to be specified as an attribute of + data streams in LocalDescriptor and RemoteDescriptor. + + 7.1.3 Multiplex descriptor + + In multimedia calls, a number of media streams are carried on a + (possibly different) number of bearers. The multiplex descriptor + associates the media and the bearers. The descriptor includes the + multiplex type: + + + Groves et al Expires - October 2003 [Page 28] + Megaco Protocol version 2 April 2003 + + + - H.221; + - H.223; + - H.226; + - V.76; + - Nx64K; + - possible extensions, + + and a set of TerminationIDs representing the multiplexed bearers, in + order. For example: + + Mux = H.221{ MyT3/1/2, MyT3/2/13, MyT3/3/6, MyT3/21/22} + + The Nx64K Multiplex type implements the Nx64K service (e.g. as + defined by Q.931 Information Transfer Rate or Q.763 Transmission + Medium Requirement). On the context side it supports a single stream + of wideband data. When a bearer termination is added implicitly to a + context as a result of the creation of an Nx64K multiplexing + termination, the streamDescriptor for the bearer termination shall + take on the same values as the streamDescriptor defined for the + Multiplex termination, except that the bearer termination bandwidth + shall be 64 kilobits per second. + + 7.1.4 Media descriptor + + The Media descriptor specifies the parameters for all the media + streams. These parameters are structured into two descriptors: a + TerminationState descriptor, which specifies the properties of a + Termination that are not stream dependent, and one or more Stream + descriptors each of which describes a single media stream. + + A stream is identified by a StreamID. The StreamID is used to link + the streams in a Context that belong together. Multiple streams + exiting a Termination shall be synchronized with each other. Within + the Stream descriptor, there are up to three subsidiary descriptors: + LocalControl, Local, and Remote. The relationship between these + descriptors is thus: + + Media descriptor + TerminationState Descriptor + Stream descriptor + LocalControl descriptor + Local descriptor + Remote descriptor + + As a convenience, LocalControl, Local, or Remote descriptors may be + included in the Media descriptor without an enclosing Stream + descriptor. In this case, the StreamID is assumed to be 1. + + + + + Groves et al Expires - October 2003 [Page 29] + Megaco Protocol version 2 April 2003 + + + 7.1.5 TerminationState descriptor + + The TerminationState descriptor contains the ServiceStates property, + the EventBufferControl property and properties of a Termination + (defined in Packages) that are not stream specific. + + The ServiceStates property describes the overall state of the + Termination (not stream specific). A Termination can be in one of the + following states: "test", "out of service", or "in service". The + "test" state indicates that the Termination is being tested. The + state "out of service" indicates that the Termination cannot be used + for traffic. The state "in service" indicates that a Termination can + be used or is being used for normal traffic. "in service" is the + default state. + + Values assigned to Properties may be simple values + (integer/string/enumeration) or may be underspecified, where more + than one value is supplied and the MG may make a choice: + + - 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 specifies whether events are buffered + following detection of an event in the Events descriptor, or + processed immediately. See 7.1.9 for details. + + 7.1.6 Stream descriptor + + A Stream descriptor specifies the parameters of a single + bidirectional stream. These parameters are structured into three + descriptors: one that contains Termination properties specific to a + stream and one each for local and remote flows. The Stream Descriptor + includes a StreamID which identifies the stream. Streams are created + by specifying a new StreamID on one of the Terminations in a Context. + A stream is deleted by setting empty Local and Remote descriptors for + the stream with ReserveGroup and ReserveValue in LocalControl set to + "false" on all Terminations in the Context that previously supported + that stream. + + + + + Groves et al Expires - October 2003 [Page 30] + Megaco Protocol version 2 April 2003 + + + StreamIDs are of local significance between MGC and MG and they are + assigned by the MGC. Within a Context, StreamID is a means by which + to indicate which media flows are interconnected: streams with the + same StreamID are connected. + + If a Termination is moved from one Context to another, the effect on + the Context to which the Termination is moved is the same as in the + case that a new Termination were added with the same StreamIDs as the + moved Termination. + + 7.1.7 LocalControl descriptor + + The LocalControl descriptor contains the Mode property, the + ReserveGroup and ReserveValue properties and properties of a + Termination (defined in Packages) that are stream specific, and are + of interest between the MG and the MGC. Values of properties may be + specified as in 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 with + respect to the exterior of the Context, so that, for example, a + stream set to mode=sendOnly does not pass received media into the + Context. The default value for the mode property is "Inactive". + Signals and Events are not affected by mode. + + The boolean-valued Reserve properties, ReserveValue and ReserveGroup, + of a Termination indicate what the MG is expected to do when it + receives a Local and/or Remote descriptor. + + If the value of a Reserve property is True, the MG SHALL reserve + resources for all alternatives specified in the Local and/or Remote + descriptors for which it currently has resources available. It SHALL + respond with the alternatives for which it reserves resources. 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 media begins to flow while more than a single alternative is + reserved, media packets may be sent/received on any of the + alternatives and must be processed, although only a single + alternative may be active at any given time. + + If the value of a Reserve property is False, the MG SHALL choose one + of the alternatives specified in the Local descriptor (if present) + and one of the alternatives specified in the Remote descriptor (if + present). If the MG has not yet reserved resources to support the + selected alternative, it SHALL reserve the resources. If, on the + other hand, it already reserved resources for the Termination + addressed (because of a prior exchange with ReserveValue and/or + ReserveGroup equal to True), it SHALL release any excess resources it + reserved previously. Finally, the MG shall send a reply to the MGC + + + Groves et al Expires - October 2003 [Page 31] + Megaco Protocol version 2 April 2003 + + + containing the alternatives for the Local and/or Remote descriptor + that it selected. If the MG does not have sufficient resources to + support any of the alternatives specified, is SHALL respond with + Error 510 - "Insufficient resources". + + The default value of ReserveValue and ReserveGroup is False. More + information on the use of the two Reserve properties is provided in + 7.1.8. + + A new setting of the LocalControl Descriptor completely replaces the + previous setting of that descriptor in the MG. Thus, to retain + information from the previous setting, the MGC must include that + information in the new setting. If the MGC wishes to delete some + information from the existing descriptor, it merely resends the + descriptor (in a Modify command) with the unwanted information + stripped out. + + 7.1.8 Local and Remote descriptors + + The MGC uses Local and Remote descriptors to reserve and commit MG + resources for media decoding and encoding for the given Stream(s) and + Termination to which they apply. The MG includes these descriptors in + its response to indicate what it is actually prepared to support. The + MG SHALL include additional properties and their values in its + response if these properties are mandatory yet not present in the + requests made by the MGC (e.g. by specifying detailed video encoding + parameters where the MGC only specified the payload type). + + Local refers to the media received by the MG and Remote refers to the + media sent by the MG. + + When text encoding the protocol, the descriptors consist of session + descriptions as defined in SDP (RFC 2327). In session descriptions + sent from the MGC to the MG, the following exceptions to the syntax + of RFC 2327 are allowed: + + - the "s=", "t=" and "o=" lines are optional; + + - the use of CHOOSE is allowed in place of a single parameter value; + and + + - the use of alternatives is allowed in place of a single parameter + value. + + A Stream Descriptor specifies a single bi-directional media stream + and so a single session description MUST NOT include more than one + media description ("m=" line). A Stream Descriptor may contain + additional session descriptions as alternatives. Each media stream + for a termination must appear in distinct Stream Descriptors. When + + + Groves et al Expires - October 2003 [Page 32] + Megaco Protocol version 2 April 2003 + + + multiple session descriptions are provided in one descriptor, the + "v=" lines are required as delimiters; otherwise they are optional in + session descriptions sent to the MG. Implementations shall accept + session descriptions that are fully conformant to RFC 2327. When + binary encoding the protocol the descriptor consists of groups of + properties (tag-value pairs) as specified in Annex C. Each such group + may contain the parameters of a session description. + + Below, the semantics of the Local and Remote descriptors are + specified in detail. The specification consists of two parts. The + first part specifies the interpretation of the contents of the + descriptor. The second part specifies the actions the MG must take + upon receiving the Local and Remote descriptors. The actions to be + taken by the MG depend on the values of the ReserveValue and + ReserveGroup properties of the LocalControl descriptor. + + Either the Local or the Remote descriptor or both may 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. + + Where the descriptors have been passed from the MGC to the MG, they + are interpreted according to the rules given in 7.1.1, with the + following additional comments for clarification: + + a) An unspecified Local or Remote descriptor is considered to be a + missing mandatory parameter. It requires the MG to use whatever + was last specified for that descriptor. It is possible that there + was no previously specified value, in which case the descriptor + concerned is ignored in further processing of the command. + + b) An empty Local (Remote) descriptor in a message from the MGC + signifies a request to release any resources reserved for the + media flow received (sent). + + c) If multiple groups of properties are present in a Local or Remote + descriptor or multiple values within a group, the order of + preference is descending. + + + + + Groves et al Expires - October 2003 [Page 33] + Megaco Protocol version 2 April 2003 + + + d) Underspecified or overspecified properties within a group of + properties sent by the MGC are requests for the MG to choose one + or more values which it can support for each of those properties. + In case of an overspecified property, the list of values is in + descending order of preference. + + Subject to the above rules, subsequent action depends on the values + of the ReserveValue and ReserveGroup properties in LocalControl. + + If ReserveGroup is True, the MG reserves the resources required to + support any of the requested property group alternatives that it can + currently support. If ReserveValue is True, the MG reserves the + resources required to support any of the requested property value + alternatives that it can currently support. + + NOTE - If a Local or Remote descriptor contains multiple groups of + properties, and ReserveGroup is True, then the MG is requested to + reserve resources so that it can decode or encode the media stream + according to any of the alternatives. For instance, if the Local + descriptor contains two groups of properties, one specifying + packetized G.711 A-law audio and the other G.723.1 audio, the MG + reserves resources so that 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 simultaneously, one + encoded in G.711 A-law and one in G.723.1. The intention for the use + of ReserveValue is analogous. + + If ReserveGroup is true or ReserveValue is True, then the following + rules apply: + + - If the MG has insufficient resources to support all alternatives + requested by the MGC and the MGC requested resources in both Local + and Remote, the MG SHOULD reserve resources to support at least + one alternative each within Local and Remote. + + - If the MG has insufficient 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 is incapable of supporting 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 + + + + Groves et al Expires - October 2003 [Page 34] + Megaco Protocol version 2 April 2003 + + + 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 is able + to support at least one alternative in Remote. + + - If the MG is unable to 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. + + A new setting of a Local or Remote descriptor completely replaces the + previous setting of that descriptor in the MG. Thus, to retain + information from the previous setting, the MGC must include that + information in the new setting. If the MGC wishes to delete some + information from the existing descriptor, it merely resends the + descriptor (in a Modify command) with the unwanted information + stripped out. + + 7.1.9 Events descriptor + + The EventsDescriptor parameter contains a RequestIdentifier and a + list of events that the Media Gateway is requested to detect and + report. The RequestIdentifier is used to correlate the request with + the notifications that it may trigger. Requested events include, for + example, fax tones, continuity test results, and on-hook and off-hook + transitions. The RequestIdentifier is omitted if the EventsDescriptor + is empty (i.e. no events are specified). + + Each event in the descriptor contains the Event name, an optional + streamID, an optional KeepActive flag, and optional parameters. The + Event name consists of a Package Name (where the event is defined) + and an EventID. The ALL wildcard may be used for the EventID, + indicating that all events from the specified package have to be + detected. The default streamID is 0, indicating that the event to be + detected is not related to a particular media stream. Events can have + parameters. This allows a single event description to have some + variation in meaning without creating large numbers of individual + events. Further event parameters are defined in the package. + + If a digit map completion event is present or implied in the + EventsDescriptor, the EventDM parameter is used to carry either the + name or the value of the associated digit map. See 7.1.14 for further + details. + + + Groves et al Expires - October 2003 [Page 35] + Megaco Protocol version 2 April 2003 + + + When an event is processed against the contents of an active Events + Descriptor and found to be present in that descriptor ("recognized"), + the default action of the MG is to send a Notify command to the MGC. + Notification may be deferred if the event is absorbed into the + current dial string of an active digit map (see 7.1.14). Any other + action is for further study. Moreover, event recognition may cause + currently active signals to stop, or may cause the current Events + and/or Signals descriptor to be replaced, as described at the end of + this subclause. Unless the Events Descriptor is replaced by another + Events Descriptor, it remains active after an event has been + recognized. + + If the value of the EventBufferControl property equals LockStep, + following detection of such an event, normal handling of events is + suspended. Any event which is subsequently detected and occurs in the + EventBuffer descriptor is added to the end of the EventBuffer (a FIFO + queue), along with the time that it was detected. The MG SHALL wait + for a new EventsDescriptor to be loaded. A new EventsDescriptor can + be loaded either as the result of receiving a command with a new + EventsDescriptor, or by activating an embedded EventsDescriptor. + + If EventBufferControl equals Off, the MG continues processing based + on the active EventsDescriptor. + + In the case of an embedded EventsDescriptor being activated, the MG + continues event processing based on the newly activated + EventsDescriptor. + + NOTE 1 - For purposes of EventBuffer handling, activation of an + embedded EventsDescriptor is equivalent to receipt of a new + EventsDescriptor. + + When the MG receives a command with a new EventsDescriptor, one or + more events may have been buffered in the EventBuffer in the MG. The + value of EventBufferControl then determines how the MG treats such + buffered events. + + + Case 1 + + If EventBufferControl equals LockStep and the MG receives a new + EventsDescriptor, it will check the FIFO EventBuffer and take the + following actions: + + 1) If the EventBuffer is empty, the MG waits for detection of events + based on the new EventsDescriptor. + + 2) If the EventBuffer is non-empty, the MG processes the FIFO queue + starting with the first event: + + + Groves et al Expires - October 2003 [Page 36] + Megaco Protocol version 2 April 2003 + + + a) If the event in the queue is in the events listed in the new + EventsDescriptor, the MG acts on the event and removes the + event from the EventBuffer. The time stamp of the Notify shall + be the time the event was actually detected. The MG then waits + for a new EventsDescriptor. While waiting for a new + EventsDescriptor, any events detected that appear in the + EventsBufferDescriptor will be placed in the EventBuffer. When + a new EventsDescriptor is received, the event processing will + repeat from step 1. + + b) If the event is not in the new EventsDescriptor, the MG SHALL + discard the event and repeat from step 1. + + + Case 2 + + If EventBufferControl equals Off and the MG receives a new + EventsDescriptor, it processes new events with the new + EventsDescriptor. + + If the MG receives a command instructing it to set the value of + EventBufferControl to Off, all events in the EventBuffer SHALL be + discarded. + + The MG may report several events in a single Transaction as long as + this does not unnecessarily delay the reporting of individual events. + + For procedures regarding transmitting the Notify command, refer to + the appropriate annex or Recommendation of the H.248 sub-series for + specific transport considerations. + + The default value of EventBufferControl is Off. + + NOTE 2 - Since the EventBufferControl property is in the + TerminationStateDescriptor, the MG might receive a command that + changes the EventBufferControl property and does not include an + EventsDescriptor. + + Normally, recognition of an event shall cause any active signals to + stop. When KeepActive is specified in the event, the MG shall not + interrupt any signals active on the Termination on which the event is + detected. + + An event can include an Embedded Signals descriptor and/or an + Embedded Events descriptor which, if present, replaces the current + Signals/Events descriptor when the event is recognized. It is + possible, for example, to specify that the dial-tone Signal be + generated when an off-hook Event is recognized, or that the dial-tone + Signal be stopped when a digit is recognized. A media gateway + + + Groves et al Expires - October 2003 [Page 37] + Megaco Protocol version 2 April 2003 + + + controller shall not send EventsDescriptors with an event both marked + KeepActive and containing an embedded SignalsDescriptor. + + Only one level of embedding is permitted. An embedded + EventsDescriptor SHALL NOT contain another embedded EventsDescriptor; + an embedded EventsDescriptor MAY contain an embedded + SignalsDescriptor. + + An EventsDescriptor received by a media gateway replaces any previous + Events descriptor. Event notification in process shall complete, and + events detected after the command containing the new EventsDescriptor + executes, shall be processed according to the new EventsDescriptor. + + An empty Events Descriptor disables all event recognition and + reporting. An empty EventBuffer Descriptor clears the EventBuffer + and disables all event accumulation in LockStep mode: the only events + reported will be those occurring while an Events Descriptor is + active. If an empty Events Descriptor is activated while the + Termination is operating in LockStep mode, the events buffer is + immediately cleared. + + 7.1.10 EventBuffer descriptor + + The EventBuffer descriptor contains a list of events, with their + parameters if any, that the MG is requested to detect and buffer when + EventBufferControl equals LockStep (see 7.1.9). + + 7.1.11 Signals descriptor + + Signals are MG generated media such as tones and announcements as + well as bearer-related signals such as hookswitch. More complex + signals may include a sequence of such simple signals interspersed + with and conditioned upon the receipt and analysis of media or + bearer-related signals. Examples include echoing of received data as + in Continuity Test package. Signals may also request preparation of + media content for future signals. + + A SignalsDescriptor is a parameter that contains the set of signals + that the Media Gateway is asked to apply to a Termination. A + SignalsDescriptor contains a number of signals and/or sequential + signal lists. A SignalsDescriptor may contain zero signals and + sequential signal lists. Support of sequential signal lists is + optional. + + Signals are defined in packages. Signals shall be named with a + Package name (in which the signal is defined) and a SignalID. No + wildcard shall be used in the SignalID. Signals that occur in a + SignalsDescriptor have an optional StreamID parameter (default is 0, + to indicate that the signal is not related to a particular media + + + Groves et al Expires - October 2003 [Page 38] + Megaco Protocol version 2 April 2003 + + + stream), an optional signal type (see below), an optional duration + and possibly parameters defined in the package that defines the + signal. This allows a single signal to have some variation in + meaning, obviating the need to create large numbers of individual + signals. + + Finally, the optional parameter "notifyCompletion" allows a MGC to + indicate that it wishes to be notified when the signal finishes + playout. The possible cases are that the signal timed out (or + otherwise completed on its own), that it was interrupted by an event, + that it was halted when a Signals descriptor was replaced, or that it + stopped or never started for other reasons. If the notifyCompletion + parameter is not included in a Signals descriptor, notification is + generated only if the signal stopped or was never started for other + reasons. For reporting to occur, the signal completion event (see + E.1.2) must be enabled in the currently active Events descriptor. + + The duration is an integer value that is expressed in hundredths of a + second. + + There are three types of signals: + + - on/off - the signal lasts until it is turned off; + + - timeout - the signal lasts until it is turned off or a specific + period of time elapses; + + - brief - the signal will stop on its own unless a new Signals + descriptor is applied that causes it to stop; no timeout value is + needed. + + If a signal of default type other than TO has its type overridden to + type TO in the Signals descriptor, the duration parameter must be + present. + + If the signal type is specified in a SignalsDescriptor, it overrides + the default signal type (see 12.1.4). If duration is specified for an + on/off signal, it SHALL be ignored. + + A sequential signal list consists of a signal list identifier and a + sequence of signals to be played sequentially. Only the trailing + element of the sequence of signals in a sequential signal list may be + an on/off signal. The duration of a sequential signal list is the sum + of the durations of the signals it contains. + + Multiple signals and sequential signal lists in the same + SignalsDescriptor shall be played simultaneously. + + + + + Groves et al Expires - October 2003 [Page 39] + Megaco Protocol version 2 April 2003 + + + Signals are defined as proceeding from the Termination towards the + exterior of the Context unless otherwise specified in a package. When + the same Signal is applied to multiple Terminations within one + Transaction, the MG SHOULD consider using the same resource to + generate these Signals. + + Production of a Signal on a Termination is stopped by application of + a new SignalsDescriptor, or detection of an Event on the Termination + (see 7.1.9). + + A new SignalsDescriptor replaces any existing SignalsDescriptor. Any + signals applied to the Termination not in the replacement descriptor + shall be stopped, and new signals are applied, except as follows. + Signals present in the replacement descriptor and containing the + KeepActive flagshall be continued if they are currently playing and + have not already completed. If a replacement signal descriptor + contains a signal that is not currently playing and contains the + KeepActive flag, that signal SHALL be ignored. If the replacement + descriptor contains a sequential signal list with the same identifier + as 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 + + The Audit descriptor specifies what information is to be audited. The + Audit descriptor specifies the list of descriptors and-or individual + properties to be returned. Audit may be used in any command to force + the return of any descriptor containing the current values of its + properties, events, signals and statistics even if that descriptor + was not present in the command, or had no underspecified parameters. + Possible items in the Audit descriptor are: + + - Modem (Deprecated, see clause 7.1.2) + - Mux + - Events + - Media + - Signals + - ObservedEvents + - DigitMap + - Statistics + - Packages + - EventBuffer + - Individual Audit Items: + - Media Properties + + + Groves et al Expires - October 2003 [Page 40] + Megaco Protocol version 2 April 2003 + + + - Events + - Event Buffer + - Signals, Signal Lists + - Digit Maps + - Statistics + - Packages + + Audit may be empty, in which case, no descriptors are returned. This + is useful in Subtract, to inhibit return of statistics, especially + when using wildcard. + + 7.1.13 ServiceChange descriptor + + The ServiceChangeDescriptor contains the following parameters: + + - ServiceChangeMethod + - ServiceChangeReason + - ServiceChangeAddress + - ServiceChangeDelay + - ServiceChangeProfile + - ServiceChangeVersion + - ServiceChangeMGCId + - TimeStamp + - Extension + + See 7.2.8. + + 7.1.14 DigitMap descriptor + + 7.1.14.1 DigitMap definition, creation, modification and deletion + + A DigitMap is a dialing plan resident in the Media Gateway used for + detecting and reporting digit events received on a Termination. The + DigitMap descriptor contains a DigitMap name and the DigitMap to be + assigned. A digit map may be preloaded into the MG by management + action and referenced by name in an EventsDescriptor, may be defined + dynamically and subsequently referenced by name, or the actual + digitmap itself may be specified in the EventsDescriptor. It is + permissible for a digit map completion event within an Events + descriptor to refer by name to a DigitMap which is defined by a + DigitMap descriptor within the same command, regardless of the + transmitted order of the respective descriptors. + + DigitMaps defined in a DigitMapDescriptor can occur in any of the + standard Termination manipulation Commands of the protocol. A + DigitMap, once defined, can be used on all Terminations specified 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, provided that a DigitMap with the same name + + + Groves et al Expires - October 2003 [Page 41] + Megaco Protocol version 2 April 2003 + + + has not been defined on the given Termination. When a DigitMap is + defined dynamically in a DigitMap descriptor: + + - A new DigitMap is created by specifying a name that is not yet + defined. The value shall be present. + + - A DigitMap value is updated by supplying a new value for a name + that is already defined. Terminations presently using the digitmap + shall continue to use the old definition; subsequent + EventsDescriptors specifying the name, including any + EventsDescriptor in the command containing the DigitMap + descriptor, shall use the new one. + + - A DigitMap is deleted by supplying an empty value for a name that + is already defined. Terminations presently using the digitmap + shall continue to use the old definition. + + 7.1.14.2 DigitMap Timers + + The collection of digits according to a DigitMap may be protected by + three timers, viz. a start timer (T), short timer (S), and long timer + (L). + + 1) The start timer (T) is used prior to any digits having been + dialed. If the start timer is overridden with the value set to + zero (T=0), then the start timer shall be disabled. This implies + that the MG will wait indefinitely for digits. + + 2) If the Media Gateway can determine 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). + + 3) If the digit string has matched one of the patterns in a digit + map, but it is possible that more digits could be received which + would cause a match with a different pattern, then instead of + reporting the match immediately, the MG must apply the short timer + (S) and wait for more digits. + + The timers are configurable parameters to a DigitMap. Default values + of these timers SHOULD be provisioned on the MG, but can be + overridden by values specified within the DigitMap. + + 7.1.14.3 DigitMap Syntax + + The formal syntax of 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 defined either by + a string or by a list of strings. Each string in the list is an + + + Groves et al Expires - October 2003 [Page 42] + Megaco Protocol version 2 April 2003 + + + alternative event sequence, specified either as a sequence of digit + map symbols or as a regular expression of digit map symbols. These + digit map symbols, the digits "0" through "9" and letters "A" through + a maximum value depending on the signalling system concerned, but + never exceeding "K", correspond to specified events within a package + which has been designated in the Events descriptor on the Termination + to which the digit map is being applied. (The mapping between events + and digit map symbols is defined in the documentation for packages + associated with channel-associated signalling systems such as DTMF, + MF, or R2. Digits "0" through "9" MUST be mapped to the corresponding + digit events within the signalling system concerned. Letters SHOULD + be allocated in logical fashion, facilitating the use of range + notation for alternative events.) + + The letter "x" is used as a wildcard, designating any event + corresponding to symbols in the range "0"-"9". The string may also + contain explicit ranges and, more generally, explicit sets of + symbols, designating alternative events any one of which satisfies + that position of the digit map. Finally, the dot symbol "." stands + for zero or more repetitions of the event selector (event, range of + events, set of alternative events, or wildcard) that precedes it. As + a consequence of the third timing rule above, inter-event timing + while matching a terminal dot symbol uses the short timer by default. + + In addition to these event symbols, the string may contain "S" and + "L" inter-event timing specifiers and the "Z" duration modifier. "S" + and "L" respectively indicate that the MG SHOULD use the short (S) + timer or the long (L) timer for subsequent events, overriding the + timing rules described above. If an explicit timing specifier is in + effect in one alternative event sequence, but none is given in any + other candidate alternative, the timer value set by the explicit + timing specifier must be used. If all sequences with explicit timing + controls are dropped from the candidate set, timing reverts to the + default rules given above. Finally, if conflicting timing specifiers + are in effect in different alternative sequences, the long timer + shall be used. + + A "Z" designates a long duration event: placed in front of the + symbol(s) designating the event(s) which satisfy a given digit + position, it indicates that that position is satisfied only if the + duration of the event exceeds the long-duration threshold. The value + of this threshold is assumed to be provisioned in the MG, but, like + the T, L, and S timers, can be overridden by specification within the + DigitMap. + + 7.1.14.4 DigitMap Completion Event + + A digit map is active while the Events descriptor which invoked it is + active and it has not completed. A digit map completes when: + + + Groves et al Expires - October 2003 [Page 43] + Megaco Protocol version 2 April 2003 + + + - 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 + through detection of an additional event (unambiguous match); or + + - an event has been detected such that a match to a complete + alternative event sequence of the digit map will be impossible no + matter what additional events are received. + + Upon completion, a digit map completion event as defined in the + package providing the events being mapped into the digit map shall be + generated. At that point the digit map is deactivated. Subsequent + events in the package are processed as follows: + + - If EventBufferControl is ON, subsequent digit events are processed + in the same way as any other events; + + - If EventBufferControl is OFF, if the active EventsDescriptor did + not change, and if individual digit events are not enabled within + that descriptor, then digit buffering will be initiated. + Buffering will continue until the buffering time specified in the + original digit map completion event has expired or until the + active EventsDescriptor is replaced. + + The digit buffer shall take the logical form of a dial string which + includes the digit characters as represented in the digit map, + possibly preceded by 'Z'. The threshold value of tone duration used + to identify long events shall be the same as that used with the most + recently completed digit map. + + Buffering time defaults to zero (no buffering) unless explicitly set + otherwise within the digit map completion event. If buffering ceases + due to buffering timer expiry, the contents of the digit buffer are + discarded. + + If buffering was stopped by a new EventsDescriptor, then if that + EventsDescriptor contains a new digit map completion event from the + same package as the previous one, any buffered digits are processed + against the digit map as described below. Buffered digits not + consumed by the new digit map are handled as if they had were + observed after that map completed. + + If instead the new EventsDescriptor enables the reporting of + individual digit events, the entire set of buffered digits shall + immediately be processed, the applicable events reported, and the + buffer cleared. + + + + + Groves et al Expires - October 2003 [Page 44] + Megaco Protocol version 2 April 2003 + + + Finally, if the new EventsDescriptor enables neither a digit map + completion event nor the reporting of individual digit events from + the package concerned, the buffer contents are discarded and + buffering is terminated. + + 7.1.14.5 DigitMap Procedures + + Pending completion, successive events shall be processed according to + the following rules: + + 1) The "current dial string", an internal variable, is initially + empty. The set of candidate alternative event sequences includes + all of the alternatives specified in the digit map. + + 2) At each step, if buffered digits are available, the oldest one + (with possible accompanying long digit (Z) qualifier) is removed + from the buffer and processing moves to the next step as if the + digit event had just been observed. Otherwise a timer is set to + wait for the next event, based either on the default timing rules + given above or on explicit timing specified in one or more + alternative event sequences. If the timer expires and a member of + the candidate set of alternatives is fully satisfied, a timeout + completion with full match is reported. If the timer expires and + part or none of any candidate alternative is satisfied, a timeout + completion with partial match is reported. In either case, if the + digit map completion event allows for detailed timeout reporting, + the reported dial string will end with 'L', 'S', or 'T' as + appropriate. + + 3) If an event is detected before the timer expires, it is 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 this is relevant in the current symbol + position (because at least one of the candidate alternative event + sequences includes the "Z" modifier at this position in the + sequence). + + 4) The current dial string is compared to the candidate alternative + event sequences. If and only if a sequence expecting a long- + duration event at this position is matched (i.e. the event had + long duration and met the specification for this position), then + any alternative event sequences not specifying a long duration + event at this position are discarded, and the current dial string + is modified by inserting a "Z" in front of the symbol representing + 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 not + specifying a long duration event in the given position remain in + the candidate set after application of the above rules, the + + + Groves et al Expires - October 2003 [Page 45] + Megaco Protocol version 2 April 2003 + + + observed event duration is treated as irrelevant in assessing + matches to them. + + 5) If exactly one candidate remains and it has been fully matched, a + completion event is 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 will + then be reported a separate event, buffered, or discarded + according to the rules described in the previous section. This + statement is qualified as follows: + + a) The digit map completion event may specify that the removed + event be reported as a parameter of the completion event. This + occurs independently of subsequent processing of the digit + event. + + b) The digit map completion event may specify that the extra digit + SHOULD be discarded. In this case, it is discarded + immediately. Any buffering or other processing applies only to + subsequent events. + + 6) If no completion event is reported out of step 5, processing + returns to step 2. + + 7.1.14.6 DigitMap Activation + + A digit map is activated whenever a new Event descriptor is applied + to the Termination or embedded Event descriptor is activated, that + Event descriptor contains a digit map completion event. The digit map + completion event contains an eventDM field in the requested actions + field. Each new activation of a digit map begins at step 1 of the + above procedure, with a clear current dial string. Any previous + contents of the current dial string from an earlier activation are + lost. + + A digit map completion event that does not contain an eventDM field + in its requested actions field is considered an error. Upon receipt + of such an event in an EventsDescriptor, a MG shall respond with an + error reponse, including Error 457 - "Missing parameter in signal or + event". + + 7.1.14.7 Interaction Of DigitMap and Event Processing + + While the digit map is activated, detection is enabled for all events + defined in the package containing the specified digit map completion + event. Normal event behaviour (e.g. stopping of signals unless the + + + Groves et al Expires - October 2003 [Page 46] + Megaco Protocol version 2 April 2003 + + + digit completion event has the KeepActive flag enabled) continues to + apply for each such event detected, except that: + + - the events in the package containing the specified digit map + completion event other than the completion event itself are not + individually notified and have no side-effects unless separately + enabled; and + + - an event that triggers a partial match completion event is not + recognized and therefore has no side effects until reprocessed + following the recognition of the digit map completion event. + Similarly buffered digit events are not recognized and have no + side effects until processed. + + 7.1.14.8 Wildcards + + Note that if a package contains a digit map completion event, then an + event specification consisting of the package name with a wildcarded + ItemID (Property Name) will activate a digit map; to that end, the + event specification must include an eventDM field according to + section 7.1.14.6. 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 are detected. + + 7.1.14.9 Example + + As an example, consider the following dial plan: + + 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 + + + + + + + Groves et al Expires - October 2003 [Page 47] + Megaco Protocol version 2 April 2003 + + + If the DTMF detection package described in E.6 is used to collect the + dialled digits, then the dialling plan shown above results in the + following digit map: + + (0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.) + + 7.1.15 Statistics descriptor + + The Statistics Descriptor provides information describing the status + and usage of a Termination during its existence within a specific + Context. There is a set of standard statistics kept for each + Termination where appropriate (number of octets sent and received for + example). The particular statistical properties that are reported for + a given Termination are determined by the Packages realized by the + Termination. By default, statistics are reported when the Termination + is Subtracted from the Context. This behaviour can be overridden by + including an empty AuditDescriptor in the Subtract command. + Statistics may also be returned from the AuditValue command, or any + Add/Move/Modify command using the Audit descriptor. + + Statistics are cumulative; reporting Statistics does not reset them. + Statistics are reset when a Termination is Subtracted from a Context. + + 7.1.16 Packages descriptor + + Used only with the AuditValue command, the PackageDescriptor returns + a list of Packages realized by the Termination. + + 7.1.17 ObservedEvents descriptor + + ObservedEvents is supplied with the Notify command to inform the MGC + of which event(s) were detected. Used with the AuditValue command, + the ObservedEventsDescriptor returns events in the event buffer which + have not been Notified. ObservedEvents contains the RequestIdentifier + of the EventsDescriptor that triggered the notification, the event(s) + detected, optionally the detection time(s) and any parameters of the + observed event. Detection times are reported with a precision of + hundredths of a second. + + 7.1.18 Topology descriptor + + A Topology descriptor is used to specify flow directions between + Terminations in a Context. Contrary to the descriptors in previous + subclauses, the Topology descriptor applies to a Context instead of a + Termination. The default topology of a Context is that each + Termination's transmission is received by all other Terminations. The + Topology descriptor is optional to implement. An MG that does not + support Topology descriptors, but receives a command containing one, + returns Error 444 - "Unsupported or unknown descriptor", and + + + Groves et al Expires - October 2003 [Page 48] + Megaco Protocol version 2 April 2003 + + + optionally includes a string containing the name of the unsupported + Descriptor ("Topology") in the error text in the error descriptor. + + The Topology descriptor occurs before the commands in an action. It + is possible to have an action containing only a Topology descriptor, + provided that the Context to which the action applies already exists. + + A Topology descriptor consists of a sequence of tuples of associated + terminations of the form (T1, T2, association[,StreamId]). T1 and T2 + specify Terminations within the Context, possibly using the ALL or + CHOOSE wildcard. If the optional StreamId field is used, the + association applies only to the particular stream between T1 and T2 + labeled by the StreamId. If the StreamId field is omitted, the + topology applies to all streams in the termination. The association + specifies how media flows between these two Terminations as follows. + + - (T1, T2, isolate) means that the Terminations matching T2 do not + receive media from the Terminations matching T1, nor vice versa. + + - (T1, T2, oneway) means that the Terminations that match T2 receive + media from the Terminations matching T1, but not vice versa. In + this case use of the ALL wildcard such that there are Terminations + that match both T1 and T2 is not allowed. + + - (T1, T2, bothway) means that the Terminations matching T2 receive + media from the Terminations matching T1, and vice versa. In this + case it is allowed to use wildcards such that there are + Terminations that match both T1 and T2. However, if there is a + Termination that matches both, no loopback is introduced. + + CHOOSE wildcards may be used in T1 and T2 as well, under the + following restrictions: + + - the action (see clause 8) of which the topology descriptor is part + contains an Add command in which a CHOOSE wildcard is used; + + - 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 to which a Termination is added, is + connected to the newly added Termination as specified by the Topology + descriptor. If a termination is not mentioned within a topology + descriptor, any topology associated with it remains unchanged. If, + however, a new termination is added into a context its association + with the other terminations within the context defaults to bothway, + unless a topology descriptor is given to change this (eg. if T3 is + + + Groves et al Expires - October 2003 [Page 49] + Megaco Protocol version 2 April 2003 + + + added to a context with T1 and T2 with topology (T3, T1, oneway) it + will be connected bothway to T2). + + If the topology is applied to one particular stream (T1, T2, + association, StreamId), the topology of other streams between the + terminations does not change. + + A topology descriptor SHALL NOT include a combination of associations + between two terminations (Ti,Tj) with and without the optional + StreamID field, to avoid undefined behavior. For example (T1,T2, + bothway) and (T1,T2,isolate,S1) shall not appear in the same + descriptor. Upon receipt of such a topology descriptor, a MG shall + respond with an error response, including Error 421 - "Unknown action + or illegal combination of actions". + + Figure 7, and the table following it and Figure 8 following it show + some examples of the effect of including topology descriptors in + actions. In these examples it is assumed that 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 + + + Groves et al Expires - October 2003 [Page 50] + Megaco Protocol version 2 April 2003 + + + + Figure 7: Example topologies + Note: the direction of the arrow indicates the direction of flow + + + Topology Description + + 1 No topology descriptors + + When no topology descriptors are included, all + Terminations have a bothway connection to all other + Terminations. + + 2 T1, T2 Isolate + + Removes the connection between T1 and T2. T3 has a + bothway 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. + + + +----+ +----+ +----+ + | T2 | | T2 | | T2 | + +----+ +----+ +----+ + //\\ //\\ //\\ + // \\ // \\ // \\ + 1//2 1\\2 1//2 1\\2 1//2 1\\2 + +---+ +---+ +---+ +---+ +---+ +---+ + | | 1 | | | | 1 | | | | 1 | | + + + Groves et al Expires - October 2003 [Page 51] + Megaco Protocol version 2 April 2003 + + + | |<->| | | |<->| | | |<--| | + |T1 | |T3 | |T1 | |T3 | |T1 | |T3 | + | | 2 | | | | 2 | | | | 2 | | + | |<->| | | |-->| | | |-->| | + | | | | | | | | | | | | + +---+ +---+ +---+ +---+ +---+ +---+ + + 1. No Topology Desc. 2. T1,T3, oneway,2 3. T3, T1,oneway,1 + + Figure 8: Example Topology at stream level + + + + A oneway connection must be implemented in such a way that the other + Terminations in the Context are not aware of the change in topology. + + 7.1.19 Error Descriptor + + If a responder encounters an error when processing a transaction + request, it must include an error descriptor in its response. A + Notify request may contain an error descriptor as well. + + An error descriptor consists of an IANA-registered error code, + optionally accompanied by an error text. H.248.8 contains a list of + valid error codes and error descriptions. + + An error descriptor shall be specified at the "deepest level" that is + semantically appropriate for the error being described and that is + possible given any parsing problems with the original request. An + error descriptor may refer to a syntactical construct other than + where it appears. For example, Error 422 - "Syntax Error in Action", + could appear within a command even though it refers to the larger + construct - the action - and not the particular command within which + it appears. + + + 7.2 Command Application Programming Interface + + Following is an Application Programming Interface (API) describing + the Commands of the protocol. This API is shown to illustrate the + Commands and their parameters and is not intended to specify + implementation (e.g. via use of blocking function calls). It + describes the input parameters in parentheses after the command name + and the return values in front of the Command. This is only for + descriptive purposes; the actual Command syntax and encoding are + specified in later subclauses. The order of parameters to commands is + not fixed. Descriptors may appear as parameters to commands in any + order. The descriptors SHALL be processed in the order in which they + appear. + + + Groves et al Expires - October 2003 [Page 52] + Megaco Protocol version 2 April 2003 + + + Any reply to a command may contain an error descriptor; the API does + not specifically show this. + + All parameters enclosed by square brackets ([. . .]) are considered + 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] + [, EventBufferDescriptor] + [, SignalsDescriptor] + [, DigitMapDescriptor] + [, AuditDescriptor] + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (05/2002). + + The TerminationID specifies the Termination to be added to the + Context. The Termination is either created, or taken from the null + Context. If a CHOOSE wildcard is used in the TerminationID, the + selected TerminationID will be returned. Wildcards may be used in an + Add, but such usage 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 MuxDescriptor specifies a multiplexer if applicable. For + convenience, if a Multiplex descriptor is present in an Add command + and lists any Terminations that are not currently in the Context, + such Terminations are added to the Context as if individual Add + + + Groves et al Expires - October 2003 [Page 53] + Megaco Protocol version 2 April 2003 + + + commands listing the Terminations were 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 present, it provides + the list of events that SHOULD be detected on the Termination. + + The EventBufferDescriptor parameter is optional. If present, it + provides the list of events that the MG is requested to detect and + buffer when EventBufferControl equals LockStep. + + The SignalsDescriptor parameter is optional. If present, it provides + the list of signals that SHOULD be applied to the Termination. + + The DigitMapDescriptor parameter is optional. If present, it defines + a DigitMap definition that may be used in an EventsDescriptor. + + The AuditDescriptor is optional. If present, the command will return + descriptors as specified in the AuditDescriptor. + + All descriptors that can be modified could be returned by 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 + + The Modify Command modifies the properties of a Termination. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] (*) + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + Modify( TerminationID + [, MediaDescriptor] + [, ModemDescriptor] (*) + [, MuxDescriptor] + [, EventsDescriptor] + [, EventBufferDescriptor] + + + Groves et al Expires - October 2003 [Page 54] + Megaco Protocol version 2 April 2003 + + + [, SignalsDescriptor] + [, DigitMapDescriptor] + [, AuditDescriptor] + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (05/2002). + + + + The TerminationID may be specific if a single Termination in the + Context is to be modified. Use of wildcards in the TerminationID may + be appropriate for some operations. 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 CHOOSE option is an error, + as the Modify command may only be used on existing Terminations. + + For convenience, if a Multiplex Descriptor is present in a Modify + command, then: + + - if the new Multiplex Descriptor lists any Terminations that are + not currently in the Context, such Terminations are added to the + context as if individual Add commands listing the Terminations + were invoked. + + - if any Terminations listed previously in the Multiplex Descriptor + are no longer present in the new Multiplex Descriptor, they are + subtracted from the context as if individual Subtract commands + listing the Terminations were invoked. + + The remaining parameters to Modify are the same as those to Add. + Possible return values are the same as those to Add. + + 7.2.3 Subtract + + The Subtract Command disconnects a Termination from its Context and + returns statistics on the Termination's participation in the Context. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] (*) + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + + + Groves et al Expires - October 2003 [Page 55] + Megaco Protocol version 2 April 2003 + + + Subtract(TerminationID + [, AuditDescriptor] + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (05/2002). + + TerminationID in the input parameters represents the Termination that + is being subtracted. The TerminationID may be specific or may be a + wildcard value indicating that all (or a set of related) Terminations + in the Context of the Subtract Command are to be 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. + + The use of CHOOSE in the TerminationID is an error, as the Subtract + command may only be used on existing Terminations. + + ALL may be used as the ContextID as well as the TerminationId in a + Subtract, which would have the effect of deleting all Contexts, + deleting all ephemeral Terminations, and returning all physical + Terminations to Null Context. Subtract of a termination from the Null + Context is not allowed. + + For convenience, if a multiplexing Termination is the object of a + Subtract command, then any bearer Terminations listed in its + Multiplex Descriptor are subtracted from the context as if individual + Subtract commands listing the Terminations were invoked. + + By default, the Statistics parameter is returned to report + information collected on the Termination or Terminations specified in + the Command. The information reported applies to the Termination's or + Terminations' existence in the Context from which it or they are + being subtracted. + + The AuditDescriptor is optional. If present, the command will return + only those descriptors as specified in the AuditDescriptor, which may + be empty. If omitted, the Statistics descriptor is returned, by + default. Possible return values are the same as those to Add. + + When a provisioned Termination is Subtracted from a Context, its + property values shall revert to: + + - the default value, if specified for the property and not + overridden by provisioning; + + - otherwise, the provisioned value. + + + + + + Groves et al Expires - October 2003 [Page 56] + Megaco Protocol version 2 April 2003 + + + 7.2.4 Move + + The Move Command moves a Termination to another Context from its + current Context in one atomic operation. The Move command is the only + command that refers to a Termination in a Context different from that + to which the command is applied. The Move command shall not be used + to move Terminations to or from the null Context. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] (*) + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + Move( TerminationID + [, MediaDescriptor] + [, ModemDescriptor] (*) + [, MuxDescriptor] + [, EventsDescriptor] + [, EventBufferDescriptor] + [, SignalsDescriptor] + [, DigitMapDescriptor] + [, AuditDescriptor] + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (05/2002). + + 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. The + Context to which the Termination is moved 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 Move command does not affect the properties of the Termination on + which it operates, except those properties explicitly modified by + descriptors included in the Move command. The AuditDescriptor with + the Statistics option, for example, would return statistics on the + Termination just prior to the Move. Possible descriptors returned + from Move are the same as for Add. + + + + + Groves et al Expires - October 2003 [Page 57] + Megaco Protocol version 2 April 2003 + + + For convenience, if a multiplexing Termination is the object of a + Move command, then any bearer Terminations listed in its Multiplex + Descriptor are also moved as if individual Move commands listing the + Terminations were invoked. + + Move SHALL NOT be used on a Termination with a serviceState of + "OutofService". + + 7.2.5 AuditValue + + The AuditValue Command returns the current values of properties, + events, signals and statistics associated with Terminations. An + AuditValue may request the contents of a descriptor or of a single + property, event, signal or statistics. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] (*) + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + AuditValue(TerminationID, + AuditDescriptor + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (05/2002). + + 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, 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. Use of CHOOSE is an error. + + Descriptors or individual properties, signals, events and statistics + can be audited. + + - An audit of a descriptor may be requested by identifying the + desired descriptor in the AuditDescriptor with no further + information. + + + + + Groves et al Expires - October 2003 [Page 58] + Megaco Protocol version 2 April 2003 + + + - To audit an individual property in the media descriptor the + relevant stream ID (optional), group ID (optional) and propertyID + are included. The current value of the property is returned. Group + ID is used in the case where the local control Reserve Group flag + is used. Group ID 1 corresponds to the first group (session + decription) reserved, Group ID 2 the next group etcetera. + + - To audit a signal the relevant signal list ID and/or signal ID are + provided. Only if the signal is active the values of all the + signal parameters are returned including: the keepactive + indication, signal type, duration, signal completion indication + and package defined properties. + + - To audit an event, the relevant stream id (optional), eventID, + requestID (optional) are provided. The values of all the event + parameters are returned including: event actions and packaged + defined parameters. + + - To audit a statistic the identity of the statistic is provided. + The current value of the statistic is returned. The statistic is + not reset. + + - To audit a package the identity and version of the package is + provided. All properties, signals, events and statistics defined + in that particular package are returned with their current value. + + It is possible to audit multiple individual items in one request. + + If a descriptor audit is requested, the appropriate descriptors, with + the current values for the Termination, are 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 + ObservedEventsDescriptor 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. 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 + + + Groves et al Expires - October 2003 [Page 59] + Megaco Protocol version 2 April 2003 + + + TerminationIDs when used with wildcard. Annexes A and B provide a + special syntax for presenting such a list in condensed form, such + that the AuditValue command tag does not have to be repeated for each + TerminationID. + + AuditValue results depend on the Context, viz. specific, null, or + wildcarded. (Note that ContextID All does not include the null + Context.) The TerminationID may be specific, or wildcarded. + + The following are examples of what is returned in case the context + and/or the termination is wildcarded and a wildcarded response has + been specified. + + Assume that the gateway has 4 terminations: t1/1, t1/2, t2/1 and + t2/2. Assume that terminations t1/* have implemented packages aaa and + bbb and that terminations t2/* have implemented packages ccc and ddd. + Assume that Context 1 has t1/1 and t2/1 in it and that Context 2 has + t1/2 and t2/2 in it. + + The command: + + Context=1{AuditValue=t1/1{Audit{Packages}}} + + Returns: + + Context=1{AuditValue=t1/1{Packages{aaa,bbb}}} + + The command: + + Context=*{AuditValue=t2/*{Audit{Packages}}} + + Returns: + + Context=1{AuditValue=t2/1{Packages{ccc,ddd}}}, + Context=2{AuditValue=t2/2{Packages{ccc,ddd}}} + + The command: + + Context=*{W-AuditValue=t1/*{Audit{Packages}}} + + Returns: + + Context=*{W-AuditValue=t1/*{Packages{aaa,bbb}}} + + Note: A wildcard response may also be used for other commands such as + Subtract. + + The following illustrates other information that can be obtained with + the AuditValue Command: + + + Groves et al Expires - October 2003 [Page 60] + Megaco Protocol version 2 April 2003 + + + 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 (the + ContextID list SHOULD be returned by + using multiple action replies, each + containing a ContextID from the + list) + + All Specific (Non-null) ContextID in which the + Termination currently exists + + + + 7.2.6 AuditCapabilities + + The AuditCapabilities Command returns the possible values of + properties, events, signals and statistics associated with + Terminations. An AuditCapabilities may be requested for the contents + of a descriptor or for a single property, event, signal or + statistics. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor](*) + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + + + Groves et al Expires - October 2003 [Page 61] + Megaco Protocol version 2 April 2003 + + + [,StatisticsDescriptor] + AuditCapabilities( + TerminationID, + AuditDescriptor + ) + + (*) ModemDescriptor has been deprecated in H.248.1 (02/2002). + + Descriptors or individual properties, signals, events and statistics + can be audited. + + - An audit of a entire descriptor may be requested by identifying + the desired descriptor in the AuditDescriptor with no further + information. + + - To audit an individual property in the media descriptor the + relevant stream ID (optional) and propertyID are included. A list + of possible values of the property are returned. + + - To audit a signal the relevant signal list ID and/or signal ID are + provided. A list of possible values associated with each signal + parameter is returned (including: the keepactive indication, + signal type, duration, signal completion indication and package + defined properties). + + - To audit an event the relevant stream id (optional), eventID, + requestID (optional) are provided. A list of possible values + associated with each event parameter is returned (including: event + actions and packaged defined parameters). + + - To audit a statistic the identity of statistic is provided. The + possible values of the statistic are returned. The statistic is + not reset. + + If a descriptor audit is requested 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. + + If a property, signal, event or statistic is audited, the appropriate + properties, signals events, and statistics with the capabilities of + the Termination are returned from AuditCapabilities. + + + + + Groves et al Expires - October 2003 [Page 62] + Megaco Protocol version 2 April 2003 + + + 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. + + The following illustrates other information that can be obtained with + the AuditCapabilties 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 MG 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 Same as for AuditValue + + All Specific Same as for AuditValue + + + + 7.2.7 Notify + + The Notify Command allows the Media Gateway to notify the Media + Gateway Controller of events occurring within the Media Gateway. + + + + Groves et al Expires - October 2003 [Page 63] + Megaco Protocol version 2 April 2003 + + + TerminationID + Notify(TerminationID, + ObservedEventsDescriptor, + [ErrorDescriptor] + ) + + The TerminationID parameter specifies the Termination issuing the + Notify Command. The TerminationID shall be a fully qualified name. + + The ObservedEventsDescriptor contains the RequestID and a list of + events that the Media Gateway detected in the order that they were + detected. Each event in the list is accompanied by parameters + associated with the event and optionally an indication of the time + that the event was detected. Procedures for sending Notify commands + with RequestID equal to 0 are for further study. + + Notify Commands with RequestID not equal to 0 shall occur only as the + result of detection of an event specified by an Events descriptor + which is active on the Termination concerned. + + The RequestID returns the RequestID parameter of the EventsDescriptor + that triggered the Notify Command. It is used to correlate the + notification with the request that triggered it. The events in the + list must have been requested via the triggering EventsDescriptor or + embedded events descriptor unless the RequestID is 0 (which is for + further study). + + The ErrorDescriptor may be sent in the Notify Command as a result of + Error 518 - "Event buffer full". + + 7.2.8 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. The Media Gateway Controller may indicate that + Termination(s) shall be taken out of or returned to service. The + Media Gateway may notify the MGC that the capability of a Termination + has changed. It also allows a MGC to hand over control of a MG to + another MGC. + + TerminationID, + [ServiceChangeDescriptor] + ServiceChange(TerminationID, + ServiceChangeDescriptor + ) + + The TerminationID parameter specifies the Termination(s) that are + taken out of or returned to service. Wildcarding of Termination names + + + Groves et al Expires - October 2003 [Page 64] + Megaco Protocol version 2 April 2003 + + + is permitted, with the exception that the CHOOSE mechanism shall not + be used. Use of the "Root" TerminationID indicates a ServiceChange + affecting the entire Media Gateway. + + The ServiceChangeDescriptor contains the following parameters as + required: + + - ServiceChangeMethod + - ServiceChangeReason + - ServiceChangeDelay + - ServiceChangeAddress + - ServiceChangeProfile + - ServiceChangeVersion + - ServiceChangeMgcId + - TimeStamp + - ServiceChangeInfo + + The ServiceChangeMethod parameter specifies the type of ServiceChange + that will or has occurred: + + 1) Graceful - indicates that the specified Terminations will be taken + out of service after the specified ServiceChangeDelay; established + connections are not yet affected, but the Media Gateway Controller + SHOULD refrain from establishing new connections and SHOULD + attempt to gracefully tear down existing connections on the + Termination(s) affected by the serviceChange command. The MG + SHOULD set Termination serviceState at the expiry of + ServiceChangeDelay or the removal of the Termination from an + active Context (whichever is first), to "out of service". + + 2) Forced - indicates that the specified Terminations were taken + abruptly out of service and any established connections associated + with them may be lost. For non-Root terminations, the MGC is + responsible for cleaning up the Context (if any) with which the + failed Termination is associated. At a minimum the Termination + shall be subtracted from the Context. The Termination serviceState + SHOULD be "out of service". For the root termination, the MGC can + assume that all connections are lost on the MG and thus can + consider that all the terminations have been subtracted. + + 3) Restart - indicates that service will be restored on the specified + Terminations after expiration of the ServiceChangeDelay. The + serviceState SHOULD be set to "inService" upon expiry of + ServiceChangeDelay. + + 4) Disconnected - always applied with the Root TerminationID, + indicates that the MG lost communication with the MGC, but it was + subsequently restored to the same MGC (possibly after trying other + MGCs on a pre-provisioned list). Since MG state may have changed, + + + Groves et al Expires - October 2003 [Page 65] + Megaco Protocol version 2 April 2003 + + + the MGC may wish to use the Audit command to resynchronize its + state with the MG's. + + 5) Handoff - sent from the MGC to the MG, this reason indicates that + the MGC is going out of service and a new MGC association must be + established. Sent from the MG to the MGC, this indicates that the + MG is attempting to establish a new association in accordance with + a Handoff received from the MGC with which it was previously + associated. + + 6) Failover - sent from MG to MGC to indicate the primary MG is out + of service and a secondary MG is taking over. This serviceChange + method is also sent from the MG to the MGC when the MG detects + that MGC has failed. + + 7) Another value whose meaning is mutually understood between the MG + and the MGC. + + The ServiceChangeReason parameter specifies the reason why the + ServiceChange has or will occur. It consists of an alphanumeric token + (IANA registered) and, optionally, an explanatory string. + + The optional ServiceChangeAddress parameter specifies the address + (e.g. IP port number for IP networks) to be used for subsequent + communications. It can be specified in the input parameter descriptor + or the returned result descriptor. ServiceChangeAddress and + ServiceChangeMgcId parameters must not both be present in the + ServiceChangeDescriptor or the ServiceChangeResultDescriptor. The + ServiceChangeAddress provides an address to be used within the + Context of the association currently being negotiated, while the + ServiceChangeMgcId provides an alternate address where the MG SHOULD + seek to establish another association. Note that the use of + ServiceChangeAddress is not encouraged. MGCs and MGs must be able to + cope with the ServiceChangeAddress being either a full address or + just a port number in the case of TCP transports. + + The optional ServiceChangeDelay parameter is expressed in seconds. If + the delay is absent or set to zero, the delay value SHOULD be + considered to be null. In the case of a "graceful" + ServiceChangeMethod, a null delay indicates that the Media Gateway + Controller SHOULD wait for the natural removal of existing + connections and SHOULD not establish new connections. For "graceful" + only, a null delay means the MG must not set serviceState "out of + service" until the Termination is in the null Context. + + The optional ServiceChangeProfile parameter specifies the Profile (if + any) of the protocol supported. The ServiceChangeProfile includes the + version of the profile supported. + + + + Groves et al Expires - October 2003 [Page 66] + Megaco Protocol version 2 April 2003 + + + The optional ServiceChangeVersion parameter contains the protocol + version and is used if protocol version negotiation occurs (see + 11.3). + + The optional TimeStamp parameter specifies the actual time as kept by + the sender. As such, it is not necessarily absolute time according + to, for example, a local time zone - it merely establishes an + arbitrary starting time against which all future timestamps + transmitted by a sender during this association shall be compared. It + can be used by the responder to determine how its notion of time + differs from that of its correspondent. TimeStamp is sent with a + precision of hundredths of a second. + + The optional Extension parameter may contain any value whose meaning + is mutually understood by the MG and MGC. + + The optional ServiceChangeInfo parameter may contain the + package/property/signal/event/statistic of the reason that caused the + service change. + + A ServiceChange Command specifying the "Root" for the TerminationID + and ServiceChangeMethod equal to Restart is a registration command by + which a Media Gateway announces its existence to the Media Gateway + Controller. The Media Gateway may also register by specifying the + "Root" for the TerminationID and ServiceChangeMethod equal to + Failover when the MG detects MGC failures. The Media Gateway is + expected to be provisioned with the name of one primary and + optionally some number of alternate Media Gateway Controllers. + Acknowledgement of the ServiceChange Command completes the + registration process, except when the MGC has returned an alternative + ServiceChangeMgcId as described in the following paragraph. The MG + may specify the transport ServiceChangeAddress to be used by the MGC + for sending messages in the ServiceChangeAddress parameter in 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. In either case, the + recipient must use the supplied address as the destination for all + subsequent transaction requests within the association. At the same + time, as indicated in clause 9, transaction replies and pending + indications must be sent to the address from which the corresponding + requests originated. This must be done even if it implies 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 Media Gateway Controller that SHOULD + preferably be contacted for further service by the Media Gateway. In + this case the Media Gateway shall reissue the ServiceChange command + + + Groves et al Expires - October 2003 [Page 67] + Megaco Protocol version 2 April 2003 + + + to the new Media Gateway Controller. The MGC specified in a + ServiceChangeMgcId, if provided, shall be contacted before any + further alternate MGCs. On a HandOff message from MGC to MG, the + ServiceChangeMgcId is the new MGC that will take over from the + current MGC. + + The return from ServiceChange is empty except when the Root + terminationID is used. In that case it includes the following + parameters as required: + + - ServiceChangeAddress, if the responding MGC wishes to specify a + new destination for messages from the MG for the remainder of the + association; + + - ServiceChangeMgcId, if the responding MGC does not wish to sustain + an association with the MG; + + - ServiceChangeProfile, if the responder wishes to negotiate the + profile to be used for the association. The profile (name and + version) is only returned in reply in the case that the MGC cannot + support the specified profiles in the ServiceChangeRequest. The + returned reply shall indicate the profile and version supported or + "NoProfile" if no profile is supported. Upon reception of a + profile in the reply the MG may continue the relationship with the + current MGC or contact secondary MGCs and establish a relationship + with them. If the profile is not returned the MGC will use the + capabilities specified by the Profile indicated in the service + change request; + + - ServiceChangeVersion, if the responder wishes to negotiate the + version of the protocol to be used for the association. + + The following ServiceChangeReasons are defined. This list may be + extended by an IANA registration as outlined in 14.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 + + + Groves et al Expires - October 2003 [Page 68] + Megaco Protocol version 2 April 2003 + + + 914 Event Capability Failure + 915 State Loss + 916 Packages Change + 917 Capability Change + + + + 7.2.9 Manipulating and Auditing Context Attributes + + The commands of the protocol as discussed in the preceding subclauses + apply to Terminations. This subclause specifies the processing of + Context attributes. + + An action may contain instructions for the manipulation and auditing + of Context properties (see clause 8). + + The MGC may audit a specific Context to determine the current value + of individual context properties. The MGC may determine the current + values for all existing (non-NULL) Contexts by specifying ContextID + ALL in the Audit request. If context attributes are added or have + been modified by the same action as the Audit request the value/s + returned shall be after the action has been applied. + + The following illustrates information that can be obtained with a + context Audit: + + ContextID TerminationID Audit + + Specific Not Applicable Context attribute's value in the + specified context. + + Null Not Applicable Not Allowed + + All Not Applicable Current values for all existing + (non-NULL) Contexts by specifying + ContextID ALL in the Audit request. + + A response for ContextID ALL is + presented through an actionReply + per context. + + + + An action may also include a request to change the attributes of a + Context. + + The Context properties that may be included in an action reply are + used to return information to a MGC. This can be information + + + Groves et al Expires - October 2003 [Page 69] + Megaco Protocol version 2 April 2003 + + + requested by an audit of Context attributes or details of the effect + of manipulation of a Context. + + If a MG receives an action which 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 processing + the manipulation request. + + 7.2.10 Generic Command Syntax + + The protocol can be encoded in a binary format or in a text format. + MGCs SHOULD support both encoding formats. MGs may support both + formats. + + The protocol syntax for the binary format of the protocol is defined + in Annex A. Annex C specifies the encoding of the Local and Remote + descriptors for use with the binary format. + + A complete ABNF of the text encoding of the protocol per RFC 2234 is + given in Annex B. SDP is used as the encoding of the Local and Remote + descriptors for use with the text encoding as modified in 7.1.8. + + + 8 TRANSACTIONS + + Commands between the Media Gateway Controller and the Media Gateway + are grouped into Transactions, each of which is identified by a + TransactionID. Transactions consist of one or more Actions. An Action + consists of a non-empty series of Commands, Context property + modifications, or Context property audits that are limited to + operating within a single Context. Consequently, each Action + typically specifies a ContextID. However, there are two circumstances + where a specific ContextID is not provided with an Action. One is the + case of modification of a Termination outside of a Context. The other + is where the controller requests the gateway to create a new Context. + Figure 9 is a graphic representation of the Transaction, Action and + Command relationships. + + +----------------------------------------------------------+ + | Transaction x | + | +----------------------------------------------------+ | + | | Action 1 | | + | | +---------+ +---------+ +---------+ +---------+ | | + | | | Command | | Command | | Command | | Command | | | + | | | 1 | | 2 | | 3 | | 4 | | | + | | +---------+ +---------+ +---------+ +---------+ | | + | +----------------------------------------------------+ | + | | + + + + Groves et al Expires - October 2003 [Page 70] + Megaco Protocol version 2 April 2003 + + + | +----------------------------------------------------+ | + | | Action 2 | | + | | +---------+ | | + | | | Command | | | + | | | 1 | | | + | | +---------+ | | + | +----------------------------------------------------+ | + | | + | +----------------------------------------------------+ | + | | Action 3 | | + | | +---------+ +---------+ +---------+ | | + | | | Command | | Command | | Command | | | + | | | 1 | | 2 | | 3 | | | + | | +---------+ +---------+ +---------+ | | + | +----------------------------------------------------+ | + +----------------------------------------------------------+ + + Figure 9: Transactions, Actions and Commands + + Transactions are presented as TransactionRequests. Corresponding + responses to a TransactionRequest are received in a single reply, + possibly preceded by a number of TransactionPending messages (see + 8.2.3). + + Transactions guarantee ordered Command processing. That is, Commands + within a Transaction are executed sequentially. Ordering of + Transactions is NOT guaranteed - transactions may be executed in any + order, or simultaneously. + + At the first failing Command in a Transaction, processing of the + remaining Commands in that Transaction stops. If a command contains a + wildcarded TerminationID, the command is attempted with each of the + actual TerminationIDs matching the wildcard. A response within the + TransactionReply is included for each matching TerminationID, even if + one or more instances generated an error. If any TerminationID + matching a wildcard results in an error when executed, any commands + following the wildcarded command are not attempted. + + Commands may be marked as "Optional" which can override this + behaviour - if a command marked as Optional results in an error, + subsequent commands in the Transaction will be executed. If a command + fails, the MG shall as far as possible restore the state that existed + prior to the attempted execution of the command before continuing + with command processing. + + A TransactionReply includes the results for all of the Commands in + the corresponding TransactionRequest. The TransactionReply includes + the return values for the Commands that were executed successfully, + and the Command and error descriptor for any Command that failed. + + + Groves et al Expires - October 2003 [Page 71] + Megaco Protocol version 2 April 2003 + + + TransactionPending is used to periodically notify the receiver that a + Transaction has not completed yet, but is actively being processed. + + Applications SHOULD implement an application level timer per + transaction. Expiration of the timer SHOULD cause a retransmission of + the request. Receipt of a Reply SHOULD cancel the timer. Receipt of + Pending SHOULD restart the timer. + + 8.1 Common parameters + + 8.1.1 Transaction Identifiers + + Transactions are identified by a TransactionID, which is assigned by + sender and is unique within the scope of the sender. A response + containing an error descriptor to indicate that the TransactionID is + missing in a request shall use TransactionID 0 in the corresponding + TransactionReply. + + 8.1.2 Context Identifiers + + Contexts are identified by a ContextID, which is assigned by the + Media Gateway and is unique within the scope of the Media Gateway. + The Media Gateway Controller shall use the ContextID supplied by the + Media Gateway in all subsequent Transactions relating to that + Context. The protocol makes reference to a distinguished value that + may be used by the Media Gateway Controller when referring to a + Termination that is currently not associated with a Context, namely + the null ContextID. + + The CHOOSE wildcard is used to request that the Media Gateway create + a new Context. + + The MGC may use the ALL wildcard to address all Contexts on the MG. + The null Context is not included when the ALL wildcard is used. + + The MGC shall not use partially specified ContextIDs containing the + CHOOSE or ALL wildcards. + + 8.2 Transaction Application Programming Interface + + Following is an Application Programming Interface (API) describing + the Transactions of the protocol. This API is shown to illustrate the + Transactions and their parameters and is not intended to specify + implementation (e.g. via use of blocking function calls). It will + describe the input parameters and return values expected to be used + by the various Transactions of the protocol from a very high level. + Transaction syntax and encodings are specified in later subclauses. + + + + + Groves et al Expires - October 2003 [Page 72] + Megaco Protocol version 2 April 2003 + + + 8.2.1 TransactionRequest + + The TransactionRequest is invoked by the sender. There is one + Transaction per request invocation. A request contains one or more + Actions, each of which specifies its target Context and one or more + Commands per Context. + + TransactionRequest(TransactionId { + ContextID {Command ... Command}, + . . . + ContextID {Command ... Command } }) + + The TransactionID parameter must specify a value for later + correlation with the TransactionReply or TransactionPending response + from the receiver. + + The ContextID parameter must specify a value to pertain to all + Commands that follow up to either the next specification of a + ContextID parameter or the end of the TransactionRequest, whichever + comes first. + + The Command parameter represents one of the Commands mentioned in 7.2 + (Command Application Programming Interface). + + 8.2.2 TransactionReply + + The TransactionReply is invoked by the receiver. There is one reply + invocation per transaction. A reply contains one or more Actions, + each of which must specify its target Context and one or more + Responses per Context. The TransactionReply is invoked by the + responder when it has processed the TransactionRequest. + + A TransactionRequest has been processed: + + - when all actions in that TransactionRequest have been processed; + or + + - when an error is encountered in processing that + TransactionRequest, except when the error is in an optional + command. + + A command has been processed when all descriptors in that command + have been processed. + + A SignalsDescriptor is considered to have been processed when it has + been established that the descriptor is syntactically valid, the + requested signals are supported and they have been queued to be + applied. + + + + Groves et al Expires - October 2003 [Page 73] + Megaco Protocol version 2 April 2003 + + + An EventsDescriptor or EventBufferDescriptor is considered to have + been processed when it has been established that the descriptor is + syntactically valid, the requested events can be observed, any + embedded signals can be generated, any embedded events can be + detected, and the MG has been brought into a state in which the + events will be detected. + + TransactionReply(TransactionID { + ContextID { Response ... Response }, + . . . + ContextID { Response ... Response } }) + + The TransactionID parameter must be the same as that of the + corresponding TransactionRequest. + + The ContextID parameter must specify a value to pertain to all + Responses for the action. The ContextID may be specific, all or null. + + Each of the Response parameters represents a return value as + mentioned in 7.2, or an error descriptor if the command execution + encountered an error. Commands after the point of failure are not + processed and, therefore, Responses are not issued for them. + + An exception to this occurs if a command has been marked as optional + in the Transaction request. If the optional command generates an + error, the transaction still continues to execute, so the Reply + would, in this case, have Responses after an Error. + + Section 7.1.19 Error Descriptor specifies the generation of error + descriptors. The text below discusses several individual cases. + + If the receiver encounters an error in processing a ContextID, the + requested Action response will consist of the Context ID and a single + error descriptor, 422 - "Syntax Error in Action". + + If the receiver encounters an error such that it cannot determine a + legal Action, it will return a TransactionReply consisting of the + TransactionID and a single error descriptor, 422 - "Syntax Error in + Action". If the end of an action cannot be reliably determined but + one or more commands can be parsed, it will process them and then + send 422 - "Syntax Error in Action" as the last action for the + transaction. If the receiver encounters an error such that is cannot + determine a legal Transaction, it will return a TransactionReply with + a null TransactionID and a single error descriptor (403 - "Syntax + Error in Transaction"). + + If the end of a transaction cannot be reliably determined and one or + more Actions can be parsed, it will process them and then return 403 + - "Syntax Error in Transaction" as the last action reply for the + + + Groves et al Expires - October 2003 [Page 74] + Megaco Protocol version 2 April 2003 + + + transaction. If no Actions can be parsed, it will return 403 - + "Syntax Error in Transaction" as the only reply. + + If the terminationID cannot be reliably determined, it will send 442 + - "Syntax Error in Command" as the action reply. + + If the end of a command cannot be reliably determined, it will return + 442 - "Syntax Error in Command" as the reply to the last action it + can parse. + + 8.2.3 TransactionPending + + The receiver invokes the TransactionPending. A TransactionPending + indicates that the Transaction is actively being processed, but has + not been completed. It is used to prevent the sender from assuming + the TransactionRequest was lost where the Transaction will take some + time to complete. + + TransactionPending(TransactionID { } ) + + The TransactionID parameter must be the same as that of the + corresponding TransactionRequest. A property of root + (normalMGExecutionTime) is settable by the MGC to indicate the + interval within which the MGC expects a response to any transaction + from the MG. Another property (normalMGCExecutionTime) is settable by + the MGC to indicate the interval within which the MG SHOULD expect a + response to any transaction from the MGC. Senders may receive more + than one TransactionPending for a command. If a duplicate request is + received when pending, the responder may send a duplicate pending + immediately, or continue waiting for its timer to trigger another + TransactionPending. + + A property of the root termination (MGOriginatedPendingLimit) is + settable by the MGC to indicate the number of TransactionPendings + that can be received from the MG. When the value expressed by this + property is exceeded, the MG shall stop the transaction processing + and send back a TransactionReply, otherwise the MGC can assume the + Transaction to be in error. + + Another property of the root termination (MGCOriginatedPendingLimit) + is settable by the MGC to indicate the number of TransactionPendings + that can be received from the MGC. When the value expressed by this + property is exceeded, the MGC shall stop the transaction processing + and send back a TransactionReply otherwise the MG can assume the + Transaction to be in error. + + The xxxOriginatedPendingLimit (MGOriginatedPendingLimit or + MGCOriginatedPendingLimit) may be exceeded either because of long + command processing or due to an error (e.g. a command caused a loop). + + + Groves et al Expires - October 2003 [Page 75] + Megaco Protocol version 2 April 2003 + + + In both cases the receiver of the original TransactionRequest will + issue a TransactionReply with an error descriptor as a response + parameter in correspondence with either the offending long command or + the command that caused the error. Further commands in the + transaction shall not be processed. Error 506 - "Number of + TransactionPendings Exceeded" shall be used. + + NOTE - To prevent a situation where the xxxOriginatedPendingLimit + (MGOriginatedPendingLimit or MGCOriginatedPendingLimit) is exceeded + due to an error and the receiver of the original TransactionRequest + keeps sending TransactionPending, the receiver of the original + TransactionRequest SHOULD implement a management protection mechanism + in order to trigger the appropriate recovery actions. The sender of + the original TransactionRequest may keep track of the number of + received Pendings and initiate corrective actions + + 8.3 Messages + + Multiple Transactions can be concatenated into a Message. Messages + have a header, which includes the identity of the sender. The Message + Identifier (MID) of a message is set to a provisioned name (e.g. + domain address/domain name/device name) of the entity transmitting + the message. Domain name is a suggested default. An H.248.1 entity + (MG/MGC) must consistently use the same MID in all messages it + originates for the duration of control association with the peer + (MGC/MG). + + Every Message contains a Version Number identifying the version of + the protocol the message conforms to. Versions consist of one or two + digits, beginning with version 1. The current version of the protocol + is Version 2. + + The transactions in a message are treated independently. There is no + order implied; there is no application or protocol acknowledgement of + a message. A message is essentially a transport mechanism. For + example, message X containing transaction requests A, B, and C may be + responded to with message Y containing replies to A and C and message + Z containing the reply to B. Likewise, message L containing request D + and message M containing request E may be responded to with message N + containing replies to both D and E. + + + 9 TRANSPORT + + The transport mechanism for the protocol SHOULD allow the reliable + transport of transactions between a MGC and MG. The transport shall + remain independent of what particular commands are being sent and + shall be applicable to all application states. There are several + transports defined for the protocol, which are defined in Annexes to + + + Groves et al Expires - October 2003 [Page 76] + Megaco Protocol version 2 April 2003 + + + this Recommendation and other Recommendations of the H.248 sub-series + (e.g. H.248.4 and H.248.5). Additional Transports may be defined as + additional Recommendations of the H.248 sub-series. For transport of + the protocol over IP, MGCs shall implement both TCP and UDP/ALF, a MG + shall implement TCP or UDP/ALF or both. + + The MG is provisioned with a name or address (such as DNS name or IP + address) of a primary and zero or more secondary MGCs (see 7.2.8) + that is the address the MG uses to send messages to the MGC. If TCP + or UDP is used as the protocol transport and the port to which the + initial ServiceChange request is to be sent is not otherwise known, + that request SHOULD be sent to the default port number for the + protocol. This port number is 2944 for text-encoded operation or 2945 + for binary-encoded operation, for either UDP or TCP. The MGC receives + the message containing the ServiceChange request from the MG and can + determine the MG's address from it. As described in 7.2.8, either the + MG or the MGC may supply an address in the ServiceChangeAddress + parameter to which subsequent transaction requests must be addressed, + but responses (including the response to the initial ServiceChange + request) must always be sent back to the address which was the source + of the corresponding request. For example, in IP networks, this is + the source address in the IP header and the source port number in the + TCP/UDP/SCTP header. + + 9.1 Ordering of Commands + + This Recommendation does not mandate that the underlying transport + protocol guarantees the sequencing of transactions sent to an entity. + This property tends to maximize the timeliness of actions, but it has + a few drawbacks. For example: + + - Notify commands may be delayed and arrive at the MGC after the + transmission of a new command changing the EventsDescriptor. + + - If a new command is transmitted before a previous one is + acknowledged, there is no guarantee that prior command will be + executed before the new one. + + Media Gateway Controllers that want to guarantee consistent operation + of the Media Gateway may use the following rules. These rules are + with respect to commands that are in different transactions. Commands + that are in the same transaction are executed in order (see clause + 8). + + 1) When a Media Gateway handles several Terminations, commands + pertaining to the different Terminations may be sent in parallel, + for example following a model where each Termination (or group of + Terminations) is controlled by its own process or its own thread. + + + + Groves et al Expires - October 2003 [Page 77] + Megaco Protocol version 2 April 2003 + + + 2) 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. However, a Subtract command may be + issued at any time. In consequence, a Media Gateway may sometimes + receive a Modify command that applies to a previously subtracted + Termination. Such commands SHOULD be ignored, and an error code + SHOULD be returned. + + 3) For transports that do not guarantee in-sequence delivery of + messages (i.e. UDP), there SHOULD normally be on a given + Termination at most one outstanding Notify command at any time. + + 4) In some cases, 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 wildcarding (or implied in + a Multiplex descriptor) SHOULD not be sent until the wildcarded + Subtract command is acknowledged. + + 5) AuditValue and AuditCapability are not subject to any sequencing. + + 6) 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 do not affect the command responder, which SHOULD always + respond to commands. + + 9.2 Protection against Restart Avalanche + + In the event that a large number of Media Gateways are powered on + simultaneously and they were to all initiate a ServiceChange + transaction, the Media Gateway Controller would very likely be + swamped, leading to message losses and network congestion during the + critical period of service restoration. In order to prevent such + avalanches, the following behaviour is suggested: + + 1) When a Media Gateway is powered on, it SHOULD initiate a restart + timer to a random value, uniformly distributed between 0 and a + maximum waiting delay (MWD). Care SHOULD be taken to avoid + synchronicity of the random number generation between multiple + Media Gateways that would use the same algorithm. + + 2) The Media Gateway SHOULD then wait for either the end of this + timer or the detection of a local user activity, such as for + example an off-hook transition on a residential Media Gateway. + + + + Groves et al Expires - October 2003 [Page 78] + Megaco Protocol version 2 April 2003 + + + 3) When the timer elapses, or when an activity is detected, the Media + Gateway SHOULD initiate the restart procedure. + + The restart procedure simply requires the MG to guarantee that the + first message that the Media Gateway Controller sees from this MG is + a ServiceChange message informing the Media Gateway Controller about + the restart. + + 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. + + Media Gateway Controllers are typically dimensioned to handle the + peak hour traffic load, during which, in 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. This simple calculation shows that 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 also 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 this 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 clause covers security when using the protocol in an IP + environment. + + 10.1 Protection of Protocol Connections + + A security mechanism is clearly needed to prevent unauthorized + entities from using the protocol defined in this Recommendation for + + + Groves et al Expires - October 2003 [Page 79] + Megaco Protocol version 2 April 2003 + + + setting up unauthorized calls or interfering with authorized calls. + The security mechanism for the protocol when transported over IP + networks is IPsec [RFC 2401 to RFC 2411]. + + The AH header [RFC 2402] affords data origin authentication, + connectionless integrity and optional anti-replay protection of + messages passed between the MG and the MGC. The ESP header [RFC 2406] + 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 Recommendation + employing the ESP header SHALL comply with section 5 of [RFC 2406], + which defines a minimum set of algorithms for integrity checking and + encryption. Similarly, implementations employing the AH header SHALL + comply with section 5 of [RFC 2402], which defines a minimum set of + algorithms for integrity checking using manual keys. + + Implementations SHOULD use IKE [RFC 2409] to permit more robust + keying options. Implementations employing IKE SHOULD support + authentication with RSA signatures and RSA public key encryption. + + 10.2 Interim AH scheme + + Implementation of IPsec requires that the AH or ESP header be + inserted immediately after the IP header. This cannot be easily done + at the application level. Therefore, this presents a deployment + problem for the protocol defined in this Recommendation where the + underlying network implementation does not support IPsec. + + As an interim solution, an optional AH header is defined within the + H.248.1 protocol header. The header fields are exactly those of the + SPI, SEQUENCE NUMBER and DATA fields as defined in [RFC 2402]. The + semantics of the header fields are the same as the "transport mode" + of [RFC 2402], 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 retain the same functionality, the ICV calculation + SHOULD be performed across all the transactions (concatenated) in the + message 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 20 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.1 protocol SHALL implement IPsec where + the underlying operating system and the transport network supports + IPsec. Implementations of the protocol using IPv4 SHALL implement the + interim AH scheme. However, this interim scheme SHALL NOT be used + + + Groves et al Expires - October 2003 [Page 80] + Megaco Protocol version 2 April 2003 + + + 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 RFC 2402 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 allows the MGC to provide MGs with "session keys" that + can be used to encrypt the audio messages, protecting 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". + + 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: 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 round trip, 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 round trip + 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. + + + + Groves et al Expires - October 2003 [Page 81] + Megaco Protocol version 2 April 2003 + + + 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 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 can be changed + by subsequent events, such as failures or manual service events. + + NOTE - 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 MG (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, and thus sharing the Termination is + straightforward. This mechanism 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 + + + Groves et al Expires - October 2003 [Page 82] + Megaco Protocol version 2 April 2003 + + + read-only access. The management mechanism is used to designate which + MGC has read/write capability, and 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 + + A MG is pre-provisioned by a management mechanism outside the scope + of this protocol with a primary and (optionally) an ordered list of + secondary MGCs. Upon a cold start of the MG, it will issue a + ServiceChange command with a "Restart" method, on the Root + Termination to its primary MGC. If the MGC accepts the MG, it sends a + Transaction Reply not including a ServiceChangeMgcId parameter. If + the MGC does not accept the MGÆs registration, it sends a Transaction + Reply, providing the address of an alternate MGC to be contacted by + including a ServiceChangeMgcId parameter. + + If the MG receives a Transaction Reply that includes a + ServiceChangeMgcId parameter, it sends a ServiceChange to the MGC + specified in the ServiceChangeMgcId. It continues this process until + it gets a controlling MGC to accept its registration, or it fails to + get a reply. Upon failure to obtain a reply, either from the primary + MGC, or a designated successor, the MG tries its pre-provisioned + secondary MGCs, in order. If the MG is unable to establish a control + relationship with any MGC, it shall wait a random amount of time as + described in 9.2 and then start contacting its primary, and if + necessary, its secondary MGCs again. + + It is possible that the reply to a ServiceChange with Restart will be + lost, and a command will be received by the MG prior to the receipt + of the ServiceChange response. The MG shall issue Error 505 - Command + Received before Restart Response. + + 11.3 Negotiation of protocol version + + A ServiceChange command from a MG that registers with an MGC shall + contain the version number of the protocol supported by the MG in the + ServiceChangeVersion parameter. Regardless of the version placed in + the ServiceChangeVersion parameter the message containing the command + shall be encoded as a version 1 message. Upon receiving such a + message, if the MGC supports only a lower version, then the MGC shall + send a ServiceChangeReply with the lower version and thereafter all + + + Groves et al Expires - October 2003 [Page 83] + Megaco Protocol version 2 April 2003 + + + the messages between MG and MGC shall conform to the lower version of + the protocol. If the MG is unable to comply and it has established a + transport connection to the MGC, it SHOULD close that connection. In + any event, it SHOULD reject all subsequent requests from the MGC with + Error 406 - "Version Not Supported". + + If the MGC supports a higher version than the MG but is able to + support the lower version proposed by the MG, it shall send a + ServiceChangeReply with the lower version and thereafter all the + messages between MG and MGC shall conform to the lower version of the + protocol. If the MGC is unable to comply, it shall reject the + association, with Error 406 - "Version Not Supported". + + Protocol version negotiation may also occur at "handoff" and + "failover" ServiceChanges. + + When extending the protocol with new versions, the following rules + SHOULD be followed: + + 1) Existing protocol elements, i.e. procedures, parameters, + descriptor, property, values, SHOULD not be changed unless a + protocol error needs to be corrected or it becomes necessary to + change the operation of the service that is being supported by the + protocol. + + 2) The semantics of a command, a parameter, a descriptor, a property, + or a value SHOULD not be changed. + + 3) Established rules for formatting and encoding messages and + parameters SHOULD not be modified. + + 4) When information elements are found to be obsolete they can be + marked as not used. However, the identifier for that information + element will be marked as reserved. In that way it can not be used + in future versions. + + 11.4 Failure of a MG + + If a MG fails, but is capable of sending a message to the MGC, it + sends a ServiceChange with an appropriate method (graceful or forced) + and specifies the Root TerminationID. When it returns to service, it + sends a ServiceChange with a "Restart" method. + + Allowing the MGC to send duplicate messages to both MGs accommodates + pairs of MGs that are capable of redundant failover of one of the + MGs. Only the Working MG shall accept or reject transactions. Upon + failover, the primary MG sends a ServiceChange command with a + "Failover" method and a "MG Impending Failure" reason. The MGC then + uses the secondary MG as the active MG. When the error condition is + + + Groves et al Expires - October 2003 [Page 84] + Megaco Protocol version 2 April 2003 + + + repaired, the Working MG can send a "ServiceChange" with a "Restart" + method. + + Note: Redundant failover MGs require a reliable transport, because + the protocol provides no means for a secondary MG running ALF to + acknowledge messages sent from the MGC. + + 11.5 Failure of an MGC + + If the MG detects a failure of its controlling MGC, it attempts to + contact the next MGC on its pre-provisioned list. It starts its + attempts at the beginning (primary MGC), unless that was the MGC that + failed, in which case it starts at its first secondary MGC. It sends + a ServiceChange message with a "Failover" method and a " MGC + Impending Failure" reason. If the MG is unable to establish a control + relationship with any MGC, it shall wait a random amount of time as + described in section 9.2 and then start again contacting its primary, + and (if necessary) its secondary MGCs. When contacting its previously + controlling MGC, the MG sends the ServiceChange message with + "Disconnected" method. + + In partial failure, or for manual maintenance reasons, an MGC may + wish to direct its controlled MGs to use a different MGC. To do so, + it sends a ServiceChange method to the MG with a "HandOff" method, + and its designated replacement in ServiceChangeMgcId. If "HandOff" is + supported, the MG shall send a ServiceChange message with a "Handoff" + method and a "MGC directed change" reason to the designated MGC. If + it fails to get a reply from the designated MGC, the MG shall behave + as if its MGC failed, and start contacting secondary MGCs as + specified in the previous paragraph. If the MG is unable to establish + a control relationship with any MGC, it shall wait a random amount of + time as described in 9.2 and then start contacting its primary, and + if necessary, its secondary MGCs again. + + No recommendation is made on how the MGCs involved in the Handoff + maintain state information; this is considered to be out of scope of + this Recommendation. The MGC and MG may take the following steps when + Handoff occurs. When the MGC initiates a HandOff, the handover SHOULD + be transparent to Operations on the Media Gateway. Transactions can + be executed in any order, and could be in progress when the + ServiceChange is executed. Accordingly, commands in progress continue + and replies to all commands from the original MGC must be sent to the + transport address from which they were sent. If the service + relationship with the sending MGC has ended, the replies SHOULD be + discarded. The MG may receive outstanding transaction replies from + the new MGC. No new messages shall be sent to the new MGC until the + control association is established. Repeated transaction requests + shall be directed to the new MGC. The MG shall maintain state on all + Terminations and Contexts. + + + Groves et al Expires - October 2003 [Page 85] + Megaco Protocol version 2 April 2003 + + + It is possible that the MGC could be implemented in such a way that a + failed MGC is replaced by a working MGC where the identity of the new + MGC is the same as the failed one. In such a case, ServiceChangeMgcId + would be specified with the previous value and the MG shall behave as + if the value was changed, and send a ServiceChange message, as above. + + Pairs of MGCs that are capable of redundant failover can notify the + controlled MGs of the failover by the above mechanism. + + + 12 PACKAGE DEFINITION + + The primary mechanism for extension is by means of Packages. Packages + define additional Properties, Events, Signals and Statistics that may + occur on Terminations. + + Packages defined by IETF will appear in separate RFCs. + + Packages defined by ITU-T may appear in the relevant Recommendations + (e.g. as Recommendations of the H.248 sub-series). + + 1) A public document or a standard forum document, which can be + referenced as the document that describes the package following + the guideline above, SHOULD be specified. + + 2) The document shall specify the version of the Package that it + describes. + + 3) The document SHOULD be available 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. + + 12.1 Guidelines for defining packages + + Packages define Properties, Events, Signals, and Statistics. + + Packages may also define new error codes according to the guidelines + given in 13.2. This is a matter of documentary convenience: the + package documentation is submitted to IANA in support of the error + code registration. If a package is modified, it is unnecessary to + provide IANA with a new document reference in support of the error + code unless the description of the error code itself is modified. + + Names of all such 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 shall be separated by a forward slash ("/") character. + Example: togen/playtone is the text encoding to refer to the play + tone signal in the tone generation package. + + + Groves et al Expires - October 2003 [Page 86] + Megaco Protocol version 2 April 2003 + + + A Package will contain the following sections: + + 12.1.1 Package + + Overall description of the package, specifying: + + 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. + + Designed to be extended only (Optional): Yes + + This indicates that the package has been expressly designed to be + extended by others, not to be directly referenced. For example, the + package may not have any function on its own or be nonsensical on its + own. The MG SHOULD NOT publish this PackageID when reporting + packages. + + Extends (Optional): existing package Descriptor + + 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 + an identifier defined in the original package and packages it may + have extended (multiple levels of extension). 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 + + Properties defined by the package, specifying: + + Property Name: only descriptive + + PropertyID: is an identifier + + + + Groves et al Expires - October 2003 [Page 87] + Megaco Protocol version 2 April 2003 + + + Description: + + Type: One of: + + Boolean + + String: UTF-8 string + + Octet String: A number of octets. See Annex A and Annex B.3 + for encoding + + 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. The type of + sub-list SHALL also be specified. The type shall be chosen + from the types specified in this section (with the exception of + sub-list). For example, Type: sub-list of enumeration. The + encoding of sub-lists is specified in Annexes A and B.3. + + Possible values: + + A package MUST specify either a specific set of values or a + description of how values are determined. A package MUST also + specify a default value or the default behaviour when the value is + omitted from its descriptor. For example, a package may specify that + procedures related to the property are suspended when it value is + omitted. A default value (but not procedures) may be specified as + provisionable. + + Defined in: + + Which H.248.1 descriptor the property is defined in. LocalControl is + for stream dependent properties. TerminationState is 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 + + + + Groves et al Expires - October 2003 [Page 88] + Megaco Protocol version 2 April 2003 + + + property is declared as global, the value of the property is shared + by all Terminations realizing the package. + + 12.1.3 Events + + Events defined by the package, specifying: + + 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 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 12.2. + + 12.1.4 Signals + + Signals defined by the package, specifying: + + Signal Name: only descriptive + + SignalID: is an identifier. SignalID is used in a + SignalsDescriptor + + Description + + SignalType: one of: + + OO (On/Off) + + TO (TimeOut) + + BR (Brief) + + NOTE - SignalType may be defined such that it is dependent on the + value of one or more parameters. The package MUST specify a default + signal type. If the default type is TO, the package MUST specify a + default duration which may be provisioned. A default duration is + meaningless for BR. + + + + Groves et al Expires - October 2003 [Page 89] + Megaco Protocol version 2 April 2003 + + + Duration: in hundredths of seconds + + Additional Parameters: see 12.2 + + 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. + + + 12.2 Guidelines to defining Parameters to Events and Signals + + Parameter Name: only descriptive + + ParameterID: is an identifier. The textual ParameterID of + parameters to Events and Signals shall not start with "EPA" and + "SPA", respectively. The textual ParameterID shall also not be + "ST", "Stream", "SY", "SignalType", "DR", "Duration", "NC", + "NotifyCompletion", "KA", "Keepactive", "EB", "Embed", "DM" or + "DigitMap". + + Type: One of: + + Boolean + + String: UTF-8 octet string + + Octet String: A number of octets. See Annex A and Annex B.3 + for encoding + + 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. + + + Groves et al Expires - October 2003 [Page 90] + Megaco Protocol version 2 April 2003 + + + 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). The type of sub-list SHALL also be specified. + The type shall be chosen from the types specified in this + section (with the exception of sub-list). For example, Type: + sub-list of enumeration. The encoding of sub-lists is + specified in Annexes A and B.3. + + Possible values: + + A package MUST specify either a specific set of values or a + description of how values are determined. A package MUST also + specify a default value or the default behavior when the value is + omitted from its descriptor. For example, a package may specify that + procedures related to the parameter are suspended when it value is + omitted. A default value (but not procedures) may be specified as + provisionable. + + Description: + + 12.3 Lists + + Possible values for parameters include enumerations. Enumerations may + be defined in a list. It is recommended that the list be IANA + registered so that packages that extend the list can be defined + without concern for conflicting names. + + 12.4 Identifiers + + Identifiers in text encoding shall be strings of up to 64 characters, + containing no spaces, starting with an alphabetic 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. + + 12.5 Package registration + + A package can be registered with IANA for interoperability reasons. + See clause 13 for IANA considerations. + + + + + + + + Groves et al Expires - October 2003 [Page 91] + Megaco Protocol version 2 April 2003 + + + 13 PROFILE DEFINITION + + Profiles may be specified to further define how the H.248.1 protocol + is used and what functionality is supported by a MG. The profile + itself specifies what options associated with H.248.1 have been used. + For example: transport and packages used for an application. + + A profile is identified by a name (IANA registered) and a Version. A + name shall be a string up to 64 characters long. Version shall be 1 + to 99. + + The profile itself is a document that indicates the options for a + particular application. There is no set format for this document. The + only mandatory element is that there SHOULD be a section indicating + the Name and Version and a summary of the profile. + + Whilst the first two points below are the only mandatory sections, + the following points SHOULD be considered for inclusion: + + - Profile Identification: The name and version of the profile that + is sent in the service change command. + + - Summary: A description of what the profile is. + + - Naming Conventions: + + - MGC/MG Naming Conventions: Addressing associated with the names + of the MGC / MG. + + - Termination Names: The termination identity structure. + + - Digit Map Names: The names of any digit maps. + + - Topology Descriptor: Is the topology descriptor used by this + profile? + + - TimeStamps: Specifies whether timestamps will be used in the + ServiceChange and/or Notify commands. + + - Transaction Timers: Specifies the values of the transaction + timers. + + - Transport: Specifies what H.248 sub-series transports are + supported by the profile. + + - Encoding: Specifies what encoding is supported by the profile. + + + + + + Groves et al Expires - October 2003 [Page 92] + Megaco Protocol version 2 April 2003 + + + - Mandatory support of SDP and H.248.1 Annex C information elements: + Specifies what SDP attributes and H.248.1 Annex C information + elements are to be supported. + + - Packages: Specifies the packages that are supported in this + profile. + + Mandatory: specifies the packages that shall be supported in this + profile. + + Optional: specifies the packages that may be supported in the + profile. + + Package Provisioning Information: specifies the values of properties + which are specified as provisioned (e.g. names and number of cycles + for an H.248.7 announcement). + + - Security: Specifies the security mechanisms used. + + - Procedures: Specifies the procedures that are associated with the + profile. + + + 14 IANA CONSIDERATIONS + + 14.1 Packages + + The following considerations SHALL be met to register a package with + IANA: + + 1) 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 0x8000 to 0xFFFF are reserved for private use. + Serial number 0 is reserved. + + 2) 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. + + 3) 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 + + + + Groves et al Expires - October 2003 [Page 93] + Megaco Protocol version 2 April 2003 + + + mechanism to provide comments and appropriate responses SHOULD be + returned. + + 4) Packages registered by other than recognized standards bodies + shall have a minimum package name length of 8 characters. + + 5) All other package names are first come-first served if all other + conditions are met. + + 14.2 Error codes + + The following considerations SHALL be met to register an error code + with IANA: + + 1) An error number and a one-line (80-character maximum) string is + registered for each error. + + 2) 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. + + 3) The document SHOULD be available on a public web server and SHOULD + have a stable URL. + + 4) Error numbers registered by recognized standards bodies shall have + 3- or 4-character error numbers. + + 5) Error numbers registered by all other organizations or individuals + shall have 4-character error numbers. + + 6) An error number shall not be redefined nor modified except by the + organization or individual that originally defined it, or their + successors or assigns. + + 14.3 ServiceChange reasons + + The following considerations SHALL be met to register service change + reason with IANA: + + 1) A one-phrase, 80-character maximum, unique reason code is + registered for each reason. + + 2) 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. + + + + + Groves et al Expires - October 2003 [Page 94] + Megaco Protocol version 2 April 2003 + + + 3) The document SHOULD be available on a public web server and SHOULD + have a stable URL. + + 14.4 Profiles + + The following considerations SHALL be met to register a Profile with + IANA: + + 1) A unique string name and version number (version may be omitted + when the profile name contains a wildcard) is registered for each + profile. + + 2) 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. + + 3) Profiles registered by other than recognized standards bodies + shall have a minimum profile name length of 6 characters. + + 4) Profile names containing a wildcard "*"on the end of their names + shall be accepted if the first 6 characters are fully specified. + It is assumed that the organisation that was issued with the + Profile name will manage the namespace associated with the + wildcard. IANA shall not issue other profiles names within "name*" + range. + + All other Profile names are first come-first served if all other + conditions are met. + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 95] + Megaco Protocol version 2 April 2003 + + + ANNEX A BINARY ENCODING OF THE PROTOCOL + + This annex specifies the syntax of messages using the notation + defined in Recommendation X.680; 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 Recommendation X.690, Information + Technology - ASN.1 Encoding Rules: Specification of Basic Encoding + Rules (BER), Canonical Encoding Rules (CER) and Distinguished + Encoding Rules. + + A.1 Coding of wildcards + + The use of wildcards ALL and CHOOSE is allowed in the protocol. This + allows a MGC to partially specify Termination IDs and to let the MG + choose from the values that conform to the partial specification. + Termination IDs may encode a hierarchy of names. This 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 wildcarding 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: + + + + Groves et al Expires - October 2003 [Page 96] + Megaco Protocol version 2 April 2003 + + + 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 it 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 subclause contains the ASN.1 specification of the H.248.1 + protocol syntax. + + NOTE 1 - In case a transport mechanism is used that employs + application level framing, the definition of Transaction below + changes. Refer to the annex or to the Recommendation of the H.248 + + + + Groves et al Expires - October 2003 [Page 97] + Megaco Protocol version 2 April 2003 + + + sub-series defining the transport mechanism for the definition that + applies in that case. + + NOTE 2 - 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. + + NOTE 3 - This syntax specification does not enforce all restrictions + on element inclusions and values. Some additional restrictions are + stated in comments and other restrictions appear in the text of this + recommendation. These additional restrictions are part of the + protocol even though not enforced by this specification. + + NOTE 4 - The ASN.1 module in this Annex uses octet string types to + encode values for property parameter, signal parameter and event + parameter values and statistics. The actual types of these values + vary and are specified in Annex C or the relevant package definition. + + A value is first BER-encoded based on its type using the table below. + The result of this BER-encoding is then encoded as an ASN.1 octet + string, "double wrapping" the value. The format specified in Annex C + or the package relates to BER encoding according to the following + table: + + Type Specified in Package ASN.1 BER Type + + String IA5String or UTF8String + (Note 4) + + Integer (4 Octet) INTEGER + + Double (8 octet signed int) INTEGER (Note 3) + + Character (UTF-8, Note 1) IA5String + + Enumeration ENUMERATED + + Boolean BOOLEAN + + Unsigned Integer (Note 2) INTEGER (Note 3) + + Octet (String) OCTET STRING + + Note 1: Can be more than one byte + + Note 2: Unsigned integer is referenced in Annex C + + + + Groves et al Expires - October 2003 [Page 98] + Megaco Protocol version 2 April 2003 + + + Note 3: The BER encoding of INTEGER does not imply the + use of 4 bytes. + + Note 4: String SHOULD be encoded as IA5String when the + contents are all ASCII characters, but as UTF8String + if it contains any non-ASCII characters. + + + + See ITU-T Rec. X.690, 8.7, for the definition of the encoding of an + octet string value. + + + MEDIA-GATEWAY-CONTROL {itu-t(0) recommendation(0) h(8) h248(248) + modules(0) media-gateway-control(0) version2(2)} + 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 2. + mId MId, -- Name/address of message originator + messageBody CHOICE + { + messageError ErrorDescriptor, + transactions SEQUENCE OF Transaction + }, + + + + Groves et al Expires - October 2003 [Page 99] + Megaco Protocol version 2 April 2003 + + + ... + } + + MId ::= CHOICE + { + ip4Address IP4Address, + ip6Address IP6Address, + domainName DomainName, + deviceName PathName, + mtpAddress OCTET STRING(SIZE(2..4)), + -- Addressing structure of mtpAddress: + -- 25 - 15 0 + -- | PC | NI | + -- 24 - 14 bits 2 bits + -- Note: 14 bits are defined for international use. + -- Two national options exist where the point code is 16 or 24 + -- bits. + -- To octet align the mtpAddress, the MSBs shall be encoded as 0s. + ... + } + + 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 + } + + IP4Address ::= SEQUENCE + { + 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 A.3 + + Transaction ::= CHOICE + { + transactionRequest TransactionRequest, + transactionPending TransactionPending, + + + Groves et al Expires - October 2003 [Page 100] + Megaco Protocol version 2 April 2003 + + + 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 OF TransactionAck + TransactionAck ::= SEQUENCE + { + firstAck TransactionId, + lastAck TransactionId OPTIONAL + } + + ErrorDescriptor ::= SEQUENCE + { + errorCode ErrorCode, + errorText ErrorText OPTIONAL + } + + ErrorCode ::= INTEGER(0..65535) + -- See clause 14 for IANA considerations with respect to error codes + + + + Groves et al Expires - October 2003 [Page 101] + Megaco Protocol version 2 April 2003 + + + ErrorText ::= IA5String + + ContextID ::= INTEGER(0..4294967295) + + -- Context NULL Value: 0 + -- Context CHOOSE Value: 4294967294 (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, + ... + } + + + + Groves et al Expires - October 2003 [Page 102] + Megaco Protocol version 2 April 2003 + + + 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) + }, + ..., + streamID StreamID OPTIONAL + } + + AmmRequest ::= SEQUENCE + { + terminationID TerminationIDList, + descriptors SEQUENCE OF AmmDescriptor, + -- At most one descriptor of each type (see AmmDescriptor) + -- allowed in the sequence. + ... + + + Groves et al Expires - October 2003 [Page 103] + Megaco Protocol version 2 April 2003 + + + } + + 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 ::= CHOICE + { + contextAuditResult TerminationIDList, + error ErrorDescriptor, + auditResult AuditResult, + ... + } + + AuditResult ::= SEQUENCE + { + + terminationID TerminationID, + + + Groves et al Expires - October 2003 [Page 104] + Megaco Protocol version 2 April 2003 + + + 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, + ..., + auditPropertyToken SEQUENCE OF IndAuditParameter OPTIONAL + } + + IndAuditParameter ::= CHOICE + { + indaudmediaDescriptor IndAudMediaDescriptor, + indaudeventsDescriptor IndAudEventsDescriptor, + indaudeventBufferDescriptor IndAudEventBufferDescriptor, + indaudsignalsDescriptor IndAudSignalsDescriptor, + indauddigitMapDescriptor IndAudDigitMapDescriptor, + indaudstatisticsDescriptor IndAudStatisticsDescriptor, + indaudpackagesDescriptor IndAudPackagesDescriptor, + ... + } + + + Groves et al Expires - October 2003 [Page 105] + Megaco Protocol version 2 April 2003 + + + + IndAudMediaDescriptor ::= SEQUENCE + { + + termStateDescr IndAudTerminationStateDescriptor OPTIONAL, + streams CHOICE + { + oneStream IndAudStreamParms, + multiStream SEQUENCE OF IndAudStreamDescriptor + } OPTIONAL, + ... + } + + IndAudStreamDescriptor ::= SEQUENCE + { + streamID StreamID, + streamParms IndAudStreamParms + } + + IndAudStreamParms ::= SEQUENCE + { + localControlDescriptor IndAudLocalControlDescriptor OPTIONAL, + localDescriptor IndAudLocalRemoteDescriptor OPTIONAL, + remoteDescriptor IndAudLocalRemoteDescriptor OPTIONAL, + ... + } + + IndAudLocalControlDescriptor ::= SEQUENCE + { + streamMode NULL OPTIONAL, + reserveValue NULL OPTIONAL, + reserveGroup NULL OPTIONAL, + propertyParms SEQUENCE OF IndAudPropertyParm OPTIONAL, + ... + } + + IndAudPropertyParm ::= SEQUENCE + { + name PkgdName, + ... + } + + IndAudLocalRemoteDescriptor ::= SEQUENCE + { + propGroupID INTEGER(0..65535) OPTIONAL, + propGrps IndAudPropertyGroup, + ... + } + + + + Groves et al Expires - October 2003 [Page 106] + Megaco Protocol version 2 April 2003 + + + IndAudPropertyGroup ::= SEQUENCE OF IndAudPropertyParm + + IndAudTerminationStateDescriptor ::= SEQUENCE + { + propertyParms SEQUENCE OF IndAudPropertyParm, + eventBufferControl NULL OPTIONAL, + serviceState NULL OPTIONAL, + ... + } + + IndAudEventsDescriptor ::= SEQUENCE + { + requestID RequestID OPTIONAL, + pkgdName PkgdName, + streamID StreamID OPTIONAL, + ... + } + + IndAudEventBufferDescriptor ::= SEQUENCE + { + eventName PkgdName, + streamID StreamID OPTIONAL, + ... + } + + IndAudSignalsDescriptor ::=CHOICE + { + signal IndAudSignal, + seqSigList IndAudSeqSigList, + ... + } + + IndAudSeqSigList ::= SEQUENCE + { + id INTEGER(0..65535), + signalList IndAudSignal OPTIONAL + } + + IndAudSignal ::= SEQUENCE + { + signalName PkgdName, + streamID StreamID OPTIONAL, + ... + } + + IndAudDigitMapDescriptor ::= SEQUENCE + { + digitMapName DigitMapNameOPTIONAL + } + + + Groves et al Expires - October 2003 [Page 107] + Megaco Protocol version 2 April 2003 + + + + IndAudStatisticsDescriptor ::= SEQUENCE + { + statName PkgdName + } + + IndAudPackagesDescriptor ::= SEQUENCE + { + packageName Name, + packageVersion INTEGER(0..99), + ... + } + + NotifyRequest ::= SEQUENCE + { + terminationID TerminationIDList, + observedEventsDescriptor ObservedEventsDescriptor, + errorDescriptor ErrorDescriptor OPTIONAL, + ... + } + + NotifyReply ::= SEQUENCE + { + terminationID TerminationIDList, + 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, + + + Groves et al Expires - October 2003 [Page 108] + Megaco Protocol version 2 April 2003 + + + -- For use of extraInfo see the comment related to PropertyParm + extraInfo CHOICE + { + relation Relation, + range BOOLEAN, + sublist BOOLEAN + } OPTIONAL, + ... + + } + + 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 A.1 for explanation of wildcarding mechanism. + -- Termination ID 0xFFFFFFFFFFFFFFFF indicates the ROOT Termination. + + TerminationIDList ::= SEQUENCE OF TerminationID + + + + + + Groves et al Expires - October 2003 [Page 109] + Megaco Protocol version 2 April 2003 + + + MediaDescriptor ::= SEQUENCE + { + termStateDescr TerminationStateDescriptor OPTIONAL, + streams CHOICE + { + oneStream StreamParms, + multiStream SEQUENCE OF StreamDescriptor + } OPTIONAL, + ... + } + + StreamDescriptor ::= SEQUENCE + { + streamID StreamID, + streamParms StreamParms + } + + StreamParms ::= SEQUENCE + { + localControlDescriptor LocalControlDescriptor OPTIONAL, + localDescriptor LocalRemoteDescriptor OPTIONAL, + remoteDescriptor LocalRemoteDescriptor OPTIONAL, + ... + } + + LocalControlDescriptor ::= SEQUENCE + { + streamMode StreamMode OPTIONAL, + reserveValue BOOLEAN OPTIONAL, + reserveGroup BOOLEAN OPTIONAL, + 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 + + + Groves et al Expires - October 2003 [Page 110] + Megaco Protocol version 2 April 2003 + + + -- "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, Event, + -- Signal Names or Statistics ID. (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. + -- To wildcard a Property, Event, Signal, or Statistics ID, use + -- 0xFFFF for last two octets, choose is not allowed. + -- Wildcarding of Package Name is permitted only if Property, + -- Event, Signal, or Statistics ID are + -- also wildcarded. + + Relation ::= ENUMERATED + { + greaterThan(0), + smallerThan(1), + unequalTo(2), + + + Groves et al Expires - October 2003 [Page 111] + Megaco Protocol version 2 April 2003 + + + ... + } + + 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), + ..., + + + Groves et al Expires - October 2003 [Page 112] + Megaco Protocol version 2 April 2003 + + + nx64k(4) + } + + StreamID ::= INTEGER(0..65535) -- 16-bit unsigned integer + + EventsDescriptor ::= SEQUENCE + { + requestID RequestID OPTIONAL, + -- RequestID must be present if eventList + -- is non empty + eventList SEQUENCE OF RequestedEvent, + ... + } + + RequestedEvent ::= SEQUENCE + { + pkgdName PkgdName, + streamID StreamID OPTIONAL, + eventAction RequestedActions OPTIONAL, + evParList SEQUENCE OF EventParameter, + ... + } + + RequestedActions ::= SEQUENCE + { + keepActive BOOLEAN OPTIONAL, + eventDM EventDM OPTIONAL, + secondEvent SecondEventsDescriptor OPTIONAL, + signalsDescriptor SignalsDescriptor OPTIONAL, + ... + } + + EventDM ::= CHOICE + { + digitMapName DigitMapName, + digitMapValue DigitMapValue + } + + SecondEventsDescriptor ::= SEQUENCE + { + requestID RequestID OPTIONAL, + eventList SEQUENCE OF SecondRequestedEvent, + ... + } + + SecondRequestedEvent ::= SEQUENCE + { + pkgdName PkgdName, + streamID StreamID OPTIONAL, + + + Groves et al Expires - October 2003 [Page 113] + Megaco Protocol version 2 April 2003 + + + eventAction SecondRequestedActions OPTIONAL, + evParList SEQUENCE OF EventParameter, + ... + } + + SecondRequestedActions ::= SEQUENCE + { + keepActive BOOLEAN OPTIONAL, + 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, + ... + + + Groves et al Expires - October 2003 [Page 114] + Megaco Protocol version 2 April 2003 + + + } + + 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, + -- For use of extraInfo see the comment related to PropertyParm + extraInfo CHOICE + { + relation Relation, + range BOOLEAN, + sublist BOOLEAN + } OPTIONAL, + ... + } + + -- For an AuditCapReply with all events, the RequestID SHALL be ALL. + -- ALL is represented by 0xffffffff. + + 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), + + + Groves et al Expires - October 2003 [Page 115] + Megaco Protocol version 2 April 2003 + + + 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, + -- Units are seconds for start, short and long timers, and + -- hundreds of milliseconds for duration timer. Thus start, + -- short, and long range from 1 to 99 seconds and duration + -- from 100 ms to 9.9 s + -- See A.3 for explanation of digit map syntax + ..., + durationTimer INTEGER (0..99) OPTIONAL + } + + ServiceChangeParm ::= SEQUENCE + { + serviceChangeMethod ServiceChangeMethod, + serviceChangeAddress ServiceChangeAddress OPTIONAL, + serviceChangeVersion INTEGER(0..99) OPTIONAL, + serviceChangeProfile ServiceChangeProfile OPTIONAL, + serviceChangeReason Value, + -- A serviceChangeReason consists of a numeric reason code + -- and an optional text description. + -- The serviceChangeReason SHALL be a string consisting of + -- a decimal reason code, optionally followed by a single + -- space character and a textual description string. + -- This string is first BER-encoded as an IA5String. + -- The result of this BER-encoding is then encoded as + -- an ASN.1 OCTET STRING type, "double wrapping" the + -- value + -- as was done for package elements. + + + Groves et al Expires - October 2003 [Page 116] + Megaco Protocol version 2 April 2003 + + + serviceChangeDelay INTEGER(0..4294967295) OPTIONAL, + -- 32-bit unsigned integer + serviceChangeMgcId MId OPTIONAL, + timeStamp TimeNotation OPTIONAL, + nonStandardData NonStandardData OPTIONAL, + ..., + serviceChangeInfo AuditDescriptor OPTIONAL + } + + ServiceChangeAddress ::= CHOICE + { + portNumber INTEGER(0..65535), -- TCP/UDP port number + ip4Address IP4Address, + ip6Address IP6Address, + domainName DomainName, + deviceName PathName, + mtpAddress OCTET STRING(SIZE(2..4)), + ... + } + + ServiceChangeResParm ::= SEQUENCE + { + serviceChangeMgcId MId OPTIONAL, + serviceChangeAddress ServiceChangeAddress OPTIONAL, + serviceChangeVersion INTEGER(0..99) OPTIONAL, + serviceChangeProfile ServiceChangeProfile OPTIONAL, + timestamp TimeNotation OPTIONAL, + ... + } + + ServiceChangeMethod ::= ENUMERATED + { + failover(0), + forced(1), + graceful(2), + restart(3), + disconnected(4), + handOff(5), + ... + } + + ServiceChangeProfile ::= SEQUENCE + { + profileName IA5String(SIZE (1..67)) + + -- 64 characters for name, 1 for "/", 2 for version to match ABNF + } + + PackagesDescriptor ::= SEQUENCE OF PackagesItem + + + Groves et al Expires - October 2003 [Page 117] + Megaco Protocol version 2 April 2003 + + + + PackagesItem ::= SEQUENCE + { + packageName Name, + packageVersion INTEGER(0..99), + ... + } + + StatisticsDescriptor ::= SEQUENCE OF StatisticsParameter + + StatisticsParameter ::= SEQUENCE + { + statName PkgdName, + statValue Value OPTIONAL + } + + 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 + -- per ISO 8601:1988 + } + + Value ::= SEQUENCE OF OCTET STRING + + + + + Groves et al Expires - October 2003 [Page 118] + Megaco Protocol version 2 April 2003 + + + END + + + + + A.3 Digit maps and path names + + From a syntactic viewpoint, digit maps are strings with syntactic + restrictions imposed upon them. The syntax of valid digit maps is + specified in ABNF [RFC 2234]. The syntax for digit maps presented in + this subclause is for illustrative purposes only. The definition of + digitMap in Annex B takes precedence in the case of differences + between the two. + + 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" / "T" ;Inter-event timers + ;(long, short, start) + / "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 / "+" / "-" / "&" / "!" / "_" / "/" / + "'" / "?" / "@" / "^" / "`" / "~" / "*" / "$" / "\" / + "(" / ")" / "%" / "." + + + + Groves et al Expires - October 2003 [Page 119] + Megaco Protocol version 2 April 2003 + + + RestChar = ";" / "[" / "]" / "{" / "}" / ":" / "," / "#" / + "<" / ">" / "=" / %x22 + + DIGIT = %x30-39 ; digits 0 through 9 + ALPHA = %x41-5A / %x61-7A ; A-Z, a-z + + A path name is also a string with syntactic restrictions imposed upon + it. The ABNF production defining it is copied from Annex B. + + ; 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 / "-" / "*" / ".") + + NAME = ALPHA *63(ALPHA / DIGIT / "_" ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 120] + Megaco Protocol version 2 April 2003 + + + ANNEX B TEXT ENCODING OF THE PROTOCOL + + B.1 Coding of wildcards + + In a text encoding of the protocol, while TerminationIDs are + arbitrary, by judicious choice of names, the wildcard character, "*" + may be made more useful. When the wildcard character is encountered, + it will "match" all TerminationIDs having the same previous and + following characters (if appropriate). For example, if there were + TerminationIDs of R13/3/1, R13/3/2 and R13/3/3, the TerminationID + R13/3/* would match all of them. There are some circumstances where + ALL Terminations must be referred to. The TerminationID "*" suffices, + and is referred to as ALL. The CHOOSE TerminationID "$" may be used + to 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 presented in ABNF according to RFC 2234. + + Note 1 - This syntax specification does not enforce all restrictions + on element inclusions and values. Some additional restrictions are + stated in comments and other restrictions appear in the text of this + recommendation. These additional restrictions are part of the + protocol even though not enforced by this specification. + + Note 2 - The syntax is context-dependent. For example, "Add" can be + the AddToken or a NAME depending on the context in which it occurs. + + Everything in the ABNF and text encoding is case insensitive. This + includes TerminationIDs, digitmap Ids etc. SDP is case sensitive as + per RFC 2327. + + ; NOTE -- The ABNF in this section uses the VALUE construct (or lists + ; of VALUE constructs) to encode various package element values + ; (properties, signal parameters, etc.). The types of these values + ; vary and are specified the relevant package definition. Several + ; such types are described in section 12.2. + ; + ; The ABNF specification for VALUE allows a quotedString form or a + ; collection of SafeChars. The encoding of package element values + ; into ABNF VALUES is specified below. If a type's encoding allows + ; characters other than SafeChars, the quotedString form MUST be used + ; for all values of that type, even for specific values that consist + ; only of SafeChars. + ; + ; String: A string MUST use the quotedString form of VALUE and can + ; contain anything allowable in the quotedString form. + ; + + + Groves et al Expires - October 2003 [Page 121] + Megaco Protocol version 2 April 2003 + + + ; Integer, Double, and Unsigned Integer: Decimal values can be + ; encoded using characters 0-9. Hexadecimal values must be prefixed + ; with '0x' and can use characters 0-9,a-f,A-F. An octal format is + ; not supported. Negative integers start with '-' and MUST be + ; Decimal. The SafeChar form of VALUE MUST be used. + ; + ; Character: A UTF-8 encoding of a single letter surrounded by + ; double quotes. + ; + ; Enumeration: An enumeration MUST use the SafeChar form of VALUE + ; and can contain anything allowable in the SafeChar form. + ; + ; Boolean: Boolean values are encoded as "on" and "off" and are + ; case insensitive. The SafeChar form of VALUE MUST be used. + ; + ; Future types: Any defined types MUST fit within + ; the ABNF specification of VALUE. Specifically, if a type's + ; encoding allows characters other than SafeChars, the quotedString + ; form MUST be used for all values of that type, even for specific + ; values that consist only of SafeChars. + ; + ; Note that there is no way to use the double quote character within + ; a value. + ; + ; Note that SDP disallows whitespace at the beginning of a line, + ; Megaco ABNF allows whitespace before the beginning of the SDP in + ; the Local/Remote descriptor. Parsers SHOULD accept whitespace + ; between the LBRKT following the Local/Remote token and the + ; beginning of the SDP. + + 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 2. + + messageBody = ( errorDescriptor / transactionList ) + + transactionList = 1*( transactionRequest / transactionReply / + transactionPending / transactionResponseAck ) + ; Use of response acks is dependent on underlying transport + + + + + Groves et al Expires - October 2003 [Page 122] + Megaco Protocol version 2 April 2003 + + + 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) + + 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 ) + + ; "O-" indicates an optional command + ; "W-" indicates a wildcarded response to a command + commandRequestList= ["O-"] ["W-"] commandRequest * + (COMMA ["O-"] ["W-"]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 ) / + (commandReply COMMA errorDescriptor) ) RBRKT + + commandReply = (( contextProperties [COMMA commandReplyList] ) / + commandReplyList ) + + + Groves et al Expires - October 2003 [Page 123] + Megaco Protocol version 2 April 2003 + + + + + 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 = SubtractToken EQUAL TerminationID + [ LBRKT auditDescriptor RBRKT] + + auditRequest = (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 + + + Groves et al Expires - October 2003 [Page 124] + Megaco Protocol version 2 April 2003 + + + [ 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 + + ;The values 0x0, 0xFFFFFFFE and 0xFFFFFFFF are reserved. + ContextID = (UINT32 / "*" / "-" / "$") + + TerminationID = "ROOT" / pathNAME / "$" / "*" + + terminationIDList = LBRKT TerminationID *(COMMA TerminationID) RBRKT + + + 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 + + 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".."255" + + ; this production, while occurring in RFC2373, is not referenced + ; IPv6prefix = hexpart SLASH 1*2DIGIT + hexpart = hexseq "::" [ hexseq ] / "::" [ hexseq ] / hexseq + + + Groves et al Expires - October 2003 [Page 125] + Megaco Protocol version 2 April 2003 + + + hexseq = hex4 *( ":" hex4) + hex4 = 1*4HEXDIG + + portNumber = UINT16 + + ; Addressing structure of mtpAddress: + ; 25 - 15 0 + ; | PC | NI | + ; 24 - 14 bits 2 bits + ; Note: 14 bits are defined for international use. + ; Two national options exist where the point code is 16 or 24 bits. + ; To octet align the mtpAddress the MSBs shall be encoded as 0s. + ; An octet shall be represented by 2 hex digits. + mtpAddress = MTPToken LBRKT 4*8 (HEXDIG) 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 / "-" / "*" / ".") + + + mediaDescriptor = MediaToken LBRKT mediaParm *(COMMA mediaParm) RBRKT + + ; at-most one terminationStateDescriptor + ; and either streamParm(s) or streamDescriptor(s) but not both + mediaParm = (streamParm / streamDescriptor / + terminationStateDescriptor) + + ; at-most-once per item + 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 except for propertyParm + localParm = ( streamMode / propertyParm / reservedValueMode + / reservedGroupMode ) + + reservedValueMode = ReservedValueToken EQUAL ( "ON" / "OFF" ) + reservedGroupMode = ReservedGroupToken EQUAL ( "ON" / "OFF" ) + + + + Groves et al Expires - October 2003 [Page 126] + Megaco Protocol version 2 April 2003 + + + 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 + + ; Note - The octet zero is not among the permitted characters in + ; octet string. As the current definition is limited to SDP, and a + ; zero octet would not be a legal character in SDP, this is not a + ; concern. + 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 except for propertyParm + terminationStateParm =(propertyParm / serviceStates / + eventBufferControl ) + + serviceStates = ServiceStatesToken EQUAL ( TestToken / + OutOfSvcToken / InSvcToken ) + + muxDescriptor = MuxToken EQUAL MuxType terminationIDList + + + + Groves et al Expires - October 2003 [Page 127] + Megaco Protocol version 2 April 2003 + + + MuxType = ( H221Token / H223Token / H226Token / V76Token + / extensionParameter / Nx64kToken ) + + StreamID = UINT16 + + pkgdName = (PackageName SLASH ItemID) ;specific item + / (PackageName SLASH "*") ;all items in package + / ("*" SLASH "*") ; all items 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 + + + + Groves et al Expires - October 2003 [Page 128] + Megaco Protocol version 2 April 2003 + + + 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) RBRKT) + + notificationReason = ( TimeOutToken / InterruptByEventToken + / InterruptByNewSignalsDescrToken + / OtherReasonToken ) + + observedEventsDescriptor = ObservedEventsToken EQUAL RequestID + LBRKT observedEvent *(COMMA observedEvent) RBRKT + + + + Groves et al Expires - October 2003 [Page 129] + Megaco Protocol version 2 April 2003 + + + ;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 + + ; For an AuditCapReply with all events, the RequestID SHOULD be ALL. + RequestID = ( UINT32 / "*" ) + + modemDescriptor = ModemToken (( EQUAL modemType) / + (LSBRKT modemType *(COMMA modemType) RSBRKT)) + [ LBRKT propertyParm + *(COMMA propertyParm) RBRKT ] + + ; at-most-once except for extensionParameter + modemType = (V32bisToken / V22bisToken / V18Token / + V22Token / V32Token / V34Token / V90Token / + V91Token / SynchISDNToken / extensionParameter) + + 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] ["Z" COLON Timer COMMA] + digitMap + + Timer = 1*2DIGIT + ; Units are seconds for T, S, and L timers, and hundreds of + ; milliseconds for Z timer. Thus T, S, and L range from 1 to 99 + ; seconds and Z from 100 ms to 9.9 s + + 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) + + + Groves et al Expires - October 2003 [Page 130] + Megaco Protocol version 2 April 2003 + + + + digitMapLetter = DIGIT ;Basic event symbols + / %x41-4B / %x61-6B ; a-k, A-K + / "L" / "S" / "T" ;Inter-event timers + ; (long, short, start) + / "Z" ;Long duration modifier + + ; at-most-once, and DigitMapToken and PackagesToken are not allowed + ; in AuditCapabilities command + auditItem = ( MuxToken / ModemToken / MediaToken / + SignalsToken / EventBufferToken / + DigitMapToken / StatsToken / EventsToken / + ObservedEventsToken / PackagesToken ) / + indAudterminationAudit) + + indAudterminationAudit = indAudauditReturnParameter + *(COMMA indAudauditReturnParameter) + + indAudauditReturnParameter = (indAudmediaDescriptor / / + indAudeventsDescriptor / + indAudsignalsDescriptor / + indAuddigitMapDescriptor / + indAudeventBufferDescriptor / + indAudstatisticsDescriptor / + indAudpackagesDescriptor) + + + indAudmediaDescriptor = MediaToken LBRKT indAudmediaParm RBRKT + + ; at-most-once per item + ; and either streamParm or streamDescriptor but not both + indAudmediaParm = (indAudstreamParm / indAudstreamDescriptor / + indAudterminationStateDescriptor) + + ; at-most-once + indAudstreamParm = ( indAudlocalControlDescriptor ) + ; SDP too complex to pull out individual pieces for audit, + ; hence no individual audit for Local and Remote + + indAudstreamDescriptor = StreamToken EQUAL StreamID + LBRKT indAudstreamParm RBRKT + + indAudlocalControlDescriptor = LocalControlToken + LBRKT indAudlocalParm RBRKT + + ; at-most-once per item + indAudlocalParm = ( ModeToken / pkgdName / + ReservedValueToken / + ReservedGroupToken ) + + + Groves et al Expires - October 2003 [Page 131] + Megaco Protocol version 2 April 2003 + + + + + indAudterminationStateDescriptor = TerminationStateToken + LBRKT indAudterminationStateParm RBRKT + + ; at-most-once per item + indAudterminationStateParm =(pkgdName / ServiceStatesToken / + BufferToken) + + indAudeventBufferDescriptor= EventBufferToken + LBRKT indAudeventSpec RBRKT + + indAudeventSpec = pkgdName [ LBRKT indAudeventSpecParameter RBRKT ] + + indAudeventSpecParameter = (eventStream / eventParameterName) + + indAudeventsDescriptor = EventsToken EQUAL RequestID + LBRKT indAudrequestedEvent RBRKT + + indAudrequestedEvent = pkgdName + + indAudsignalsDescriptor = SignalsToken + LBRKT [ indAudsignalParm ] RBRKT + + indAudsignalParm = indAudsignalList / indAudsignalRequest + indAudsignalRequest = signalName + + indAudsignalList = SignalListToken EQUAL signalListId + LBRKTindAudsignalListParm RBRKT + + indAudsignalListParm = indAudsignalRequest + + indAuddigitMapDescriptor = DigitMapToken EQUAL (digitMapName ) + + indAudstatisticsDescriptor = StatsToken LBRKT pkgdName RBRKT + + indAudpackagesDescriptor = PackagesToken LBRKT packagesItem RBRKT + + + serviceChangeDescriptor = ServicesToken LBRKT serviceChangeParm + *(COMMA serviceChangeParm) RBRKT + + ; each parameter at-most-once + ; at most one of either serviceChangeAddress or serviceChangeMgcId + ; but not both + ; serviceChangeMethod and serviceChangeReason are REQUIRED + serviceChangeParm = (serviceChangeMethod / serviceChangeReason / + serviceChangeDelay / serviceChangeAddress / + serviceChangeProfile / extension / TimeStamp / + + + Groves et al Expires - October 2003 [Page 132] + Megaco Protocol version 2 April 2003 + + + serviceChangeMgcId / serviceChangeVersion / + auditItem) + + serviceChangeReplyDescriptor = ServicesToken LBRKT + servChgReplyParm *(COMMA servChgReplyParm) RBRKT + + ; at-most-once. Version is REQUIRED on first ServiceChange response + ; at most one of either serviceChangeAddress or serviceChangeMgcId + ; but not both + servChgReplyParm = (serviceChangeAddress / serviceChangeMgcId / + serviceChangeProfile / serviceChangeVersion / + TimeStamp) + + serviceChangeMethod = MethodToken EQUAL (FailoverToken / + ForcedToken / GracefulToken / RestartToken / + DisconnectedToken / HandOffToken / + extensionParameter) + + ; A serviceChangeReason consists of a numeric reason code + ; and an optional text description. + ; A serviceChangeReason MUST be encoded using the quotedString + ; form of VALUE. + ; The quotedString SHALL contain a decimal reason code, + ; optionally followed by a single space character and a + ; textual description string. + serviceChangeReason = ReasonToken EQUAL VALUE + + serviceChangeDelay = DelayToken EQUAL UINT32 + + serviceChangeAddress = ServiceChangeAddressToken EQUAL ( mId / + portNumber ) + + serviceChangeMgcId = MgcIdToken EQUAL mId + + serviceChangeProfile = ProfileToken EQUAL NAME SLASH Version + + serviceChangeVersion = VersionToken EQUAL Version + + extension = extensionParameter parmValue + + packagesDescriptor = PackagesToken LBRKT packagesItem + *(COMMA packagesItem) RBRKT + + Version = 1*2(DIGIT) + + packagesItem = NAME "-" UINT16 + + TimeStamp = Date "T" Time ; per ISO 8601:1988 + ; Date = yyyymmdd + + + Groves et al Expires - October 2003 [Page 133] + Megaco Protocol version 2 April 2003 + + + 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 topologyTriple + *(COMMA topologyTriple) RBRKT + + topologyTriple = terminationA COMMA + terminationB COMMA topologyDirection + [COMMA eventStream ] + terminationA = TerminationID + terminationB = TerminationID + + topologyDirection = BothwayToken / IsolateToken / OnewayToken + + priority = PriorityToken EQUAL UINT16 + + extensionParameter = "X" ("-" / "+") 1*6(ALPHA / DIGIT) + + ; 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 ) + + ; Note - The double-quote character is not allowed in quotedString. + quotedString = DQUOTE *(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 / "+" / "-" / "&" / + "!" / "_" / "/" / "'" / "?" / "@" / + "^" / "`" / "~" / "*" / "$" / "\" / + "(" / ")" / "%" / "|" / "." + + EQUAL = LWSP %x3D LWSP ; "=" + COLON = %x3A ; ":" + LBRKT = LWSP %x7B LWSP ; "{" + + + Groves et al Expires - October 2003 [Page 134] + Megaco Protocol version 2 April 2003 + + + 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 = ";" / "[" / "]" / "{" / "}" / ":" / "," / "#" / + "<" / ">" / "=" + + ; New Tokens added to sigParameter must take the format of SPA* + ; * may be of any form i.e. SPAM + ; New Tokens added to eventParameter must take the form of EPA* + ; * may be of any form i.e. EPAD + + 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" / "EM") + EmergencyToken = ("Emergency" / "EG") + ErrorToken = ("Error" / "ER") + EventBufferToken = ("EventBuffer" / "EB") + EventsToken = ("Events" / "E") + FailoverToken = ("Failover" / "FL") + ForcedToken = ("Forced" / "FO") + GracefulToken = ("Graceful" / "GR") + H221Token = ("H221" ) + H223Token = ("H223" ) + + + Groves et al Expires - October 2003 [Page 135] + Megaco Protocol version 2 April 2003 + + + 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") + Nx64kToken = ("Nx64Kservice" / "N64") + 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") + + + Groves et al Expires - October 2003 [Page 136] + Megaco Protocol version 2 April 2003 + + + 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") + + + B.3 Hexadecimal octet coding + + Hexadecimal octet coding is a means for representing a string of + octets as a string of hexadecimal digits, with two digits + representing each octet. This octet encoding SHOULD be used when + encoding octet strings in the text version of the protocol. + + For each octet, the 8-bit sequence is encoded as two hexadecimal + digits. Bit 0 is the first transmitted; bit 7 is the last. + + Bits 7-4 are encoded as the first hexadecimal digit, with Bit 7 as + MSB and Bit 4 as LSB. Bits 3-0 are encoded as the second hexadecimal + digit, with Bit 3 as MSB and Bit 0 as LSB. + + Examples: + + Octet bit pattern Hexadecimal + coding + + 00011011 D8 + + 11100100 27 + + + + + Groves et al Expires - October 2003 [Page 137] + Megaco Protocol version 2 April 2003 + + + 10000011 10100010 11001000 C1451390 + 00001001 + + + + B.4 Hexadecimal octet sequence + + A hexadecimal octet sequence is an even number of hexadecimal digits, + terminated by a character. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 138] + Megaco Protocol version 2 April 2003 + + + ANNEX C TAGS FOR MEDIA STREAM PROPERTIES + + Parameters for Local, Remote and LocalControl descriptors are + specified as tag-value pairs if binary encoding is used for the + protocol. This annex contains the property names (PropertyID), the + tags (Property tag), type of the property (Type) and the values + (Value). Values presented in the Value field when the field contains + references shall be regarded as "information". The reference contains + the normative values. If a value field does not contain a reference, + then the values in that field can be considered as "normative". + + Tags are given as hexadecimal numbers in this annex. When setting the + value of a property, a MGC may underspecify the value according to + one of the mechanisms specified in 7.1.1. + + It is optional to support the properties in this Annex or any of its + sub-sections. For example, only three properties from C.3 and only + five properties from C.8 might be implemented. + + For type "enumeration" the value is represented by the value in + brackets, e.g. Send(0), Receive(1). Annex C properties with the types + "N bits" or "M Octets" SHOULD be treated as octet strings when + encoding the protocol. Properties with "N bit integer" shall be + treated as an integers. "String" shall be treated as an IA5String + when encoding the protocol. + + 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 + + + PropertyID Property Type Value + tag + + Media 1001 Enumeration Audio(0), Video(1), Data(2) + + Transmission 1002 Enumeration Send(0), Receive(1), + mode Send&Receive(2) + + Number of 1003 Unsigned 0-255 + Channels integer + + Sampling 1004 Unsigned 0-2^32 + rate integer + + + + + Groves et al Expires - October 2003 [Page 139] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + Bitrate 1005 Integer (0..4294967295) + + NOTE - Units of 100 bit/s. + + ACodec 1006 Octet string Audio Codec Type: + + Ref.: ITU-T Q.765.5 + + Non-ITU-T codecs are defined + with the appropriate + standards organization 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 string Ref.: ITU-T H.245 + + Encryptkey 100A Octet string Encryption key + size + (0..65535) Ref.: ITU-T H.235 + + Echocanc 100B Not Used. See H.248.1 E.13 + for an example of possible + Echo Control properties. + + 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: 0..65535 + integer + Maximum propagation delay in + milliseconds for the bearer + connection between two media + gateways. The maximum delay + will be dependent on the + bearer technology. + + + + Groves et al Expires - October 2003 [Page 140] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + RTPpayload 100F Integer Payload type in RTP Profile + for Audio and Video + Conferences with Minimal + Control + + Ref.: RFC 1890 + + + + + C.2 Mux properties + + + PropertyID Property Type Value + tag + + H222 2001 Octet H222LogicalChannelParameters + string + Ref.: ITU-T H.245 + + H223 2002 Octet H223LogicalChannelParameters + string + Ref.: ITU-T H.245 + + V76 2003 Octet V76LogicalChannelParameters + string + Ref.: ITU-T H.245 + + H2250 2004 Octet H2250LogicalChannelParameters + string + Ref.: ITU-T H.245 + + + + + C.3 General bearer properties + + + PropertyID Property Type Value + tag + + Mediatx 3001 Enumerati Media Transport Type + on + TDM Circuit(0), ATM(1), FR(2), + + + + Groves et al Expires - October 2003 [Page 141] + Megaco Protocol version 2 April 2003 + + + Ipv4(3), Ipv6(4), ... + + BIR 3002 4 octets Value depends on transport + technology + + NSAP 3003 1-20 See NSAP. + octets + Ref.: Annex A/X.213 + + + + + C.4 General ATM properties + + + PropertyID Property Type Value + tag + + AESA 4001 20 octets ATM End System Address + + VPVC 4002 4 octets: VPCI/VCI + VPCI in + first two Ref.: ITU-T Q.2931 + least + significant + octets, VCI + in second + two octets + + SC 4003 Enumeration Service Category: 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). + + Ref.: ATM Forum UNI 4.0 + + BCOB 4004 5-bit Broadband Bearer Class + integer + Ref.: ITU-T Q.2961.2 + + BBTC 4005 7-bit Broadband Transfer Capability + integer + Ref.: ITU-T Q.2961.1 + + + + + + + Groves et al Expires - October 2003 [Page 142] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + ATC 4006 Enumeration I.371 ATM Traffic Capability + + DBR(0), SBR1(1), SBR2(2), + SBR3(3), ABT/IT(4), ABT/DT(5), + ABR(6) + + Ref.: ITU-T I.371 + + STC 4007 2 bits Susceptibility to clipping: + + Bits + 21 + -- + 00 not susceptible to clipping + 01 susceptible to clipping + + Ref.: ITU-T Q.2931 + + UPCC 4008 2 bits User Plane Connection + configuration: + + Bits + 21 + -- + 00 point-to-point + 01 point-to-multipoint + + Ref.: ITU-T Q.2931 + + PCR0 4009 24-bit Peak Cell Rate (For CLP = 0) + integer + Ref.: ITU-T Q.2931 + + SCR0 400A 24-bit Sustainable Cell Rate + integer (For CLP = 0) + + Ref.: ITU-T Q.2961.1 + + MBS0 400B 24-bit Maximum Burst Size + integer (For CLP = 0) + + Ref.: ITU-T Q.2961.1 + + + + + + Groves et al Expires - October 2003 [Page 143] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + PCR1 400C 24-bit Peak Cell Rate (For + integer CLP = 0 + 1) + + Ref.: ITU-T Q.2931 + + SCR1 400D 24-bit Sustainable Cell Rate + integer (For CLP = 0 + 1) + + Ref.: ITU-T Q.2961.1 + + MBS1 400E 24-bit Maximum Burst Size + integer (For CLP = 0 + 1) + + Ref.: ITU-T Q.2961.1 + + BEI 400F Boolean Best Effort Indicator + + Value 1 indicates that BEI is + to be included in the ATM + signaling; value 0 indicates + that BEI is not to be included + in the ATM signaling. + + Ref.: ATM Forum UNI 4.0 + + TI 4010 Boolean Tagging Indicator + + Value 0 indicates that tagging + is not allowed; value 1 + indicates that tagging is + requested. + + Ref.: ITU-T Q.2961.1 + + FD 4011 Boolean Frame Discard + + Value 0 indicates that no + frame discard is allowed; + value 1 indicates that frame + discard is allowed. + + Ref.: ATM Forum UNI 4.0 + + + + + + Groves et al Expires - October 2003 [Page 144] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + A2PCDV 4012 24-bit Acceptable 2-point CDV + integer + Ref.: ITU-T Q.2965.2 + + C2PCDV 4013 24-bit Cumulative 2-point CDV + integer + Ref.: ITU-T Q.2965.2 + + APPCDV 4014 24-bit Acceptable P-P CDV + integer + Ref.: ATM Forum UNI 4.0 + + CPPCDV 4015 24-bit Cumulative P-P CDV + integer + Ref.: ATM Forum UNI 4.0 + + ACLR 4016 8-bit Acceptable Cell Loss Ratio + integer + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + MEETD 4017 16-bit Maximum End-to-end transit + integer delay + + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + CEETD 4018 16-bit Cumulative End-to-end transit + integer delay + + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + QosClass 4019 Integer 0-5 QoS Class + + QoS Meaning + Class + + 0 Default QoS + associated with the + ATC as defined in + ITU-T Q.2961.2 + + 1 Stringent + + + + Groves et al Expires - October 2003 [Page 145] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + 2 Tolerant + + 3 Bi-level + + 4 Unbounded + + 5 Stringent Bi-level + + Ref.: ITU-T Q.2965.1 + + AALtype 401A 1 octet AAL Type + + Bits + 87654321 + -------- + 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 + + Ref.: ITU-T Q.2931 + + + + + C.5 Frame Relay + + + PropertyID Property Type Value + tag + + DLCI 5001 Unsigned Data link connection id + integer + + CID 5002 Unsigned sub-channel id + integer + + SID/ 5003 Unsigned silence insertion + Noiselevel integer descriptor + + Primary 5004 Unsigned Primary Payload Type + Payload type integer + + + + Groves et al Expires - October 2003 [Page 146] + Megaco Protocol version 2 April 2003 + + + Covers FAX and codecs + + + + C.6 IP + + + PropertyID Property Type Value + tag + + IPv4 6001 32 bits Ipv4Address + Ipv4Address Ref.: IETF RFC 791 + + IPv6 6002 128 bits IPv6 Address + Ref.: IETF RFC 2460 + + Port 6003 Unsigned 0..65535 + integer + + Porttype 6004 Enumerated TCP(0), UDP(1), SCTP(2) + + + + C.7 ATM AAL2 + + + PropertyID Property Type Value + tag + + AESA 7001 20 octets AAL2 service endpoint + address as defined in the + referenced Recommendation. + + ESEA + + NSEA + + Ref.: ITU-T Q.2630.1 + + BIR See C.3 4 octets Served user generated + reference as defined in the + referenced Recommendation. + + SUGR + + Ref.: ITU-T Q.2630.1 + + + + + Groves et al Expires - October 2003 [Page 147] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + ALC 7002 12 octets AAL2 link characteristics as + defined in the referenced + Recommendation. + + Maximum/Average CPS-SDU bit + rate; + + Maximum/Average CPS-SDU size + + Ref.: ITU-T Q.2630.1 + + SSCS 7003 I.366.2: Service specific convergence + sublayer information as + Audio defined in: + (8 octets); - ITU-T Q.2630.1, + Multirate and used in: + (3 octets), + or - ITU-T I.366.2: + Audio/Multirate; + I.366.1: + - ITU-T I.366.1: + SAR-assured SAR-assured/-unassured. + (14 octets); + SAR-unassured Ref.: ITU-T Q.2630.1, + (7 octets). I.366.1 and I.366.2 + + SUT 7004 1..254 octets Served user transport + parameter as defined in the + referenced Recommendation. + + Ref.: ITU-T Q.2630.1 + + TCI 7005 Boolean Test connection indicator as + defined in the referenced + Recommendation. + + Ref.: ITU-T Q.2630.1 + + Timer_CU 7006 32-bit Timer-CU + integer + Milliseconds to hold + partially filled cell before + sending. + + + + + Groves et al Expires - October 2003 [Page 148] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + MaxCPSSDU 7007 8-bit integer Maximum Common Part Sublayer + Service Data Unit + + Ref.: ITU-T Q.2630.1 + + CID 7008 8 bits subchannel id: 0-255 + + Ref.: ITU-T I.363.2 + + + + C.8 ATM AAL1 + + + Property Property Type Value + ID tag + + BIR See table 4-29 GIT (Generic Identifier Transport) + in C.3 octets + Ref.: ITU-T Q.2941.1 + + AAL1ST 8001 1 octet AAL1 Subtype + + Bits + 87654321 + -------- + 00000000 null + 00000001 voiceband signal + transport on 64 kbit/s + 00000010 circuit transport + 00000100 high-quality audio signal + transport + 00000101 video signal transport + + Ref.: ITU-T Q.2931 + + CBRR 8002 1 octet CBR Rate + + Bits + 87654321 + -------- + 00000001 64 kbit/s + 00000100 1544 kbit/s + 00000101 6312 kbit/s + 00000110 32 064 kbit/s + + + Groves et al Expires - October 2003 [Page 149] + Megaco Protocol version 2 April 2003 + + + Property Property Type Value + ID tag + + 00000111 44 736 kbit/s + 00001000 97 728 kbit/s + 00010000 2048 kbit/s + 00010001 8448 kbit/s + 00010010 34 368 kbit/s + 00010011 139 264 kbit/s + 01000000 n x 64 kbit/s + 01000001 n x 8 kbit/s + + Ref.: ITU-T Q.2931 + + MULT See table Multiplier, or n x 64k/8k/300 + in C.9 + Ref.: ITU-T Q.2931 + + SCRI 8003 1 octet Source Clock Frequency Recovery + Method + + Bits + 87654321 + -------- + 00000000 null + 00000001 SRTS + 00000010 ACM + + Ref.: ITU-T Q.2931 + + ECM 8004 1 octet Error Correction Method + + Bits + 87654321 + -------- + 00000000 null + 00000001 FEC - Loss + 00000010 FEC - Delay + + Ref.: ITU-T Q.2931 + + SDTB 8005 16-bit Structured Data Transfer Blocksize + integer + Block size of SDT CBR service + + Ref.: ITU-T I.363.1 + + + + + Groves et al Expires - October 2003 [Page 150] + Megaco Protocol version 2 April 2003 + + + Property Property Type Value + ID tag + + PFCI 8006 8-bit Partially filled cells identifier + integer + 1-47 + + Ref.: ITU-T I.363.1 + + + + C.9 Bearer capabilities + + The table entries referencing Recommendation Q.931 refer to the + encoding in the bearer capability information element of Q.931, not + to the low layer information element. + + + Property + PropertyID Type Value + tag + + TMR 9001 1 octet Transmission Medium Requirement + (Q.763) + + Bits + 87654321 + -------- + 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 spare + 00001111 + + + Groves et al Expires - October 2003 [Page 151] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 00010000 3 x 64 kbit/s + through through + 00101010 29 x 64 kbit/s + unrestricted + 00101011 + through spare + 11111111 + + Ref.: ITU-T Q.763 + + TMRSR 9002 1 octet Transmission Medium Requirement + Subrate + + 0 unspecified + + 1 8 kbit/s + 2 16 kbit/s + 3 32 kbit/s + + Contcheck 9003 Boolean Continuity Check + + 0 continuity check not required + on this circuit + + 1 continuity check required on + this circuit + + Ref.: ITU-T Q.763 + + ITC 9004 5 bits Information Transfer Capability + + Bits + 54321 + ----- + + 00000 Speech + + 01000 Unrestricted digital + information + + 01001 Restricted digital + information + + 10000 3.1 kHz audio + + + + Groves et al Expires - October 2003 [Page 152] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 10001 Unrestricted digital + information with + tones/announcements + + 11000 Video + + All other values are reserved. + + Ref.: ITU-T Q.763 + + TransMode 9005 2 bits Transfer Mode + + Bits + 21 + -- + 00 Circuit mode + 10 Packet mode + + Ref.: ITU-T Q.931 + + TransRate 9006 5 bits Transfer Rate + + Bits + 54321 + ----- + 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) + + Ref.: ITU-T Q.931 + + MULT 9007 7 bits Rate Multiplier + + Any value from 2 to n (maximum + number of B-channels) + + Ref.: ITU-T Q.931 + + + + + Groves et al Expires - October 2003 [Page 153] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + layer1prot 9008 5 bits User Information Layer 1 Protocol + + Bits + 54321 + ----- + 00001 ITU-T standardized rate + adaption V.110 and X.30. + 00010 Rec. G.711 mu-law + 00011 Rec. G.711 A-law + 00100 Rec. G.726 32 kbit/s ADPCM + and Rec. I.460 + 00101 Rec. H.221 and H.242 + 00110 Rec. H.223 and H.245 + 00111 Non-ITU-T standardized + rate adaption. + 01000 ITU-T standardized rate + adaption V.120. + 01001 ITU-T standardized rate + adaption X.31 HDLC flag + stuffing + + All other values are reserved. + + Ref.: ITU Recommendation Q.931 + syncasync 9009 Boolean Synchronous/Asynchronous + + 0 Synchronous data + 1 Asynchronous data + + Ref.: ITU-T Q.931 + + negotiatio 900A Boolean Negotiation + n + 0 In-band negotiation possible + 1 In-band negotiation not possible + + Ref.: ITU-T Q.931 + + Userrate 900B 5 bits User Rate + + 54321 + ----- + 00000 Rate is indicated by E-bits + specified in Rec. I.460 or + may be negotiated in-band + + + Groves et al Expires - October 2003 [Page 154] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 00001 0.6 kbit/s Recs. V.6 & X.1 + 00010 1.2 kbit/s Rec. V.6 + 00011 2.4 kbit/s Recs. V.6 & X.1 + 00100 3.6 kbit/s Rec. V.6 + 00101 4.8 kbit/s Recs. V.6 & X.1 + 00110 7.2 kbit/s Rec. V.6 + 00111 8 kbit/s Rec. I.460 + 01000 9.6 kbit/s Recs. V.6 & X.1 + 01001 14.4 kbit/s Rec. V.6 + 01010 16 kbit/s Rec. I.460 + 01011 19.2 kbit/s Rec. V.6 + 01100 32 kbit/s Rec. I.460 + 01101 38.4 kbit/s Rec. V.110 + 01110 48 kbit/s Recs. V.6 & X.1 + 01111 56 kbit/s Rec. V.6 + 10010 57.6 kbit/s Rec. V.14 + extended + 10011 28.8 kbit/s Rec. V.110 + 10100 24 kbit/s Rec. V.110 + 10101 0.1345 kbit/s Rec. X.1 + 10110 0.100 kbit/s Rec. X.1 + + Recommendations V.6 and X.1: + 10111 0.075/1.2 kbit/s + 11000 1.2/0.075 kbit/s + 11001 0.050 kbit/s + 11010 0.075 kbit/s + 11011 0.110 kbit/s + 11100 0.150 kbit/s + 11101 0.200 kbit/s + 11110 0.300 kbit/s + + 11111 12 kbit/s Rec. V.6 + + All other values are reserved. + + Ref.: ITU-T Q.931 + + INTRATE 900C 2 bits Intermediate Rate + + Bits + 21 + -- + 00 Not used + 01 8 kbit/s + + + + Groves et al Expires - October 2003 [Page 155] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 10 16 kbit/s + 11 32 kbit/s + + Ref.: ITU-T Q.931 + + nictx 900D Boolean Network Independent Clock (NIC) on + transmission + + 0 Not required to send data with + network independent clock + + 1 Required to send data with + network independent clock + + Ref.: ITU-T Q.931 + + nicrx 900E Boolean Network independent clock (NIC) on + reception + + 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) + + Ref.: ITU-T Q.931 + + flowconttx 900F Boolean Flow Control on transmission (Tx) + + 0 Not required to send data with + flow control mechanism + + 1 Required to send data with flow + control mechanism + + Ref.: ITU-T Q.931 + + flowcontrx 9010 Boolean Flow control on reception (Rx) + + 0 Cannot accept data with flow + control mechanism (i.e. sender + + + Groves et al Expires - October 2003 [Page 156] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + does not support this optional + procedure) + + 1 Can accept data with flow + control mechanism (i.e. sender + does support this optional + procedure) + + Ref.: ITU-T Q.931 + + rateadapth 9011 Boolean Rate adaption header/no header + dr + 0 Rate adaption header not + included + + 1 Rate adaption header included + + Ref.: ITU-T Q.931 + + multiframe 9012 Boolean Multiple frame establishment + support in data link + + 0 Multiple frame establishment + not supported. Only UI frames + allowed + + 1 Multiple frame establishment + supported + + Ref.: ITU-T Q.931 + + OPMODE 9013 Boolean Mode of operation + + 0 Bit transparent mode of + operation + + 1 Protocol sensitive mode of + operation + + Ref.: ITU-T Q.931 + + llidnegot 9014 Boolean Logical link identifier + negotiation + + + + + Groves et al Expires - October 2003 [Page 157] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 0 Default, LLI = 256 only + + 1 Full protocol negotiation + + Ref.: ITU-T Q.931 + + assign 9015 Boolean Assignor/assignee + + 0 Message originator is "default + assignee" + + 1 Message originator is "assignor + only" + + Ref.: ITU-T Q.931 + + inbandneg 9016 Boolean In-band/out-band negotiation + + 0 Negotiation is done with USER + INFORMATION messages on a + temporary signalling connection + + 1 Negotiation is done in-band + using logical link zero + + Ref.: ITU-T Q.931 + + stopbits 9017 2 bits Number of stop bits + + Bits + 21 + -- + 00 Not used + 01 1 bit + 10 1.5 bits + 11 2 bits + + Ref.: ITU-T Q.931 + + databits 9018 2 bits Number of data bits excluding + parity bit if present + + Bits + 21 + -- + + + Groves et al Expires - October 2003 [Page 158] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 00 Not used + 01 5 bits + 10 7 bits + 11 8 bits + + Ref.: ITU-T Q.931 + + parity 9019 3 bits Parity information + + Bits + 321 + --- + 000 Odd + 010 Even + 011 None + 100 Forced to 0 + 101 Forced to 1 + + All other values are reserved. + + Ref.: ITU-T Q.931 + + duplexmode 901A Boolean Mode duplex + + 0 Half duplex + 1 Full duplex + + Ref.: ITU-T Q.931 + + modem 901B 6 bits Modem Type + + Bits + 654321 + ------ + 000000 + through National use + 000101 + + 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 + + + Groves et al Expires - October 2003 [Page 159] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 011000 RecommendationV.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 National use + 101111 + + 110000 + through User specified + 111111 + + Ref.: ITU-T Q.931 + + layer2prot 901C 5 bits User information layer 2 protocol + + Bits + 54321 + ----- + + 00010 Rec. Q.921 / I.441 + + 00110 Rec. X.25, link layer + + 01100 LAN logical link control + + (ISO/IEC 8802-2) + + All other values are reserved. + + Ref.: ITU-T Q.931 + + layer3prot 901D 5 bits User information layer 3 protocol + + Bits + 54321 + ----- + + 00010 ITU-T Q.931 + + 00110 ITU-T X.25, packet layer + + + + + Groves et al Expires - October 2003 [Page 160] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 01011 ISO/IEC TR 9577 (Protocol + identification in the + network layer) + + All other values are reserved. + + Ref.: ITU-T Q.931 + + addlayer3p 901E Octet Additional User Information layer + rot 3 protocol + + Bits Bits + 4321 4321 + ---- ---- + + 1100 1100 Internet Protocol + (RFC 791) + (ISO/IEC TR 9577) + + 1100 1111 Point-to-point + Protocol (RFC 1661) + + Ref.: ITU-T Q.931 + + DialledN 901F 30 Dialled Number + octets + + DiallingN 9020 30 Dialling Number + octets + + ECHOCI 9021 Not Used. See H.248.1 E.13 for an + example of possible Echo Control + properties. + + NCI 9022 1 octet Nature of Connection Indicators + + Bits + 21 Satellite Indicator + -- + 00 no satellite circuit in the + connection + 01 one satellite circuit in the + connection + 10 two satellite circuits in the + connection + + + Groves et al Expires - October 2003 [Page 161] + Megaco Protocol version 2 April 2003 + + + Property + PropertyID Type Value + tag + + 11 spare + + Bits + 43 Continuity check indicator + -- + 00 continuity check not required + 01 continuity check required on + this circuit + 10 continuity check performed on + a previous circuit + 11 spare + + Bit + 5 Echo control device indicator + - + 0 outgoing echo control device + not included + 1 outgoing echo control device + included + + Bits + 8 7 6 Spare + + Ref.: ITU-T Q.763 + + USI 9023 Octet User Service Information + string + Ref.: ITU-T Q.763 Clause 3.57 + + + + C.10 AAL5 properties + + + PropertyID Property Type Value + tag + + FMSDU A001 32-bit Forward Maximum CPCS-SDU Size: + integer + Maximum CPCS-SDU size sent in + the direction from the calling + user to the called user. + + Ref.: ITU-T Q.2931 + + + + Groves et al Expires - October 2003 [Page 162] + Megaco Protocol version 2 April 2003 + + + BMSDU A002 32-bit Backwards Maximum CPCS-SDU + integer Size: + + Maximum CPCS-SDU size sent in + the direction from the called + user to the calling user. + + Ref.: ITU-T Q.2931 + + SSCS See See table See table in C.7 + table in in C.7 + C.7 Additional values: + + VPI/VCI + + + + C.11 SDP equivalents + + + PropertyID Property Type Value + tag + + SDP_V B001 String Protocol Version + + Ref.: RFC 2327 + + SDP_O B002 String Owner/creator and session ID + + Ref.: RFC 2327 + + SDP_S B003 String Session name + + Ref.: RFC 2327 + + SDP_I B004 String Session identifier + + Ref.: RFC 2327 + + SDP_U B005 String URI of descriptor + + Ref.: RFC 2327 + + SDC_E B006 String email address + + Ref.: RFC 2327 + + + + + Groves et al Expires - October 2003 [Page 163] + Megaco Protocol version 2 April 2003 + + + SDP_P B007 String phone number + + Ref.: RFC 2327 + + SDP_C B008 String Connection information + + Ref.: RFC 2327 + + SDP_B B009 String Bandwidth Information + + Ref.: RFC 2327 + + SDP_Z B00A String Time zone adjustment + + Ref.: RFC 2327 + + SDP_K B00B String Encryption Key + + Ref.: RFC 2327 + + SDP_A B00C String Zero or more session + attributes + + Ref.: RFC 2327 + + SDP_T B00D String Active Session Time + + Ref.: RFC 2327 + + SDP_R B00E String Zero or more repeat times + + Reference: RFC 2327 + + SDP_M B00F String Media type, port, transport + and format + + Ref.: RFC 2327 + + + + C.12 H.245 + + + PropertyID Property Type Value + tag + + OLC C001 Octet The value of H.245 + OpenLogicalChannel + + + Groves et al Expires - October 2003 [Page 164] + Megaco Protocol version 2 April 2003 + + + PropertyID Property Type Value + tag + + string structure. + + Ref.: ITU-T H.245 + + OLCack C002 Octet The value of H.245 + string OpenLogicalChannelAck + structure. + + Ref.: ITU-T H.245 + + OLCcnf C003 Octet The value of H.245 + string OpenLogicalChannelConfirm + structure. + + Ref.: ITU-T H.245 + + OLCrej C004 Octet The value of H.245 + string OpenLogicalChannelReject + structure. + + Ref.: ITU-T H.245 + + CLC C005 Octet The value of H.245 + string CloseLogicalChannel + structure. + + Ref.: ITU-T H.245 + + CLCack C006 Octet The value of H.245 + string CloseLogicalChannelAck + structure. + + Ref.: ITU-T H.245 + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 165] + Megaco Protocol version 2 April 2003 + + + ANNEX D TRANSPORT OVER IP + + D.1 Transport over IP/UDP using Application Level Framing (ALF) + + Protocol messages defined in this Recommendation may be transmitted + over UDP. When no port is provided by the peer (see 7.2.8), commands + SHOULD be sent to the default port number: 2944 for text-encoded + operation, or 2945 for binary-encoded operation. Responses must be + sent to the address and port from which the corresponding commands + were sent. + + ALF is a set of techniques that allows an application, as opposed to + a stack, to affect how messages are sent to the other side. A typical + ALF technique is to allow an application to change the order of + messages sent when there is a queue after it has queued them. There + is no formal specification for ALF. The procedures in Annex D.1 + contain a minimum suggested set of ALF behaviours + + 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 + + Messages, being carried over UDP, may be subject to losses. In the + absence of a timely response, commands are repeated. Most commands + are not idempotent. The state of the MG would become unpredictable + if, for example, Add commands were executed several times. The + transmission procedures shall thus provide an "At-Most-Once" + functionality. + + Peer protocol entities are expected to keep in memory a list of the + responses that they sent to recent transactions and a list of the + transactions that are currently outstanding. The transaction + identifier of each incoming message is compared to the transaction + identifiers of the recent responses sent to the same MId. If a match + is found, the entity does not execute the transaction, but simply + repeats the response. If no match is found, the message will be + compared to the list of currently outstanding transactions. If a + match is found in that list, indicating a duplicate transaction, the + entity does not execute the transaction (see D.1.4 for procedures on + sending TransactionPending). + + The procedure uses a long timer value, noted LONG-TIMER in the + following. The timer SHOULD be set larger than the maximum duration + of a transaction, which 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. + + + + Groves et al Expires - October 2003 [Page 166] + Megaco Protocol version 2 April 2003 + + + 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 has been received, through the + "Response Acknowledgement parameter". For transactions that are + acknowledged through this parameter, the entity shall keep a copy of + the transaction-id for LONG-TIMER seconds after the response is + issued, in order to 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 may decide to use a specific number space for each of the + MGs that they manage, or to use the same number space for all MGs + that belong to some arbitrary group. MGCs may decide to share the + load of managing a large MG between several independent processes. + These processes will share the same transaction number space. There + are multiple possible implementations of this sharing, such as having + a centralized allocation of transaction identifiers, or pre- + allocating non-overlapping ranges of identifiers to different + processes. The implementations 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" receivedfor LONG-TIMER seconds. + + + + + Groves et al Expires - October 2003 [Page 167] + Megaco Protocol version 2 April 2003 + + + In the binary encoding, if only the firstAck is present in a response + acknowledgement (see A.2), only one transaction is acknowledged. 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 B.2). + + D.1.3 Computing retransmission timers + + It is the responsibility of the requesting entity to provide suitable + timeouts for all outstanding transactions, and to retry transactions + when timeouts have been exceeded. Furthermore, when repeated + transactions fail to be acknowledged, it is the responsibility of the + requesting entity to seek redundant services and/or clear existing or + pending connections. + + The specification purposely avoids specifying any value for the + retransmission timers. These values are typically network dependent. + 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. 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. + + 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 + Recommendation, in order to guarantee that no repeated packet + would be received by the gateways after LONG-TIMER seconds. 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. + + + + + Groves et al Expires - October 2003 [Page 168] + Megaco Protocol version 2 April 2003 + + + - 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 + + The protocol is organized as a set of transactions, each of which is + composed request and a response, commonly referred to as an + acknowledgement. The protocol messages, being carried over UDP, may + be subject to losses. In the absence of a timely response, + transactions are repeated. Entities are expected to keep in memory a + list of the responses that they sent to recent transactions, i.e. a + list of all the responses they sent over the last LONG-TIMER seconds, + and a list of the transactions that are currently being executed. + + The repetition mechanism is used to guard against three types of + possible errors: + + - transmission errors, when for example a packet is lost due to + noise on a line or congestion in a queue; + + + Groves et al Expires - October 2003 [Page 169] + Megaco Protocol version 2 April 2003 + + + - component failure, when for example an interface to a entity + becomes unavailable; + + - entity failure, when for example an entire entity become + unavailable. + + The entities SHOULD be able to derive from the past history an + estimate of the packet loss rate due to transmission errors. In a + properly configured system, this loss rate SHOULD be kept very low, + typically less than 1%. If a Media Gateway Controller or a Media + Gateway has to repeat a message more than a few times, it is very + legitimate to assume that something else than a transmission error is + occurring. For example, given a loss rate of 1%, the probability that + five consecutive transmission attempts fail is 1 in 100 billion, an + event that SHOULD occur less than once every 10 days for a Media + Gateway Controller that processes 1000 transactions per second. + (Indeed, the number of repetition that is considered excessive SHOULD + be a function of the prevailing packet loss rate.) We SHOULD note + that the "suspicion threshold", which we will call "Max1", is + normally lower than the "disconnection threshold", which SHOULD be + set to a larger value. + + A classic retransmission algorithm would simply count the number of + successive repetitions, and conclude that the association is broken + after retransmitting the packet an excessive number of times + (typically between 7 and 11 times.) In order to account for the + possibility of an undetected or in progress "failover", we modify the + classic algorithm so that if the Media Gateway receives a valid + ServiceChange message announcing a failover, it will start + transmitting outstanding commands to that new MGC. Responses to + commands are still transmitted to the source address of the command. + + In order to automatically adapt to network load, this Recommendation + specifies exponentially increasing timers. If the initial timer is + set to 200 milliseconds, the loss of a fifth retransmission will be + detected after about 6 seconds. This is probably an acceptable + waiting delay to detect a failover. The repetitions SHOULD continue + after that delay not only in order to perhaps overcome a transient + connectivity problem, but also in order to allow some more time for + the execution of a failover (waiting a total delay of 30 seconds is + probably acceptable). + + It is, however, important that the maximum delay of retransmissions + be bounded. Prior to any retransmission, it is checked that the time + elapsed since the sending of the initial datagram is no greater than + T-MAX. If more than T-MAX time has elapsed, the MG concludes that the + MGC has failed, and it begins its recovery process as described in + section 11.5. If the MG retries to connect to the current MGC it + shall use a ServiceChange with ServiceChangeMethod set to + + + Groves et al Expires - October 2003 [Page 170] + Megaco Protocol version 2 April 2003 + + + Disconnected so that the new MGC will be aware that the MG lost one + or more transactions. The value T-MAX is related to the LONG-TIMER + value: the LONG-TIMER value is obtained by adding to T MAX the + maximum propagation delay in the network. + + D.2 Using TCP + + Protocol messages as defined in this Recommendation may be + transmitted over TCP. When no port is specified by the other side + (see 7.2.8), the commands SHOULD be sent to the default port. The + defined protocol has messages as the unit of transfer, while TCP is a + stream-oriented protocol. TPKT, according to RFC 1006, SHALL be used + to delineate messages within the TCP stream. + + In a transaction-oriented protocol, there are still ways for + transaction requests or responses to be lost. As such, it is + recommended that entities using TCP transport implement application + level timers for each request and each response, similar to those + specified for application level framing over UDP. + + D.2.1 Providing the At-Most-Once functionality + + Messages, being carried over TCP, are not subject to transport + losses, but loss of a transaction request or its reply may + nonetheless be noted in real implementations. In the absence of a + timely response, commands are repeated. Most commands are not + idempotent. The state of the MG would become unpredictable if, for + example, Add commands were executed several times. + + To guard against such losses, it is recommended that entities follow + the procedures in D.1.1. + + D.2.2 Transaction identifiers and three-way handshake + + For the same reasons, it is possible that transaction replies may be + lost even with a reliable delivery protocol such as TCP. It is + recommended that entities follow the procedures in D.1.2.2. + + D.2.3 Computing retransmission timers + + With reliable delivery, the incidence of loss of a transaction + request or reply is expected to be very low. Therefore, only simple + timer mechanisms are required. Exponential back-off algorithms SHOULD + not be necessary, although they could be employed where, as in an + MGC, the code to do so is already required, since MGCs must implement + ALF/UDP as well as TCP. + + + + + + Groves et al Expires - October 2003 [Page 171] + Megaco Protocol version 2 April 2003 + + + D.2.4 Provisional responses + + As with UDP, executing some transactions may require a long time. + 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 longer + repetition timer for that transaction. + + Entities shall retain Transactions and replies until they are + confirmed. The basic procedure of D.1.4 SHOULD be followed, but + simple timer values SHOULD be sufficient. There is no need to send an + immediate confirmation upon receipt of a final response. + + D.2.5 Ordering of commands + + TCP provides ordered delivery of transactions. No special procedures + are required. It SHOULD be noted that ALF/UDP allows sending entity + to modify its behaviour under congestion, and in particular, could + reorder transactions when congestion is encountered. TCP could not + achieve the same results. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 172] + Megaco Protocol version 2 April 2003 + + + ANNEX E BASIC PACKAGES + + This annex contains definitions of some packages for use with + Recommendation H.248.1. + + 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 + + EventsDescriptor parameters: None + + ObservedEvents Descriptor Parameters: + + General Cause + + ParameterID: Generalcause (0x0001) + + This parameter groups the failures into six groups, which + the MGC may act upon. + + Type: enumeration + + Possible values: + "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 + + + + Groves et al Expires - October 2003 [Page 173] + Megaco Protocol version 2 April 2003 + + + ParameterID: Failurecause (0x0002) + + Possible values: OCTET STRING + + Description: The Failure 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. + + + Signal Completion + + EventID: sc (0x0002) + + Indicates the termination of a signal for which the + notifyCompletion parameter was set to enable reporting of a + completion event. For further procedural description, see 7.1.1, + 7.1.17 and 7.2.7. + + EventsDescriptor parameters: None + + ObservedEvents Descriptor parameters: + + Signal Identity + + ParameterID: SigID (0x0001) + + This parameter identifies the signal which has terminated. + For a signal that is contained in a signal list, the signal + list identity parameter SHOULD also be returned indicating + the appropriate list. + + Type: Binary: octet (string), Text: string + + Possible values: a signal which has terminated. A signal + shall be identified using the pkgdName syntax without + wildcarding. + + Termination Method + + ParameterID: Meth (0x0002) + + Indicates the means by which the signal terminated. + + Type: enumeration + + Possible values: + "TO" (0x0001) Signal timed out or otherwise completed on + its own + + + Groves et al Expires - October 2003 [Page 174] + Megaco Protocol version 2 April 2003 + + + "EV" (0x0002) Interrupted by event + "SD" (0x0003) Halted by new Signals descriptor + "NC" (0x0004) Not completed, other cause + + Signal List ID + + ParameterID: SLID (0x0003) + + Indicates to which signal list a signal belongs. The + SignalList ID is only returned in cases where the signal + resides in a signal list. + + Type: integer + + Possible values: any integer + + E.1.3 Signals + + None. + + E.1.4 Statistics + + None. + + + + E.2 Base Root Package + + Base Root Package + + PackageID: root (0x0002) + Version: 2 + Extends: None + + Description: + + This package defines Gateway wide properties. + + E.2.1 Properties + + MaxNumberOfContexts + + 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 + + + Groves et al Expires - October 2003 [Page 175] + Megaco Protocol version 2 April 2003 + + + Possible values: 1 and up + + Defined in: TerminationState + + Characteristics: read only + + + MaxTerminationsPerContext + + PropertyID: maxTerminationsPerContext (0x0002) + + The maximum number of allowed terminations in a context, see 6.1 + + Type: integer + + Possible values: any integer + + Defined in: TerminationState + + Characteristics: read only + + + 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 + + Characteristics: read / write + + + 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 + + + + Groves et al Expires - October 2003 [Page 176] + Megaco Protocol version 2 April 2003 + + + Possible values: any integer, represents milliseconds + + Defined in: TerminationState + + Characteristics: read / write + + + MGProvisionalResponseTimerValue + + PropertyId: MGProvisionalResponseTimerValue (0x0005) + + Indicates the time within which the MGC SHOULD expect a Pending + Response from the MG if a Transaction cannot be completed. + Initially set to normalMGExecutionTime plus network delay, but may + be lowered. + + Type: Integer + + Possible Values: any integer, represents milliseconds + + Defined in: TerminationState + + Characteristics: read / write + + + MGCProvisionalResponseTimerValue + + PropertyId: MGCProvisionalResponseTimerValue (0x0006) + + Indicates the time within which the MG SHOULD expect a Pending + Response from the MGC if a Transaction cannot be completed. + Initially set to normalMGCExecutionTime plus network delay, but + may be lowered. + + Type: Integer + + Possible Values: any integer, represents milliseconds + + Defined in: TerminationState + + Characteristics: read / write + + + MGCOriginatedPendingLimit + + PropertyId: MGCOriginatedPendingLimit (0x0007) + + Indicates the number of TransactionPendings that can be received + from the MGC. Once this limit is exceeded the MGC SHOULD issue a + + + Groves et al Expires - October 2003 [Page 177] + Megaco Protocol version 2 April 2003 + + + TransactionReply with Error 506 Number of TransactionPendings + Exceeded, otherwise the MG can assume the Transaction to be in + error. + + Type: Integer + + Possible Values: any possible integer + + Defined in: TerminationState + + Characteristics: Read/Write + + + MGOriginatedPendingLimit + + PropertyId: MGOriginatedPendingLimit (0x0008) + + Indicates the number of TransactionPendings that can be received + from the MG. Once this limit is exceeded the MG SHOULD issue a + TransactionReply with Error 506 Number of TransactionPendings + Exceeded, otherwise the MGC can assume the Transaction to be in + error. + + Type: Integer + + Possible Values: any possible integer + + Defined in: TerminationState + + Characteristics: Read/Write + + E.2.2 Events + + None. + + E.2.3 Signals + + None. + + E.2.4 Statistics + + None. + + E.2.5 Procedures + + None. + + + + + + Groves et al Expires - October 2003 [Page 178] + Megaco Protocol version 2 April 2003 + + + E.3 Tone Generator Package + + PackageID: tonegen (0x0003) + Version: 1 + Extends: None + + Description: + + This package defines signals to generate audio tones. This package + does not specify parameter values. It is intended to be extendable. + Generally, tones are defined as an individual signal with a + parameter, ind, representing "interdigit" time delay, and a tone id + to be used with playtones. A tone id SHOULD be kept consistent with + any tone generation for the same tone. MGs are expected to be + provisioned with the characteristics of appropriate tones for the + country in which the MG is located. + + Designed to be extended only: Yes + + E.3.1 Properties + + None. + + E.3.2 Events + + None. + + E.3.3 Signals + + Play tone + + SignalID: pt (0x0001) + + Plays audio tone over an audio channel + + Signal Type: Brief + + Duration: Provisioned + + Additional parameters: + + Tone id list + + ParameterID: tl (0x0001) + + Type: list of tone ids + + List of tones to be played in sequence. The list SHALL + contain one or more tone ids. + + + Groves et al Expires - October 2003 [Page 179] + Megaco Protocol version 2 April 2003 + + + Inter signal duration + + ParameterID: ind (0x0002) + + Type: integer + + Timeout between two consecutive tones in milliseconds + + No tone ids are specified in this package. Packages that extend this + package can add possible values for tone id as well as adding + individual tone signals. + + E.3.4 Statistics + + None. + + E.3.5 Procedures + + None. + + + + E.4 Tone Detection Package + + PackageID: tonedet (0x0004) + Version: 1 + Extends: None + + Designed to be extended only: Yes + + This Package defines events for audio tone detection. Tones are + selected by name (tone id). MGs are expected to be provisioned with + the characteristics of appropriate tones for the country in which the + MG is located. + + This package does not specify parameter values. It is intended to be + extendable. + + E.4.1 Properties + + None. + + E.4.2 Events + + Start tone detected + + EventID: std, 0x0001 + + + + + Groves et al Expires - October 2003 [Page 180] + Megaco Protocol version 2 April 2003 + + + Detects the start of a tone. The characteristics of positive tone + detection are implementation dependent. + + EventsDescriptor parameters: + + Tone id list + + ParameterID: tl (0x0001) + + Type: list of tone ids + + Possible values: The only tone id defined in this package is + "wild card" which is "*" in text encoding and 0x0000 in + binary. Extensions to this package would add possible values + for tone id. If tl is "wild card", any tone id is detected. + + ObservedEventsDescriptor parameters: + + Tone id + + ParameterID: tid (0x0003) + + Type: enumeration + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this package + would add additional possible values for tone id. + + + End tone detected + + EventID: etd, 0x0002 + + Detects the end of a tone. + + EventDescriptor parameters: + + Tone id list + + ParameterID: tl (0x0001) + + Type: enumeration or list of enumerated types + + Possible values: No possible values are specified in this + package. Extensions to this package would add possible + values for tone id. + + ObservedEventsDescriptor parameters: + + + + Groves et al Expires - October 2003 [Page 181] + Megaco Protocol version 2 April 2003 + + + Tone id + + ParameterID: tid (0x0003) + + Type: enumeration + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this package + would add possible values for tone id. + + Duration + + ParameterId: dur (0x0002) + + Type: integer, in milliseconds + + This parameter contains the duration of the tone from first + detection until it stopped. + + + Long tone detected + + EventID: ltd, 0x0003 + + 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 list + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this package + would add possible values for tone id. + + Duration: + + ParameterID: dur (0x0002) + + Type: integer, duration to test against + + Possible values: any legal integer, expressed in + milliseconds + + + + + Groves et al Expires - October 2003 [Page 182] + Megaco Protocol version 2 April 2003 + + + ObservedEventsDescriptor parameters: + + Tone id: + + ParameterID: tid (0x0003) + + Type: Enumeration + + Possible values: No possible values are specified in this + package. Extensions to this package 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 1 + + This package defines the basic DTMF tones as signals and 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 + + SignalID: d0 (0x0010) + + + + Groves et al Expires - October 2003 [Page 183] + Megaco Protocol version 2 April 2003 + + + Generate DTMF 0 tone. The physical characteristic of DTMF 0 is + defined in the gateway. + + Signal Type: Brief + + Duration: Provisioned + + Additional parameters: + + None + + Additional values: + + d0 (0x0010) is defined as a tone id for playtone + + The other DTMF characters are specified in exactly the same + way. A table with all signal names and signal IDs is included. + Note that each DTMF character is defined as both a signal and a + tone id, thus extending the basic tone generation package. Also + note that DTMF SignalIds are different from the names used in a + digit map. + + 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. + + + + Groves et al Expires - October 2003 [Page 184] + Megaco Protocol version 2 April 2003 + + + + + E.6 DTMF detection Package + + PackageID: dd (0x0006) + Version: 1 + Extends: tonedet version 1 + + This package defines the basic DTMF tones detection. This Package + extends the possible values of tone id in the "start tone detected" + "end tone detected" and "long tone detected" events. + + Additional tone id values are all tone ids described in package dg + (basic DTMF generator package). + + The following table maps DTMF events to digit map symbols as + described in 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 defined in + the table found in E.5.3. + + + + Groves et al Expires - October 2003 [Page 185] + Megaco Protocol version 2 April 2003 + + + + + DigitMap Completion Event + + EventID: ce, 0x0004 + + Generated when a digit map completes as described in 7.1.14. + + EventsDescriptor parameters: None. + + 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". + + Description: the portion of the current dial string as + described in 7.1.14 which matched part or all of an + alternative event sequence specified 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 event + + Description: indicates the reason for generation of the + event. See the procedures in 7.1.14. + + E.6.3 Signals + + None. + + + + Groves et al Expires - October 2003 [Page 186] + Megaco Protocol version 2 April 2003 + + + E.6.4 Statistics + + None. + + E.6.5 Procedures + + Digit map processing is activated only if an events descriptor is + activated that contains a digit map completion event as defined in + Section E.6.2 and that digit map completion event contains an eventDM + field in the requested actions as defined in Section 7.1.9. Other + parameters such as KeepActive or embedded events of signals + descriptors may also be present in the events descriptor and do not + affect the activation of digit map processing. + + + + E.7 Call Progress Tones Generator Package + + PackageID: cg, 0x0007 + Version: 1 + Extends: tonegen version 1 + + This package defines the basic call progress tones as signals and + 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 + + SignalID: dt (0x0030) + + Generate dial tone. The physical characteristic of dial tone is + available in the gateway. + + Signal Type: TimeOut + + Duration: Provisioned + + Additional parameters: + + + + Groves et al Expires - October 2003 [Page 187] + Megaco Protocol version 2 April 2003 + + + None + + Additional values: + + dt (0x0030) is defined as a tone id for playtone + + The other tones of this package are defined in exactly the same way. + A table with all signal names and signal IDs is included. Note that + each tone is defined as both a signal and a tone id, thus extending + 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) + + (Recording) Warning Tone wt (0x0035) + + Payphone Recognition Tone prt (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. See Recommendation E.180/Q.35 for + definition of the meanings of these tones. + + + + E.8 Call Progress Tones Detection Package + + PackageID: cd (0x0008) + Version: 1 + + + Groves et al Expires - October 2003 [Page 188] + Megaco Protocol version 2 April 2003 + + + Extends: tonedet version 1 + + This package defines the basic call progress detection tones. This + package 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 are defined for start tone detected, end tone + detected and long tone detected with the same values as those in + package cg (call progress tones generation package). + + The required set of tone ids corresponds to Recommendation + E.180/Q.35. See Recommendation E.180/Q.35 for definition of the + meanings of these tones. + + E.8.1 Properties + + None. + + E.8.2 Events + + Events are defined as in the call progress tones generator package + (cg) for the tones listed in the table of 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: None + + This package defines events and signals for an analog line. + + + + + + Groves et al Expires - October 2003 [Page 189] + Megaco Protocol version 2 April 2003 + + + E.9.1 Properties + + None + + E.9.2 Events + + onhook + + EventID: on (0x0004) + + Detects handset going on hook. Whenever an events descriptor is + activated that requests monitoring for 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): only an actual hook state transition to on- + hook is to be recognized; + + "state" (0x01): the event is to be recognized either if the + hook state transition is detected or if the hook state is + already on-hook; + + "failWrong" (0x02): if the hook state is already on-hook, + the command fails and an error is reported. + + ObservedEventsDescriptor parameters + + Initial State + ParameterID: init (0x0002) + + Type: Boolean + + Possible values: + + "True" means that the event was reported because the line + was already on-hook when the events descriptor containing + this event was activated; + + "False" means that the event represents an actual state + transition to on-hook. + + + Groves et al Expires - October 2003 [Page 190] + Megaco Protocol version 2 April 2003 + + + + offhook + + EventID: of (0x0005) + + Detects handset going off hook. Whenever an events descriptor is + activated that requests monitoring for 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): only an actual hook state transition to off- + hook is to be recognized; + + "state" (0x01): the event is to be recognized either if the + hook state transition is detected or if the hook state is + already off-hook; + + "failWrong" (0x02): if the hook state is already off-hook, + the command fails and an error is reported. + + ObservedEventsDescriptor parameters + + Initial State + ParameterID: init (0x0002) + + Type: Boolean + + Possible values: + + "True" means that the event was reported because the line + was already off-hook when the events descriptor containing + this event was activated; + + "False" means that the event represents an actual state + transition to off-hook. + + + + flashhook + + + + Groves et al Expires - October 2003 [Page 191] + Megaco Protocol version 2 April 2003 + + + EventID: fl, 0x0006 + + Detects handset flash. A flash occurs when an onhook is followed + by an offhook between a minimum and maximum duration. + + EventDescriptor parameters + + Minimum duration + + ParameterID: mindur (0x0004) + + Type: integer in milliseconds + + Default value is provisioned. + + Maximum duration + + ParameterID: maxdur (0x0005) + + Type: integer in milliseconds + + Default value is provisioned. + + ObservedEventsDescriptor parameters + + None + + E.9.3 Signals + + ring + + SignalID: ri, 0x0002 + + Applies ringing on the line + + Signal Type: TimeOut + + Duration: Provisioned + + Additional 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 + + + + Groves et al Expires - October 2003 [Page 192] + Megaco Protocol version 2 April 2003 + + + 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 reponse. + + E.9.6 Error code + + This package defines a new error code: + + 540 - Unexpected initial hook state + + The procedure for use of this code is given in E.9.5. + + + + E.10 Basic Continuity Package + + PackageID: ct (0x000a) + Version: 1 + Extends: None + + This 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. + + + + Groves et al Expires - October 2003 [Page 193] + Megaco Protocol version 2 April 2003 + + + E.10.2 Events + + Completion + + EventID: cmp, 0x0005 + + This event detects test completion of 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: TimeOut + + Default value is provisioned + + Additional parameters: + + None + + + Respond + + SignalID: rsp (0x0004) + + The signal is used to respond to a continuity test. See E.10.5 for + further explanation. + + Signal Type: On/Off + + + + Groves et al Expires - October 2003 [Page 194] + Megaco Protocol version 2 April 2003 + + + Default 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. + + (Informative Note) Example tones and test procedure details are given + in Q.724 sections 7 and 8, Q.764 section 2.1.8 and Q.1902.4. + + + + + + + Groves et al Expires - October 2003 [Page 195] + Megaco Protocol version 2 April 2003 + + + E.11 Network Package + + PackageID: nt (0x000b) + Version: 1 + Extends: None + + This 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 milliseconds + + Possible values: This property is specified in milliseconds. + + Defined in: LocalControlDescriptor + + Characteristics: read/write + + E.11.2 Events + + network failure + + EventID: netfail, 0x0005 + + The 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 string + + + + + Groves et al Expires - October 2003 [Page 196] + Megaco Protocol version 2 April 2003 + + + This parameter may be included with the failure event to + provide diagnostic information on the reason of failure. + + + quality alert + + EventID: qualert, 0x0006 + + This event allows the MG to indicate a loss of quality of the + network connection. The MG may do this by measuring packet loss, + interarrival jitter, propogation delay and then indicating this + using a percentage of quality loss. + + EventDescriptor parameters + + Threshold + + ParameterId: th (0x0001) + + Type: integer + + Possible values: 0 to 99 + + Description: 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. Event is triggered when calculation exceeds the + threshold. + + ObservedEventsDescriptor parameters + + Threshold + + ParameterId: th (0x0001) + + Type: integer + + Possible values: 0 to 99 + + Description: 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 + + + + Groves et al Expires - October 2003 [Page 197] + Megaco Protocol version 2 April 2003 + + + Duration + + StatisticsID: dur (0x0001) + + Description: provides 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 1 + + This package is used to support 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, 0x0001 + + + Groves et al Expires - October 2003 [Page 198] + Megaco Protocol version 2 April 2003 + + + This event detects and notifies when there is a transition of the + RTP payload format from one format to another. + + EventDescriptor parameters + + None + + ObservedEventsDescriptor parameters + + ParameterName: 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) + + Describes the current rate of packet loss on an RTP stream, as + defined in IETF RFC 1889. Packet loss is expressed as percentage + value: number of packets lost in the interval between two + + + + Groves et al Expires - October 2003 [Page 199] + Megaco Protocol version 2 April 2003 + + + reception reports, divided by the number of packets expected + during that interval. + + Type: double + + Possible values: a 32-bit whole number and a 32-bit fraction. + + Jitter + + StatisticID: jit (0x0007) + + Requests the current value of the interarrival jitter on an RTP + stream as defined in IETF RFC 1889. Jitter measures the variation + in interarrival time for RTP data packets. + + Delay + + StatisticID:delay (0x0008) + + Requests the current value of packet propagation delay expressed + in timestamp units. Same as average latency. + + E.12.5 Procedures + + None. + + + + E.13 TDM Circuit Package + + PackageID: tdmc (0x000d) + Version: 1 + Extends: Network Package version 1 + + This package may be used by any termination that supports gain and + echo control. It was originally intended for use on TDM circuits but + may be more widely used. + + New versions or extensions of this package SHOULD take non-TDM use + into account. + + E.13.1 Properties + + Echo Cancellation + + PropertyID: ec (0x0008) + + Type: boolean + + + + Groves et al Expires - October 2003 [Page 200] + Megaco Protocol version 2 April 2003 + + + Possible values: + + "on" (when the echo cancellation is requested) and + + "off" (when it is turned off.) + + The default is provisioned. + + Defined in: LocalControlDescriptor + + Characteristics: read/write + + Gain Control + + PropertyID: gain (0x000a) + + Gain control, or usage of of signal level adaptation and noise + level reduction is used to adapt the level of the signal. However, + it is necessary, for example for modem calls, to turn off this + function. + + Type: 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. + + + + + Groves et al Expires - October 2003 [Page 201] + Megaco Protocol version 2 April 2003 + + + APPENDIX I Example Call Flows + + All H.248.1 implementors must read the normative part of this + document carefully before implementing from it. No one SHOULD use the + examples in this appendix as stand-alone explanations of how to + create protocol messages. + + The examples in this appendix 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 SDP, and is assigned profile + 0. G.723.1 is called G723 and is profile 4; H.263 is called H263 and + is profile 34. See also http://www.iana.org/assignments/rtp- + parameters. + + I.1 Residential Gateway to Residential Gateway Call + + This example scenario illustrates the use of the elements of the + protocol to set up a Residential Gateway to Residential Gateway call + over an IP-based network. For simplicity, this example assumes that + both Residential Gateways involved in the call are controlled by the + same Media Gateway Controller. + + I.1.1 Programming Residential GW Analog Line Terminations for Idle + Behaviour + + The following illustrates the API invocations from the Media Gateway + Controller and Media Gateways to get the Terminations in this + scenario programmed for idle behaviour. 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. + + 1) An MG registers with an MGC using the ServiceChange command: + + MG1 to MGC: + + MEGACO/1 [124.124.124.222] + Transaction = 9998 { + Context = - { + + + Groves et al Expires - October 2003 [Page 202] + Megaco Protocol version 2 April 2003 + + + ServiceChange = ROOT {Services { + Method=Restart, + ServiceChangeAddress=55555, Profile=ResGW/1} + } + } + } + + 2) 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} } } + } + + 3) The MGC programs a Termination in the NULL context. The + terminationId is A4444, the streamId is 1, the requestId in the + Events descriptor is 2222. The mId is the identifier of the sender of + this message, in this case, it is 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. Local and Remote are + assumed to be provisioned. + + 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 + }, + } + }, + Events = 2222 {al/of (strict=state)} + } + } + } + + 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). + + + Groves et al Expires - October 2003 [Page 203] + Megaco Protocol version 2 April 2003 + + + 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. + + 4) The MG1 accepts the Modify with this reply: + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 + Reply = 9999 { + Context = - {Modify = A4444} + } + + 5) A similar exchange happens between MG2 and the MGC, resulting in + an idle Termination called A5555. + + I.1.2 Collecting Originator Digits and Initiating Termination + + The following builds upon the previously shown conditions. It + illustrates the transactions from the Media Gateway Controller and + originating Media Gateway (MG1) to get the originating Termination + (A4444) through the stages of digit collection required to initiate a + connection to the terminating Media Gateway (MG2). + + 6) 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(init=false)}} + } + } + + 7) And the Notify is acknowledged. + + MGC to MG1: + + MEGACO/1 [123.123.123.4]:55555 + Reply = 10000 { + Context = - {Notify = A4444} + } + + 8) 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. + + MGC to MG1: + + + Groves et al Expires - October 2003 [Page 204] + Megaco Protocol version 2 April 2003 + + + MEGACO/1 [123.123.123.4]:55555 + Transaction = 10001 { + Context = - { + Modify = A4444 { + Events = 2223 { + al/on(strict=state), dd/ce {DigitMap=Dialplan0} + }, + Signals {cg/dt}, + DigitMap= Dialplan0{ + (0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.)} + } + } + } + + 9) And the Modify is acknowledged. + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 + Reply = 10001 { + Context = - {Modify = A4444} + } + + 10) 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. + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 + Transaction = 10002 { + Context = - { + Notify = A4444 {ObservedEvents =2223 { + 19990729T22010001:dd/ce{ds="916135551212",Meth=UM}}} + } + } + + 11) And the Notify is acknowledged. + + MGC to MG1: + + MEGACO/1 [123.123.123.4]:55555 + Reply = 10002 { + Context = - {Notify = A4444} + } + + + + + Groves et al Expires - October 2003 [Page 205] + Megaco Protocol version 2 April 2003 + + + 12) 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. + + 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. + + 13) 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. + + MG1->MGC: + + MEGACO/1 [124.124.124.222]:55555 + Reply = 10003 { + Context = 2000 { + Add = A4444, + + + Groves et al Expires - October 2003 [Page 206] + Megaco Protocol version 2 April 2003 + + + Add=A4445{ + Media { + Stream = 1 { + Local { + v=0 + o=- 2890844526 2890842807 IN IP4 124.124.124.222 + s=- + t= 00 + c=IN IP4 124.124.124.222 + m=audio 2222 RTP/AVP 4 + a=ptime:30 + a=recvonly + } ; RTP profile for G.723.1 is 4 + } + } + } + } + } + + 14) 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. + + 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(strict=state)}, + 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 + + + Groves et al Expires - October 2003 [Page 207] + Megaco Protocol version 2 April 2003 + + + c=IN IP4 124.124.124.222 + m=audio 2222 RTP/AVP 4 + a=ptime:30 + } ; RTP profile for G.723.1 is 4 + } + } + } + } + } + + 15) This is acknowledged. The stream port number is different from + the control port number. In this case it is 1111 (in SDP). + + MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 + Reply = 50003 { + Context = 5000 { + Add = A5555, + Add = A5556{ + Media { + Stream = 1 { + Local { + v=0 + o=- 7736844526 7736842807 IN IP4 125.125.125.111 + s=- + t= 00 + c=IN IP4 125.125.125.111 + m=audio 1111 RTP/AVP 4 + } + } ; RTP profile for G.723.1 is 4 + } + } + } + } + + 16) 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 { + + + Groves et al Expires - October 2003 [Page 208] + Megaco Protocol version 2 April 2003 + + + Remote { + v=0 + o=- 7736844526 7736842807 IN IP4 125.125.125.111 + s=- + t= 00 + c=IN IP4 125.125.125.111 + m=audio 1111 RTP/AVP 4 + } + } ; RTP profile for G.723.1 is 4 + } + } + } + } + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 + Reply = 10005 { + Context = 2000 {Modify = A4444, Modify = A4445} + } + + 17) 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. + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 + Transaction = 50005 { + Context = 5000 { + Notify = A5555 {ObservedEvents =1234 { + 19990729T22020002:al/of(init=false)}} + } + } + + 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(strict=state)}, + + + Groves et al Expires - October 2003 [Page 209] + Megaco Protocol version 2 April 2003 + + + Signals { } ; to turn off ringing + } + } + } + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 + Reply = 50006 { + Context = 5000 {Modify = A4445} + } + + 18) Change mode on MG1 to SendReceive, and stop the ringback. + + 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}} + + 19) 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 }} + } + } + + + + Groves et al Expires - October 2003 [Page 210] + Megaco Protocol version 2 April 2003 + + + 20) 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 + o=- 7736844526 7736842807 IN IP4 125.125.125.111 + s=- + t= 00 + c=IN IP4 125.125.125.111 + m=audio 1111 RTP/AVP 4 + a=ptime:30 + }, + Remote { + v=0 + o=- 2890844526 2890842807 IN IP4 124.124.124.222 + s=- + t= 00 + 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 + } + } + } + + 21) 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. + + + + Groves et al Expires - October 2003 [Page 211] + Megaco Protocol version 2 April 2003 + + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 + Transaction = 50008 { + Context = 5000 { + Notify = A5555 {ObservedEvents =1235 { + 19990729T24020002:al/on(init=false)} + } + } + } + + From MGC to MG2: + + MEGACO/1 [123.123.123.4]:55555 + Reply = 50008 { + Context = - {Notify = A5555} + } + + 22) 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. + + 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 + + + Groves et al Expires - October 2003 [Page 212] + Megaco Protocol version 2 April 2003 + + + rtp/pr=780, ; packets received + nt/or=45123, ; octets received + rtp/pl=10, ; % packets lost + rtp/jit=27, + rtp/delay=48 ; average latency + } + } + } + } + + 23) 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 213] + Megaco Protocol version 2 April 2003 + + + APPENDIX II CHANGES FROM RFC XXXX [draft-ietf-megaco-3015corr-02.txt] + + Section Source Description + + Abstract PTT Describes changes between v1 and v2. + + 1 Edit Added instructions on indication of versions in + ServiceChangeVersion. + + 2.1 Edit Added references to H.248.4, H.248.5. + + 5 PTT New approach to discrepancy between ITU-T and IETF + definition of "SHOULD". + + 6 para 2 List Deleted "modem" [parameters] from last sentence. + + 6.2 para Edit Replaced "taken out of the call it is in" with + 4 "subtracted from a context". + + 6.2 Edit Rewritten to clarify. + final + para + + 6.2.4 List Added note that use of Modem descriptor is + table deprecated. + + 6.2.5 AVD Added ability to set signals on ROOT. Affects first + para, Modify. + + 6.2.5 Edit Added clarifying phrase "as an entity in itself". + first + para + + 7.1.2 List Added para spelling out deprecation of Modem + descriptor. + + 7.1.3 AVD Added Nx64K multiplex type with description. + + 7.1.7 Edit Removed "under" in last sentence, so that all cases + first of specification can be seen to apply. + para + + 7.1.12 AVD Added ability to specify individual property, event, + signal or statistics to be audited. + + 7.1.12 List Noted deprecation of Modem descriptor. + + 7.1.14.3 AVD Added ability to specify value of "long duration" + + + + Groves et al Expires - October 2003 [Page 214] + Megaco Protocol version 2 April 2003 + + + threshold within the digit map itself. + + 7.1.14.4 AVD Added text requiring digit buffering and spelling + out procedures, if EventBufferControl is OFF. + + 7.1.14.5 AVD Added text on handling of buffered digits. + step 2) + + 7.1.14.5 AVD Added provision for inclusion of indication of which + step 2) timer expired if digit map completion event allows + this. + + 7.1.14.5 AVD Added text providing alternatives for handling of + step 5) excess digits. + + 7.1.14.7 AVD Added text on applicability of this clause to + final buffered digits. + bullet + + 7.1.18 AVD Added ability to specify topology by stream: mention + in para 3, new paras before introduction to figures, + new Figure 8. + + 7.2.1, List Deprecation of Modem descriptor noted. + 7.2.2, + 7.2.3, + 7.2.4, + 7.2.5, + 7.2.6 + + 7.2.5, AVD Added ability to audit individual property, event, + 7.2.6 signal or statistics. Added detailed instructions + for this. + + 7.2.8 AVD Added ability to indicate capability change to be + audited: added ServiceChangeInfo to bulleted list of + contents of ServiceChange descriptor, added para + explaining what it is for. + + 7.2.8 Edit Para following new ServiceChangeInfo para: cleanup + of wording in second sentence on registration with + Failover method. + + 7.2.8 AVD Bullet dealing with ServiceChangeProfile on + registration: added text on procedures associated + with profiles. + + 7.2.8 AVD Added 916 and 917 ServiceChangeReasons. + + + + Groves et al Expires - October 2003 [Page 215] + Megaco Protocol version 2 April 2003 + + + 7.2.9 AVD Added text describing the auditing of context + properties. + + 7.3 Edit Deleted. Explanation of error descriptors is now in + section 7.1.19, and error codes are documented in + H.248.8. + + 8.2.3 AVD Added text on properties and procedures to limite + the number of pending notices sent for a given + transaction. + + 8.3 Edit Added sentence indicating that messages conforming + second to this document specify version 2 of the protocol. + para + + 9 Edit Added mention of H.248.4 and H.248.5 (were + transport-related Annexes to H.248). + + 11 AAP Second para demoted to Note to resolve objection + during ITU-T Last Call process. + + 11.3 Edit Modified first sentence to refer specifically to + ServiceChange commands constituting registrations. + [Hidden issue: reestablishment of contact with + Disconnected method does not constitute + registration.] Added second sentence requiring that + the registration message always conform to version 1 + [to ensure interoperability before common working + version can be established]. + + 12.1.1 Edit Slight clarification of "designed to be extended + only" description. + + 13 AVD New section providing extended description of + profile contents and registration. + + 14 and Edit Renumbered as a result of the new Profile section. + sub- + sections + + 14.4 AVD IANA considerations for profiles added. + + A.2 Edit Added object identifier including version to ASN.1 + header. + + A.2 AVD Production TopologyRequest: added optional streamId. + + A.2 AVD Production AuditDescriptor: added auditPropertyToken + + + + Groves et al Expires - October 2003 [Page 216] + Megaco Protocol version 2 April 2003 + + + term for more specific audit items. + + A.2 AVD New productions IndAuditParameter through + IndAudPackagesDescriptor added for more specific + audit items. + + A.2 AVD Production MuxType: added nx64k. + + A.2 AVD Production DigitMapValue: added durationTimer term. + + A.2 AVD Production ServiceChangeParm: added + serviceChangeInfo term. + + A.3 AVD Production digitMapLetter: added "T" for start + timer. + + A.3 Edit Production pathDomainName: added "*" and ".". + + B.2 Edit Production message: version changed to 2 in comment. + + B.2 Post- Production transactionAck: TransactionID + edit capitalized. + + B.2 PTT Productions contextID, terminationID, and + terminationIDList reordered: grouped with + TransactionID to make fundamental productions more + visible. + + B.2 AVD Production MuxType: added Nx64kToken. + + B.2 AVD Production digitMapValue: added ["Z" COLON Timer + COMMA] alternative. + + B.2 AVD Production digitMapLetter: added "T" (start timer) + alternative. + + B.2 AVD Production auditItem: added indAudterminationAudit + term. + + B.2 AVD New productions indAudterminationAudit through + indAudpackagesDescriptor added for more specific + auditing. + + B.2 AVD Production ServiceChangeParm: term auditItem added + to indicate nature of capability change. + + B.2 AVD Production topologyTriple: optional eventStream + (sic) term added. + + + + Groves et al Expires - October 2003 [Page 217] + Megaco Protocol version 2 April 2003 + + + B.2 AVD New production Nx64kToken. + + C.1 Edit ACodec: reference corrected to Q.765.5 + + E.2.1 Edit Editorial correction to informal name of property + maxNumberOfContexts. + + E.2.1 AVD Added properties to govern TransactionPending + retransmissions. + + E.4 Edit Added extend-only package usage indicator. + + E.7.3 Edit Added "recording" qualifier to warning tone. + table + + E.11.2 Edit For quality alert event: replaced "property" with + "event" in description. + + Appendix Edit Expanded on codec examples. Added reference to IANA + I second registry for RTP payload types. + para + + + + + + + + + + + + + INTELLECTUAL PROPERTY RIGHTS + + The ITU draws attention to the possibility that the practice or + implementation of this Recommendation may involve the use of a + claimed Intellectual Property Right. The ITU takes no position + concerning the evidence, validity or applicability of claimed + Intellectual Property Rights, whether asserted by ITU members or + others outside of the Recommendation development process. + + As of the date of approval of this Recommendation, the ITU had + received notice of intellectual property, protected by patents, which + may be required to implement this Recommendation. However, + implementors are cautioned that this may not represent the latest + information and are therefore strongly urged to consult the TSB + patent database. + + + + Groves et al Expires - October 2003 [Page 218] + Megaco version 2 April 2003 + + + The IETF has also received notice of intellectual property claims + relating to Megaco/H.248.1. Please consult the IETF IPR + announcements at http://www.ietf.org/ipr.html. + + + Acknowledgments + + Megaco/H.248.1 is the result of hard work by many people in both the + IETF and in ITU-T Study Group 16. This section records those who + played a prominent role in ITU-T meetings, on the Megaco list, or + both. + + Megaco/H.248 owes a large initial debt to the MGCP protocol (RFC + 2705), and thus to its authors, Mauricio Arango, Andrew Dugan, Ike + Elliott, Christian Huitema, and Scott Pickett. Flemming Andreasen + does not appear on this list of authors, but was a major contributor + to the development of both MGCP and Megaco/H.248.1. RFC 3435 (MGCP) + has an extensive acknowledgement of many other people who worked on + media gateway control before Megaco got started. + + The authors of the first Megaco RFCs (2885, then 3015) were Fernando + Cuervo, Nancy Greene, Abdallah Rayhan, Christian Huitema, Brian + Rosen, and John Segers. Christian Groves conceived and was editor of + Annex C. The people most active on the Megaco list in the period + leading up to the completion of RFC 2885 were Brian Rosen, Tom + Taylor, Nancy Greene, Christian Huitema, Matt Holdrege, Chip Sharp, + John Segers, Michael Thomas, Henry Sinnreich, and Paul Sijben. The + people who sacrificed sleep and meals to complete the massive amount + of work required in the decisive Study Group 16 meeting of February, + 2000, were Michael Brown, Ranga Dendi, Larry Forni, Glen Freundlich, + Christian Groves, Alf Heidemark, Steve Magnell, Selvam Rengasami, + Rich Rubin, Klaus Sambor, John Segers, Chip Sharp, Tom Taylor, and + Stephen Terrill. + + The most active people on the Megaco list in the period since the + February 2000 have been Tom Taylor, Brian Rosen, Christian Groves, + Madhu Babu Brahmanapally, Troy Cauble, Terry Anderson, Chuong Nguyen, + and Kevin Boyle, but many other people have been regular + contributors. Brian Rosen did tremendous service in putting together + the Megaco interoperability tests. On the Study Group 16 side, the + editorial team for the final document in February, 2002 included + Christian Groves, Marcello Pantaleo, Terry Anderson, Peter Leis, + Kevin Boyle, and Tom Taylor. + + Tom Taylor as Megaco Chair managed the day to day operation of the + Megaco list, with Brian Rosen taking an equal share of the burden for + most of the last three years. Glen Freundlich as the Study Group 16 + Rapporteur ran the ITU-T meetings and ensured that all of the work at + hand was completed. Without Glen's determination the Megaco/H.248 + + + Groves et al Expires - October 2003 [Page 219] + Megaco version 2 April 2003 + + + standard would have taken at least half a year longer to produce. + Christian Groves filled in ably as Rapporteur when Glen could no + longer take part. + + + Authors' Addresses + + Terry L Anderson + Lucent Technologies/INS/Voice Over IP Access Networks + Rm 2G-219A, 101 Crawfords Corner Rd, Holmdel, NJ 07733-3030 + Phone: +1.732.949.5628 + Email: tla@lucent.com + + Christian Groves + Ericsson AsiaPacificLab Australia + 37/360 Elizabeth St + Melbourne, Victoria 3000 + Australia + Email: Christian.Groves@ericsson.com.au + + Marcello Pantaleo + Ericsson Eurolab Deutschland + Ericsson Allee 1 + 52134 Herzogenrath, Germany + e-mail: Marcello.Pantaleo@eed.ericsson.se + + Tom Taylor + Nortel Networks + 1852 Lorraine Ave, + Ottawa, Ontario + Canada K1H 6Z8 + Phone: +1 613 736 0961 + E-mail: taylor@nortelnetworks.com + + + + + + + + + + + + + + + + + + + Groves et al Expires - October 2003 [Page 220] \ No newline at end of file diff --git a/lib/megaco/doc/standard/implementors_guide_v10-13.pdf b/lib/megaco/doc/standard/implementors_guide_v10-13.pdf new file mode 100644 index 0000000000..c743c808a9 Binary files /dev/null and b/lib/megaco/doc/standard/implementors_guide_v10-13.pdf differ diff --git a/lib/megaco/doc/standard/rfc2327.txt b/lib/megaco/doc/standard/rfc2327.txt new file mode 100644 index 0000000000..ce77de6128 --- /dev/null +++ b/lib/megaco/doc/standard/rfc2327.txt @@ -0,0 +1,2355 @@ + + + + + + +Network Working Group M. Handley +Request for Comments: 2327 V. Jacobson +Category: Standards Track ISI/LBNL + April 1998 + + + SDP: Session Description Protocol + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + This document defines the Session Description Protocol, SDP. SDP is + intended for describing multimedia sessions for the purposes of + session announcement, session invitation, and other forms of + multimedia session initiation. + + This document is a product of the Multiparty Multimedia Session + Control (MMUSIC) working group of the Internet Engineering Task + Force. Comments are solicited and should be addressed to the working + group's mailing list at confctrl@isi.edu and/or the authors. + +1. Introduction + + On the Internet multicast backbone (Mbone), a session directory tool + is used to advertise multimedia conferences and communicate the + conference addresses and conference tool-specific information + necessary for participation. This document defines a session + description protocol for this purpose, and for general real-time + multimedia session description purposes. This memo does not describe + multicast address allocation or the distribution of SDP messages in + detail. These are described in accompanying memos. SDP is not + intended for negotiation of media encodings. + + + + + + + + +Handley & Jacobson Standards Track [Page 1] + +RFC 2327 SDP April 1998 + + +2. Background + + The Mbone is the part of the internet that supports IP multicast, and + thus permits efficient many-to-many communication. It is used + extensively for multimedia conferencing. Such conferences usually + have the property that tight coordination of conference membership is + not necessary; to receive a conference, a user at an Mbone site only + has to know the conference's multicast group address and the UDP + ports for the conference data streams. + + Session directories assist the advertisement of conference sessions + and communicate the relevant conference setup information to + prospective participants. SDP is designed to convey such information + to recipients. SDP is purely a format for session description - it + does not incorporate a transport protocol, and is intended to use + different transport protocols as appropriate including the Session + Announcement Protocol [4], Session Initiation Protocol [11], Real- + Time Streaming Protocol [12], electronic mail using the MIME + extensions, and the Hypertext Transport Protocol. + + SDP is intended to be general purpose so that it can be used for a + wider range of network environments and applications than just + multicast session directories. However, it is not intended to + support negotiation of session content or media encodings - this is + viewed as outside the scope of session description. + +3. Glossary of Terms + + The following terms are used in this document, and have specific + meaning within the context of this document. + + Conference + A multimedia conference is a set of two or more communicating users + along with the software they are using to communicate. + + Session + A multimedia session is a set of multimedia senders and receivers + and the data streams flowing from senders to receivers. A + multimedia conference is an example of a multimedia session. + + Session Advertisement + See session announcement. + + Session Announcement + A session announcement is a mechanism by which a session + description is conveyed to users in a proactive fashion, i.e., the + session description was not explicitly requested by the user. + + + + +Handley & Jacobson Standards Track [Page 2] + +RFC 2327 SDP April 1998 + + + Session Description + A well defined format for conveying sufficient information to + discover and participate in a multimedia session. + +3.1. Terminology + + 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 RFC 2119. + +4. SDP Usage + +4.1. Multicast Announcements + + SDP is a session description protocol for multimedia sessions. A + common mode of usage is for a client to announce a conference session + by periodically multicasting an announcement packet to a well known + multicast address and port using the Session Announcement Protocol + (SAP). + + SAP packets are UDP packets with the following format: + + |--------------------| + | SAP header | + |--------------------| + | text payload | + |////////// + + + The header is the Session Announcement Protocol header. SAP is + described in more detail in a companion memo [4] + + The text payload is an SDP session description, as described in this + memo. The text payload should be no greater than 1 Kbyte in length. + If announced by SAP, only one session announcement is permitted in a + single packet. + +4.2. Email and WWW Announcements + + Alternative means of conveying session descriptions include + electronic mail and the World Wide Web. For both email and WWW + distribution, the use of the MIME content type "application/sdp" + should be used. This enables the automatic launching of applications + for participation in the session from the WWW client or mail reader + in a standard manner. + + + + + + +Handley & Jacobson Standards Track [Page 3] + +RFC 2327 SDP April 1998 + + + Note that announcements of multicast sessions made only via email or + the World Wide Web (WWW) do not have the property that the receiver + of a session announcement can necessarily receive the session because + the multicast sessions may be restricted in scope, and access to the + WWW server or reception of email is possible outside this scope. SAP + announcements do not suffer from this mismatch. + +5. Requirements and Recommendations + + The purpose of SDP is to convey information about media streams in + multimedia sessions to allow the recipients of a session description + to participate in the session. SDP is primarily intended for use in + an internetwork, although it is sufficiently general that it can + describe conferences in other network environments. + + A multimedia session, for these purposes, is defined as a set of + media streams that exist for some duration of time. Media streams + can be many-to-many. The times during which the session is active + need not be continuous. + + Thus far, multicast based sessions on the Internet have differed from + many other forms of conferencing in that anyone receiving the traffic + can join the session (unless the session traffic is encrypted). In + such an environment, SDP serves two primary purposes. It is a means + to communicate the existence of a session, and is a means to convey + sufficient information to enable joining and participating in the + session. In a unicast environment, only the latter purpose is likely + to be relevant. + + Thus SDP includes: + + o Session name and purpose + + o Time(s) the session is active + + o The media comprising the session + + o Information to receive those media (addresses, ports, formats and + so on) + + As resources necessary to participate in a session may be limited, + some additional information may also be desirable: + + o Information about the bandwidth to be used by the conference + + o Contact information for the person responsible for the session + + + + + +Handley & Jacobson Standards Track [Page 4] + +RFC 2327 SDP April 1998 + + + In general, SDP must convey sufficient information to be able to join + a session (with the possible exception of encryption keys) and to + announce the resources to be used to non-participants that may need + to know. + +5.1. Media Information + + SDP includes: + + o The type of media (video, audio, etc) + + o The transport protocol (RTP/UDP/IP, H.320, etc) + + o The format of the media (H.261 video, MPEG video, etc) + + For an IP multicast session, the following are also conveyed: + + o Multicast address for media + + o Transport Port for media + + This address and port are the destination address and destination + port of the multicast stream, whether being sent, received, or both. + + For an IP unicast session, the following are conveyed: + + o Remote address for media + + o Transport port for contact address + + The semantics of this address and port depend on the media and + transport protocol defined. By default, this is the remote address + and remote port to which data is sent, and the remote address and + local port on which to receive data. However, some media may define + to use these to establish a control channel for the actual media + flow. + +5.2. Timing Information + + Sessions may either be bounded or unbounded in time. Whether or not + they are bounded, they may be only active at specific times. + + SDP can convey: + + o An arbitrary list of start and stop times bounding the session + + o For each bound, repeat times such as "every Wednesday at 10am for + one hour" + + + +Handley & Jacobson Standards Track [Page 5] + +RFC 2327 SDP April 1998 + + + This timing information is globally consistent, irrespective of local + time zone or daylight saving time. + +5.3. Private Sessions + + It is possible to create both public sessions and private sessions. + Private sessions will typically be conveyed by encrypting the session + description to distribute it. The details of how encryption is + performed are dependent on the mechanism used to convey SDP - see [4] + for how this is done for session announcements. + + If a session announcement is private it is possible to use that + private announcement to convey encryption keys necessary to decode + each of the media in a conference, including enough information to + know which encryption scheme is used for each media. + +5.4. Obtaining Further Information about a Session + + A session description should convey enough information to decide + whether or not to participate in a session. SDP may include + additional pointers in the form of Universal Resources Identifiers + (URIs) for more information about the session. + +5.5. Categorisation + + When many session descriptions are being distributed by SAP or any + other advertisement mechanism, it may be desirable to filter + announcements that are of interest from those that are not. SDP + supports a categorisation mechanism for sessions that is capable of + being automated. + +5.6. Internationalization + + The SDP specification recommends the use of the ISO 10646 character + sets in the UTF-8 encoding (RFC 2044) to allow many different + languages to be represented. However, to assist in compact + representations, SDP also allows other character sets such as ISO + 8859-1 to be used when desired. Internationalization only applies to + free-text fields (session name and background information), and not + to SDP as a whole. + +6. SDP Specification + + SDP session descriptions are entirely textual using the ISO 10646 + character set in UTF-8 encoding. SDP field names and attributes names + use only the US-ASCII subset of UTF-8, but textual fields and + attribute values may use the full ISO 10646 character set. The + textual form, as opposed to a binary encoding such as ASN/1 or XDR, + + + +Handley & Jacobson Standards Track [Page 6] + +RFC 2327 SDP April 1998 + + + was chosen to enhance portability, to enable a variety of transports + to be used (e.g, session description in a MIME email message) and to + allow flexible, text-based toolkits (e.g., Tcl/Tk ) to be used to + generate and to process session descriptions. However, since the + total bandwidth allocated to all SAP announcements is strictly + limited, the encoding is deliberately compact. Also, since + announcements may be transported via very unreliable means (e.g., + email) or damaged by an intermediate caching server, the encoding was + designed with strict order and formatting rules so that most errors + would result in malformed announcements which could be detected + easily and discarded. This also allows rapid discarding of encrypted + announcements for which a receiver does not have the correct key. + + An SDP session description consists of a number of lines of text of + the form = is always exactly one character and is + case-significant. is a structured text string whose format + depends on . It also will be case-significant unless a + specific field defines otherwise. Whitespace is not permitted either + side of the `=' sign. In general is either a number of fields + delimited by a single space character or a free format string. + + A session description consists of a session-level description + (details that apply to the whole session and all media streams) and + optionally several media-level descriptions (details that apply onto + to a single media stream). + + An announcement consists of a session-level section followed by zero + or more media-level sections. The session-level part starts with a + `v=' line and continues to the first media-level section. The media + description starts with an `m=' line and continues to the next media + description or end of the whole session description. In general, + session-level values are the default for all media unless overridden + by an equivalent media-level value. + + When SDP is conveyed by SAP, only one session description is allowed + per packet. When SDP is conveyed by other means, many SDP session + descriptions may be concatenated together (the `v=' line indicating + the start of a session description terminates the previous + description). Some lines in each description are required and some + are optional but all must appear in exactly the order given here (the + fixed order greatly enhances error detection and allows for a simple + parser). Optional items are marked with a `*'. + +Session description + v= (protocol version) + o= (owner/creator and session identifier). + s= (session name) + i=* (session information) + + + +Handley & Jacobson Standards Track [Page 7] + +RFC 2327 SDP April 1998 + + + u=* (URI of description) + e=* (email address) + p=* (phone number) + c=* (connection information - not required if included in all media) + b=* (bandwidth information) + One or more time descriptions (see below) + z=* (time zone adjustments) + k=* (encryption key) + a=* (zero or more session attribute lines) + Zero or more media descriptions (see below) + +Time description + t= (time the session is active) + r=* (zero or more repeat times) + +Media description + m= (media name and transport address) + i=* (media title) + c=* (connection information - optional if included at session-level) + b=* (bandwidth information) + k=* (encryption key) + a=* (zero or more media attribute lines) + + The set of `type' letters is deliberately small and not intended to + be extensible -- SDP parsers must completely ignore any announcement + that contains a `type' letter that it does not understand. The + `attribute' mechanism ("a=" described below) is the primary means for + extending SDP and tailoring it to particular applications or media. + Some attributes (the ones listed in this document) have a defined + meaning but others may be added on an application-, media- or + session-specific basis. A session directory must ignore any + attribute it doesn't understand. + + The connection (`c=') and attribute (`a=') information in the + session-level section applies to all the media of that session unless + overridden by connection information or an attribute of the same name + in the media description. For instance, in the example below, each + media behaves as if it were given a `recvonly' attribute. + + An example SDP description is: + + v=0 + o=mhandley 2890844526 2890842807 IN IP4 126.16.64.4 + s=SDP Seminar + i=A Seminar on the session description protocol + u=http://www.cs.ucl.ac.uk/staff/M.Handley/sdp.03.ps + e=mjh@isi.edu (Mark Handley) + c=IN IP4 224.2.17.12/127 + + + +Handley & Jacobson Standards Track [Page 8] + +RFC 2327 SDP April 1998 + + + t=2873397496 2873404696 + a=recvonly + m=audio 49170 RTP/AVP 0 + m=video 51372 RTP/AVP 31 + m=application 32416 udp wb + a=orient:portrait + + Text records such as the session name and information are bytes + strings which may contain any byte with the exceptions of 0x00 (Nul), + 0x0a (ASCII newline) and 0x0d (ASCII carriage return). The sequence + CRLF (0x0d0a) is used to end a record, although parsers should be + tolerant and also accept records terminated with a single newline + character. By default these byte strings contain ISO-10646 + characters in UTF-8 encoding, but this default may be changed using + the `charset' attribute. + + Protocol Version + + v=0 + + The "v=" field gives the version of the Session Description Protocol. + There is no minor version number. + + Origin + + o=
+
+ + The "o=" field gives the originator of the session (their username + and the address of the user's host) plus a session id and session + version number. + + is the user's login on the originating host, or it is "-" + if the originating host does not support the concept of user ids. + must not contain spaces. is a numeric string + such that the tuple of , , , +
and
form a globally unique identifier for + the session. + + The method of allocation is up to the creating tool, but + it has been suggested that a Network Time Protocol (NTP) timestamp be + used to ensure uniqueness [1]. + + is a version number for this announcement. It is needed + for proxy announcements to detect which of several announcements for + the same session is the most recent. Again its usage is up to the + + + + + +Handley & Jacobson Standards Track [Page 9] + +RFC 2327 SDP April 1998 + + + creating tool, so long as is increased when a modification + is made to the session data. Again, it is recommended (but not + mandatory) that an NTP timestamp is used. + + is a text string giving the type of network. + Initially "IN" is defined to have the meaning "Internet".
is a text string giving the type of the address that follows. + Initially "IP4" and "IP6" are defined.
is the globally + unique address of the machine from which the session was created. + For an address type of IP4, this is either the fully-qualified domain + name of the machine, or the dotted-decimal representation of the IP + version 4 address of the machine. For an address type of IP6, this + is either the fully-qualified domain name of the machine, or the + compressed textual representation of the IP version 6 address of the + machine. For both IP4 and IP6, the fully-qualified domain name is + the form that SHOULD be given unless this is unavailable, in which + case the globally unique address may be substituted. A local IP + address MUST NOT be used in any context where the SDP description + might leave the scope in which the address is meaningful. + + In general, the "o=" field serves as a globally unique identifier for + this version of this session description, and the subfields excepting + the version taken together identify the session irrespective of any + modifications. + + Session Name + + s= + + The "s=" field is the session name. There must be one and only one + "s=" field per session description, and it must contain ISO 10646 + characters (but see also the `charset' attribute below). + + Session and Media Information + + i= + + The "i=" field is information about the session. There may be at + most one session-level "i=" field per session description, and at + most one "i=" field per media. Although it may be omitted, this is + discouraged for session announcements, and user interfaces for + composing sessions should require text to be entered. If it is + present it must contain ISO 10646 characters (but see also the + `charset' attribute below). + + A single "i=" field can also be used for each media definition. In + media definitions, "i=" fields are primarily intended for labeling + media streams. As such, they are most likely to be useful when a + + + +Handley & Jacobson Standards Track [Page 10] + +RFC 2327 SDP April 1998 + + + single session has more than one distinct media stream of the same + media type. An example would be two different whiteboards, one for + slides and one for feedback and questions. + + URI + + u= + + o A URI is a Universal Resource Identifier as used by WWW clients + + o The URI should be a pointer to additional information about the + conference + + o This field is optional, but if it is present it should be specified + before the first media field + + o No more than one URI field is allowed per session description + + + Email Address and Phone Number + + e= + p= + + o These specify contact information for the person responsible for + the conference. This is not necessarily the same person that + created the conference announcement. + + o Either an email field or a phone field must be specified. + Additional email and phone fields are allowed. + + o If these are present, they should be specified before the first + media field. + + o More than one email or phone field can be given for a session + description. + + o Phone numbers should be given in the conventional international + + format - preceded by a "+ and the international country code. + There must be a space or a hyphen ("-") between the country code + and the rest of the phone number. Spaces and hyphens may be used + to split up a phone field to aid readability if desired. For + example: + + p=+44-171-380-7777 or p=+1 617 253 6011 + + + + + +Handley & Jacobson Standards Track [Page 11] + +RFC 2327 SDP April 1998 + + + o Both email addresses and phone numbers can have an optional free + text string associated with them, normally giving the name of the + person who may be contacted. This should be enclosed in + parenthesis if it is present. For example: + + e=mjh@isi.edu (Mark Handley) + + The alternative RFC822 name quoting convention is also allowed for + both email addresses and phone numbers. For example, + + e=Mark Handley + + The free text string should be in the ISO-10646 character set with + UTF-8 encoding, or alternatively in ISO-8859-1 or other encodings + if the appropriate charset session-level attribute is set. + + Connection Data + + c=
+ + The "c=" field contains connection data. + + A session announcement must contain one "c=" field in each media + description (see below) or a "c=" field at the session-level. It may + contain a session-level "c=" field and one additional "c=" field per + media description, in which case the per-media values override the + session-level settings for the relevant media. + + The first sub-field is the network type, which is a text string + giving the type of network. Initially "IN" is defined to have the + meaning "Internet". + + The second sub-field is the address type. This allows SDP to be used + for sessions that are not IP based. Currently only IP4 is defined. + + The third sub-field is the connection address. Optional extra + subfields may be added after the connection address depending on the + value of the
field. + + For IP4 addresses, the connection address is defined as follows: + + o Typically the connection address will be a class-D IP multicast + + group address. If the session is not multicast, then the + connection address contains the fully-qualified domain name or the + unicast IP address of the expected data source or data relay or + data sink as determined by additional attribute fields. It is not + expected that fully-qualified domain names or unicast addresses + + + +Handley & Jacobson Standards Track [Page 12] + +RFC 2327 SDP April 1998 + + + will be given in a session description that is communicated by a + multicast announcement, though this is not prohibited. If a + unicast data stream is to pass through a network address + translator, the use of a fully-qualified domain name rather than an + unicast IP address is RECOMMENDED. In other cases, the use of an + IP address to specify a particular interface on a multi-homed host + might be required. Thus this specification leaves the decision as + to which to use up to the individual application, but all + applications MUST be able to cope with receiving both formats. + + o Conferences using an IP multicast connection address must also have + a time to live (TTL) value present in addition to the multicast + address. The TTL and the address together define the scope with + which multicast packets sent in this conference will be sent. TTL + values must be in the range 0-255. + + The TTL for the session is appended to the address using a slash as + a separator. An example is: + + c=IN IP4 224.2.1.1/127 + + Hierarchical or layered encoding schemes are data streams where the + encoding from a single media source is split into a number of + layers. The receiver can choose the desired quality (and hence + bandwidth) by only subscribing to a subset of these layers. Such + layered encodings are normally transmitted in multiple multicast + groups to allow multicast pruning. This technique keeps unwanted + traffic from sites only requiring certain levels of the hierarchy. + For applications requiring multiple multicast groups, we allow the + following notation to be used for the connection address: + + // + + If the number of addresses is not given it is assumed to be one. + Multicast addresses so assigned are contiguously allocated above + the base address, so that, for example: + + c=IN IP4 224.2.1.1/127/3 + + would state that addresses 224.2.1.1, 224.2.1.2 and 224.2.1.3 are + to be used at a ttl of 127. This is semantically identical to + including multiple "c=" lines in a media description: + + c=IN IP4 224.2.1.1/127 + c=IN IP4 224.2.1.2/127 + c=IN IP4 224.2.1.3/127 + + + + + +Handley & Jacobson Standards Track [Page 13] + +RFC 2327 SDP April 1998 + + + Multiple addresses or "c=" lines can only be specified on a per- + media basis, and not for a session-level "c=" field. + + It is illegal for the slash notation described above to be used for + IP unicast addresses. + + Bandwidth + + b=: + + o This specifies the proposed bandwidth to be used by the session or + media, and is optional. + + o is in kilobits per second + + o is a single alphanumeric word giving the meaning of the + bandwidth figure. + + o Two modifiers are initially defined: + + CT Conference Total: An implicit maximum bandwidth is associated with + each TTL on the Mbone or within a particular multicast + administrative scope region (the Mbone bandwidth vs. TTL limits are + given in the MBone FAQ). If the bandwidth of a session or media in + a session is different from the bandwidth implicit from the scope, + a `b=CT:...' line should be supplied for the session giving the + proposed upper limit to the bandwidth used. The primary purpose of + this is to give an approximate idea as to whether two or more + conferences can co-exist simultaneously. + + AS Application-Specific Maximum: The bandwidth is interpreted to be + application-specific, i.e., will be the application's concept of + maximum bandwidth. Normally this will coincide with what is set on + the application's "maximum bandwidth" control if applicable. + + Note that CT gives a total bandwidth figure for all the media at + all sites. AS gives a bandwidth figure for a single media at a + single site, although there may be many sites sending + simultaneously. + + o Extension Mechanism: Tool writers can define experimental bandwidth + modifiers by prefixing their modifier with "X-". For example: + + b=X-YZ:128 + + SDP parsers should ignore bandwidth fields with unknown modifiers. + Modifiers should be alpha-numeric and, although no length limit is + given, they are recommended to be short. + + + +Handley & Jacobson Standards Track [Page 14] + +RFC 2327 SDP April 1998 + + + Times, Repeat Times and Time Zones + + t= + + o "t=" fields specify the start and stop times for a conference + session. Multiple "t=" fields may be used if a session is active + at multiple irregularly spaced times; each additional "t=" field + specifies an additional period of time for which the session will + be active. If the session is active at regular times, an "r=" + field (see below) should be used in addition to and following a + "t=" field - in which case the "t=" field specifies the start and + stop times of the repeat sequence. + + o The first and second sub-fields give the start and stop times for + the conference respectively. These values are the decimal + representation of Network Time Protocol (NTP) time values in + seconds [1]. To convert these values to UNIX time, subtract + decimal 2208988800. + + o If the stop-time is set to zero, then the session is not bounded, + though it will not become active until after the start-time. If + the start-time is also zero, the session is regarded as permanent. + + User interfaces should strongly discourage the creation of + unbounded and permanent sessions as they give no information about + when the session is actually going to terminate, and so make + scheduling difficult. + + The general assumption may be made, when displaying unbounded + sessions that have not timed out to the user, that an unbounded + session will only be active until half an hour from the current + time or the session start time, whichever is the later. If + behaviour other than this is required, an end-time should be given + and modified as appropriate when new information becomes available + about when the session should really end. + + Permanent sessions may be shown to the user as never being active + unless there are associated repeat times which state precisely when + the session will be active. In general, permanent sessions should + not be created for any session expected to have a duration of less + than 2 months, and should be discouraged for sessions expected to + have a duration of less than 6 months. + + r= + + o "r=" fields specify repeat times for a session. For example, if + a session is active at 10am on Monday and 11am on Tuesday for one + + + +Handley & Jacobson Standards Track [Page 15] + +RFC 2327 SDP April 1998 + + + hour each week for three months, then the in the + corresponding "t=" field would be the NTP representation of 10am on + the first Monday, the would be 1 week, the + would be 1 hour, and the offsets would be zero + and 25 hours. The corresponding "t=" field stop time would be the + NTP representation of the end of the last session three months + later. By default all fields are in seconds, so the "r=" and "t=" + fields might be: + + t=3034423619 3042462419 + r=604800 3600 0 90000 + + To make announcements more compact, times may also be given in units + of days, hours or minutes. The syntax for these is a number + immediately followed by a single case-sensitive character. + Fractional units are not allowed - a smaller unit should be used + instead. The following unit specification characters are allowed: + + d - days (86400 seconds) + h - minutes (3600 seconds) + m - minutes (60 seconds) + s - seconds (allowed for completeness but not recommended) + + Thus, the above announcement could also have been written: + + r=7d 1h 0 25h + + Monthly and yearly repeats cannot currently be directly specified + with a single SDP repeat time - instead separate "t" fields should + be used to explicitly list the session times. + + z= .... + + o To schedule a repeated session which spans a change from daylight- + saving time to standard time or vice-versa, it is necessary to + specify offsets from the base repeat times. This is required + because different time zones change time at different times of day, + different countries change to or from daylight time on different + dates, and some countries do not have daylight saving time at all. + + Thus in order to schedule a session that is at the same time winter + and summer, it must be possible to specify unambiguously by whose + time zone a session is scheduled. To simplify this task for + receivers, we allow the sender to specify the NTP time that a time + zone adjustment happens and the offset from the time when the + session was first scheduled. The "z" field allows the sender to + specify a list of these adjustment times and offsets from the base + time. + + + +Handley & Jacobson Standards Track [Page 16] + +RFC 2327 SDP April 1998 + + + An example might be: + + z=2882844526 -1h 2898848070 0 + + This specifies that at time 2882844526 the time base by which the + session's repeat times are calculated is shifted back by 1 hour, + and that at time 2898848070 the session's original time base is + restored. Adjustments are always relative to the specified start + time - they are not cumulative. + + o If a session is likely to last several years, it is expected + that + the session announcement will be modified periodically rather than + transmit several years worth of adjustments in one announcement. + + Encryption Keys + + k= + k=: + + o The session description protocol may be used to convey encryption + keys. A key field is permitted before the first media entry (in + which case it applies to all media in the session), or for each + media entry as required. + + o The format of keys and their usage is outside the scope of this + document, but see [3]. + + o The method indicates the mechanism to be used to obtain a usable + key by external means, or from the encoded encryption key given. + + The following methods are defined: + + k=clear: + The encryption key (as described in [3] for RTP media streams + under the AV profile) is included untransformed in this key + field. + + k=base64: + The encryption key (as described in [3] for RTP media streams + under the AV profile) is included in this key field but has been + base64 encoded because it includes characters that are + prohibited in SDP. + + k=uri: + A Universal Resource Identifier as used by WWW clients is + included in this key field. The URI refers to the data + containing the key, and may require additional authentication + + + +Handley & Jacobson Standards Track [Page 17] + +RFC 2327 SDP April 1998 + + + before the key can be returned. When a request is made to the + given URI, the MIME content-type of the reply specifies the + encoding for the key in the reply. The key should not be + obtained until the user wishes to join the session to reduce + synchronisation of requests to the WWW server(s). + + k=prompt + No key is included in this SDP description, but the session or + media stream referred to by this key field is encrypted. The + user should be prompted for the key when attempting to join the + session, and this user-supplied key should then be used to + decrypt the media streams. + + Attributes + + a= + a=: + + Attributes are the primary means for extending SDP. Attributes may + be defined to be used as "session-level" attributes, "media-level" + attributes, or both. + + A media description may have any number of attributes ("a=" fields) + which are media specific. These are referred to as "media-level" + attributes and add information about the media stream. Attribute + fields can also be added before the first media field; these + "session-level" attributes convey additional information that applies + to the conference as a whole rather than to individual media; an + example might be the conference's floor control policy. + + Attribute fields may be of two forms: + + o property attributes. A property attribute is simply of the form + "a=". These are binary attributes, and the presence of the + attribute conveys that the attribute is a property of the session. + An example might be "a=recvonly". + + o value attributes. A value attribute is of the form + "a=:". An example might be that a whiteboard + could have the value attribute "a=orient:landscape" + + Attribute interpretation depends on the media tool being invoked. + Thus receivers of session descriptions should be configurable in + their interpretation of announcements in general and of attributes in + particular. + + Attribute names must be in the US-ASCII subset of ISO-10646/UTF-8. + + + + +Handley & Jacobson Standards Track [Page 18] + +RFC 2327 SDP April 1998 + + + Attribute values are byte strings, and MAY use any byte value except + 0x00 (Nul), 0x0A (LF), and 0x0D (CR). By default, attribute values + are to be interpreted as in ISO-10646 character set with UTF-8 + encoding. Unlike other text fields, attribute values are NOT + normally affected by the `charset' attribute as this would make + comparisons against known values problematic. However, when an + attribute is defined, it can be defined to be charset-dependent, in + which case it's value should be interpreted in the session charset + rather than in ISO-10646. + + Attributes that will be commonly used can be registered with IANA + (see Appendix B). Unregistered attributes should begin with "X-" to + prevent inadvertent collision with registered attributes. In either + case, if an attribute is received that is not understood, it should + simply be ignored by the receiver. + + Media Announcements + + m= + + A session description may contain a number of media descriptions. + Each media description starts with an "m=" field, and is terminated + by either the next "m=" field or by the end of the session + description. A media field also has several sub-fields: + + o The first sub-field is the media type. Currently defined media are + "audio", "video", "application", "data" and "control", though this + list may be extended as new communication modalities emerge (e.g., + telepresense). The difference between "application" and "data" is + that the former is a media flow such as whiteboard information, and + the latter is bulk-data transfer such as multicasting of program + executables which will not typically be displayed to the user. + "control" is used to specify an additional conference control + channel for the session. + + o The second sub-field is the transport port to which the media + stream will be sent. The meaning of the transport port depends on + the network being used as specified in the relevant "c" field and + on the transport protocol defined in the third sub-field. Other + ports used by the media application (such as the RTCP port, see + [2]) should be derived algorithmically from the base media port. + + Note: For transports based on UDP, the value should be in the range + 1024 to 65535 inclusive. For RTP compliance it should be an even + number. + + + + + + +Handley & Jacobson Standards Track [Page 19] + +RFC 2327 SDP April 1998 + + + For applications where hierarchically encoded streams are being + sent to a unicast address, it may be necessary to specify multiple + transport ports. This is done using a similar notation to that + used for IP multicast addresses in the "c=" field: + + m= / + + In such a case, the ports used depend on the transport protocol. + For RTP, only the even ports are used for data and the + corresponding one-higher odd port is used for RTCP. For example: + + m=video 49170/2 RTP/AVP 31 + + would specify that ports 49170 and 49171 form one RTP/RTCP pair and + 49172 and 49173 form the second RTP/RTCP pair. RTP/AVP is the + transport protocol and 31 is the format (see below). + + It is illegal for both multiple addresses to be specified in the + "c=" field and for multiple ports to be specified in the "m=" field + in the same session description. + + o The third sub-field is the transport protocol. The transport + protocol values are dependent on the address-type field in the "c=" + fields. Thus a "c=" field of IP4 defines that the transport + protocol runs over IP4. For IP4, it is normally expected that most + media traffic will be carried as RTP over UDP. The following + transport protocols are preliminarily defined, but may be extended + through registration of new protocols with IANA: + + - RTP/AVP - the IETF's Realtime Transport Protocol using the + Audio/Video profile carried over UDP. + + - udp - User Datagram Protocol + + If an application uses a single combined proprietary media format + and transport protocol over UDP, then simply specifying the + transport protocol as udp and using the format field to distinguish + the combined protocol is recommended. If a transport protocol is + used over UDP to carry several distinct media types that need to be + distinguished by a session directory, then specifying the transport + protocol and media format separately is necessary. RTP is an + example of a transport-protocol that carries multiple payload + formats that must be distinguished by the session directory for it + to know how to start appropriate tools, relays, mixers or + recorders. + + + + + + +Handley & Jacobson Standards Track [Page 20] + +RFC 2327 SDP April 1998 + + + The main reason to specify the transport-protocol in addition to + the media format is that the same standard media formats may be + carried over different transport protocols even when the network + protocol is the same - a historical example is vat PCM audio and + RTP PCM audio. In addition, relays and monitoring tools that are + transport-protocol-specific but format-independent are possible. + + For RTP media streams operating under the RTP Audio/Video Profile + [3], the protocol field is "RTP/AVP". Should other RTP profiles be + defined in the future, their profiles will be specified in the same + way. For example, the protocol field "RTP/XYZ" would specify RTP + operating under a profile whose short name is "XYZ". + + o The fourth and subsequent sub-fields are media formats. For audio + and video, these will normally be a media payload type as defined + in the RTP Audio/Video Profile. + + When a list of payload formats is given, this implies that all of + these formats may be used in the session, but the first of these + formats is the default format for the session. + + For media whose transport protocol is not RTP or UDP the format + field is protocol specific. Such formats should be defined in an + additional specification document. + + For media whose transport protocol is RTP, SDP can be used to + provide a dynamic binding of media encoding to RTP payload type. + The encoding names in the RTP AV Profile do not specify unique + audio encodings (in terms of clock rate and number of audio + channels), and so they are not used directly in SDP format fields. + Instead, the payload type number should be used to specify the + format for static payload types and the payload type number along + with additional encoding information should be used for dynamically + allocated payload types. + + An example of a static payload type is u-law PCM coded single + channel audio sampled at 8KHz. This is completely defined in the + RTP Audio/Video profile as payload type 0, so the media field for + such a stream sent to UDP port 49232 is: + + m=video 49232 RTP/AVP 0 + + An example of a dynamic payload type is 16 bit linear encoded + stereo audio sampled at 16KHz. If we wish to use dynamic RTP/AVP + payload type 98 for such a stream, additional information is + required to decode it: + + m=video 49232 RTP/AVP 98 + + + +Handley & Jacobson Standards Track [Page 21] + +RFC 2327 SDP April 1998 + + + a=rtpmap:98 L16/16000/2 + + The general form of an rtpmap attribute is: + + a=rtpmap: /[/] + + For audio streams, may specify the number of + audio channels. This parameter may be omitted if the number of + channels is one provided no additional parameters are needed. For + video streams, no encoding parameters are currently specified. + + Additional parameters may be defined in the future, but + codecspecific parameters should not be added. Parameters added to + an rtpmap attribute should only be those required for a session + directory to make the choice of appropriate media too to + participate in a session. Codec-specific parameters should be + added in other attributes. + + Up to one rtpmap attribute can be defined for each media format + specified. Thus we might have: + + m=audio 49230 RTP/AVP 96 97 98 + a=rtpmap:96 L8/8000 + a=rtpmap:97 L16/8000 + a=rtpmap:98 L16/11025/2 + + RTP profiles that specify the use of dynamic payload types must + define the set of valid encoding names and/or a means to register + encoding names if that profile is to be used with SDP. + + Experimental encoding formats can also be specified using rtpmap. + RTP formats that are not registered as standard format names must + be preceded by "X-". Thus a new experimental redundant audio + stream called GSMLPC using dynamic payload type 99 could be + specified as: + + m=video 49232 RTP/AVP 99 + a=rtpmap:99 X-GSMLPC/8000 + + Such an experimental encoding requires that any site wishing to + receive the media stream has relevant configured state in its + session directory to know which tools are appropriate. + + Note that RTP audio formats typically do not include information + about the number of samples per packet. If a non-default (as + defined in the RTP Audio/Video Profile) packetisation is required, + the "ptime" attribute is used as given below. + + + +Handley & Jacobson Standards Track [Page 22] + +RFC 2327 SDP April 1998 + + + For more details on RTP audio and video formats, see [3]. + + o Formats for non-RTP media should be registered as MIME content + types as described in Appendix B. For example, the LBL whiteboard + application might be registered as MIME content-type application/wb + with encoding considerations specifying that it operates over UDP, + with no appropriate file format. In SDP this would then be + expressed using a combination of the "media" field and the "fmt" + field, as follows: + + m=application 32416 udp wb + + Suggested Attributes + + The following attributes are suggested. Since application writers + may add new attributes as they are required, this list is not + exhaustive. + + a=cat: + This attribute gives the dot-separated hierarchical category of + the session. This is to enable a receiver to filter unwanted + sessions by category. It would probably have been a compulsory + separate field, except for its experimental nature at this time. + It is a session-level attribute, and is not dependent on charset. + + a=keywds: + Like the cat attribute, this is to assist identifying wanted + sessions at the receiver. This allows a receiver to select + interesting session based on keywords describing the purpose of + the session. It is a session-level attribute. It is a charset + dependent attribute, meaning that its value should be interpreted + in the charset specified for the session description if one is + specified, or by default in ISO 10646/UTF-8. + + a=tool: + This gives the name and version number of the tool used to create + the session description. It is a session-level attribute, and is + not dependent on charset. + + a=ptime: + This gives the length of time in milliseconds represented by the + media in a packet. This is probably only meaningful for audio + data. It should not be necessary to know ptime to decode RTP or + vat audio, and it is intended as a recommendation for the + encoding/packetisation of audio. It is a media attribute, and is + not dependent on charset. + + + + + +Handley & Jacobson Standards Track [Page 23] + +RFC 2327 SDP April 1998 + + + a=recvonly + This specifies that the tools should be started in receive-only + mode where applicable. It can be either a session or media + attribute, and is not dependent on charset. + + a=sendrecv + This specifies that the tools should be started in send and + receive mode. This is necessary for interactive conferences with + tools such as wb which defaults to receive only mode. It can be + either a session or media attribute, and is not dependent on + charset. + + a=sendonly + This specifies that the tools should be started in send-only + mode. An example may be where a different unicast address is to + be used for a traffic destination than for a traffic source. In + such a case, two media descriptions may be use, one sendonly and + one recvonly. It can be either a session or media attribute, but + would normally only be used as a media attribute, and is not + dependent on charset. + + a=orient: + Normally this is only used in a whiteboard media specification. + It specifies the orientation of a the whiteboard on the screen. + It is a media attribute. Permitted values are `portrait', + `landscape' and `seascape' (upside down landscape). It is not + dependent on charset + + a=type: + This specifies the type of the conference. Suggested values are + `broadcast', `meeting', `moderated', `test' and `H332'. + `recvonly' should be the default for `type:broadcast' sessions, + `type:meeting' should imply `sendrecv' and `type:moderated' + should indicate the use of a floor control tool and that the + media tools are started so as to "mute" new sites joining the + conference. + + Specifying the attribute type:H332 indicates that this loosely + coupled session is part of a H.332 session as defined in the ITU + H.332 specification [10]. Media tools should be started + `recvonly'. + + Specifying the attribute type:test is suggested as a hint that, + unless explicitly requested otherwise, receivers can safely avoid + displaying this session description to users. + + The type attribute is a session-level attribute, and is not + dependent on charset. + + + +Handley & Jacobson Standards Track [Page 24] + +RFC 2327 SDP April 1998 + + + a=charset: + This specifies the character set to be used to display the + session name and information data. By default, the ISO-10646 + character set in UTF-8 encoding is used. If a more compact + representation is required, other character sets may be used such + as ISO-8859-1 for Northern European languages. In particular, + the ISO 8859-1 is specified with the following SDP attribute: + + a=charset:ISO-8859-1 + + This is a session-level attribute; if this attribute is present, + it must be before the first media field. The charset specified + MUST be one of those registered with IANA, such as ISO-8859-1. + The character set identifier is a US-ASCII string and MUST be + compared against the IANA identifiers using a case-insensitive + comparison. If the identifier is not recognised or not + supported, all strings that are affected by it SHOULD be regarded + as byte strings. + + Note that a character set specified MUST still prohibit the use + of bytes 0x00 (Nul), 0x0A (LF) and 0x0d (CR). Character sets + requiring the use of these characters MUST define a quoting + mechanism that prevents these bytes appearing within text fields. + + a=sdplang: + This can be a session level attribute or a media level attribute. + As a session level attribute, it specifies the language for the + session description. As a media level attribute, it specifies + the language for any media-level SDP information field associated + with that media. Multiple sdplang attributes can be provided + either at session or media level if multiple languages in the + session description or media use multiple languages, in which + case the order of the attributes indicates the order of + importance of the various languages in the session or media from + most important to least important. + + In general, sending session descriptions consisting of multiple + languages should be discouraged. Instead, multiple descriptions + should be sent describing the session, one in each language. + However this is not possible with all transport mechanisms, and + so multiple sdplang attributes are allowed although not + recommended. + + The sdplang attribute value must be a single RFC 1766 language + tag in US-ASCII. It is not dependent on the charset attribute. + An sdplang attribute SHOULD be specified when a session is of + + + + + +Handley & Jacobson Standards Track [Page 25] + +RFC 2327 SDP April 1998 + + + sufficient scope to cross geographic boundaries where the + language of recipients cannot be assumed, or where the session is + in a different language from the locally assumed norm. + + a=lang: + This can be a session level attribute or a media level attribute. + As a session level attribute, it specifies the default language + for the session being described. As a media level attribute, it + specifies the language for that media, overriding any session- + level language specified. Multiple lang attributes can be + provided either at session or media level if multiple languages + if the session description or media use multiple languages, in + which case the order of the attributes indicates the order of + importance of the various languages in the session or media from + most important to least important. + + The lang attribute value must be a single RFC 1766 language tag + in US-ASCII. It is not dependent on the charset attribute. A + lang attribute SHOULD be specified when a session is of + sufficient scope to cross geographic boundaries where the + language of recipients cannot be assumed, or where the session is + in a different language from the locally assumed norm. + + a=framerate: + This gives the maximum video frame rate in frames/sec. It is + intended as a recommendation for the encoding of video data. + Decimal representations of fractional values using the notation + "." are allowed. It is a media attribute, is + only defined for video media, and is not dependent on charset. + + a=quality: + This gives a suggestion for the quality of the encoding as an + integer value. + + The intention of the quality attribute for video is to specify a + non-default trade-off between frame-rate and still-image quality. + For video, the value in the range 0 to 10, with the following + suggested meaning: + + 10 - the best still-image quality the compression scheme can + give. + + 5 - the default behaviour given no quality suggestion. + + 0 - the worst still-image quality the codec designer thinks is + still usable. + + It is a media attribute, and is not dependent on charset. + + + +Handley & Jacobson Standards Track [Page 26] + +RFC 2327 SDP April 1998 + + + a=fmtp: + This attribute allows parameters that are specific to a + particular format to be conveyed in a way that SDP doesn't have + to understand them. The format must be one of the formats + specified for the media. Format-specific parameters may be any + set of parameters required to be conveyed by SDP and given + unchanged to the media tool that will use this format. + + It is a media attribute, and is not dependent on charset. + +6.1. Communicating Conference Control Policy + + There is some debate over the way conference control policy should be + communicated. In general, the authors believe that an implicit + declarative style of specifying conference control is desirable where + possible. + + A simple declarative style uses a single conference attribute field + before the first media field, possibly supplemented by properties + such as `recvonly' for some of the media tools. This conference + attribute conveys the conference control policy. An example might be: + + a=type:moderated + + In some cases, however, it is possible that this may be insufficient + to communicate the details of an unusual conference control policy. + If this is the case, then a conference attribute specifying external + control might be set, and then one or more "media" fields might be + used to specify the conference control tools and configuration data + for those tools. An example is an ITU H.332 session: + + c=IN IP4 224.5.6.7 + a=type:H332 + m=audio 49230 RTP/AVP 0 + m=video 49232 RTP/AVP 31 + m=application 12349 udp wb + m=control 49234 H323 mc + c=IN IP4 134.134.157.81 + + In this example, a general conference attribute (type:H332) is + specified stating that conference control will be provided by an + external H.332 tool, and a contact addresses for the H.323 session + multipoint controller is given. + + In this document, only the declarative style of conference control + declaration is specified. Other forms of conference control should + specify an appropriate type attribute, and should define the + implications this has for control media. + + + +Handley & Jacobson Standards Track [Page 27] + +RFC 2327 SDP April 1998 + + +7. Security Considerations + + SDP is a session description format that describes multimedia + sessions. A session description should not be trusted unless it has + been obtained by an authenticated transport protocol from a trusted + source. Many different transport protocols may be used to distribute + session description, and the nature of the authentication will differ + from transport to transport. + + One transport that will frequently be used to distribute session + descriptions is the Session Announcement Protocol (SAP). SAP + provides both encryption and authentication mechanisms but due to the + nature of session announcements it is likely that there are many + occasions where the originator of a session announcement cannot be + authenticated because they are previously unknown to the receiver of + the announcement and because no common public key infrastructure is + available. + + On receiving a session description over an unauthenticated transport + mechanism or from an untrusted party, software parsing the session + should take a few precautions. Session description contain + information required to start software on the receivers system. + Software that parses a session description MUST not be able to start + other software except that which is specifically configured as + appropriate software to participate in multimedia sessions. It is + normally considered INAPPROPRIATE for software parsing a session + description to start, on a user's system, software that is + appropriate to participate in multimedia sessions, without the user + first being informed that such software will be started and giving + their consent. Thus a session description arriving by session + announcement, email, session invitation, or WWW page SHOULD not + deliver the user into an {it interactive} multimedia session without + the user being aware that this will happen. As it is not always + simple to tell whether a session is interactive or not, applications + that are unsure should assume sessions are interactive. + + In this specification, there are no attributes which would allow the + recipient of a session description to be informed to start multimedia + tools in a mode where they default to transmitting. Under some + circumstances it might be appropriate to define such attributes. If + this is done an application parsing a session description containing + such attributes SHOULD either ignore them, or inform the user that + joining this session will result in the automatic transmission of + multimedia data. The default behaviour for an unknown attribute is + to ignore it. + + + + + + +Handley & Jacobson Standards Track [Page 28] + +RFC 2327 SDP April 1998 + + + Session descriptions may be parsed at intermediate systems such as + firewalls for the purposes of opening a hole in the firewall to allow + the participation in multimedia sessions. It is considered + INAPPROPRIATE for a firewall to open such holes for unicast data + streams unless the session description comes in a request from inside + the firewall. + + For multicast sessions, it is likely that local administrators will + apply their own policies, but the exclusive use of "local" or "site- + local" administrative scope within the firewall and the refusal of + the firewall to open a hole for such scopes will provide separation + of global multicast sessions from local ones. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Handley & Jacobson Standards Track [Page 29] + +RFC 2327 SDP April 1998 + + +Appendix A: SDP Grammar + + This appendix provides an Augmented BNF grammar for SDP. ABNF is + defined in RFC 2234. + + + announcement = proto-version + origin-field + session-name-field + information-field + uri-field + email-fields + phone-fields + connection-field + bandwidth-fields + time-fields + key-field + attribute-fields + media-descriptions + + proto-version = "v=" 1*DIGIT CRLF + ;this memo describes version 0 + + origin-field = "o=" username space + sess-id space sess-version space + nettype space addrtype space + addr CRLF + + session-name-field = "s=" text CRLF + + information-field = ["i=" text CRLF] + + uri-field = ["u=" uri CRLF] + + email-fields = *("e=" email-address CRLF) + + phone-fields = *("p=" phone-number CRLF) + + + connection-field = ["c=" nettype space addrtype space + connection-address CRLF] + ;a connection field must be present + ;in every media description or at the + ;session-level + + + bandwidth-fields = *("b=" bwtype ":" bandwidth CRLF) + + + + +Handley & Jacobson Standards Track [Page 30] + +RFC 2327 SDP April 1998 + + + time-fields = 1*( "t=" start-time space stop-time + *(CRLF repeat-fields) CRLF) + [zone-adjustments CRLF] + + + repeat-fields = "r=" repeat-interval space typed-time + 1*(space typed-time) + + + zone-adjustments = time space ["-"] typed-time + *(space time space ["-"] typed-time) + + + key-field = ["k=" key-type CRLF] + + + key-type = "prompt" | + "clear:" key-data | + "base64:" key-data | + "uri:" uri + + + key-data = email-safe | "~" | " + + + attribute-fields = *("a=" attribute CRLF) + + + media-descriptions = *( media-field + information-field + *(connection-field) + bandwidth-fields + key-field + attribute-fields ) + + + media-field = "m=" media space port ["/" integer] + space proto 1*(space fmt) CRLF + + + media = 1*(alpha-numeric) + ;typically "audio", "video", "application" + ;or "data" + + fmt = 1*(alpha-numeric) + ;typically an RTP payload type for audio + ;and video media + + + + +Handley & Jacobson Standards Track [Page 31] + +RFC 2327 SDP April 1998 + + + proto = 1*(alpha-numeric) + ;typically "RTP/AVP" or "udp" for IP4 + + + port = 1*(DIGIT) + ;should in the range "1024" to "65535" inclusive + ;for UDP based media + + + attribute = (att-field ":" att-value) | att-field + + + att-field = 1*(alpha-numeric) + + + att-value = byte-string + + + sess-id = 1*(DIGIT) + ;should be unique for this originating username/host + + + sess-version = 1*(DIGIT) + ;0 is a new session + + + connection-address = multicast-address + | addr + + + multicast-address = 3*(decimal-uchar ".") decimal-uchar "/" ttl + [ "/" integer ] + ;multicast addresses may be in the range + ;224.0.0.0 to 239.255.255.255 + + ttl = decimal-uchar + + start-time = time | "0" + + stop-time = time | "0" + + time = POS-DIGIT 9*(DIGIT) + ;sufficient for 2 more centuries + + + repeat-interval = typed-time + + + + + +Handley & Jacobson Standards Track [Page 32] + +RFC 2327 SDP April 1998 + + + typed-time = 1*(DIGIT) [fixed-len-time-unit] + + + fixed-len-time-unit = "d" | "h" | "m" | "s" + + + bwtype = 1*(alpha-numeric) + + bandwidth = 1*(DIGIT) + + + username = safe + ;pretty wide definition, but doesn't include space + + + email-address = email | email "(" email-safe ")" | + email-safe "<" email ">" + + + email = ;defined in RFC822 + + + uri= ;defined in RFC1630 + + + phone-number = phone | phone "(" email-safe ")" | + email-safe "<" phone ">" + + + phone = "+" POS-DIGIT 1*(space | "-" | DIGIT) + ;there must be a space or hyphen between the + ;international code and the rest of the number. + + + nettype = "IN" + ;list to be extended + + + addrtype = "IP4" | "IP6" + ;list to be extended + + + addr = FQDN | unicast-address + + + FQDN = 4*(alpha-numeric|"-"|".") + ;fully qualified domain name as specified in RFC1035 + + + + +Handley & Jacobson Standards Track [Page 33] + +RFC 2327 SDP April 1998 + + + unicast-address = IP4-address | IP6-address + + + IP4-address = b1 "." decimal-uchar "." decimal-uchar "." b4 + b1 = decimal-uchar + ;less than "224"; not "0" or "127" + b4 = decimal-uchar + ;not "0" + + IP6-address = ;to be defined + + + text = byte-string + ;default is to interpret this as IS0-10646 UTF8 + ;ISO 8859-1 requires a "a=charset:ISO-8859-1" + ;session-level attribute to be used + + + byte-string = 1*(0x01..0x09|0x0b|0x0c|0x0e..0xff) + ;any byte except NUL, CR or LF + + + decimal-uchar = DIGIT + | POS-DIGIT DIGIT + | ("1" 2*(DIGIT)) + | ("2" ("0"|"1"|"2"|"3"|"4") DIGIT) + | ("2" "5" ("0"|"1"|"2"|"3"|"4"|"5")) + + + integer = POS-DIGIT *(DIGIT) + + + alpha-numeric = ALPHA | DIGIT + + + DIGIT = "0" | POS-DIGIT + + + POS-DIGIT = "1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9" + + + ALPHA = "a"|"b"|"c"|"d"|"e"|"f"|"g"|"h"|"i"|"j"|"k"| + "l"|"m"|"n"|"o "|"p"|"q"|"r"|"s"|"t"|"u"|"v"| + "w"|"x"|"y"|"z"|"A"|"B"|"C "|"D"|"E"|"F"|"G"| + "H"|"I"|"J"|"K"|"L"|"M"|"N"|"O"|"P"|" Q"|"R"| + "S"|"T"|"U"|"V"|"W"|"X"|"Y"|"Z" + + + + + +Handley & Jacobson Standards Track [Page 34] + +RFC 2327 SDP April 1998 + + + email-safe = safe | space | tab + + + safe = alpha-numeric | + "'" | "'" | "-" | "." | "/" | ":" | "?" | """ | + "#" | "$" | "&" | "*" | ";" | "=" | "@" | "[" | + "]" | "^" | "_" | "`" | "{" | "|" | "}" | "+" | + "~" | " + + + space = %d32 + tab = %d9 + CRLF = %d13.10 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Handley & Jacobson Standards Track [Page 35] + +RFC 2327 SDP April 1998 + + +Appendix B: Guidelines for registering SDP names with IANA + + There are seven field names that may be registered with IANA. Using + the terminology in the SDP specification BNF, they are "media", + "proto", "fmt", "att-field", "bwtype", "nettype" and "addrtype". + + "media" (eg, audio, video, application, data). + + Packetized media types, such as those used by RTP, share the + namespace used by media types registry [RFC 2048] (i.e. "MIME + types"). The list of valid media names is the set of top-level + MIME content types. The set of media is intended to be small and + not to be extended except under rare circumstances. (The MIME + subtype corresponds to the "fmt" parameter below). + + "proto" + + In general this should be an IETF standards-track transport + protocol identifier such as RTP/AVP (rfc 1889 under the rfc 1890 + profile). + + However, people will want to invent their own proprietary + transport protocols. Some of these should be registered as a + "fmt" using "udp" as the protocol and some of which probably + can't be. + + Where the protocol and the application are intimately linked, + such as with the LBL whiteboard wb which used a proprietary and + special purpose protocol over UDP, the protocol name should be + "udp" and the format name that should be registered is "wb". The + rules for formats (see below) apply to such registrations. + + Where the proprietary transport protocol really carries many + different data formats, it is possible to register a new protocol + name with IANA. In such a case, an RFC MUST be produced + describing the protocol and referenced in the registration. Such + an RFC MAY be informational, although it is preferable if it is + standards-track. + + "fmt" + + The format namespace is dependent on the context of the "proto" + field, so a format cannot be registered without specifying one or + more transport protocols that it applies to. + + Formats cover all the possible encodings that might want to be + transported in a multimedia session. + + + + +Handley & Jacobson Standards Track [Page 36] + +RFC 2327 SDP April 1998 + + + For RTP formats that have been assigned static payload types, the + payload type number is used. For RTP formats using a dynamic + payload type number, the dynamic payload type number is given as + the format and an additional "rtpmap" attribute specifies the + format and parameters. + + For non-RTP formats, any unregistered format name may be + registered through the MIME-type registration process [RFC 2048]. + The type given here is the MIME subtype only (the top-level MIME + content type is specified by the media parameter). The MIME type + registration SHOULD reference a standards-track RFC which + describes the transport protocol for this media type. If there + is an existing MIME type for this format, the MIME registration + should be augmented to reference the transport specification for + this media type. If there is not an existing MIME type for this + format, and there exists no appropriate file format, this should + be noted in the encoding considerations as "no appropriate file + format". + + "att-field" (Attribute names) + + Attribute field names MAY be registered with IANA, although this + is not compulsory, and unknown attributes are simply ignored. + + When an attribute is registered, it must be accompanied by a + brief specification stating the following: + + o contact name, email address and telephone number + + o attribute-name (as it will appear in SDP) + + o long-form attribute name in English + + o type of attribute (session level, media level, or both) + + o whether the attribute value is subject to the charset + attribute. + + o a one paragraph explanation of the purpose of the attribute. + + o a specification of appropriate attribute values for this + attribute. + + IANA will not sanity check such attribute registrations except to + ensure that they do not clash with existing registrations. + + + + + + +Handley & Jacobson Standards Track [Page 37] + +RFC 2327 SDP April 1998 + + + Although the above is the minimum that IANA will accept, if the + attribute is expected to see widespread use and interoperability + is an issue, authors are encouraged to produce a standards-track + RFC that specifies the attribute more precisely. + + Submitters of registrations should ensure that the specification + is in the spirit of SDP attributes, most notably that the + attribute is platform independent in the sense that it makes no + implicit assumptions about operating systems and does not name + specific pieces of software in a manner that might inhibit + interoperability. + + "bwtype" (bandwidth specifiers) + + A proliferation of bandwidth specifiers is strongly discouraged. + + New bandwidth specifiers may be registered with IANA. The + submission MUST reference a standards-track RFC specifying the + semantics of the bandwidth specifier precisely, and indicating + when it should be used, and why the existing registered bandwidth + specifiers do not suffice. + + "nettype" (Network Type) + + New network types may be registered with IANA if SDP needs to be + used in the context of non-internet environments. Whilst these + are not normally the preserve of IANA, there may be circumstances + when an Internet application needs to interoperate with a non- + internet application, such as when gatewaying an internet + telephony call into the PSTN. The number of network types should + be small and should be rarely extended. A new network type + cannot be registered without registering at least one address + type to be used with that network type. A new network type + registration MUST reference an RFC which gives details of the + network type and address type and specifies how and when they + would be used. Such an RFC MAY be Informational. + + "addrtype" (Address Type) + + New address types may be registered with IANA. An address type + is only meaningful in the context of a network type, and any + registration of an address type MUST specify a registered network + type, or be submitted along with a network type registration. A + new address type registration MUST reference an RFC giving + details of the syntax of the address type. Such an RFC MAY be + Informational. Address types are not expected to be registered + frequently. + + + + +Handley & Jacobson Standards Track [Page 38] + +RFC 2327 SDP April 1998 + + + Registration Procedure + + To register a name the above guidelines should be followed regarding + the required level of documentation that is required. The + registration itself should be sent to IANA. Attribute registrations + should include the information given above. Other registrations + should include the following additional information: + + o contact name, email address and telephone number + + o name being registered (as it will appear in SDP) + + o long-form name in English + + o type of name ("media", "proto", "fmt", "bwtype", "nettype", or + "addrtype") + + o a one paragraph explanation of the purpose of the registered name. + + o a reference to the specification (eg RFC number) of the registered + name. + + IANA may refer any registration to the IESG or to any appropriate + IETF working group for review, and may request revisions to be made + before a registration will be made. + + + + + + + + + + + + + + + + + + + + + + + + + + +Handley & Jacobson Standards Track [Page 39] + +RFC 2327 SDP April 1998 + + +Appendix C: Authors' Addresses + + Mark Handley + Information Sciences Institute + c/o MIT Laboratory for Computer Science + 545 Technology Square + Cambridge, MA 02139 + United States + electronic mail: mjh@isi.edu + + Van Jacobson + MS 46a-1121 + Lawrence Berkeley Laboratory + Berkeley, CA 94720 + United States + electronic mail: van@ee.lbl.gov + +Acknowledgments + + Many people in the IETF MMUSIC working group have made comments and + suggestions contributing to this document. In particular, we would + like to thank Eve Schooler, Steve Casner, Bill Fenner, Allison + Mankin, Ross Finlayson, Peter Parnes, Joerg Ott, Carsten Bormann, Rob + Lanphier and Steve Hanna. + +References + + [1] Mills, D., "Network Time Protocol (version 3) specification and + implementation", RFC 1305, March 1992. + + [2] Schulzrinne, H., Casner, S., Frederick, R. and V. Jacobson, "RTP: + A Transport Protocol for Real-Time Applications", RFC 1889, January + 1996. + + [3] Schulzrinne, H., "RTP Profile for Audio and Video Conferences + with Minimal Control", RFC 1890, January 1996 + + [4] Handley, M., "SAP - Session Announcement Protocol", Work in + Progress. + + [5] V. Jacobson, S. McCanne, "vat - X11-based audio teleconferencing + tool" vat manual page, Lawrence Berkeley Laboratory, 1994. + + [6] The Unicode Consortium, "The Unicode Standard -- Version 2.0", + Addison-Wesley, 1996. + + + + + + +Handley & Jacobson Standards Track [Page 40] + +RFC 2327 SDP April 1998 + + + [7] ISO/IEC 10646-1:1993. International Standard -- Information + technol- ogy -- Universal Multiple-Octet Coded Character Set (UCS) -- + Part 1: Architecture and Basic Multilingual Plane. Five amendments + and a techn- ical corrigendum have been published up to now. UTF-8 + is described in Annex R, published as Amendment 2. + + [8] Goldsmith, D., and M. Davis, "Using Unicode with MIME", RFC 1641, + July 1994. + + [9] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO + 10646", RFC 2044, October 1996. + + [10] ITU-T Recommendation H.332 (1998): "Multimedia Terminal for + Receiving Internet-based H.323 Conferences", ITU, Geneva. + + [11] Handley, M., Schooler, E., and H. Schulzrinne, "Session + Initiation Protocol (SIP)", Work in Progress. + + [12] Schulzrinne, H., Rao, A., and R. Lanphier, "Real Time Streaming + Protocol (RTSP)", RFC 2326, April 1998. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Handley & Jacobson Standards Track [Page 41] + +RFC 2327 SDP April 1998 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1998). 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. + + + + + + + + + + + + + + + + + + + + + + + + +Handley & Jacobson Standards Track [Page 42] + diff --git a/lib/megaco/doc/standard/rfc3266.txt b/lib/megaco/doc/standard/rfc3266.txt new file mode 100644 index 0000000000..f047f12a1f --- /dev/null +++ b/lib/megaco/doc/standard/rfc3266.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group S. Olson +Request for Comments: 3266 Microsoft +Updates: 2327 G. Camarillo +Category: Standards Track Ericsson + A. B. Roach + dynamicsoft + June 2002 + + + Support for IPv6 in Session Description Protocol (SDP) + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2002). All Rights Reserved. + +Abstract + + This document describes the use of Internet Protocol Version 6 (IPv6) + addresses in conjunction with the Session Description Protocol (SDP). + Specifically, this document clarifies existing text in SDP with + regards to the syntax of IPv6 addresses. + +1. Introduction + + SDP is intended for describing multimedia sessions for the purposes + of session announcement, session invitation, and other forms of + multimedia session initiation. It is a text format description that + provides many details of a multimedia session including: the + originator of the session, a URL related to the session, the + connection address for the session media(s), and optional attributes + for the session media(s). Each of these pieces of information may + involve one or more IPv6 addresses. The ABNF for IP addresses in SDP + currently leaves the syntax for IPv6 addresses undefined. This + document attempts to complete the ABNF to include IPv6 addresses. + + Accordingly, the address type "IP6" indicating an IPv6 address, + should be allowed in the connection field, "c=", of the SDP. The + ABNF already reflects this, though the "Connection Data" text under + section 6 of RFC 2328 currently only defines the "IP4" address type. + + + + +Olson, et. al. Standards Track [Page 1] + +RFC 3266 Support for IPv6 in Session Description Protocol June 2002 + + +2. Terminology + + 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 RFC 2119 [5]. + +3. Syntax + + RFC 2373 [1] gives an ABNF for the text representation of IPv6 + addresses in Appendix B. RFC 2732 [3] covers the text representation + of IPv6 addresses when used within a URL. Using the ABNF described + in these documents, the following updated ABNF for SDP is proposed. + + uri = ; defined in RFC1630 and RFC2732 + + multicast-address = IP4-multicast / IP6-multicast + + IP4-multicast = m1 3*( "." decimal-uchar ) + "/" ttl [ "/" integer ] + ; IPv4 multicast addresses may be in the + ; range 224.0.0.0 to 239.255.255.255 + + m1 = ("22" ("4"/"5"/"6"/"7"/"8"/"9")) / + ("23" DIGIT )) + + IP6-multicast = hexpart + ; IPv6 address starting with FF + + addr = FQDN / unicast-address + + FQDN = 4*(alpha-numeric/"-"/".") + ; fully qualified domain name as specified + ; in RFC1035 + unicast-address = IP4-address / IP6-address + + IP4-address = b1 3*("." decimal-uchar) / "0.0.0.0" + + b1 = decimal-uchar + ; less than "224"; not "0" or "127" + + ; The following is from RFC2373 Appendix B. It is a direct copy. + IP6-address = hexpart [ ":" IP4-address ] + + hexpart = hexseq / hexseq "::" [ hexseq ] / + "::" [ hexseq ] + + + + + + +Olson, et. al. Standards Track [Page 2] + +RFC 3266 Support for IPv6 in Session Description Protocol June 2002 + + + hexseq = hex4 *( ":" hex4) + + hex4 = 1*4HEXDIG + +4. Example SDP description with IPv6 addresses + + The following is an example SDP description using the above ABNF for + IPv6 addresses. In particular, the origin and connection fields + contain IPv6 addresses. + + v=0 + o=nasa1 971731711378798081 0 IN IP6 2201:056D::112E:144A:1E24 + s=(Almost) live video feed from Mars-II satellite + p=+1 713 555 1234 + c=IN IP6 FF1E:03AD::7F2E:172A:1E24 + t=3338481189 3370017201 + m=audio 6000 RTP/AVP 2 + a=rtpmap:2 G726-32/8000 + m=video 6024 RTP/AVP 107 + a=rtpmap:107 H263-1998/90000 + +5. Note for implementors + + An implementation may receive an SDP session description with an IPv6 + address whose format [1] is internally that of an IPv4 mapped + address. Note that such an address is actually the address of an + IPv4-only node, and implementors are warned to interpret IPv4 mapped + addresses as equivalent to IP4. + +6. IANA Considerations + + This document updates the definition of the IP6 addrtype parameter + found in RFC 2327. + +7. Security Considerations + + No additional considerations above what is stated in section 7 of RFC + 2327. + +8. References + + [1] Hinden, R. and S. Deering, "IP Version 6 Addressing + Architecture", RFC 2373, July 1998. + + [2] Handley, M. and V. Jacobson, "SDP: Session Description + Protocol", RFC 2327, April 1998. + + + + + +Olson, et. al. Standards Track [Page 3] + +RFC 3266 Support for IPv6 in Session Description Protocol June 2002 + + + [3] Hinden, R., Carpenter, B. and L. Masinter, "Format for Literal + IPv6 Addresses in URL's", RFC 2732, December 1999. + + [4] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [5] Bradner, S., "Key words for Use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + +9. Authors' Addresses + + Sean Olson + Microsoft + One Microsoft Way + Redmond, WA 98052 + USA + + EMail: seanol@microsoft.com + + + Gonzalo Camarillo + Ericsson + Advanced Signalling Research Lab. + FIN-02420 Jorvas + Finland + + Phone: +358 9 299 3371 + Fax: +358 9 299 3118 + EMail: Gonzalo.Camarillo@ericsson.com + + + Adam Roach + dynamicsoft + 5100 Tennyson Parkway + Suite 1200 + Plano, TX 75024 + USA + + EMail: adam@dynamicsoft.com + Voice: + + + + + + + + + + + +Olson, et. al. Standards Track [Page 4] + +RFC 3266 Support for IPv6 in Session Description Protocol June 2002 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (2002). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Olson, et. al. Standards Track [Page 5] + diff --git a/lib/megaco/doc/standard/rfc3525.txt b/lib/megaco/doc/standard/rfc3525.txt new file mode 100644 index 0000000000..80663cc2cd --- /dev/null +++ b/lib/megaco/doc/standard/rfc3525.txt @@ -0,0 +1,11931 @@ + + + + + + +Network Working Group C. Groves +Request for Comments: 3525 M. Pantaleo +Obsoletes: 3015 LM Ericsson +Category: Standards Track T. Anderson + Consultant + T. Taylor + Nortel Networks + Editors + June 2003 + + + Gateway Control Protocol Version 1 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + This document defines the protocol used between elements of a + physically decomposed multimedia gateway, i.e., a Media Gateway and a + Media Gateway Controller. The protocol presented in this document + meets the requirements for a media gateway control protocol as + presented in RFC 2805. + + This document replaces RFC 3015. It is the result of continued + cooperation between the IETF Megaco Working Group and ITU-T Study + Group 16. It incorporates the original text of RFC 3015, modified by + corrections and clarifications discussed on the Megaco + E-mail list and incorporated into the Study Group 16 Implementor's + Guide for Recommendation H.248. The present version of this document + underwent ITU-T Last Call as Recommendation H.248 Amendment 1. + Because of ITU-T renumbering, it was published by the ITU-T as + Recommendation H.248.1 (03/2002), Gateway Control Protocol Version 1. + + Users of this specification are advised to consult the H.248 Sub- + series Implementors' Guide at http://www.itu.int/itudoc/itu- + t/com16/implgd for additional corrections and clarifications. + + + + + +Groves, et al. Standards Track [Page 1] + +RFC 3525 Gateway Control Protocol June 2003 + + +Conventions used in this document + + 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 RFC 2119 [RFC2119]. + +Table of Contents + + 1 Scope.........................................................5 + 1.1 Changes From RFC 3015.....................................5 + 1.2 Differences From ITU-T Recommendation H.248.1 (03/2002)...5 + 2 References....................................................6 + 2.1 Normative references......................................6 + 2.2 Informative references....................................9 + 3 Definitions..................................................10 + 4 Abbreviations................................................11 + 5 Conventions..................................................12 + 6 Connection model.............................................13 + 6.1 Contexts.................................................16 + 6.2 Terminations.............................................17 + 6.2.1 Termination dynamics.................................21 + 6.2.2 TerminationIDs.......................................21 + 6.2.3 Packages.............................................22 + 6.2.4 Termination properties and descriptors...............23 + 6.2.5 Root Termination.....................................25 + 7 Commands.....................................................26 + 7.1 Descriptors..............................................27 + 7.1.1 Specifying parameters................................27 + 7.1.2 Modem descriptor.....................................28 + 7.1.3 Multiplex descriptor.................................28 + 7.1.4 Media descriptor.....................................29 + 7.1.5 TerminationState descriptor..........................29 + 7.1.6 Stream descriptor....................................30 + 7.1.7 LocalControl descriptor..............................31 + 7.1.8 Local and Remote descriptors.........................32 + 7.1.9 Events descriptor....................................35 + 7.1.10 EventBuffer descriptor..............................38 + 7.1.11 Signals descriptor..................................38 + 7.1.12 Audit descriptor....................................40 + 7.1.13 ServiceChange descriptor............................41 + 7.1.14 DigitMap descriptor.................................41 + 7.1.15 Statistics descriptor...............................46 + 7.1.16 Packages descriptor.................................47 + 7.1.17 ObservedEvents descriptor...........................47 + 7.1.18 Topology descriptor.................................47 + 7.1.19 Error Descriptor....................................50 + 7.2 Command Application Programming Interface................50 + 7.2.1 Add..................................................51 + + + +Groves, et al. Standards Track [Page 2] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7.2.2 Modify...............................................52 + 7.2.3 Subtract.............................................53 + 7.2.4 Move.................................................55 + 7.2.5 AuditValue...........................................56 + 7.2.6 AuditCapabilities....................................59 + 7.2.7 Notify...............................................60 + 7.2.8 ServiceChange........................................61 + 7.2.9 Manipulating and Auditing Context Attributes.........65 + 7.2.10 Generic Command Syntax..............................66 + 7.3 Command Error Codes......................................66 + 8 Transactions.................................................66 + 8.1 Common parameters........................................68 + 8.1.1 Transaction Identifiers..............................68 + 8.1.2 Context Identifiers..................................68 + 8.2 Transaction Application Programming Interface............69 + 8.2.1 TransactionRequest...................................69 + 8.2.2 TransactionReply.....................................69 + 8.2.3 TransactionPending...................................71 + 8.3 Messages.................................................72 + 9 Transport....................................................72 + 9.1 Ordering of Commands.....................................73 + 9.2 Protection against Restart Avalanche.....................74 + 10 Security Considerations.....................................75 + 10.1 Protection of Protocol Connections......................75 + 10.2 Interim AH scheme.......................................76 + 10.3 Protection of Media Connections.........................77 + 11 MG-MGC Control Interface....................................78 + 11.1 Multiple Virtual MGs....................................78 + 11.2 Cold start..............................................79 + 11.3 Negotiation of protocol version.........................79 + 11.4 Failure of a MG.........................................80 + 11.5 Failure of an MGC.......................................81 + 12 Package definition..........................................82 + 12.1 Guidelines for defining packages........................82 + 12.1.1 Package.............................................83 + 12.1.2 Properties..........................................84 + 12.1.3 Events..............................................85 + 12.1.4 Signals.............................................85 + 12.1.5 Statistics..........................................86 + 12.1.6 Procedures..........................................86 + 12.2 Guidelines to defining Parameters to Events and Signals.86 + 12.3 Lists...................................................87 + 12.4 Identifiers.............................................87 + 12.5 Package registration....................................88 + 13 IANA Considerations.........................................88 + 13.1 Packages................................................88 + 13.2 Error codes.............................................89 + 13.3 ServiceChange reasons...................................89 + + + +Groves, et al. Standards Track [Page 3] + +RFC 3525 Gateway Control Protocol June 2003 + + + ANNEX A Binary encoding of the protocol.......................90 + A.1 Coding of wildcards......................................90 + A.2 ASN.1 syntax specification...............................92 + A.3 Digit maps and path names...............................111 + ANNEX B Text encoding of the protocol.........................113 + B.1 Coding of wildcards.....................................113 + B.2 ABNF specification......................................113 + B.3 Hexadecimal octet coding................................127 + B.4 Hexadecimal octet sequence..............................127 + ANNEX C Tags for media stream properties......................128 + C.1 General media attributes................................128 + C.2 Mux properties..........................................130 + C.3 General bearer properties...............................130 + C.4 General ATM properties..................................130 + C.5 Frame Relay.............................................134 + C.6 IP......................................................134 + C.7 ATM AAL2................................................134 + C.8 ATM AAL1................................................136 + C.9 Bearer capabilities.....................................137 + C.10 AAL5 properties........................................147 + C.11 SDP equivalents........................................148 + C.12 H.245..................................................149 + ANNEX D Transport over IP.....................................150 + D.1 Transport over IP/UDP using Application Level Framing ..150 + D.1.1 Providing At-Most-Once functionality................150 + D.1.2 Transaction identifiers and three-way handshake.....151 + D.1.3 Computing retransmission timers.....................152 + D.1.4 Provisional responses...............................153 + D.1.5 Repeating Requests, Responses and Acknowledgements..153 + D.2 Using TCP...............................................155 + D.2.1 Providing the At-Most-Once functionality............155 + D.2.2 Transaction identifiers and three-way handshake.....155 + D.2.3 Computing retransmission timers.....................156 + D.2.4 Provisional responses...............................156 + D.2.5 Ordering of commands................................156 + ANNEX E Basic packages.......................................157 + E.1 Generic.................................................157 + E.2 Base Root Package.......................................159 + E.3 Tone Generator Package..................................161 + E.4 Tone Detection Package..................................163 + E.5 Basic DTMF Generator Package............................166 + E.6 DTMF detection Package..................................167 + E.7 Call Progress Tones Generator Package...................169 + E.8 Call Progress Tones Detection Package...................171 + E.9 Analog Line Supervision Package.........................172 + E.10 Basic Continuity Package...............................175 + E.11 Network Package........................................178 + E.12 RTP Package............................................180 + + + +Groves, et al. Standards Track [Page 4] + +RFC 3525 Gateway Control Protocol June 2003 + + + E.13 TDM Circuit Package....................................182 + APPENDIX I EXAMPLE CALL FLOWS (INFORMATIVE)...................184 + A.1 Residential Gateway to Residential Gateway Call.........184 + A.1.1 Programming Residential GW Analog Line Terminations + for Idle Behavior...................................184 + A.1.2 Collecting Originator Digits and Initiating + Termination.........................................186 + APPENDIX II Changes From RFC 3015............................195 + Intellectual Property Rights..................................210 + Acknowledgments...............................................211 + Authors' Addresses............................................212 + Full Copyright Statement......................................213 + +1 Scope + + The present document, which is identical to the published version of + ITU-T Recommendation H.248.1 (03/2002) except as noted below, defines + the protocols used between elements of a physically decomposed + multimedia gateway. There are no functional differences from a + system view between a decomposed gateway, with distributed sub- + components potentially on more than one physical device, and a + monolithic gateway such as described in ITU-T Recommendation H.246. + This document does not define how gateways, multipoint control units + or interactive voice response units (IVRs) work. Instead it creates + a general framework that is suitable for these applications. + + Packet network interfaces may include IP, ATM or possibly others. + The interfaces will support a variety of Switched Circuit Network + (SCN) signalling systems, including tone signalling, ISDN, ISUP, QSIG + and GSM. National variants of these signalling systems will be + supported where applicable. + +1.1 Changes From RFC 3015 + + The differences between this document and RFC 3015 are documented in + Appendix II. + +1.2 Differences From ITU-T Recommendation H.248.1 (03/2002) + + This document differs from the corresponding ITU-T publication in the + following respects: + + - Added IETF front matter in place of the corresponding ITU-T + material. + + - The ITU-T summary is too H.323-specific and has been omitted. + + + + + +Groves, et al. Standards Track [Page 5] + +RFC 3525 Gateway Control Protocol June 2003 + + + - The IETF conventions have been stated as governing this document. + As discussed in section 5 below, this gives slightly greater + strength to "should" requirements. + + - The Scope section (just above) has been edited slightly to suit + its IETF context. + + - Added normative references to RFCs 2026 and 2119. + + - Figures 4, 5, and 6 show the centre of the context for greater + clarity. Also added Figure 6a showing an important additional + example. + + - Added a paragraph in section 7.1.18 which was approved in the + Implementor's Guide but lost inadvertently in the ITU-T approved + version. + + - This document incorporates corrections to the informative examples + in Appendix I which also appear in H.248.1 version 2, but which + were not picked up in H.248.1 (03/2002). + + - This document includes a new Appendix II listing all the changes + from RFC 3015. + + - This document includes an Acknowledgements section listing the + authors of RFC 3015 but also many other people who contributed to + the development of the Megaco/H.248.x protocol. + + - Moved the Intellectual Property declaration to its usual place in + an IETF document and added a reference to declarations on the IETF + web site. + +2 References + + The following ITU-T Recommendations and other references contain + provisions which, through reference in this text, constitute + provisions of this RFC. At the time of publication, the editions + indicated were valid. All Recommendations and other references are + subject to revision; all users of this RFC are therefore encouraged + to investigate the possibility of applying the most recent edition of + the Recommendations and other references listed below. A list of the + currently valid ITU-T Recommendations is regularly published. + +2.1 Normative references + + - ITU-T Recommendation H.225.0 (1999), Call signalling protocols and + media stream packetization for packet-based multimedia + communication systems. + + + +Groves, et al. Standards Track [Page 6] + +RFC 3525 Gateway Control Protocol June 2003 + + + - ITU-T Recommendation H.235 (1998), Security and encryption for + H-Series (H.323 and other H.245-based) multimedia terminals. + + - ITU-T Recommendation H.245 (1998), Control protocol for multimedia + communication. + + - 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. + + - ITU-T Recommendation H.248.8 (2002), H.248 Error Codes and Service + Change Reasons. + + - ITU-T Recommendation H.323 (1999), Packet-based multimedia + communication systems. + + - ITU-T Recommendation I.363.1 (1996), B-ISDN ATM adaptation layer + (AAL) specification: Type 1 AAL. + + - ITU-T Recommendation I.363.2 (1997), B-ISDN ATM adaptation layer + (AAL) specification: Type 2 AAL. + + - ITU-T Recommendation I.363.5 (1996), B-ISDN ATM adaptation layer + (AAL) specification: Type 5 AAL. + + - ITU-T Recommendation I.366.1 (1998), Segmentation and Reassembly + Service Specific Convergence Sublayer for the AAL type 2. + + - ITU-T Recommendation I.366.2 (1999), AAL type 2 service specific + convergence sublayer for trunking. + + - ITU-T Recommendation I.371 (2000), Traffic control and congestion + control in B-ISDN. + + - ITU-T Recommendation Q.763 (1999), Signalling System No. 7 - ISDN + user part formats and codes. + + - ITU-T Recommendation Q.765.5 (2001), Application transport + mechanism - Bearer independent call control (BICC). + + - ITU-T Recommendation Q.931 (1998), ISDN user-network interface + layer 3 specification for basic call control. + + - ITU-T Recommendation Q.2630.1 (1999), AAL type 2 signalling + protocol (Capability Set 1). + + + + + + +Groves, et al. Standards Track [Page 7] + +RFC 3525 Gateway Control Protocol June 2003 + + + - ITU-T Recommendation Q.2931 (1995), Digital Subscriber Signalling + System No. 2 (DSS2) - User-Network Interface (UNI) - Layer 3 + specification for basic call/connection control. + + - ITU-T Recommendation Q.2941.1 (1997), Digital Subscriber + Signalling System No. 2 - Generic identifier transport. + + - ITU-T Recommendation Q.2961.1 (1995), Additional signalling + capabilities to support traffic parameters for the tagging option + and the sustainable call rate parameter set. + + - ITU-T Recommendation Q.2961.2 (1997), Additional traffic + parameters: Support of ATM transfer capability in the broadband + bearer capability information element. + + - ITU-T Recommendation Q.2965.1 (1999), Digital subscriber + signalling system No. 2 - Support of Quality of Service classes. + + - ITU-T Recommendation Q.2965.2 (1999), Digital subscriber + signalling system No. 2 - Signalling of individual Quality of + Service parameters. + + - ITU-T Recommendation V.76 (1996), Generic multiplexer using V.42 + LAPM-based procedures. + + - ITU-T Recommendation X.213 (1995), Information technology - Open + Systems Interconnection - Network service definition plus + Amendment 1 (1997), Addition of the Internet protocol address + format identifier. + + - ITU-T Recommendation X.680 (1997), Information technology - + Abstract Syntax Notation One (ASN.1): Specification of basic + notation. + + - ITU-T Recommendation X.690 (1997), Information Technology - ASN.1 + Encoding Rules: Specification of Basic Encoding Rules (BER), + Canonical Encoding Rules (CER) and Distinguished Encoding Rules + (DER). + + - ATM Forum (1996), ATM User-Network Interface (UNI) Signalling + Specification - Version 4.0. + + [RFC 1006] Rose, M. and D. Cass, "ISO Transport Service on top of the + TCP, Version 3", STD 35, RFC 1006, May 1987. + + [RFC 2026] Brander, S., "The Internet Standards Process -- Revision + 3", BCP 9, RFC 2026, October 1996. + + + + +Groves, et al. Standards Track [Page 8] + +RFC 3525 Gateway Control Protocol June 2003 + + + [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC 2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [RFC 2327] Handley, M. and V. Jacobson, "SDP: Session Description + Protocol", RFC 2327, April 1998. + + [RFC 2402] Kent, S. and R. Atkinson, "IP Authentication Header", RFC + 2402, November 1998. + + [RFC 2406] 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 (1999), 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. + + - ITU-T Recommendation H.226 (1998), Channel aggregation protocol + for multilink operation on circuit-switched networks + + - ITU-T Recommendation Q.724 (1998), Signalling procedures. + + - ITU-T Recommendation Q.764 (1999), Signalling system No. 7 - ISDN + user part signalling procedures. + + - ITU-T Recommendation Q.1902.4 (2001), Bearer independent call + control protocol - Basic call procedures. + + [RFC 768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + August 1980. + + [RFC 791] Postel, J., "Internet Protocol", STD 5, RFC 791, September + 1981. + + [RFC 793] Postel, J., "Transmission Control Protocol", STD 7, RFC + 793, September 1981. + + + +Groves, et al. Standards Track [Page 9] + +RFC 3525 Gateway Control Protocol June 2003 + + + [RFC 1661] Simpson, W., Ed., "The Point-to-Point Protocol (PPP)", STD + 51, RFC 1661, July 1994. + + [RFC 1889] Schulzrinne, H., Casner, S., Frederick, R. and V. + Jacobson, "RTP: A Transport Protocol for Real-Time + Applications", RFC 1889, January 1996. + + [RFC 1890] Schulzrinne, H. and G. Fokus, "RTP Profile for Audio and + Video Conferences with Minimal Control", RFC 1890, + January 1996. + + [RFC 2401] Kent, S. and R. Atkinson, "Security Architecture for the + Internet Protocol", RFC 2401, November 1998. + + [RFC 2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 + (IPv6) Specification", RFC 2460, December 1998. + + [RFC 2543] Handley, M., Schulzrinne, H., Schooler, E. and J. + Rosenberg, "SIP: Session Initiation Protocol", RFC 2543, + March 1999. + + [RFC 2805] Greene, N., Ramalho, M. and B. Rosen, "Media Gateway + Control Protocol Architecture and Requirements", RFC 2805, + April 2000. + +3 Definitions + + This document defines the following terms: + + Access gateway: + A type of gateway that provides a User-Network Interface (UNI) such + as ISDN. + + Descriptor: + A syntactic element of the protocol that groups related properties. + For instance, the properties of a media flow on the MG can be set by + the MGC by including the appropriate descriptor in a command. + + Media Gateway (MG): + The media gateway converts media provided in one type of network to + the format required in another type of network. For example, a MG + could terminate bearer channels from a switched circuit network + (e.g., DS0s) and media streams from a packet network (e.g., RTP + streams in an IP network). This gateway may be capable of processing + audio, video and T.120 alone or in any combination, and will be + capable of full duplex media translations. The MG may also play + audio/video messages and perform other IVR functions, or may perform + media conferencing. + + + +Groves, et al. Standards Track [Page 10] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 that typically includes processing of audio, video and + data. + + Residential gateway: + A gateway that interworks an analogue line to a packet network. A + residential gateway typically contains one or two analogue lines and + is located at the customer premises. + + SCN FAS signalling gateway: + This function contains 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 contains 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/sent by a media gateway + as part of a call or conference. + + Trunk: + A communication channel between two switching systems such as a DS0 + on a T1 or E1 line. + + Trunking gateway: + A gateway between SCN network and packet network that typically + terminates a large number of digital circuits. + +4 Abbreviations + + This RFC document uses the following abbreviations: + + ALF Application Layer Framing + + ATM Asynchronous Transfer Mode + + CAS Channel Associated Signalling + + DTMF Dual Tone Multi-Frequency + + + + +Groves, et al. Standards Track [Page 11] + +RFC 3525 Gateway Control Protocol June 2003 + + + FAS Facility Associated Signalling + + GSM Global System for Mobile communications + + GW GateWay + + IANA Internet Assigned Numbers Authority (superseded by Internet + Corporation for Assigned Names and Numbers - ICANN) + + 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. 7 + +5 Conventions + + In the H.248.1 Recommendation, "SHALL" refers to a mandatory + requirement, while "SHOULD" refers to a suggested but optional + feature or procedure. The term "MAY" refers to an optional course of + action without expressing a preference. Note that these definition + are overridden in the present document by the RFC 2119 conventions + stated at the beginning of this document. RFC 2119 has a more + precise definition of "should" than is provided by the ITU-T. + + + + + + + +Groves, et al. Standards Track [Page 12] + +RFC 3525 Gateway Control Protocol June 2003 + + +6 Connection model + + The connection model for the protocol describes the logical entities, + or objects, within the Media Gateway that can be controlled by the + Media Gateway Controller. The main abstractions used in the + connection model are Terminations and Contexts. + + A Termination sources and/or sinks one or more streams. In a + multimedia conference, a Termination can be multimedia and sources or + sinks multiple media streams. The media stream parameters, as well + as modem, and bearer parameters are encapsulated within the + Termination. + + A Context is an association between a collection of Terminations. + There is a special type of Context, the null Context, which contains + all Terminations that are not associated to any other Termination. + For instance, in a decomposed access gateway, all idle lines are + represented by Terminations in the null Context. + + Following is a graphical depiction of these concepts. The diagram of + Figure 1 gives several examples and is not meant to be an + all-inclusive illustration. The asterisk box in each of the Contexts + represents the logical association of Terminations implied by the + Context. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 13] + +RFC 3525 Gateway Control Protocol June 2003 + + + +------------------------------------------------------+ + |Media Gateway | + | +-------------------------------------------------+ | + | |Context +-------------+ | | + | | | Termination | | | + | | |-------------| | | + | | +-------------+ +->| SCN Bearer |<---+-> + | | | Termination | +-----+ | | Channel | | | + | | |-------------| | |---+ +-------------+ | | + <-+--->| RTP Stream |---| * | | | + | | | | | |---+ +-------------+ | | + | | +-------------+ +-----+ | | Termination | | | + | | | |-------------| | | + | | +->| SCN Bearer |<---+-> + | | | Channel | | | + | | +-------------+ | | + | +-------------------------------------------------+ | + | | + | | + | +------------------------------+ | + | (NULL Context) |Context | | + | +-------------+ | +-------------+ | | + | | Termination | | +-----+ | Termination | | | + | |-------------| | | | |-------------| | | + | | SCN Bearer | | | * |------| SCN Bearer |<---+-> + | | Channel | | | | | Channel | | | + | +-------------+ | +-----+ +-------------+ | | + | +------------------------------+ | + | | + | | + | +-------------------------------------------------+ | + | |Context | | + | | +-------------+ +-------------+ | | + | | | Termination | +-----+ | Termination | | | + | | |-------------| | | |-------------| | | + <-+--->| SCN Bearer |---| * |------| SCN Bearer |<---+-> + | | | Channel | | | | Channel | | | + | | +-------------+ +-----+ +-------------+ | | + | +-------------------------------------------------+ | + | ___________________________________________________ | + +------------------------------------------------------+ + + Figure 1: Examples of Megaco/H.248 Connection Model + + + + + + + + +Groves, et al. Standards Track [Page 14] + +RFC 3525 Gateway Control Protocol June 2003 + + + The example in Figure 2 shows an example of one way to accomplish a + call-waiting scenario in a decomposed access gateway, illustrating + the relocation of a Termination between Contexts. Terminations T1 + and T2 belong to Context C1 in a two-way audio call. A second audio + call is waiting for T1 from Termination T3. T3 is alone in Context + C2. T1 accepts the call from T3, placing T2 on hold. This action + results in T1 moving into Context C2, as shown in Figure 3. + + +------------------------------------------------------+ + |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 + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 15] + +RFC 3525 Gateway Control Protocol June 2003 + + + +------------------------------------------------------+ + |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 T1 + +6.1 Contexts + + A Context is an association between a number of Terminations. The + Context describes the topology (who hears/sees whom) and the media + mixing and/or switching parameters if more than two Terminations are + involved in the association. + + There is a special Context called the null Context. It contains + Terminations that are not associated to any other Termination. + Terminations in the null Context can have their parameters examined + or modified, and may have events detected on them. + + In general, an Add command is used to add Terminations to Contexts. + If the MGC does not specify an existing Context to which the + Termination is to be added, the MG creates a new Context. A + Termination may be removed from a Context with a Subtract command, + and a Termination may be moved from one Context to another with a + Move command. A Termination SHALL exist in only one Context at a + time. + + + + + + + +Groves, et al. Standards Track [Page 16] + +RFC 3525 Gateway Control Protocol June 2003 + + + The maximum number of Terminations in a Context is a MG property. + Media gateways that offer only point-to-point connectivity might + allow at most two Terminations per Context. Media gateways that + support multipoint conferences might allow three or more Terminations + per Context. + +6.1.1 Context attributes and descriptors + + The attributes of Contexts are: + + - ContextID. + + - The topology (who hears/sees whom). + + The topology of a Context describes the flow of media between the + Terminations within a Context. In contrast, the mode of a + Termination (send/receive/...) describes the flow of the media at + the ingress/egress of the media gateway. + + - The priority is used for a Context in order to provide the MG with + information about a certain precedence handling for a Context. + The MGC can also use the priority to control autonomously the + traffic precedence in the MG in a smooth way in certain + situations (e.g., restart), when a lot of Contexts must be handled + simultaneously. Priority 0 is the lowest priority and a priority + of 15 is the highest priority. + + - An indicator for an emergency call is also provided to allow a + preference handling in the MG. + +6.1.2 Creating, deleting and modifying Contexts + + The protocol can be used to (implicitly) create Contexts and modify + the parameter values of existing Contexts. The protocol has commands + to add Terminations to Contexts, subtract them from Contexts, and to + move Terminations between Contexts. Contexts are deleted implicitly + when the last remaining Termination is subtracted or moved out. + +6.2 Terminations + + A Termination is a logical entity on a MG that sources and/or sinks + media and/or control streams. A Termination is described by a number + of characterizing Properties, which are grouped in a set of + Descriptors that are included in commands. Terminations have unique + identities (TerminationIDs), assigned by the MG at the time of their + creation. + + + + + +Groves, et al. Standards Track [Page 17] + +RFC 3525 Gateway Control Protocol June 2003 + + + Terminations representing physical entities have a semi-permanent + existence. For example, a Termination representing a TDM channel + might exist for as long as it is provisioned in the gateway. + Terminations representing ephemeral information flows, such as RTP + flows, would usually exist only for the duration of their use. + + Ephemeral Terminations are created by means of an Add command. They + are destroyed by means of a Subtract command. In contrast, when a + physical Termination is Added to or Subtracted from a Context, it is + taken from or to the null Context, respectively. + + Terminations may have signals applied to them (see 7.1.11). + Terminations may be programmed to detect Events, the occurrence of + which can trigger notification messages to the MGC, or action by the + MG. Statistics may be accumulated on a Termination. Statistics are + reported to the MGC upon request (by means of the AuditValue command, + see 7.2.5) and when the Termination is taken out of the call it is + in. + + Multimedia gateways may process multiplexed media streams. For + example, Recommendation H.221 describes a frame structure for + multiple media streams multiplexed on a number of digital 64 kbit/s + channels. Such a case is handled in the connection model in the + following way. For every bearer channel that carries part of the + multiplexed streams, there is a physical or ephemeral "bearer + Termination". The bearer Terminations that source/sink the digital + channels are connected to a separate Termination called the + "multiplexing Termination". The multiplexing termination is an + ephemeral termination representing a frame-oriented session. The + MultiplexDescriptor for this Termination describes the multiplex used + (e.g., H.221 for an H.320 session) and indicates the order in which + the contained digital channels are assembled into a frame. + + Multiplexing terminations may be cascades (e.g., H.226 multiplex of + digital channels feeding into a H.223 multiplex supporting an H.324 + session). + + The individual media streams carried in the session are described by + StreamDescriptors on the multiplexing Termination. These media + streams can be associated with streams sourced/sunk by Terminations + in the Context other than the bearer Terminations supporting the + multiplexing Termination. Each bearer Termination supports only a + single data stream. These data streams do not appear explicitly as + streams on the multiplexing Termination and they are hidden from the + rest of the context. + + Figures 4, 5, 6, and 6a illustrate typical applications of the + multiplexing termination and Multiplex Descriptor. + + + +Groves, et al. Standards Track [Page 18] + +RFC 3525 Gateway Control Protocol June 2003 + + + +-----------------------------------+ + | Context +-------+ | + +----+ | | | + Circuit 1 -|--| TC1|---------+ Tmux | | + | +----+ (Str 1) | | Audio +-----+ + | | | +-----*-----+ |----- + | +----+ | H.22x | Stream 1 | | + Circuit 2 -|--| TC2|---------+ multi-| | TR1 | + | +----+ (Str 1) | plex | |(RTP)| + | | | | Video | | + | +----+ | +-----*-----+ |----- + Circuit 3 -|--| TC3|---------+ | Stream 2 | | + / +----+ (Str 1) | | +-----+ + / | +-------+ | + / +-----------------\-----------------+ + Audio, video, and control \ + signals are carried in frames Tmux is an ephemeral with two + spanning the circuits. explicit Stream Descriptors + and a Multiplex Descriptor. + + Figure 4: Multiplexed Termination Scenario - Circuit to Packet + (Asterisks * denote the centre of the context) + + Context + +--------------------------------------+ + | +-------+ +-------+ | + +----+ | | | | +----+ + Circuit 1 ----| TC1|---+ Tmux1 | Audio | Tmux2 +---| TC4|--- + +----+ | +---*----+ | +----+ + | | | Str 1 | | | + +----+ | H.22x | | H.22x | +----+ + Circuit 2 ----| TC2|---+ multi-| | multi-+---| TC5|--- + +----+ | plex | | plex | +----+ + | | | Video | | | + +----+ | +---*----+ | +----+ + Circuit 3 ----| TC3|---+ | Str 2 | +---| TC6|--- + +----+ | | | | +----+ + | +-------+ +-------+ | + +-----------------\-----/--------------+ + \ / + Tmux1 and Tmux2 are ephemerals each with two + explicit Stream Descriptors and a Multiplex Descriptor. + + Figure 5: Multiplexed Termination Scenario - Circuit to Circuit + (Asterisks * denote the centre of the context) + + + + + + +Groves, et al. Standards Track [Page 19] + +RFC 3525 Gateway Control Protocol June 2003 + + + +-----------------------------------+ + | Context +-------+ | + +----+ | | | + Circuit 1 -|--| TC1|---------+ Tmux | | + | +----+ (Str 1) | | Audio +-----+ + | | | +-----*-----+ TR1 |----- + | +----+ | H.22x | Stream 1 |(RTP)| + Circuit 2 -|--| TC2|---------+ multi-| +-----+ + | +----+ (Str 1) | plex | | + | | | | Video +-----+ + | +----+ | +-----*-----+ TR2 |----- + Circuit 3 -|--| TC3|---------+ | Stream 2 |(RTP)| + / +----+ (Str 1) | | +-----+ + / | +-------+ | + / +-----------------\-----------------+ + Audio, video, and control \ Tmux is an ephemeral with two + signals are carried in frames explicit Stream Descriptors and + spanning the circuits. and a Multiplex Descriptor. + + Figure 6: Multiplexed Termination Scenario - Single to Multiple + Terminations + (Asterisks * denote the centre of the context) + + Context + +---------------------------------------------+ + | +-------+ +-------+ | + Cct 1 +----+ | | | | Audio +-----+ + ----| TC1|---+ Tmux1 | | Tmux2 +-----*-----| TR1 |----- + +----+ | | | | Stream 1 |(RTP)| + | | | Data | | +-----+ + Cct 2 +----+ | H.226 +-------+ H.223 | | + ----| TC2|---+ multi-|(Str 1)| multi-| Control +-----+ + +----+ | plex | | plex +-----*-----+ Tctl|----- + | | | | | Stream 3 +-----+ + Cct 3 +----+ | | | | | + ----| TC3|---+ | | | +-----+ + +----+ | | | +-----*-----+ TR2 |----- + | +-------+ | | Video |(RTP)| + | +-------+ Stream 2 +-----+ + | | + +---------------------------------------------+ + Tmux1 has a Multiplex Descriptor and a single data stream. + Tmux2 has a Multiplex Descriptor with a single bearer and + three explicit Stream Descriptors. + + Figure 6a: Multiplexed Termination Scenario - Cascaded Multiplexes + (Asterisks * denote the centre of the context) + Note: this figure does not appear in Rec. H.248.1 + + + +Groves, et al. Standards Track [Page 20] + +RFC 3525 Gateway Control Protocol June 2003 + + + Terminations may be created which represent multiplexed bearers, such + as an ATM AAL Type 2 bearer. When a new multiplexed bearer is to be + created, an ephemeral Termination is created in a Context established + for this purpose. When the Termination is subtracted, the + multiplexed bearer is destroyed. + +6.2.1 Termination dynamics + + The protocol can be used to create new Terminations and to modify + property values of existing Terminations. These modifications + include the possibility of adding or removing events and/or signals. + The Termination properties, and events and signals are described in + the ensuing subclauses. An MGC can only release/modify Terminations + and the resources that the Termination represents which it has + previously seized via, e.g., the Add command. + +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. The TerminationIDs may be chosen to have structure. For + instance, a TerminationID may consist of trunk group and a trunk + within the group. + + A wildcarding mechanism using two types of wildcards can be used with + TerminationIDs. The two wildcards are ALL and CHOOSE. The former is + used to address multiple Terminations at once, while the latter is + used to indicate to a media gateway that it must select a Termination + satisfying the partially specified TerminationID. This allows, for + instance, that a MGC instructs a MG to choose a circuit within a + trunk group. + + When ALL is used in the TerminationID of a command, the effect is + identical to repeating the command with each of the matching + TerminationIDs. The use of ALL does not address the ROOT + termination. Since each of these commands may generate a response, + the size of the entire response may be large. If individual + responses are not required, a wildcard response may be requested. In + such a case, a single response is generated, which contains the UNION + of all of the individual responses which otherwise would have been + generated, with duplicate values suppressed. For instance, given a + Termination Ta with properties p1=a, p2=b and Termination Tb with + + + + + + + +Groves, et al. Standards Track [Page 21] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 response may be particularly 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 may implement Terminations that have + widely differing characteristics. Variations in Terminations are + accommodated in the protocol by allowing Terminations to have + optional Properties, Events, Signals and Statistics implemented by + MGs. + + In order to achieve MG/MGC interoperability, such options are grouped + into Packages, and typically a Termination realizes a set of such + Packages. More information on definition of packages can be found in + clause 12. An MGC can audit a Termination to determine which + Packages it realizes. + + Properties, Events, Signals and Statistics defined in Packages, as + well as parameters to them, are referenced by identifiers (Ids). + Identifiers are scoped. For each package, PropertyIds, EventIds, + SignalIds, StatisticsIds and ParameterIds have unique name spaces and + the same identifier may be used in each of them. Two PropertyIds in + different packages may also have the same identifier, etc. + + To support a particular package the MG must support all properties, + signals, events and statistics defined in a package. It must also + support all Signal and Event parameters. The MG may support a subset + of the values listed in a package for a particular Property or + Parameter. + + When packages are extended, the properties, events, signals and + statistics defined in the base package can be referred to using + either the extended package name or the base package name. For + example, if Package A defines event e1, and Package B extends Package + A, then B/e1 is an event for a termination implementing Package B. By + definition, the MG MUST also implement the base Package, but it is + optional to publish the base package as an allowed interface. If it + does publish A, then A would be reported on the Package Descriptor + in AuditValue as well as B, and event A/e1 would be available on a + termination. If the MG does not publish A, then only B/e1 would be + available. If published through AuditValue, A/e1 and B/e1 are the + same event. + + + + + +Groves, et al. Standards Track [Page 22] + +RFC 3525 Gateway Control Protocol June 2003 + + + For improved interoperability and backward compatibility, an MG MAY + publish all Packages supported by its Terminations, including base + Packages from which extended Packages are derived. An exception to + this is in cases where the base packages are expressly "Designed to + be extended only". + +6.2.4 Termination properties and descriptors + + Terminations have properties. The properties have unique + PropertyIDs. Most properties have default values, which are + explicitly defined in this protocol specification or in a package + (see clause 12) or set by provisioning. If not provisioned + otherwise, the properties in all descriptors except TerminationState + and LocalControl default to empty/"no value" when a Termination is + first created or returned to the null Context. The default contents + of the two exceptions are described in 7.1.5 and 7.1.7. + + The provisioning of a property value in the MG will override any + default value, be it supplied in this protocol specification or in a + package. Therefore if it is essential for the MGC to have full + control over the property values of a Termination, it should supply + explicit values when ADDing the Termination to a Context. + Alternatively, for a physical Termination the MGC can determine any + provisioned property values by auditing the Termination while it is + in the NULL Context. + + There are a number of common properties for Terminations and + properties specific to media streams. The common properties are also + called the Termination state properties. For each media stream, + there are local properties and properties of the received and + transmitted flows. + + Properties not included in the base protocol are defined in Packages. + These properties are referred to by a name consisting of the + PackageName and a PropertyId. Most properties have default values + described in the Package description. Properties may be read-only or + read/write. The possible values of a property may be audited, as can + their current values. For properties that are read/write, the MGC + can set their values. A property may be declared as "Global" which + has a single value shared by all Terminations realizing the package. + Related properties are grouped into descriptors for convenience. + + When a Termination is added to a Context, the value of its read/write + properties can be set by including the appropriate descriptors as + parameters to the Add command. Similarly, a property of a + Termination in a Context may have its value changed by the Modify + command. + + + + +Groves, et al. Standards Track [Page 23] + +RFC 3525 Gateway Control Protocol June 2003 + + + Properties may also have their values changed when a Termination is + moved from one Context to another as a result of a Move command. In + some cases, descriptors are returned as output from a command. + + In general, if a Descriptor is completely omitted from one of the + aforementioned Commands, the properties in that Descriptor retain + their prior values for the Termination(s) upon which the Command + acts. On the other hand, if some read/write properties are omitted + from a Descriptor in a Command (i.e., the Descriptor is only + partially specified), those properties will be reset to their default + values for the Termination(s) upon which the Command acts, unless the + package specifies other behavior. For more details, see clause 7.1 + dealing with the individual Descriptors. + + The following table lists all of the possible descriptors and their + use. Not all descriptors are legal as input or output parameters to + every command. + + 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. + + + + +Groves, et al. Standards Track [Page 24] + +RFC 3525 Gateway Control Protocol June 2003 + + + EventBuffer Describes events to be detected by the MG when + Event Buffering is active. + + Signals Describes signals (see 7.1.11) applied to + 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. + + Topology Specifies flow directions between Terminations in a + Context. + + Error Contains an error code and optionally error text; + it may occur in command replies and in Notify + requests. + +6.2.5 Root Termination + + Occasionally, a command must refer to the entire gateway, rather than + a Termination within it. A special TerminationID, "Root" is reserved + for this purpose. Packages may be defined on Root. Root thus may + have properties, events and statistics (signals are not appropriate + for root). Accordingly, the root TerminationID may appear in: + + - 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 determine what properties of root are + implemented + + + +Groves, et al. Standards Track [Page 25] + +RFC 3525 Gateway Control Protocol June 2003 + + + - a ServiceChange - to declare the gateway in or out of service. + + Any other use of the root TerminationID is an error. Error code + 410 - Incorrect identifier shall be returned in these cases. + +7 Commands + + The protocol provides commands for manipulating the logical entities + of the protocol connection model, Contexts and Terminations. + Commands provide control at the finest level of granularity supported + by the protocol. For example, Commands exist to add Terminations to + a Context, modify Terminations, subtract Terminations from a Context, + and audit properties of Contexts or Terminations. Commands provide + for complete control of the properties of Contexts and Terminations. + This includes specifying which events a Termination is to report, + which signals/actions are to be applied to a Termination and + specifying the topology of a Context (who hears/sees whom). + + Most commands are for the specific use of the Media Gateway + Controller as command initiator in controlling Media Gateways as + command responders. The exceptions are the Notify and ServiceChange + commands: Notify is sent from Media Gateway to Media Gateway + Controller, and ServiceChange may be sent by either entity. Below is + an overview of the commands; they are explained in more detail in + 7.2. + + 1) 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. + + 2) Modify - The Modify command modifies the properties, events and + signals of a Termination. + + 3) 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. + + 4) Move - The Move command atomically moves a Termination to another + Context. + + 5) AuditValue - The AuditValue command returns the current state of + properties, events, signals and statistics of Terminations. + + 6) AuditCapabilities - The AuditCapabilities command returns all the + possible values for Termination properties, events and signals + allowed by the Media Gateway. + + + + +Groves, et al. Standards Track [Page 26] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7) Notify - The Notify command allows the Media Gateway to inform the + Media Gateway Controller of the occurrence of events in the Media + Gateway. + + 8) 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 a 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 7.2.1 through 7.2.8. + +7.1 Descriptors + + The parameters to a command are termed Descriptors. A descriptor + consists of a name and a list of items. Some items may have values. + Many Commands share common descriptors. This subclause enumerates + these descriptors. Descriptors may be returned as output from a + command. In any such return of descriptor contents, an empty + descriptor is represented by its name unaccompanied by any list. + Parameters and parameter usage specific to a given Command type are + described in the subclause that describes the Command. + +7.1.1 Specifying parameters + + Command parameters are structured into a number of descriptors. In + general, the text format of descriptors is + DescriptorName={parm=value, parm=value, ...}. + + Parameters may be fully specified, overspecified or underspecified: + + 1) Fully specified parameters have a single, unambiguous value that + the command initiator is instructing the command responder to use + for the specified parameter. + + 2) Underspecified parameters, using the CHOOSE value, allow the + command responder to choose any value it can support. + + 3) Overspecified parameters have a list of potential values. The + list order specifies the command initiator's order of preference + of selection. The command responder chooses one value from + the offered list and returns that value to the command initiator. + + + + + +Groves, et al. Standards Track [Page 27] + +RFC 3525 Gateway Control Protocol June 2003 + + + If a required descriptor other than the Audit descriptor is + unspecified (i.e., entirely absent) from a command, the previous + values set in that descriptor for that Termination, if any, are + retained. In commands other than Subtract, a missing Audit + descriptor is equivalent to an empty Audit descriptor. The Behaviour + of the MG with respect to unspecified parameters within a descriptor + varies with the descriptor concerned, as indicated in succeeding + subclauses. Whenever a parameter is underspecified or overspecified, + the descriptor containing the value chosen by the responder is + included as output from the command. + + Each command specifies the TerminationId the command operates on. + This TerminationId may be "wildcarded". When the TerminationId of a + command is wildcarded, the effect shall be as if the command was + repeated with each of the TerminationIds matched. + +7.1.2 Modem descriptor + + The Modem descriptor specifies the modem type and parameters, if any, + required for use in e.g., H.324 and text conversation. The + descriptor includes the following modem types: V.18, V.22, V.22 bis, + V.32, V.32 bis, V.34, V.90, V.91, Synchronous ISDN, and allows for + extensions. By default, no Modem descriptor is present in a + Termination. + +7.1.3 Multiplex descriptor + + In multimedia calls, a number of media streams are carried on a + (possibly different) number of bearers. The multiplex descriptor + associates the media and the bearers. The descriptor includes the + multiplex type: + + - H.221; + + - H.223; + + - H.226; + + - V.76; + + - possible extensions, + + and a set of TerminationIDs representing the multiplexed bearers, in + order. For example: + + Mux = H.221{ MyT3/1/2, MyT3/2/13, MyT3/3/6, MyT3/21/22} + + + + + +Groves, et al. Standards Track [Page 28] + +RFC 3525 Gateway Control Protocol June 2003 + + +7.1.4 Media descriptor + + The Media descriptor specifies the parameters for all the media + streams. These parameters are structured into two descriptors: a + TerminationState descriptor, which specifies the properties of a + Termination that are not stream dependent, and one or more Stream + descriptors each of which describes a single media stream. + + A stream is identified by a StreamID. The StreamID is used to link + the streams in a Context that belong together. Multiple streams + exiting a Termination shall be synchronized with each other. Within + the Stream descriptor, there are up to three subsidiary descriptors: + LocalControl, Local, and Remote. The relationship between these + descriptors is thus: + + Media descriptor + TerminationState Descriptor + Stream descriptor + LocalControl descriptor + Local descriptor + Remote descriptor + + As a convenience, LocalControl, Local, or Remote descriptors may be + included in the Media descriptor without an enclosing Stream + descriptor. In this case, the StreamID is assumed to be 1. + +7.1.5 TerminationState descriptor + + The TerminationState descriptor contains the ServiceStates property, + the EventBufferControl property and properties of a Termination + (defined in Packages) that are not stream specific. + + The ServiceStates property describes the overall state of the + Termination (not stream specific). A Termination can be in one of + the following states: "test", "out of service", or "in service". The + "test" state indicates that the Termination is being tested. The + state "out of service" indicates that the Termination cannot be used + for traffic. The state "in service" indicates that a Termination can + be used or is being used for normal traffic. "in service" is the + default state. + + + + + + + + + + + +Groves, et al. Standards Track [Page 29] + +RFC 3525 Gateway Control Protocol June 2003 + + + Values assigned to Properties may be simple values + (integer/string/enumeration) or may be underspecified, where more + than one value is supplied and the MG may make a choice: + + - 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 specifies whether events are buffered + following detection of an event in the Events descriptor, or + processed immediately. See 7.1.9 for details. + +7.1.6 Stream descriptor + + A Stream descriptor specifies the parameters of a single + bidirectional stream. These parameters are structured into three + descriptors: one that contains Termination properties specific to a + stream and one each for local and remote flows. The Stream + Descriptor includes a StreamID which identifies the stream. Streams + are created by specifying a new StreamID on one of the Terminations + in a Context. A stream is deleted by setting empty Local and Remote + descriptors for the stream with ReserveGroup and ReserveValue in + LocalControl set to "false" on all Terminations in the Context that + previously supported that stream. + + StreamIDs are of local significance between MGC and MG and they are + assigned by the MGC. Within a Context, StreamID is a means by which + to indicate which media flows are interconnected: streams with the + same StreamID are connected. + + If a Termination is moved from one Context to another, the effect on + the Context to which the Termination is moved is the same as in the + case that a new Termination were added with the same StreamIDs as the + moved Termination. + + + + + + + + + +Groves, et al. Standards Track [Page 30] + +RFC 3525 Gateway Control Protocol June 2003 + + +7.1.7 LocalControl descriptor + + The LocalControl descriptor contains the Mode property, the + ReserveGroup and ReserveValue properties and properties of a + Termination (defined in Packages) that are stream specific, and are + of interest between the MG and the MGC. Values of properties may be + underspecified as in 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 with + respect to the exterior of the Context, so that, for example, a + stream set to mode=sendOnly does not pass received media into the + Context. The default value for the mode property is "Inactive". + Signals and Events are not affected by mode. + + The boolean-valued Reserve properties, ReserveValue and ReserveGroup, + of a Termination indicate what the MG is expected to do when it + receives a Local and/or Remote descriptor. + + If the value of a Reserve property is True, the MG SHALL reserve + resources for all alternatives specified in the Local and/or Remote + descriptors for which it currently has resources available. It SHALL + respond with the alternatives for which it reserves resources. 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 media begins to flow while more than a single alternative is + reserved, media packets may be sent/received on any of the + alternatives and must be processed, although only a single + alternative may be active at any given time. + + If the value of a Reserve property is False, the MG SHALL choose one + of the alternatives specified in the Local descriptor (if present) + and one of the alternatives specified in the Remote descriptor (if + present). If the MG has not yet reserved resources to support the + selected alternative, it SHALL reserve the resources. If, on the + other hand, it already reserved resources for the Termination + addressed (because of a prior exchange with ReserveValue and/or + ReserveGroup equal to True), it SHALL release any excess resources it + reserved previously. Finally, the MG shall send a reply to the MGC + containing the alternatives for the Local and/or Remote descriptor + that it selected. If the MG does not have sufficient resources to + support any of the alternatives specified, it SHALL respond with + error 510 (insufficient resources). + + The default value of ReserveValue and ReserveGroup is False. More + information on the use of the two Reserve properties is provided in + 7.1.8. + + + + +Groves, et al. Standards Track [Page 31] + +RFC 3525 Gateway Control Protocol June 2003 + + + A new setting of the LocalControl Descriptor completely replaces the + previous setting of that descriptor in the MG. Thus, to retain + information from the previous setting, the MGC must include that + information in the new setting. If the MGC wishes to delete some + information from the existing descriptor, it merely resends the + descriptor (in a Modify command) with the unwanted information + stripped out. + +7.1.8 Local and Remote descriptors + + The MGC uses Local and Remote descriptors to reserve and commit MG + resources for media decoding and encoding for the given Stream(s) and + Termination to which they apply. The MG includes these descriptors + in its response to indicate what it is actually prepared to support. + The MG SHALL include additional properties and their values in its + response if these properties are mandatory yet not present in the + requests made by the MGC (e.g., by specifying detailed video encoding + parameters where the MGC only specified the payload type). + + Local refers to the media received by the MG and Remote refers to the + media sent by the MG. + + When text encoding the protocol, the descriptors consist of session + descriptions as defined in SDP (RFC 2327). In session descriptions + sent from the MGC to the MG, the following exceptions to the syntax + of RFC 2327 are allowed: + + - the "s=", "t=" and "o=" lines are optional; + + - the use of CHOOSE is allowed in place of a single parameter value; + and + + - the use of alternatives is allowed in place of a single parameter + value. + + A Stream Descriptor specifies a single bi-directional media stream + and so a single session description MUST NOT include more than one + media description ("m=" line). A Stream Descriptor may contain + additional session descriptions as alternatives. Each media stream + for a termination must appear in distinct Stream Descriptors. When + multiple session descriptions are provided in one descriptor, the + "v=" lines are required as delimiters; otherwise they are optional in + session descriptions sent to the MG. Implementations shall accept + session descriptions that are fully conformant to RFC 2327. When + binary encoding the protocol the descriptor consists of groups of + properties (tag-value pairs) as specified in Annex C. Each such + group may contain the parameters of a session description. + + + + +Groves, et al. Standards Track [Page 32] + +RFC 3525 Gateway Control Protocol June 2003 + + + Below, the semantics of the Local and Remote descriptors are + specified in detail. The specification consists of two parts. The + first part specifies the interpretation of the contents of the + descriptor. The second part specifies the actions the MG must take + upon receiving the Local and Remote descriptors. The actions to be + taken by the MG depend on the values of the ReserveValue and + ReserveGroup properties of the LocalControl descriptor. + + Either the Local or the Remote descriptor or both may be: + + 1) unspecified (i.e., absent); + + 2) empty; + + 3) underspecified through use of CHOOSE in a property value; + + 4) fully specified; or + + 5) overspecified through presentation of multiple groups of + properties and possibly multiple property values in one or more of + these groups. + + Where the descriptors have been passed from the MGC to the MG, they + are interpreted according to the rules given in 7.1.1, with the + following additional comments for clarification: + + a) An unspecified Local or Remote descriptor is considered to be a + missing mandatory parameter. It requires the MG to use whatever + was last specified for that descriptor. It is possible that there + was no previously specified value, in which case the descriptor + concerned is ignored in further processing of the command. + + b) An empty Local (Remote) descriptor in a message from the MGC + signifies a request to release any resources reserved for the + media flow received (sent). + + c) If multiple groups of properties are present in a Local or Remote + descriptor or multiple values within a group, the order of + preference is descending. + + d) Underspecified or overspecified properties within a group of + properties sent by the MGC are requests for the MG to choose one + or more values which it can support for each of those properties. + In case of an overspecified property, the list of values is in + descending order of preference. + + Subject to the above rules, subsequent action depends on the values + of the ReserveValue and ReserveGroup properties in LocalControl. + + + +Groves, et al. Standards Track [Page 33] + +RFC 3525 Gateway Control Protocol June 2003 + + + If ReserveGroup is True, the MG reserves the resources required to + support any of the requested property group alternatives that it can + currently support. If ReserveValue is True, the MG reserves the + resources required to support any of the requested property value + alternatives that it can currently support. + + NOTE - If a Local or Remote descriptor contains multiple groups of + properties, and ReserveGroup is True, then the MG is requested to + reserve resources so that it can decode or encode the media stream + according to any of the alternatives. For instance, if the Local + descriptor contains two groups of properties, one specifying + packetized G.711 A-law audio and the other G.723.1 audio, the MG + reserves resources so that 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 simultaneously, one + encoded in G.711 A-law and one in G.723.1. The intention for the use + of ReserveValue is analogous. + + If ReserveGroup is true or ReserveValue is True, then the following + rules apply: + + - If the MG has insufficient resources to support all alternatives + requested by the MGC and the MGC requested resources in both Local + and Remote, the MG should reserve resources to support at least + one alternative each within Local and Remote. + + - If the MG has insufficient 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 is incapable of supporting 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 is able + to support at least one alternative in Remote. + + + +Groves, et al. Standards Track [Page 34] + +RFC 3525 Gateway Control Protocol June 2003 + + + - If the MG is unable to 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. + + A new setting of a Local or Remote descriptor completely replaces the + previous setting of that descriptor in the MG. Thus, to retain + information from the previous setting, the MGC must include that + information in the new setting. If the MGC wishes to delete some + information from the existing descriptor, it merely resends the + descriptor (in a Modify command) with the unwanted information + stripped out. + +7.1.9 Events descriptor + + The EventsDescriptor parameter contains a RequestIdentifier and a + list of events that the Media Gateway is requested to detect and + report. The RequestIdentifier is used to correlate the request with + the notifications that it may trigger. Requested events include, for + example, fax tones, continuity test results, and on-hook and off-hook + transitions. The RequestIdentifier is omitted if the + EventsDescriptor is empty (i.e., no events are specified). + + Each event in the descriptor contains the Event name, an optional + streamID, an optional KeepActive flag, and optional parameters. The + Event name consists of a Package Name (where the event is defined) + and an EventID. The ALL wildcard may be used for the EventID, + indicating that all events from the specified package have to be + detected. The default streamID is 0, indicating that the event to be + detected is not related to a particular media stream. Events can + have parameters. This allows a single event description to have some + variation in meaning without creating large numbers of individual + events. Further event parameters are defined in the package. + + If a digit map completion event is present or implied in the + EventsDescriptor, the EventDM parameter is used to carry either the + name or the value of the associated digit map. See 7.1.14 for + further details. + + When an event is processed against the contents of an active Events + Descriptor and found to be present in that descriptor ("recognized"), + the default action of the MG is to send a Notify command to the MGC. + Notification may be deferred if the event is absorbed into the + current dial string of an active digit map (see 7.1.14). Any other + action is for further study. Moreover, event recognition may cause + currently active signals to stop, or may cause the current Events + and/or Signals descriptor to be replaced, as described at the end of + + + +Groves, et al. Standards Track [Page 35] + +RFC 3525 Gateway Control Protocol June 2003 + + + this subclause. Unless the Events Descriptor is replaced by another + Events Descriptor, it remains active after an event has been + recognized. + + If the value of the EventBufferControl property equals LockStep, + following detection of such an event, normal handling of events is + suspended. Any event which is subsequently detected and occurs in + the EventBuffer descriptor is added to the end of the EventBuffer (a + FIFO queue), along with the time that it was detected. The MG SHALL + wait for a new EventsDescriptor to be loaded. A new EventsDescriptor + can be loaded either as the result of receiving a command with a new + EventsDescriptor, or by activating an embedded EventsDescriptor. + + If EventBufferControl equals Off, the MG continues processing based + on the active EventsDescriptor. + + In the case of an embedded EventsDescriptor being activated, the MG + continues event processing based on the newly activated + EventsDescriptor. + + NOTE 1 - For purposes of EventBuffer handling, activation of an + embedded EventsDescriptor is equivalent to receipt of a new + EventsDescriptor. + + When the MG receives a command with a new EventsDescriptor, one or + more events may have been buffered in the EventBuffer in the MG. The + value of EventBufferControl then determines how the MG treats such + buffered events. + + Case 1 + + If EventBufferControl equals LockStep and the MG receives a new + EventsDescriptor, it will check the FIFO EventBuffer and take the + following actions: + + 1) If the EventBuffer is empty, the MG waits for detection of events + based on the new EventsDescriptor. + + 2) If the EventBuffer is non-empty, the MG processes the FIFO queue + starting with the first event: + + a) If the event in the queue is in the events listed in the new + EventsDescriptor, the MG acts on the event and removes the + event from the EventBuffer. The time stamp of the Notify shall + be the time the event was actually detected. The MG then waits + for a new EventsDescriptor. While waiting for a new + EventsDescriptor, any events detected that appear in the + + + + +Groves, et al. Standards Track [Page 36] + +RFC 3525 Gateway Control Protocol June 2003 + + + EventsBufferDescriptor will be placed in the EventBuffer. When + a new EventsDescriptor is received, the event processing will + repeat from step 1. + + b) If the event is not in the new EventsDescriptor, the MG SHALL + discard the event and repeat from step 1. + + Case 2 + + If EventBufferControl equals Off and the MG receives a new + EventsDescriptor, it processes new events with the new + EventsDescriptor. + + If the MG receives a command instructing it to set the value of + EventBufferControl to Off, all events in the EventBuffer SHALL be + discarded. + + The MG may report several events in a single Transaction as long as + this does not unnecessarily delay the reporting of individual events. + + For procedures regarding transmitting the Notify command, refer to + the appropriate annex or Recommendation of the H.248 sub-series for + specific transport considerations. + + The default value of EventBufferControl is Off. + + NOTE 2 - Since the EventBufferControl property is in the + TerminationStateDescriptor, the MG might receive a command that + changes the EventBufferControl property and does not include an + EventsDescriptor. + + Normally, recognition of an event shall cause any active signals to + stop. When KeepActive is specified in the event, the MG shall not + interrupt any signals active on the Termination on which the event is + detected. + + An event can include an Embedded Signals descriptor and/or an + Embedded Events descriptor which, if present, replaces the current + Signals/Events descriptor when the event is recognized. It is + possible, for example, to specify that the dial-tone Signal be + generated when an off-hook Event is recognized, or that the dial-tone + Signal be stopped when a digit is recognized. A media gateway + controller shall not send EventsDescriptors with an event both marked + KeepActive and containing an embedded SignalsDescriptor. + + + + + + + +Groves, et al. Standards Track [Page 37] + +RFC 3525 Gateway Control Protocol June 2003 + + + Only one level of embedding is permitted. An embedded + EventsDescriptor SHALL NOT contain another embedded EventsDescriptor; + an embedded EventsDescriptor MAY contain an embedded + SignalsDescriptor. + + An EventsDescriptor received by a media gateway replaces any previous + Events descriptor. Event notification in process shall complete, and + events detected after the command containing the new EventsDescriptor + executes, shall be processed according to the new EventsDescriptor. + + An empty Events Descriptor disables all event recognition and + reporting. An empty EventBuffer Descriptor clears the EventBuffer + and disables all event accumulation in LockStep mode: the only events + reported will be those occurring while an Events Descriptor is + active. If an empty Events Descriptor is activated while the + Termination is operating in LockStep mode, the events buffer is + immediately cleared. + +7.1.10 EventBuffer descriptor + + The EventBuffer descriptor contains a list of events, with their + parameters if any, that the MG is requested to detect and buffer when + EventBufferControl equals LockStep (see 7.1.9). + +7.1.11 Signals descriptor + + Signals are MG generated media such as tones and announcements as + well as bearer-related signals such as hookswitch. More complex + signals may include a sequence of such simple signals interspersed + with and conditioned upon the receipt and analysis of media or + bearer-related signals. Examples include echoing of received data as + in Continuity Test package. Signals may also request preparation of + media content for future signals. + + A SignalsDescriptor is a parameter that contains the set of signals + that the Media Gateway is asked to apply to a Termination. A + SignalsDescriptor contains a number of signals and/or sequential + signal lists. A SignalsDescriptor may contain zero signals and + sequential signal lists. Support of sequential signal lists is + optional. + + Signals are defined in packages. Signals shall be named with a + Package name (in which the signal is defined) and a SignalID. No + wildcard shall be used in the SignalID. Signals that occur in a + SignalsDescriptor have an optional StreamID parameter (default is 0, + to indicate that the signal is not related to a particular media + stream), an optional signal type (see below), an optional duration + and possibly parameters defined in the package that defines the + + + +Groves, et al. Standards Track [Page 38] + +RFC 3525 Gateway Control Protocol June 2003 + + + signal. This allows a single signal to have some variation in + meaning, obviating the need to create large numbers of individual + signals. + + Finally, the optional parameter "notifyCompletion" allows a MGC to + indicate that it wishes to be notified when the signal finishes + playout. The possible cases are that the signal timed out (or + otherwise completed on its own), that it was interrupted by an event, + that it was halted when a Signals descriptor was replaced, or that it + stopped or never started for other reasons. If the notifyCompletion + parameter is not included in a Signals descriptor, notification is + generated only if the signal stopped or was never started for other + reasons. For reporting to occur, the signal completion event (see + E.1.2) must be enabled in the currently active Events descriptor. + + The duration is an integer value that is expressed in hundredths of a + second. + + There are three types of signals: + + - on/off - the signal lasts until it is turned off; + + - timeout - the signal lasts until it is turned off or a specific + period of time elapses; + + - brief - the signal will stop on its own unless a new Signals + descriptor is applied that causes it to stop; no timeout value is + needed. + + If a signal of default type other than TO has its type overridden to + type TO in the Signals descriptor, the duration parameter must be + present. + + If the signal type is specified in a SignalsDescriptor, it overrides + the default signal type (see 12.1.4). If duration is specified for + an on/off signal, it SHALL be ignored. + + A sequential signal list consists of a signal list identifier and a + sequence of signals to be played sequentially. Only the trailing + element of the sequence of signals in a sequential signal list may be + an on/off signal. The duration of a sequential signal list is the + sum of the durations of the signals it contains. + + Multiple signals and sequential signal lists in the same + SignalsDescriptor shall be played simultaneously. + + Signals are defined as proceeding from the Termination towards the + exterior of the Context unless otherwise specified in a package. + + + +Groves, et al. Standards Track [Page 39] + +RFC 3525 Gateway Control Protocol June 2003 + + + When the same Signal is applied to multiple Terminations within one + Transaction, the MG should consider using the same resource to + generate these Signals. + + Production of a Signal on a Termination is stopped by application of + a new SignalsDescriptor, or detection of an Event on the Termination + (see 7.1.9). + + A new SignalsDescriptor replaces any existing SignalsDescriptor. Any + signals applied to the Termination not in the replacement descriptor + shall be stopped, and new signals are applied, except as follows. + Signals present in the replacement descriptor and containing the + KeepActive flag shall be continued if they are currently playing and + have not already completed. If a replacement signal descriptor + contains a signal that is not currently playing and contains the + KeepActive flag, that signal SHALL be ignored. If the replacement + descriptor contains a sequential signal list with the same identifier + as 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 + + The Audit descriptor specifies what information is to be audited. + The Audit descriptor specifies the list of descriptors to be + returned. Audit may be used in any command to force the return of + any descriptor containing the current values of its properties, + events, signals and statistics even if that descriptor was not + present in the command, or had no underspecified parameters. + Possible items in the Audit descriptor are: + + Modem + Mux + Events + Media + Signals + ObservedEvents + DigitMap + Statistics + Packages + EventBuffer + + + + + + +Groves, et al. Standards Track [Page 40] + +RFC 3525 Gateway Control Protocol June 2003 + + + Audit may be empty, in which case, no descriptors are returned. This + is useful in Subtract, to inhibit return of statistics, especially + when using wildcard. + +7.1.13 ServiceChange descriptor + + The ServiceChangeDescriptor contains the following parameters: + + . ServiceChangeMethod + . ServiceChangeReason + . ServiceChangeAddress + . ServiceChangeDelay + . ServiceChangeProfile + . ServiceChangeVersion + . ServiceChangeMGCId + . TimeStamp + . Extension + + See 7.2.8. + +7.1.14 DigitMap descriptor + +7.1.14.1 DigitMap definition, creation, modification and deletion + + A DigitMap is a dialing plan resident in the Media Gateway used for + detecting and reporting digit events received on a Termination. The + DigitMap descriptor contains a DigitMap name and the DigitMap to be + assigned. A digit map may be preloaded into the MG by management + action and referenced by name in an EventsDescriptor, may be defined + dynamically and subsequently referenced by name, or the actual + digitmap itself may be specified in the EventsDescriptor. It is + permissible for a digit map completion event within an Events + descriptor to refer by name to a DigitMap which is defined by a + DigitMap descriptor within the same command, regardless of the + transmitted order of the respective descriptors. + + DigitMaps defined in a DigitMapDescriptor can occur in any of the + standard Termination manipulation Commands of the protocol. A + DigitMap, once defined, can be used on all Terminations specified 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, provided that a DigitMap with the same name + has not been defined on the given Termination. When a DigitMap is + defined dynamically in a DigitMap descriptor: + + - A new DigitMap is created by specifying a name that is not yet + defined. The value shall be present. + + + + +Groves, et al. Standards Track [Page 41] + +RFC 3525 Gateway Control Protocol June 2003 + + + - A DigitMap value is updated by supplying a new value for a name + that is already defined. Terminations presently using the + digitmap shall continue to use the old definition; subsequent + EventsDescriptors specifying the name, including any + EventsDescriptor in the command containing the DigitMap + descriptor, shall use the new one. + + - A DigitMap is deleted by supplying an empty value for a name that + is already defined. Terminations presently using the digitmap + shall continue to use the old definition. + +7.1.14.2 DigitMap Timers + + The collection of digits according to a DigitMap may be protected by + three timers, viz. a start timer (T), short timer (S), and long timer + (L). + + 1) The start timer (T) is used prior to any digits having been + dialed. If the start timer is overridden with the value set to + zero (T=0), then the start timer shall be disabled. This implies + that the MG will wait indefinitely for digits. + + 2) If the Media Gateway can determine 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). + + 3) If the digit string has matched one of the patterns in a digit + map, but it is possible that more digits could be received which + would cause a match with a different pattern, then instead of + reporting the match immediately, the MG must apply the short timer + (S) and wait for more digits. + + The timers are configurable parameters to a DigitMap. Default values + of these timers should be provisioned on the MG, but can be + overridden by values specified within the DigitMap. + +7.1.14.3 DigitMap Syntax + + The formal syntax of 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 defined either by + a string or by a list of strings. Each string in the list is an + alternative event sequence, specified either as a sequence of digit + map symbols or as a regular expression of digit map symbols. These + digit map symbols, the digits "0" through "9" and letters "A" through + a maximum value depending on the signalling system concerned, but + never exceeding "K", correspond to specified events within a package + + + +Groves, et al. Standards Track [Page 42] + +RFC 3525 Gateway Control Protocol June 2003 + + + which has been designated in the Events descriptor on the Termination + to which the digit map is being applied. (The mapping between events + and digit map symbols is defined in the documentation for packages + associated with channel-associated signalling systems such as DTMF, + MF, or R2. Digits "0" through "9" MUST be mapped to the + corresponding digit events within the signalling system concerned. + Letters should be allocated in logical fashion, facilitating the use + of range notation for alternative events.) + + The letter "x" is used as a wildcard, designating any event + corresponding to symbols in the range "0"-"9". The string may also + contain explicit ranges and, more generally, explicit sets of + symbols, designating alternative events any one of which satisfies + that position of the digit map. Finally, the dot symbol "." stands + for zero or more repetitions of the event selector (event, range of + events, set of alternative events, or wildcard) that precedes it. As + a consequence of the third timing rule above, inter-event timing + while matching a terminal dot symbol uses the short timer by default. + + In addition to these event symbols, the string may contain "S" and + "L" inter-event timing specifiers and the "Z" duration modifier. "S" + and "L" respectively indicate that the MG should use the short (S) + timer or the long (L) timer for subsequent events, overriding the + timing rules described above. If an explicit timing specifier is in + effect in one alternative event sequence, but none is given in any + other candidate alternative, the timer value set by the explicit + timing specifier must be used. If all sequences with explicit timing + controls are dropped from the candidate set, timing reverts to the + default rules given above. Finally, if conflicting timing specifiers + are in effect in different alternative sequences, the long timer + shall be used. + + A "Z" designates a long duration event: placed in front of the + symbol(s) designating the event(s) which satisfy a given digit + position, it indicates that that position is satisfied only if the + duration of the event exceeds the long-duration threshold. The value + of this 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 which invoked it is + active and it has not completed. 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 + through detection of an additional event (unambiguous match); or + + + +Groves, et al. Standards Track [Page 43] + +RFC 3525 Gateway Control Protocol June 2003 + + + - an event has been detected such that a match to a complete + alternative event sequence of the digit map will be impossible no + matter what additional events are received. + + Upon completion, a digit map completion event as defined in the + package providing the events being mapped into the digit map shall be + generated. At that point the digit map is deactivated. Subsequent + events in the package are processed as per the currently active event + processing mechanisms. + +7.1.14.5 DigitMap Procedures + + Pending completion, successive events shall be processed according to + the following rules: + + 1) The "current dial string", an internal variable, is initially + empty. The set of candidate alternative event sequences includes + all of the alternatives specified in the digit map. + + 2) At each step, a timer is set to wait for the next event, based + either on the default timing rules given above or on explicit + timing specified in one or more alternative event sequences. If + the timer expires and a member of the candidate set of + alternatives is fully satisfied, a timeout completion with full + match is reported. If the timer expires and part or none of any + candidate alternative is satisfied, a timeout completion with + partial match is reported. + + 3) If an event is detected before the timer expires, it is 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 this is relevant in the current symbol + position (because at least one of the candidate alternative event + sequences includes the "Z" modifier at this position in the + sequence). + + 4) The current dial string is compared to the candidate alternative + event sequences. If and only if a sequence expecting a + long-duration event at this position is matched (i.e., the event + had long duration and met the specification for this position), + then any alternative event sequences not specifying a long + duration event at this position are discarded, and the current + dial string is modified by inserting a "Z" in front of the symbol + representing 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 not specifying a long duration event in the given + + + + +Groves, et al. Standards Track [Page 44] + +RFC 3525 Gateway Control Protocol June 2003 + + + position remain in the candidate set after application of the + above rules, the observed event duration is treated as irrelevant + in assessing matches to them. + + 5) If exactly one candidate remains and it has been fully matched, a + completion event is 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 will + then be reported as per the currently active event processing + mechanisms. + + 6) If no completion event is reported out of step 5, processing + returns to step 2. + +7.1.14.6 DigitMap Activation + + A digit map is activated whenever a new Event descriptor is applied + to the Termination or embedded Event descriptor is activated, and + that Event descriptor contains a digit map completion event. The + digit map completion event contains an eventDM field in the requested + actions field. Each new activation of a digit map begins at step 1 + of the above procedure, with a clear current dial string. Any + previous contents of the current dial string from an earlier + activation are lost. + + A digit map completion event that does not contain an eventDM field + in its requested actions field is considered an error. Upon receipt + of such an event in an EventsDescriptor, a MG shall respond with an + error response, including Error 457 - Missing parameter in signal or + event. + +7.1.14.7 Interaction Of DigitMap and Event Processing + + While the digit map is activated, detection is enabled for all events + defined in the package containing the specified digit map completion + event. Normal event behaviour (e.g., stopping of signals unless the + digit completion event has the KeepActive flag enabled) continues to + apply for each such event detected, except that: + + - the events in the package containing the specified digit map + completion event other than the completion event itself are not + individually notified and have no side-effects unless separately + enabled; and + + + + + +Groves, et al. Standards Track [Page 45] + +RFC 3525 Gateway Control Protocol June 2003 + + + - an event that triggers a partial match completion event is not + recognized and therefore has no side effects until reprocessed + following the recognition of the digit map completion event. + +7.1.14.8 Wildcards + + Note that if a package contains a digit map completion event, then an + event specification consisting of the package name with a wildcarded + ItemID (Property Name) will activate a digit map; to that end, the + event specification must include an eventDM field according to + section 7.1.14.6. 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 are detected. + +7.1.14.9 Example + + As an example, consider the following dial plan: + + 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 E.6 is used to collect the + dialed digits, then the dialing plan shown above results in the + following digit map: + + (0| 00|[1-7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.) + +7.1.15 Statistics descriptor + + The Statistics Descriptor provides information describing the status + and usage of a Termination during its existence within a specific + Context. There is a set of standard statistics kept for each + Termination where appropriate (number of octets sent and received for + + + +Groves, et al. Standards Track [Page 46] + +RFC 3525 Gateway Control Protocol June 2003 + + + example). The particular statistical properties that are reported + for a given Termination are determined by the Packages realized by + the Termination. By default, statistics are reported when the + Termination is Subtracted from the Context. This behaviour can be + overridden by including an empty AuditDescriptor in the Subtract + command. Statistics may also be returned from the AuditValue + command, or any Add/Move/Modify command using the Audit descriptor. + + Statistics are cumulative; reporting Statistics does not reset them. + Statistics are reset when a Termination is Subtracted from a Context. + +7.1.16 Packages descriptor + + Used only with the AuditValue command, the PackageDescriptor returns + a list of Packages realized by the Termination. + +7.1.17 ObservedEvents descriptor + + ObservedEvents is supplied with the Notify command to inform the MGC + of which event(s) were detected. Used with the AuditValue command, + the ObservedEventsDescriptor returns events in the event buffer which + have not been Notified. ObservedEvents contains the + RequestIdentifier of the EventsDescriptor that triggered the + notification, the event(s) detected, optionally the detection time(s) + and any parameters of the observed event. Detection times are + reported with a precision of hundredths of a second. + +7.1.18 Topology descriptor + + A Topology descriptor is used to specify flow directions between + Terminations in a Context. Contrary to the descriptors in previous + subclauses, the Topology descriptor applies to a Context instead of a + Termination. The default topology of a Context is that each + Termination's transmission is received by all other Terminations. + The Topology descriptor is optional to implement. An MG that does + not support Topology descriptors, but receives a command containing + one, returns Error 444 Unsupported or unknown descriptor, and + optionally includes a string containing the name of the unsupported + Descriptor ("Topology") in the error text in the error descriptor. + + The Topology descriptor occurs before the commands in an action. It + is possible to have an action containing only a Topology descriptor, + provided that the Context to which the action applies already exists. + + + + + + + + +Groves, et al. Standards Track [Page 47] + +RFC 3525 Gateway Control Protocol June 2003 + + + A Topology descriptor consists of a sequence of triples of the form + (T1, T2, association). T1 and T2 specify Terminations within the + Context, possibly using the ALL or CHOOSE wildcard. The association + specifies how media flows between these two Terminations as follows. + + - (T1, T2, isolate) means that the Terminations matching T2 do not + receive media from the Terminations matching T1, nor vice versa. + + - (T1, T2, oneway) means that the Terminations that match T2 receive + media from the Terminations matching T1, but not vice versa. In + this case use of the ALL wildcard such that there are Terminations + that match both T1 and T2 is not allowed. + + - (T1, T2, bothway) means that the Terminations matching T2 receive + media from the Terminations matching T1, and vice versa. In this + case it is allowed to use wildcards such that there are + Terminations that match both T1 and T2. However, if there is a + Termination that matches both, no loopback is introduced. + + CHOOSE wildcards may be used in T1 and T2 as well, under the + following restrictions: + + - the action (see clause 8) of which the topology descriptor is part + contains an Add command in which a CHOOSE wildcard is used; + + - 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 to which a Termination is added, is + connected to the newly added Termination as specified by the Topology + descriptor. + + If a termination is not mentioned within a Topology Descriptor, any + topology associated with it remains unchanged. If, however, a new + termination is added into a context its association with the other + terminations within the context defaults to bothway, unless a + Topology Descriptor is given to change this (e.g., if T3 is added to + a context with T1 and T2 with topology (T3, T1, oneway) it will be + connected bothway to T2). + + Figure 7 and the table following it show some examples of the effect + of including topology descriptors in actions. In these examples it + is assumed that the topology descriptors are applied in sequence. + + + + + +Groves, et al. Standards Track [Page 48] + +RFC 3525 Gateway Control Protocol June 2003 + + + +------------------+ +------------------+ +------------------+ + | +----+ | | +----+ | | +----+ | + | | 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 + + Note: the direction of the arrow indicates the direction of flow. + + Figure 7: Example topologies + + Topology Description + + 1 No topology descriptors When no topology descriptors are + included, all Terminations have a + bothway connection to all other + Terminations. + + 2 T1, T2 Isolate Removes the connection between T1 and + T2. T3 has a bothway connection with + both T1 and T2. T1 and T2 have bothway + connection to T3. + + + + + + +Groves, et al. Standards Track [Page 49] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 All Terminations have a bothway + bothway and T1, T3 connection to all other Terminations. + bothway may be implied or + explicit). + + A oneway connection must be implemented in such a way that the other + Terminations in the Context are not aware of the change in topology. + +7.1.19 Error Descriptor + + If a responder encounters an error when processing a transaction + request, it must include an error descriptor in its response. A + Notify request may contain an error descriptor as well. + + An error descriptor consists of an IANA-registered error code, + optionally accompanied by an error text. H.248.8 contains a list of + valid error codes and error descriptions. + + An error descriptor shall be specified at the "deepest level" that is + semantically appropriate for the error being described and that is + possible given any parsing problems with the original request. An + error descriptor may refer to a syntactical construct other than + where it appears. For example, Error descriptor 422 - Syntax Error + in Action, could appear within a command even though it refers to the + larger construct - the action - and not the particular command within + which it appears. + +7.2 Command Application Programming Interface + + Following is an Application Programming Interface (API) describing + the Commands of the protocol. This API is shown to illustrate the + Commands and their parameters and is not intended to specify + implementation (e.g., via use of blocking function calls). It + describes the input parameters in parentheses after the command name + and the return values in front of the Command. This is only for + descriptive purposes; the actual Command syntax and encoding are + + + + + +Groves, et al. Standards Track [Page 50] + +RFC 3525 Gateway Control Protocol June 2003 + + + specified in later subclauses. The order of parameters to commands + is not fixed. Descriptors may appear as parameters to commands in + any order. The descriptors SHALL be processed in the order in which + they appear. + + Any reply to a command may contain an error descriptor; the API does + not specifically show this. + + All parameters enclosed by square brackets ([. . .]) are considered + 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] + [, EventBufferDescriptor] + [, 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. If a CHOOSE wildcard is used in the TerminationID, the + selected TerminationID will be returned. Wildcards may be used in an + Add, but such usage 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. + + + + +Groves, et al. Standards Track [Page 51] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 are not currently in the Context, such Terminations are added to + the Context as if individual Add commands listing the Terminations + were 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 present, it provides + the list of events that should be detected on the Termination. + + The EventBufferDescriptor parameter is optional. If present, it + provides the list of events that the MG is requested to detect and + buffer when EventBufferControl equals LockStep. + + The SignalsDescriptor parameter is optional. If present, it provides + the list of signals that should be applied to the Termination. + + The DigitMapDescriptor parameter is optional. If present, it defines + a DigitMap definition that may be used in an EventsDescriptor. + + The AuditDescriptor is optional. If present, the command will return + descriptors as specified in the AuditDescriptor. + + All descriptors that can be modified could be returned by 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 + + The Modify Command modifies the properties of a Termination. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + + + +Groves, et al. Standards Track [Page 52] + +RFC 3525 Gateway Control Protocol June 2003 + + + Modify( TerminationID + [, MediaDescriptor] + [, ModemDescriptor] + [, MuxDescriptor] + [, EventsDescriptor] + [, EventBufferDescriptor] + [, SignalsDescriptor] + [, DigitMapDescriptor] + [, AuditDescriptor] + ) + + The TerminationID may be specific if a single Termination in the + Context is to be modified. Use of wildcards in the TerminationID may + be appropriate for some operations. 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 CHOOSE option is an + error, as the Modify command may only be used on existing + Terminations. + + For convenience, if a Multiplex Descriptor is present in a Modify + command, then: + + - if the new Multiplex Descriptor lists any Terminations that are + not currently in the Context, such Terminations are added to the + context as if individual commands listing the Terminations were + invoked. + + - if any Terminations listed previously in the Multiplex Descriptor + are no longer present in the new Multiplex Descriptor, they are + subtracted from the context as if individual Subtract commands + listing the Terminations were invoked. + + The remaining parameters to Modify are the same as those to Add. + Possible return values are the same as those to Add. + +7.2.3 Subtract + + The Subtract Command disconnects a Termination from its Context and + returns statistics on the Termination's participation in the Context. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + + + +Groves, et al. Standards Track [Page 53] + +RFC 3525 Gateway Control Protocol June 2003 + + + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + Subtract(TerminationID + [, AuditDescriptor] + ) + + TerminationID in the input parameters represents the Termination that + is being subtracted. The TerminationID may be specific or may be a + wildcard value indicating that all (or a set of related) Terminations + in the Context of the Subtract Command are to be 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. + + The use of CHOOSE in the TerminationID is an error, as the Subtract + command may only be used on existing Terminations. + + ALL may be used as the ContextID as well as the TerminationId in a + Subtract, which would have the effect of deleting all Contexts, + deleting all ephemeral Terminations, and returning all physical + Terminations to Null Context. Subtract of a termination from the + Null Context is not allowed. + + For convenience, if a multiplexing Termination is the object of a + Subtract command, then any bearer Terminations listed in its + Multiplex Descriptor are subtracted from the context as if individual + Subtract commands listing the Terminations were invoked. + + By default, the Statistics parameter is returned to report + information collected on the Termination or Terminations specified in + the Command. The information reported applies to the Termination's + or Terminations' existence in the Context from which it or they are + being subtracted. + + The AuditDescriptor is optional. If present, the command will return + only those descriptors as specified in the AuditDescriptor, which may + be empty. If omitted, the Statistics descriptor is returned, by + default. Possible return values are the same as those to Add. + + When a provisioned Termination is Subtracted from a Context, its + property values shall revert to: + + - the default value, if specified for the property and not + overridden by provisioning; + + - otherwise, the provisioned value. + + + +Groves, et al. Standards Track [Page 54] + +RFC 3525 Gateway Control Protocol June 2003 + + +7.2.4 Move + + The Move Command moves a Termination to another Context from its + current Context in one atomic operation. The Move command is the + only command that refers to a Termination in a Context different from + that to which the command is applied. The Move command shall not be + used to move Terminations to or from the null Context. + + TerminationID + [,MediaDescriptor] + [,ModemDescriptor] + [,MuxDescriptor] + [,EventsDescriptor] + [,SignalsDescriptor] + [,DigitMapDescriptor] + [,ObservedEventsDescriptor] + [,EventBufferDescriptor] + [,StatisticsDescriptor] + [,PackagesDescriptor] + Move( TerminationID + [, MediaDescriptor] + [, ModemDescriptor] + [, MuxDescriptor] + [, EventsDescriptor] + [, EventBufferDescriptor] + [, 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. The + Context to which the Termination is moved 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 Move command does not affect the properties of the Termination on + which it operates, except those properties explicitly modified by + descriptors included in the Move command. The AuditDescriptor with + the Statistics option, for example, would return statistics on the + Termination just prior to the Move. Possible descriptors returned + from Move are the same as for Add. + + + + + + +Groves, et al. Standards Track [Page 55] + +RFC 3525 Gateway Control Protocol June 2003 + + + For convenience, if a multiplexing Termination is the object of a + Move command, then any bearer Terminations listed in its Multiplex + Descriptor are also moved as if individual Move commands listing the + Terminations were invoked. + + Move SHALL NOT be used on a Termination with a serviceState of + "OutofService". + +7.2.5 AuditValue + + The AuditValue Command 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, 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. Use of CHOOSE is an error. + + The appropriate descriptors, with the current values for the + Termination, are 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 + ObservedEventsDescriptor 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. + + + +Groves, et al. Standards Track [Page 56] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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. 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 wildcard. Annexes A and B + provide a special syntax for presenting such a list in condensed + form, such that the AuditValue command tag does not have to be + repeated for each TerminationID. + + AuditValue results depend on the Context, viz. specific, null, or + wildcarded. (Note that ContextID ALL does not include the null + Context.) The TerminationID may be specific, or wildcarded. + + The following are examples of what is returned in case the context + and/or the termination is wildcarded and a wildcarded response has + been specified. + + Assume that the gateway has 4 terminations: t1/1, t1/2, t2/1 and + t2/2. Assume that terminations t1/* have implemented packages aaa + and bbb and that terminations t2/* have implemented packages ccc and + ddd. Assume that Context 1 has t1/1 and t2/1 in it and that Context + 2 has t1/2 and t2/2 in it. + + The command: + + Context=1{AuditValue=t1/1{Audit{Packages}}} + + Returns: + + Context=1{AuditValue=t1/1{Packages{aaa,bbb}}} + + The command: + + Context=*{AuditValue=t2/*{Audit{Packages}}} + + Returns: + + Context=1{AuditValue=t2/1{Packages{ccc,ddd}}}, + Context=2{AuditValue=t2/2{Packages{ccc,ddd}}} + + The command: + + Context=*{W-AuditValue=t1/*{Audit{Packages}}} + + + +Groves, et al. Standards Track [Page 57] + +RFC 3525 Gateway Control Protocol June 2003 + + + Returns: + + Context=*{W-AuditValue=t1/*{Packages{aaa,bbb}}} + + Note: A wildcard response may also be used for other commands such as + Subtract. + + The following illustrates other information that can be obtained with + the AuditValue 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 (the ContextID list + should be returned by using multiple action + replies, each containing a ContextID from + the list) + + All Specific (Non-null) ContextID in which the + Termination currently exists + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 58] + +RFC 3525 Gateway Control Protocol June 2003 + + +7.2.6 AuditCapabilities + + The AuditCapabilities Command returns the possible values of + properties, events, signals and statistics associated with + Terminations. + + 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. + + + + + + + + + + + +Groves, et al. Standards Track [Page 59] + +RFC 3525 Gateway Control Protocol June 2003 + + + The following illustrates other information that can be obtained with + the AuditCapabilties 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 MG 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 Same as for AuditValue + + All Specific Same as for AuditValue + +7.2.7 Notify + + The Notify Command allows the Media Gateway to notify the Media + Gateway Controller of events occurring within the Media Gateway. + + TerminationID + Notify(TerminationID, + ObservedEventsDescriptor, + [ErrorDescriptor] + ) + + The TerminationID parameter specifies the Termination issuing the + Notify Command. The TerminationID shall be a fully qualified name. + + The ObservedEventsDescriptor contains the RequestID and a list of + events that the Media Gateway detected in the order that they were + detected. Each event in the list is accompanied by parameters + associated with the event and optionally an indication of the time + that the event was detected. Procedures for sending Notify commands + with RequestID equal to 0 are for further study. + + Notify Commands with RequestID not equal to 0 shall occur only as the + result of detection of an event specified by an Events descriptor + which is active on the Termination concerned. + + + +Groves, et al. Standards Track [Page 60] + +RFC 3525 Gateway Control Protocol June 2003 + + + The RequestID returns the RequestID parameter of the EventsDescriptor + that triggered the Notify Command. It is used to correlate the + notification with the request that triggered it. The events in the + list must have been requested via the triggering EventsDescriptor or + embedded events descriptor unless the RequestID is 0 (which is for + further study). + + The ErrorDescriptor may be sent in the Notify Command as a result of + Error 518 - Event buffer full. + +7.2.8 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. The Media Gateway Controller may indicate that + Termination(s) shall be taken out of or returned to service. The + Media Gateway may notify the MGC that the capability of a Termination + has changed. It also allows a MGC to hand over control of a MG to + another MGC. + + TerminationID, + + [ServiceChangeDescriptor] + ServiceChange ( TerminationID, + ServiceChangeDescriptor + ) + + The TerminationID parameter specifies the Termination(s) that are + taken out of or returned to service. Wildcarding of Termination + names is permitted, with the exception that the CHOOSE mechanism + shall not be used. Use of the "Root" TerminationID indicates a + ServiceChange affecting the entire Media Gateway. + + The ServiceChangeDescriptor contains the following parameters as + required: + + - ServiceChangeMethod + - ServiceChangeReason + - ServiceChangeDelay + - ServiceChangeAddress + - ServiceChangeProfile + - ServiceChangeVersion + - ServiceChangeMgcId + - TimeStamp + + + + + + +Groves, et al. Standards Track [Page 61] + +RFC 3525 Gateway Control Protocol June 2003 + + + The ServiceChangeMethod parameter specifies the type of ServiceChange + that will or has occurred: + + 1) Graceful - indicates that the specified Terminations will be taken + out of service after the specified ServiceChangeDelay; established + connections are not yet affected, but the Media Gateway Controller + should refrain from establishing new connections and should + attempt to gracefully tear down existing connections on the + Termination(s) affected by the serviceChange command. The MG + should set Termination serviceState at the expiry of + ServiceChangeDelay or the removal of the Termination from an + active Context (whichever is first), to "out of service". + + 2) Forced - indicates that the specified Terminations were taken + abruptly out of service and any established connections associated + with them may be lost. For non-Root terminations, the MGC is + responsible for cleaning up the Context (if any) with which the + failed Termination is associated. At a minimum the Termination + shall be subtracted from the Context. The Termination + serviceState should be "out of service". For the root + termination, the MGC can assume that all connections are lost on + the MG and thus can consider that all the terminations have been + subtracted. + + 3) Restart - indicates that service will be restored on the specified + Terminations after expiration of the ServiceChangeDelay. The + serviceState should be set to "inService" upon expiry of + ServiceChangeDelay. + + 4) Disconnected - always applied with the Root TerminationID, + indicates that the MG lost communication with the MGC, but it was + subsequently restored to the same MGC (possibly after trying other + MGCs on a pre-provisioned list). Since MG state may have changed, + the MGC may wish to use the Audit command to resynchronize its + state with the MG's. + + 5) Handoff - sent from the MGC to the MG, this reason indicates that + the MGC is going out of service and a new MGC association must be + established. Sent from the MG to the MGC, this indicates that the + MG is attempting to establish a new association in accordance with + a Handoff received from the MGC with which it was previously + associated. + + 6) Failover - sent from MG to MGC to indicate the primary MG is out + of service and a secondary MG is taking over. This serviceChange + method is also sent from the MG to the MGC when the MG detects + that MGC has failed. + + + + +Groves, et al. Standards Track [Page 62] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7) Another value whose meaning is mutually understood between the MG + and the MGC. + + The ServiceChangeReason parameter specifies the reason why the + ServiceChange has or will occur. It consists of an alphanumeric + token (IANA registered) and, optionally, an explanatory string. + + The optional ServiceChangeAddress parameter specifies the address + (e.g., IP port number for IP networks) to be used for subsequent + communications. It can be specified in the input parameter + descriptor or the returned result descriptor. ServiceChangeAddress + and ServiceChangeMgcId parameters must not both be present in the + ServiceChangeDescriptor or the ServiceChangeResultDescriptor. The + ServiceChangeAddress provides an address to be used within the + Context of the association currently being negotiated, while the + ServiceChangeMgcId provides an alternate address where the MG should + seek to establish another association. Note that the use of + ServiceChangeAddress is not encouraged. MGCs and MGs must be able to + cope with the ServiceChangeAddress being either a full address or + just a port number in the case of TCP transports. + + The optional ServiceChangeDelay parameter is expressed in seconds. + If the delay is absent or set to zero, the delay value should be + considered to be null. In the case of a "graceful" + ServiceChangeMethod, a null delay indicates that the Media Gateway + Controller should wait for the natural removal of existing + connections and should not establish new connections. For "graceful" + only, a null delay means the MG must not set serviceState "out of + service" until the Termination is in the null Context. + + The optional ServiceChangeProfile parameter specifies the Profile (if + any) of the protocol supported. The ServiceChangeProfile includes + the version of the profile supported. + + The optional ServiceChangeVersion parameter contains the protocol + version and is used if protocol version negotiation occurs (see + 11.3). + + The optional TimeStamp parameter specifies the actual time as kept by + the sender. As such, it is not necessarily absolute time according + to, for example, a local time zone - it merely establishes an + arbitrary starting time against which all future timestamps + transmitted by a sender during this association shall be compared. + It can be used by the responder to determine how its notion of time + differs from that of its correspondent. TimeStamp is sent with a + precision of hundredths of a second. + + + + + +Groves, et al. Standards Track [Page 63] + +RFC 3525 Gateway Control Protocol June 2003 + + + The optional Extension parameter may contain any value whose meaning + is mutually understood by the MG and MGC. + + A ServiceChange Command specifying the "Root" for the TerminationID + and ServiceChangeMethod equal to Restart is a registration command by + which a Media Gateway announces its existence to the Media Gateway + Controller. The Media Gateway may also announce a registration + command by specifying the "Root" for the TerminationID and + ServiceChangeMethod equal to Failover when the MG detects MGC + failures. The Media Gateway is expected to be provisioned with the + name of one primary and optionally some number of alternate Media + Gateway Controllers. Acknowledgement of the ServiceChange Command + completes the registration process, except when the MGC has returned + an alternative ServiceChangeMgcId as described in the following + paragraph. The MG may specify the transport ServiceChangeAddress to + be used by the MGC for sending messages in the ServiceChangeAddress + parameter in 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. In + either case, the recipient must use the supplied address as the + destination for all subsequent transaction requests within the + association. At the same time, as indicated in clause 9, transaction + replies and pending indications must be sent to the address from + which the corresponding requests originated. This must be done even + if it implies 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 Media Gateway Controller that should + preferably be contacted for further service by the Media Gateway. In + this case the Media Gateway shall reissue the ServiceChange command + to the new Media Gateway Controller. The MGC specified in a + ServiceChangeMgcId, if provided, shall be contacted before any + further alternate MGCs. On a HandOff message from MGC to MG, the + ServiceChangeMgcId is the new MGC that will take over from the + current MGC. + + The return from ServiceChange is empty except when the Root + terminationID is used. In that case it includes the following + parameters as required: + + - ServiceChangeAddress, if the responding MGC wishes to specify a + new destination for messages from the MG for the remainder of the + association; + + - ServiceChangeMgcId, if the responding MGC does not wish to sustain + an association with the MG; + + + +Groves, et al. Standards Track [Page 64] + +RFC 3525 Gateway Control Protocol June 2003 + + + - ServiceChangeProfile, if the responder wishes to negotiate the + profile to be used for the association; + + - ServiceChangeVersion, if the responder wishes to negotiate the + version of the protocol to be used for the association. + + The following ServiceChangeReasons are defined. This list may be + extended by an IANA registration as outlined in 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 Loss + +7.2.9 Manipulating and Auditing Context Attributes + + The commands of the protocol as discussed in the preceding subclauses + apply to Terminations. This subclause specifies how Contexts are + manipulated and audited. + + Commands are grouped into actions (see clause 8). An action applies + to one Context. In addition to commands, an action may contain + Context manipulation and auditing instructions. + + An action request sent to a MG may include a request to audit + attributes of a Context. An action may also include a request to + change the attributes of a Context. + + The Context properties that may be included in an action reply are + used to return information to a MGC. This can be information + requested by an audit of Context attributes or details of the effect + of manipulation of a Context. + + + + + + + +Groves, et al. Standards Track [Page 65] + +RFC 3525 Gateway Control Protocol June 2003 + + + If a MG receives an action which 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 processing + the manipulation request. + +7.2.10 Generic Command Syntax + + The protocol can be encoded in a binary format or in a text format. + MGCs should support both encoding formats. MGs may support both + formats. + + The protocol syntax for the binary format of the protocol is defined + in Annex A. Annex C specifies the encoding of the Local and Remote + descriptors for use with the binary format. + + A complete ABNF of the text encoding of the protocol per RFC 2234 is + given in Annex B. SDP is used as the encoding of the Local and + Remote descriptors for use with the text encoding as modified in + 7.1.8. + +7.3 Command Error Codes + + Errors consist of an IANA registered error code and an explanatory + string. Sending the explanatory string is optional. Implementations + are encouraged to append diagnostic information to the end of the + string. + + When a MG reports an error to a MGC, it does so in an error + descriptor. An error descriptor consists of an error code and + optionally the associated explanatory string. + + H.248.8 contains the error codes supported by Recommendations in the + H.248 sub-series. + +8 Transactions + + Commands between the Media Gateway Controller and the Media Gateway + are grouped into Transactions, each of which is identified by a + TransactionID. Transactions consist of one or more Actions. An + Action consists of a non-empty series of Commands, Context property + modifications, or Context property audits that are limited to + operating within a single Context. Consequently, each Action + typically specifies a ContextID. However, there are two + circumstances where a specific ContextID is not provided with an + Action. One is the case of modification of a Termination outside of + a Context. The other is where the controller requests the gateway to + create a new Context. Figure 8 is a graphic representation of the + Transaction, Action and Command relationships. + + + +Groves, et al. Standards Track [Page 66] + +RFC 3525 Gateway Control Protocol June 2003 + + + +----------------------------------------------------------+ + | 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 8: Transactions, Actions and Commands + + Transactions are presented as TransactionRequests. Corresponding + responses to a TransactionRequest are received in a single reply, + possibly preceded by a number of TransactionPending messages (see + 8.2.3). + + Transactions guarantee ordered Command processing. That is, Commands + within a Transaction are executed sequentially. Ordering of + Transactions is NOT guaranteed - transactions may be executed in any + order, or simultaneously. + + At the first failing Command in a Transaction, processing of the + remaining Commands in that Transaction stops. If a command contains + a wildcarded TerminationID, the command is attempted with each of the + actual TerminationIDs matching the wildcard. A response within the + TransactionReply is included for each matching TerminationID, even if + one or more instances generated an error. If any TerminationID + matching a wildcard results in an error when executed, any commands + following the wildcarded command are not attempted. + + + + +Groves, et al. Standards Track [Page 67] + +RFC 3525 Gateway Control Protocol June 2003 + + + Commands may be marked as "Optional" which can override this + behaviour - if a command marked as Optional results in an error, + subsequent commands in the Transaction will be executed. If a + command fails, the MG shall as far as possible restore the state that + existed prior to the attempted execution of the command before + continuing with command processing. + + A TransactionReply includes the results for all of the Commands in + the corresponding TransactionRequest. The TransactionReply includes + the return values for the Commands that were executed successfully, + and the Command and error descriptor for any Command that failed. + + TransactionPending is used to periodically notify the receiver that a + Transaction has not completed yet, but is actively being processed. + + Applications SHOULD implement an application level timer per + transaction. Expiration of the timer should cause a retransmission + of the request. Receipt of a Reply should cancel the timer. Receipt + of Pending should restart the timer. + +8.1 Common parameters + +8.1.1 Transaction Identifiers + + Transactions are identified by a TransactionID, which is assigned by + sender and is unique within the scope of the sender. A response + containing an error descriptor to indicate that the TransactionID is + missing in a request shall use TransactionID 0 in the corresponding + TransactionReply. + +8.1.2 Context Identifiers + + Contexts are identified by a ContextID, which is assigned by the + Media Gateway and is unique within the scope of the Media Gateway. + The Media Gateway Controller shall use the ContextID supplied by the + Media Gateway in all subsequent Transactions relating to that + Context. The protocol makes reference to a distinguished value that + may be used by the Media Gateway Controller when referring to a + Termination that is currently not associated with a Context, namely + the null ContextID. + + The CHOOSE wildcard is used to request that the Media Gateway create + a new Context. + + The MGC may use the ALL wildcard to address all Contexts on the MG. + The null Context is not included when the ALL wildcard is used. + + + + + +Groves, et al. Standards Track [Page 68] + +RFC 3525 Gateway Control Protocol June 2003 + + + The MGC shall not use partially specified ContextIDs containing the + CHOOSE or ALL wildcards. + +8.2 Transaction Application Programming Interface + + Following is an Application Programming Interface (API) describing + the Transactions of the protocol. This API is shown to illustrate + the Transactions and their parameters and is not intended to specify + implementation (e.g., via use of blocking function calls). It will + describe the input parameters and return values expected to be used + by the various Transactions of the protocol from a very high level. + Transaction syntax and encodings are specified in later subclauses. + +8.2.1 TransactionRequest + + The TransactionRequest is invoked by the sender. There is one + Transaction per request invocation. A request contains one or more + Actions, each of which specifies its target Context and one or more + Commands per Context. + + TransactionRequest(TransactionId { + ContextID {Command ... Command}, + . . . + ContextID {Command ... Command } }) + + The TransactionID parameter must specify a value for later + correlation with the TransactionReply or TransactionPending response + from the receiver. + + The ContextID parameter must specify a value to pertain to all + Commands that follow up to either the next specification of a + ContextID parameter or the end of the TransactionRequest, whichever + comes first. + + The Command parameter represents one of the Commands mentioned in 7.2 + (Command Application Programming Interface). + +8.2.2 TransactionReply + + The TransactionReply is invoked by the receiver. There is one reply + invocation per transaction. A reply contains one or more Actions, + each of which must specify its target Context and one or more + Responses per Context. The TransactionReply is invoked by the + responder when it has processed the TransactionRequest. + + + + + + + +Groves, et al. Standards Track [Page 69] + +RFC 3525 Gateway Control Protocol June 2003 + + + A TransactionRequest has been processed: + + - when all actions in that TransactionRequest have been processed; + or + + - when an error is encountered in processing that + TransactionRequest, except when the error is in an optional + command. + + A command has been processed when all descriptors in that command + have been processed. + + A SignalsDescriptor is considered to have been processed when it has + been established that the descriptor is syntactically valid, the + requested signals are supported and they have been queued to be + applied. + + An EventsDescriptor or EventBufferDescriptor is considered to have + been processed when it has been established that the descriptor is + syntactically valid, the requested events can be observed, any + embedded signals can be generated, any embedded events can be + detected, and the MG has been brought into a state in which the + events will be detected. + + TransactionReply(TransactionID { + ContextID { Response ... Response }, + . . . + ContextID { Response ... Response } }) + + The TransactionID parameter must be the same as that of the + corresponding TransactionRequest. + + The ContextID parameter must specify a value to pertain to all + Responses for the action. The ContextID may be specific, all or + null. + + Each of the Response parameters represents a return value as + mentioned in 7.2, or an error descriptor if the command execution + encountered an error. Commands after the point of failure are not + processed and, therefore, Responses are not issued for them. + + An exception to this occurs if a command has been marked as optional + in the Transaction request. If the optional command generates an + error, the transaction still continues to execute, so the Reply + would, in this case, have Responses after an Error. + + Section 7.1.19 Error Descriptor specifies the generation of error + descriptors. The text below discusses several individual cases. + + + +Groves, et al. Standards Track [Page 70] + +RFC 3525 Gateway Control Protocol June 2003 + + + If the receiver encounters an error in processing a ContextID, the + requested Action response will consist of the Context ID and a single + error descriptor, 422 - Syntax Error in Action. + + If the receiver encounters an error such that it cannot determine a + legal Action, it will return a TransactionReply consisting of the + TransactionID and a single error descriptor, 422 - Syntax Error in + Action. If the end of an action cannot be reliably determined but + one or more commands can be parsed, it will process them and then + send 422 - Syntax Error in Action as the last action for the + transaction. If the receiver encounters an error such that is cannot + determine a legal Transaction, it will return a TransactionReply with + a null TransactionID and a single error descriptor (403 - Syntax + Error in TransactionRequest). + + If the end of a transaction cannot be reliably determined and one or + more Actions can be parsed, it will process them and then return 403 + - Syntax Error in Transaction as the last action reply for the + transaction. If no Actions can be parsed, it will return 403 - + Syntax Error in TransactionRequest as the only reply. + + If the terminationID cannot be reliably determined, it will send 442 + - Syntax Error in Command as the action reply. + + If the end of a command cannot be reliably determined, it will return + 442 - Syntax Error in Command as the reply to the last action it can + parse. + +8.2.3 TransactionPending + + The receiver invokes the TransactionPending. A TransactionPending + indicates that the Transaction is actively being processed, but has + not been completed. It is used to prevent the sender from assuming + the TransactionRequest was lost where the Transaction will take some + time to complete. + + TransactionPending(TransactionID { } ) + + The TransactionID parameter must be the same as that of the + corresponding TransactionRequest. A property of root + (normalMGExecutionTime) is settable by the MGC to indicate the + interval within which the MGC expects a response to any transaction + from the MG. Another property (normalMGCExecutionTime) is settable + by the MGC to indicate the interval within which the MG should expect + a response to any transaction from the MGC. Senders may receive more + than one TransactionPending for a command. If a duplicate request is + + + + + +Groves, et al. Standards Track [Page 71] + +RFC 3525 Gateway Control Protocol June 2003 + + + received when pending, the responder may send a duplicate pending + immediately, or continue waiting for its timer to trigger another + TransactionPending. + +8.3 Messages + + Multiple Transactions can be concatenated into a Message. Messages + have a header, which includes the identity of the sender. The + Message Identifier (MID) of a message is set to a provisioned name + (e.g., domain address/domain name/device name) of the entity + transmitting the message. Domain name is a suggested default. An + H.248.1 entity (MG/MGC) must consistently use the same MID in all + messages it originates for the duration of control association with + the peer (MGC/MG). + + Every Message contains a Version Number identifying the version of + the protocol the message conforms to. Versions consist of one or two + digits, beginning with version 1 for the present version of the + protocol. + + The transactions in a message are treated independently. There is no + order implied; there is no application or protocol acknowledgement of + a message. A message is essentially a transport mechanism. For + example, message X containing transaction requests A, B, and C may be + responded to with message Y containing replies to A and C and message + Z containing the reply to B. Likewise, message L containing request + D and message M containing request E may be responded to with message + N containing replies to both D and E. + +9 Transport + + The transport mechanism for the protocol should allow the reliable + transport of transactions between a MGC and MG. The transport shall + remain independent of what particular commands are being sent and + shall be applicable to all application states. There are several + transports defined for the protocol, which are defined in Annexes to + this RFC and other Recommendations of the H.248 + sub-series. Additional Transports may be defined as additional + + Recommendations of the H.248 sub-series. For transport of the + protocol over IP, MGCs shall implement both TCP and UDP/ALF, a MG + shall implement TCP or UDP/ALF or both. + + The MG is provisioned with a name or address (such as DNS name or IP + address) of a primary and zero or more secondary MGCs (see 7.2.8) + that is the address the MG uses to send messages to the MGC. If TCP + or UDP is used as the protocol transport and the port to which the + initial ServiceChange request is to be sent is not otherwise known, + + + +Groves, et al. Standards Track [Page 72] + +RFC 3525 Gateway Control Protocol June 2003 + + + that request should be sent to the default port number for the + protocol. This port number is 2944 for text-encoded operation or + 2945 for binary-encoded operation, for either UDP or TCP. The MGC + receives the message containing the ServiceChange request from the MG + and can determine the MG's address from it. As described in 7.2.8, + either the MG or the MGC may supply an address in the + ServiceChangeAddress parameter to which subsequent transaction + requests must be addressed, but responses (including the response to + the initial ServiceChange request) must always be sent back to the + address which was the source of the corresponding request. For + example, in IP networks, this is the source address in the IP header + and the source port number in the TCP/UDP/SCTP header. + +9.1 Ordering of Commands + + This RFC does not mandate that the underlying transport protocol + guarantees the sequencing of transactions sent to an entity. This + property tends to maximize the timeliness of actions, but it has a + few drawbacks. For example: + + - Notify commands may be delayed and arrive at the MGC after the + transmission of a new command changing the EventsDescriptor. + + - If a new command is transmitted before a previous one is + acknowledged, there is no guarantee that prior command will be + executed before the new one. + + Media Gateway Controllers that want to guarantee consistent operation + of the Media Gateway may use the following rules. These rules are + with respect to commands that are in different transactions. + Commands that are in the same transaction are executed in order (see + clause 8). + + 1) When a Media Gateway handles several Terminations, commands + pertaining to the different Terminations may be sent in parallel, + for example following a model where each Termination (or group of + Terminations) is controlled by its own process or its own thread. + + 2) 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. However, a Subtract command may be + issued at any time. In consequence, a Media Gateway may sometimes + receive a Modify command that applies to a previously subtracted + Termination. Such commands should be ignored, and an error code + should be returned. + + + + + + +Groves, et al. Standards Track [Page 73] + +RFC 3525 Gateway Control Protocol June 2003 + + + 3) For transports that do not guarantee in-sequence delivery of + messages (i.e., UDP), there should normally be on a given + Termination at most one outstanding Notify command at any time. + + 4) In some cases, 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 wildcarding (or implied in + a Multiplex descriptor) should not be sent until the wildcarded + Subtract command is acknowledged. + + 5) AuditValue and AuditCapability are not subject to any sequencing. + + 6) 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 do not affect the command responder, which should always + respond to commands. + +9.2 Protection against Restart Avalanche + + In the event that a large number of Media Gateways are powered on + simultaneously and they were to all initiate a ServiceChange + transaction, the Media Gateway Controller would very likely be + swamped, leading to message losses and network congestion during the + critical period of service restoration. In order to prevent such + avalanches, the following behaviour is suggested: + + 1) When a Media Gateway is powered on, it should initiate a restart + timer to a random value, uniformly distributed between 0 and a + maximum waiting delay (MWD). Care should be taken to avoid + synchronicity of the random number generation between multiple + Media Gateways that would use the same algorithm. + + 2) The Media Gateway should then wait for either the end of this + timer or the detection of a local user activity, such as for + example an off-hook transition on a residential Media Gateway. + + 3) When the timer elapses, or when an activity is detected, the Media + Gateway should initiate the restart procedure. + + The restart procedure simply requires the MG to guarantee that the + first message that the Media Gateway Controller sees from this MG is + a ServiceChange message informing the Media Gateway Controller about + the restart. + + + +Groves, et al. Standards Track [Page 74] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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. + + Media Gateway Controllers are typically dimensioned to handle the + peak hour traffic load, during which, in 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. This simple calculation shows that 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 also 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 this 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 clause covers security when using the protocol in an IP + environment. + +10.1 Protection of Protocol Connections + + A security mechanism is clearly needed to prevent unauthorized + entities from using the protocol defined in this RFC for setting up + unauthorized calls or interfering with authorized calls. The + security mechanism for the protocol when transported over IP networks + is IPsec [RFC 2401 to RFC 2411]. + + The AH header [RFC 2402] affords data origin authentication, + connectionless integrity and optional anti-replay protection of + messages passed between the MG and the MGC. The ESP header [RFC + 2406] provides confidentiality of messages, if desired. For + + + +Groves, et al. Standards Track [Page 75] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 RFC employing the ESP + header SHALL comply with section 5 of [RFC 2406], which defines a + minimum set of algorithms for integrity checking and encryption. + Similarly, implementations employing the AH header SHALL comply with + section 5 of [RFC 2402], which defines a minimum set of algorithms + for integrity checking using manual keys. + + Implementations SHOULD use IKE [RFC 2409] to permit more robust + keying options. Implementations employing IKE SHOULD support + authentication with RSA signatures and RSA public key encryption. + +10.2 Interim AH scheme + + Implementation of IPsec requires that the AH or ESP header be + inserted immediately after the IP header. This cannot be easily done + at the application level. Therefore, this presents a deployment + problem for the protocol defined in this RFC where the underlying + network implementation does not support IPsec. + + As an interim solution, an optional AH header is defined within the + H.248.1 protocol header. The header fields are exactly those of the + SPI, SEQUENCE NUMBER and DATA fields as defined in [RFC 2402]. The + semantics of the header fields are the same as the "transport mode" + of [RFC 2402], 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 retain the same functionality, the ICV calculation + should be performed across all the transactions (concatenated) in the + message 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 20 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.1 protocol SHALL implement IPsec where + the underlying operating system and the transport network supports + 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. + + + + + + +Groves, et al. Standards Track [Page 76] + +RFC 3525 Gateway Control Protocol June 2003 + + + All implementations of the interim AH mechanism SHALL comply with + section 5 of RFC 2402 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 allows the MGC to provide MGs with "session keys" that + can be used to encrypt the audio messages, protecting 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". + + 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: 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 round trip, 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 round trip + 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. + + + + + + + +Groves, et al. Standards Track [Page 77] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 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 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 MG (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, and thus sharing the Termination is + straightforward. This mechanism 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 + + + + + +Groves, et al. Standards Track [Page 78] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 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 + + A MG is pre-provisioned by a management mechanism outside the scope + of this protocol with a primary and (optionally) an ordered list of + secondary MGCs. Upon a cold start of the MG, it will issue a + ServiceChange command with a "Restart" method, on the Root + Termination to its primary MGC. If the MGC accepts the MG, it sends + a Transaction Reply not including a ServiceChangeMgcId parameter. If + the MGC does not accept the MG's registration, it sends a Transaction + Reply, providing the address of an alternate MGC to be contacted by + including a ServiceChangeMgcId parameter. + + If the MG receives a Transaction Reply that includes a + ServiceChangeMgcId parameter, it sends a ServiceChange to the MGC + specified in the ServiceChangeMgcId. It continues this process until + it gets a controlling MGC to accept its registration, or it fails to + get a reply. Upon failure to obtain a reply, either from the primary + MGC, or a designated successor, the MG tries its pre-provisioned + secondary MGCs, in order. If the MG is unable to establish a control + relationship with any MGC, it shall wait a random amount of time as + described in 9.2 and then start contacting its primary, and if + necessary, its secondary MGCs again. + + It is possible that the reply to a ServiceChange with Restart will be + lost, and a command will be received by the MG prior to the receipt + of the ServiceChange response. The MG shall issue Error 505 - + Command Received before a ServiceChange Reply has been received. + +11.3 Negotiation of protocol version + + The first ServiceChange command from a MG shall contain the version + number of the protocol supported by the MG in the + ServiceChangeVersion parameter. Upon receiving such a message, if + the MGC supports only a lower version, then the MGC shall send a + + + +Groves, et al. Standards Track [Page 79] + +RFC 3525 Gateway Control Protocol June 2003 + + + ServiceChangeReply with the lower version and thereafter all the + messages between MG and MGC shall conform to the lower version of the + protocol. If the MG is unable to comply and it has established a + transport connection to the MGC, it should close that connection. In + any event, it should reject all subsequent requests from the MGC with + error 406 - Version Not Supported. + + If the MGC supports a higher version than the MG but is able to + support the lower version proposed by the MG, it shall send a + ServiceChangeReply with the lower version and thereafter all the + messages between MG and MGC shall conform to the lower version of the + protocol. If the MGC is unable to comply, it shall reject the + association, with error 406 - Version Not Supported. + + Protocol version negotiation may also occur at "handoff" and + "failover" ServiceChanges. + + When extending the protocol with new versions, the following rules + should be followed: + + 1) Existing protocol elements, i.e., procedures, parameters, + descriptor, property, values, should not be changed unless a + protocol error needs to be corrected or it becomes necessary to + change the operation of the service that is being supported by the + protocol. + + 2) The semantics of a command, a parameter, a descriptor, a property, + or a value should not be changed. + + 3) Established rules for formatting and encoding messages and + parameters should not be modified. + + 4) When information elements are found to be obsolete they can be + marked as not used. However, the identifier for that information + element will be marked as reserved. In that way it can not be + used in future versions. + +11.4 Failure of a MG + + If a MG fails, but is capable of sending a message to the MGC, it + sends a ServiceChange with an appropriate method (graceful or forced) + and specifies the Root TerminationID. When it returns to service, it + sends a ServiceChange with a "Restart" method. + + Allowing the MGC to send duplicate messages to both MGs accommodates + pairs of MGs that are capable of redundant failover of one of the + MGs. Only the Working MG shall accept or reject transactions. Upon + failover, the primary MG sends a ServiceChange command with a + + + +Groves, et al. Standards Track [Page 80] + +RFC 3525 Gateway Control Protocol June 2003 + + + "Failover" method and a "MG Impending Failure" reason. The MGC then + uses the secondary MG as the active MG. When the error condition is + repaired, the Working MG can send a "ServiceChange" with a "Restart" + method. + + Note: Redundant failover MGs require a reliable transport, because + the protocol provides no means for a secondary MG running ALF to + acknowledge messages sent from the MGC. + +11.5 Failure of an MGC + + If the MG detects a failure of its controlling MGC, it attempts to + contact the next MGC on its pre-provisioned list. It starts its + attempts at the beginning (primary MGC), unless that was the MGC that + failed, in which case it starts at its first secondary MGC. It sends + a ServiceChange message with a "Failover" method and a "MGC Impending + Failure" reason. If the MG is unable to establish a control + relationship with any MGC, it shall wait a random amount of time as + described in section 9.2 and then start again contacting its primary, + and (if necessary) its secondary MGCs. When contacting its + previously controlling MGC, the MG sends the ServiceChange message + with "Disconnected" method. + + In partial failure, or for manual maintenance reasons, an MGC may + wish to direct its controlled MGs to use a different MGC. To do so, + it sends a ServiceChange method to the MG with a "HandOff" method, + and its designated replacement in ServiceChangeMgcId. If "HandOff" + is supported, the MG shall send a ServiceChange message with a + "Handoff" method and a "MGC directed change" reason to the designated + MGC. If it fails to get a reply from the designated MGC, the MG + shall behave as if its MGC failed, and start contacting secondary + MGCs as specified in the previous paragraph. If the MG is unable to + establish a control relationship with any MGC, it shall wait a random + amount of time as described in 9.2 and then start contacting its + primary, and if necessary, its secondary MGCs again. + + No recommendation is made on how the MGCs involved in the Handoff + maintain state information; this is considered to be out of scope of + this RFC. The MGC and MG may take the following steps when Handoff + occurs. When the MGC initiates a HandOff, the handover should be + transparent to Operations on the Media Gateway. Transactions can be + executed in any order, and could be in progress when the + ServiceChange is executed. Accordingly, commands in progress + continue and replies to all commands from the original MGC must be + sent to the transport address from which they were sent. If the + service relationship with the sending MGC has ended, the replies + should be discarded. The MG may receive outstanding transaction + replies from the new MGC. No new messages shall be sent to the new + + + +Groves, et al. Standards Track [Page 81] + +RFC 3525 Gateway Control Protocol June 2003 + + + MGC until the control association is established. Repeated + transaction requests shall be directed to the new MGC. The MG shall + maintain state on all Terminations and Contexts. + + It is possible that the MGC could be implemented in such a way that a + failed MGC is replaced by a working MGC where the identity of the new + MGC is the same as the failed one. In such a case, + ServiceChangeMgcId would be specified with the previous value and the + MG shall behave as if the value was changed, and send a ServiceChange + message, as above. + + Pairs of MGCs that are capable of redundant failover can notify the + controlled MGs of the failover by the above mechanism. + +12 Package definition + + The primary mechanism for extension is by means of Packages. + Packages define additional Properties, Events, Signals and Statistics + that may occur on Terminations. + + Packages defined by IETF will appear in separate RFCs. + + Packages defined by ITU-T may appear in the relevant Recommendations + (e.g., as Recommendations of the H.248 sub-series). + + 1) A public document or a standard forum document, which can be + referenced as the document that describes the package following + the guideline above, should be specified. + + 2) The document shall specify the version of the Package that it + describes. + + 3) The document should be available 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. + +12.1 Guidelines for defining packages + + Packages define Properties, Events, Signals, and Statistics. + + Packages may also define new error codes according to the guidelines + given in 13.2. This is a matter of documentary convenience: the + package documentation is submitted to IANA in support of the error + code registration. If a package is modified, it is unnecessary to + provide IANA with a new document reference in support of the error + code unless the description of the error code itself is modified. + + + + + +Groves, et al. Standards Track [Page 82] + +RFC 3525 Gateway Control Protocol June 2003 + + + Names of all such 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 shall be separated by a forward slash ("/") character. + Example: togen/playtone is the text encoding to refer to the play + tone signal in the tone generation package. + + A Package will contain the following sections: + +12.1.1 Package + + Overall description of the package, specifying: + + 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. + + Designed to be extended only (Optional): + + This indicates that the package has been expressly designed to + be extended by others, not to be directly referenced. For + example, the package may not have any function on its own or be + nonsensical on its own. The MG SHOULD NOT publish this + PackageID when reporting packages. + + Extends (Optional): existing package Descriptor + + 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 an identifier + defined in the original package and packages it may have + extended (multiple levels of extension). 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. + + + +Groves, et al. Standards Track [Page 83] + +RFC 3525 Gateway Control Protocol June 2003 + + +12.1.2 Properties + + Properties defined by the package, specifying: + + Property Name: only descriptive + + PropertyID: is an identifier + + Description: + + Type: One of: + + Boolean + + String: UTF-8 string + + Octet String: A number of octets. See Annex A and Annex B.3 + for encoding + + 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. The type of + sub-list SHALL also be specified. The type shall be chosen + from the types specified in this section (with the exception of + sub-list). For example, Type: sub-list of enumeration. The + encoding of sub-lists is specified in Annexes A and B.3. + + Possible values: + + A package MUST specify either a specific set of values or a + description of how values are determined. A package MUST also + specify a default value or the default behaviour when the value + is omitted from its descriptor. For example, a package may + specify that procedures related to the property are suspended + when its value is omitted. A default value (but not + procedures) + may be specified as provisionable. + + Defined in: + + Which H.248.1 descriptor the property is defined in. + + + +Groves, et al. Standards Track [Page 84] + +RFC 3525 Gateway Control Protocol June 2003 + + + LocalControl is for stream dependent properties. + TerminationState is 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 + + Events defined by the package, specifying: + + 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 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 12.2. + +12.1.4 Signals + + Signals defined by the package, specifying: + + Signal Name: only descriptive + + SignalID: is an identifier. SignalID is used in a + SignalsDescriptor + + Description + + SignalType: one of: + + OO (On/Off) + + + +Groves, et al. Standards Track [Page 85] + +RFC 3525 Gateway Control Protocol June 2003 + + + TO (TimeOut) + + BR (Brief) + + NOTE - SignalType may be defined such that it is dependent on the + value of one or more parameters. The package MUST specify a + default signal type. If the default type is TO, the package MUST + specify a default duration which may be provisioned. A default + duration is meaningless for BR. + + Duration: in hundredths of seconds + + Additional Parameters: see 12.2 + +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. + +12.2 Guidelines to defining Parameters to Events and Signals + + Parameter Name: only descriptive + + ParameterID: is an identifier. The textual ParameterID of parameters + to Events and Signals shall not start with "EPA" and "SPA", + respectively. The textual ParameterID shall also not be "ST", + "Stream", "SY", "SignalType", "DR", "Duration", "NC", + "NotifyCompletion", "KA", "Keepactive", "EB", "Embed", "DM" or + "DigitMap". + + Type: One of: + + Boolean + + String: UTF-8 octet string + + + +Groves, et al. Standards Track [Page 86] + +RFC 3525 Gateway Control Protocol June 2003 + + + Octet String: A number of octets. See Annex A and Annex B.3 for + encoding + + 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). The type of sub-list SHALL also be specified. The + type shall be chosen from the types specified in this section + (with the exception of sub-list). For example, Type: sub-list of + enumeration. The encoding of sub-lists is specified in Annexes A + and B.3. + + Possible values: + + A package MUST specify either a specific set of values or a + description of how values are determined. A package MUST also + specify a default value or the default behavior when the value is + omitted from its descriptor. For example, a package may specify + that procedures related to the parameter are suspended when it + value is omitted. A default value (but not procedures) may be + specified as provisionable. + + Description: + +12.3 Lists + + Possible values for parameters include enumerations. Enumerations + may be defined in a list. It is recommended that the list be IANA + registered so that packages that extend the list can be defined + without concern for conflicting names. + +12.4 Identifiers + + Identifiers in text encoding shall be strings of up to 64 characters, + containing no spaces, starting with an alphabetic character and + consisting of alphanumeric characters and/or digits, and possibly + including the special character underscore ("_"). + + + + + + + +Groves, et al. Standards Track [Page 87] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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. + +12.5 Package registration + + A package can be registered with IANA for interoperability reasons. + See clause 13 for IANA Considerations. + +13 IANA Considerations + +13.1 Packages + + The following considerations SHALL be met to register a package with + IANA: + + 1) 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 0x8000 to 0xFFFF are reserved for private use. + Serial number 0 is reserved. + + 2) 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. + + 3) 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. + + 4) Packages registered by other than recognized standards bodies + shall have a minimum package name length of 8 characters. + + 5) All other package names are first come-first served if all other + conditions are met. + + + + + + + + +Groves, et al. Standards Track [Page 88] + +RFC 3525 Gateway Control Protocol June 2003 + + +13.2 Error codes + + The following considerations SHALL be met to register an error code + with IANA: + + 1) An error number and a one-line (80-character maximum) string is + registered for each error. + + 2) 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. + + 3) The document should be available on a public web server and should + have a stable URL. + + 4) Error numbers registered by recognized standards bodies shall have + 3- or 4-character error numbers. + + 5) Error numbers registered by all other organizations or individuals + shall have 4-character error numbers. + + 6) An error number shall not be redefined nor modified except by the + organization or individual that originally defined it, or their + successors or assigns. + +13.3 ServiceChange reasons + + The following considerations SHALL be met to register service change + reason with IANA: + + 1) A one-phrase, 80-character maximum, unique reason code is + registered for each reason. + + 2) 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. + + 3) The document should be available on a public web server and should + have a stable URL. + + + + + + + + + + +Groves, et al. Standards Track [Page 89] + +RFC 3525 Gateway Control Protocol June 2003 + + +ANNEX A - Binary encoding of the protocol + + This annex specifies the syntax of messages using the notation + defined in Recommendation X.680; 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 Recommendation X.690, Information + Technology - ASN.1 Encoding Rules: Specification of Basic Encoding + Rules (BER), Canonical Encoding Rules (CER) and Distinguished + Encoding Rules. + +A.1 Coding of wildcards + + The use of wildcards ALL and CHOOSE is allowed in the protocol. This + allows a MGC to partially specify Termination IDs and to let the MG + choose from the values that conform to the partial specification. + Termination IDs may encode a hierarchy of names. This 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 wildcarding 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. + + + + + + +Groves, et al. Standards Track [Page 90] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 it 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. + + + + + + + + + +Groves, et al. Standards Track [Page 91] + +RFC 3525 Gateway Control Protocol June 2003 + + +A.2 ASN.1 syntax specification + + This subclause contains the ASN.1 specification of the H.248.1 + protocol syntax. + + NOTE 1 - In case a transport mechanism is used that employs + application level framing, the definition of Transaction below + changes. Refer to the annex or to the Recommendation of the H.248 + sub-series defining the transport mechanism for the definition that + applies in that case. + + NOTE 2 - 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. + + NOTE 3 - This syntax specification does not enforce all + restrictions on element inclusions and values. Some additional + restrictions are stated in comments and other restrictions appear + in the text of this RFC. These additional restrictions + are part of the protocol even though not enforced by this + specification. + + NOTE 4 - The ASN.1 module in this Annex uses octet string types to + encode values for property parameter, signal parameter and event + parameter values and statistics. The actual types of these values + vary and are specified in Annex C or the relevant package + definition. + + A value is first BER-encoded based on its type using the table below. + The result of this BER-encoding is then encoded as an ASN.1 octet + string, "double wrapping" the value. The format specified in Annex C + or the package relates to BER encoding according to the following + table: + + Type Specified in Package ASN.1 BER Type + + String IA5String or UTF8String (Note 4) + + Integer (4 Octet) INTEGER + + Double (8 octet signed int) INTEGER (Note 3) + + Character (UTF-8, Note 1) IA5String + + Enumeration ENUMERATED + + Boolean BOOLEAN + + + +Groves, et al. Standards Track [Page 92] + +RFC 3525 Gateway Control Protocol June 2003 + + + Unsigned Integer (Note 2) INTEGER (Note 3) + + Octet (String) OCTET STRING + + Note 1: Can be more than one byte + + Note 2: Unsigned integer is referenced in Annex C + + Note 3: The BER encoding of INTEGER does not imply the use of 4 + bytes. + + Note 4: String should be encoded as IA5String when the contents + are all ASCII characters, but as UTF8String if it contains any + Non-ASCII characters. + + See ITU-T Rec. X.690, 8.7, for the definition of the encoding of an + octet string value. + + 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, + + + +Groves, et al. Standards Track [Page 93] + +RFC 3525 Gateway Control Protocol June 2003 + + + transactions SEQUENCE OF Transaction + }, + ... + } + + MId ::= CHOICE + { + ip4Address IP4Address, + ip6Address IP6Address, + domainName DomainName, + deviceName PathName, + mtpAddress OCTET STRING(SIZE(2..4)), + -- Addressing structure of mtpAddress: + -- 25 - 15 0 + -- | PC | NI | + -- 24 - 14 bits 2 bits + -- Note: 14 bits are defined for international use. + -- Two national options exist where the point code is 16 or 24 + -- bits. + -- To octet align the mtpAddress, the MSBs shall be encoded as 0s. + ... + } + + 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 + } + + IP4Address ::= SEQUENCE + { + 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 A.3 + + Transaction ::= CHOICE + + + +Groves, et al. Standards Track [Page 94] + +RFC 3525 Gateway Control Protocol June 2003 + + + { + 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 OF TransactionAck + TransactionAck ::= SEQUENCE + { + firstAck TransactionId, + lastAck TransactionId OPTIONAL + } + + ErrorDescriptor ::= SEQUENCE + { + errorCode ErrorCode, + errorText ErrorText OPTIONAL + } + + + +Groves, et al. Standards Track [Page 95] + +RFC 3525 Gateway Control Protocol June 2003 + + + + ErrorCode ::= INTEGER(0..65535) + -- See clause 13 for IANA Considerations with respect to error codes + + ErrorText ::= IA5String + + ContextID ::= INTEGER(0..4294967295) + + -- Context NULL Value: 0 + -- Context CHOOSE Value: 4294967294 (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, + + + +Groves, et al. Standards Track [Page 96] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 + { + + + +Groves, et al. Standards Track [Page 97] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 ::= CHOICE + { + contextAuditResult TerminationIDList, + error ErrorDescriptor, + auditResult AuditResult, + ... + } + + + +Groves, et al. Standards Track [Page 98] + +RFC 3525 Gateway Control Protocol June 2003 + + + + AuditResult ::= SEQUENCE + { + + terminationID TerminationID, + 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, + ... + } + + + + +Groves, et al. Standards Track [Page 99] + +RFC 3525 Gateway Control Protocol June 2003 + + + NotifyReply ::= SEQUENCE + { + terminationID TerminationIDList, + 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, + -- For use of extraInfo see the comment related to PropertyParm + extraInfo CHOICE + { + relation Relation, + range BOOLEAN, + sublist BOOLEAN + } OPTIONAL, + ... + } + + ServiceChangeRequest ::= SEQUENCE + { + terminationID TerminationIDList, + serviceChangeParms ServiceChangeParm, + ... + } + + ServiceChangeReply ::= SEQUENCE + { + terminationID TerminationIDList, + + + +Groves, et al. Standards Track [Page 100] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 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 + } OPTIONAL, + ... + } + + StreamDescriptor ::= SEQUENCE + { + streamID StreamID, + streamParms StreamParms + } + + StreamParms ::= SEQUENCE + { + localControlDescriptor LocalControlDescriptor OPTIONAL, + localDescriptor LocalRemoteDescriptor OPTIONAL, + + + +Groves, et al. Standards Track [Page 101] + +RFC 3525 Gateway Control Protocol June 2003 + + + remoteDescriptor LocalRemoteDescriptor OPTIONAL, + ... + } + + LocalControlDescriptor ::= SEQUENCE + { + + streamMode StreamMode OPTIONAL, + reserveValue BOOLEAN OPTIONAL, + reserveGroup BOOLEAN OPTIONAL, + 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 + { + + + +Groves, et al. Standards Track [Page 102] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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, Event, + -- Signal Names or Statistics ID. (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. + -- To wildcard a Property, Event, Signal, or Statistics ID, use + -- 0xFFFF for last two octets, choose is not allowed. + -- Wildcarding of Package Name is permitted only if Property, + -- Event, Signal, or Statistics ID are + -- also wildcarded. + + Relation ::= ENUMERATED + { + greaterThan(0), + smallerThan(1), + unequalTo(2), + ... + } + + LocalRemoteDescriptor ::= SEQUENCE + { + propGrps SEQUENCE OF PropertyGroup, + ... + } + + PropertyGroup ::= SEQUENCE OF PropertyParm + + TerminationStateDescriptor ::= SEQUENCE + { + propertyParms SEQUENCE OF PropertyParm, + eventBufferControl EventBufferControl OPTIONAL, + serviceState ServiceState OPTIONAL, + ... + } + + + +Groves, et al. Standards Track [Page 103] + +RFC 3525 Gateway Control Protocol June 2003 + + + + 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 OPTIONAL, + -- RequestID must be present if eventList + -- is non empty + eventList SEQUENCE OF RequestedEvent, + ... + } + + RequestedEvent ::= SEQUENCE + { + pkgdName PkgdName, + + + +Groves, et al. Standards Track [Page 104] + +RFC 3525 Gateway Control Protocol June 2003 + + + streamID StreamID OPTIONAL, + eventAction RequestedActions OPTIONAL, + evParList SEQUENCE OF EventParameter, + ... + } + + RequestedActions ::= SEQUENCE + { + keepActive BOOLEAN OPTIONAL, + eventDM EventDM OPTIONAL, + secondEvent SecondEventsDescriptor OPTIONAL, + signalsDescriptor SignalsDescriptor OPTIONAL, + ... + } + + EventDM ::= CHOICE + { digitMapName DigitMapName, + digitMapValue DigitMapValue + } + + SecondEventsDescriptor ::= SEQUENCE + { + requestID RequestID OPTIONAL, + eventList SEQUENCE OF SecondRequestedEvent, + ... + } + + SecondRequestedEvent ::= SEQUENCE + { + pkgdName PkgdName, + streamID StreamID OPTIONAL, + eventAction SecondRequestedActions OPTIONAL, + evParList SEQUENCE OF EventParameter, + ... + } + + SecondRequestedActions ::= SEQUENCE + { + keepActive BOOLEAN OPTIONAL, + eventDM EventDM OPTIONAL, + signalsDescriptor SignalsDescriptor OPTIONAL, + ... + } + + EventBufferDescriptor ::= SEQUENCE OF EventSpec + + EventSpec ::= SEQUENCE + { + + + +Groves, et al. Standards Track [Page 105] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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) + } + + + +Groves, et al. Standards Track [Page 106] + +RFC 3525 Gateway Control Protocol June 2003 + + + + SigParameter ::= SEQUENCE + { + sigParameterName Name, + value Value, + -- For use of extraInfo see the comment related to PropertyParm + extraInfo CHOICE + { + relation Relation, + range BOOLEAN, + sublist BOOLEAN + + } OPTIONAL, + ... + } + + -- For an AuditCapReply with all events, the RequestID SHALL be ALL. + -- ALL is represented by 0xffffffff. + + 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 + } + + + + +Groves, et al. Standards Track [Page 107] + +RFC 3525 Gateway Control Protocol June 2003 + + + DigitMapName ::= Name + + DigitMapValue ::= SEQUENCE + { + startTimer INTEGER(0..99) OPTIONAL, + shortTimer INTEGER(0..99) OPTIONAL, + longTimer INTEGER(0..99) OPTIONAL, + digitMapBody IA5String, + -- Units are seconds for start, short and long timers, and + -- hundreds of milliseconds for duration timer. Thus start, + -- short, and long range from 1 to 99 seconds and duration + -- from 100 ms to 9.9 s + -- See 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, + -- A serviceChangeReason consists of a numeric reason code + -- and an optional text description. + -- The serviceChangeReason SHALL be a string consisting of + -- a decimal reason code, optionally followed by a single + -- space character and a textual description string. + -- This string is first BER-encoded as an IA5String. + -- The result of this BER-encoding is then encoded as + -- an ASN.1 OCTET STRING type, "double wrapping" the + -- value as was done for package elements. + 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..4)), + + + +Groves, et al. Standards Track [Page 108] + +RFC 3525 Gateway Control Protocol June 2003 + + + ... + } + + ServiceChangeResParm ::= SEQUENCE + { + serviceChangeMgcId MId OPTIONAL, + serviceChangeAddress ServiceChangeAddress OPTIONAL, + serviceChangeVersion INTEGER(0..99) OPTIONAL, + serviceChangeProfile ServiceChangeProfile OPTIONAL, + timestamp TimeNotation OPTIONAL, + ... + } + + ServiceChangeMethod ::= ENUMERATED + + { + failover(0), + forced(1), + graceful(2), + restart(3), + disconnected(4), + handOff(5), + ... + } + + ServiceChangeProfile ::= SEQUENCE + { + profileName IA5String(SIZE (1..67)) + -- 64 characters for name, 1 for "/", 2 for version to match ABNF + } + + PackagesDescriptor ::= SEQUENCE OF PackagesItem + + PackagesItem ::= SEQUENCE + { + packageName Name, + packageVersion INTEGER(0..99), + ... + } + + StatisticsDescriptor ::= SEQUENCE OF StatisticsParameter + + StatisticsParameter ::= SEQUENCE + { + statName PkgdName, + statValue Value OPTIONAL + } + + + + +Groves, et al. Standards Track [Page 109] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 + -- per ISO 8601:1988 + } + + Value ::= SEQUENCE OF OCTET STRING + + END + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 110] + +RFC 3525 Gateway Control Protocol June 2003 + + +A.3 Digit maps and path names + + From a syntactic viewpoint, digit maps are strings with syntactic + restrictions imposed upon them. The syntax of valid digit maps is + specified in ABNF [RFC 2234]. The syntax for digit maps presented in + this subclause is for illustrative purposes only. The definition of + digitMap in Annex B takes precedence in the case of differences + between the two. + + 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-z + + A path name is also a string with syntactic restrictions imposed upon + it. The ABNF production defining it is copied from Annex B. + + ; Total length of pathNAME must not exceed 64 chars. + pathNAME = ["*"] NAME *("/" / "*"/ ALPHA / DIGIT /"_" / "$" ) + ["@" pathDomainName ] + + + + + +Groves, et al. Standards Track [Page 111] + +RFC 3525 Gateway Control Protocol June 2003 + + + ; ABNF allows two or more consecutive "." although it is + ; meaningless in a path domain name. + pathDomainName = (ALPHA / DIGIT / "*" ) + *63(ALPHA / DIGIT / "-" + NAME = ALPHA *63(ALPHA / DIGIT / "_" ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 112] + +RFC 3525 Gateway Control Protocol June 2003 + + +ANNEX B - Text encoding of the protocol + +B.1 Coding of wildcards + + In a text encoding of the protocol, while TerminationIDs are + arbitrary, by judicious choice of names, the wildcard character, "*" + may be made more useful. When the wildcard character is encountered, + it will "match" all TerminationIDs having the same previous and + following characters (if appropriate). For example, if there were + TerminationIDs of R13/3/1, R13/3/2 and R13/3/3, the TerminationID + R13/3/* would match all of them. There are some circumstances where + ALL Terminations must be referred to. The TerminationID "*" + suffices, and is referred to as ALL. The CHOOSE TerminationID "$" + may be used to 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 presented in ABNF according to RFC 2234. + + Note 1 - This syntax specification does not enforce all + restrictions on element inclusions and values. Some additional + restrictions are stated in comments and other restrictions appear + in the text of this RFC. These additional restrictions are part + of the protocol even though not enforced by this specification. + + Note 2 - The syntax is context-dependent. For example, "Add" can + be the AddToken or a NAME depending on the context in which it + occurs. + + Everything in the ABNF and text encoding is case insensitive. This + includes TerminationIDs, digitmap Ids etc. SDP is case sensitive as + per RFC 2327. + + ; NOTE -- The ABNF in this section uses the VALUE construct (or lists + ; of VALUE constructs) to encode various package element values + ; (properties, signal parameters, etc.). The types of these values + ; vary and are specified the relevant package definition. Several + ; such types are described in section 12.2. + ; + ; The ABNF specification for VALUE allows a quotedString form or a + ; collection of SafeChars. The encoding of package element values + ; into ABNF VALUES is specified below. If a type's encoding allows + ; characters other than SafeChars, the quotedString form MUST be used + ; for all values of that type, even for specific values that consist + ; only of SafeChars. + ; + + + + +Groves, et al. Standards Track [Page 113] + +RFC 3525 Gateway Control Protocol June 2003 + + + ; String: A string MUST use the quotedString form of VALUE and can + ; contain anything allowable in the quotedString form. + ; + ; Integer, Double, and Unsigned Integer: Decimal values can be + ; encoded using characters 0-9. Hexadecimal values must be prefixed + ; with '0x' and can use characters 0-9,a-f,A-F. An octal format is + ; not supported. Negative integers start with '-' and MUST be + ; Decimal. The SafeChar form of VALUE MUST be used. + ; + ; Character: A UTF-8 encoding of a single letter surrounded by + ; double quotes. + ; + ; Enumeration: An enumeration MUST use the SafeChar form of VALUE + ; and can contain anything allowable in the SafeChar form. + ; + ; Boolean: Boolean values are encoded as "on" and "off" and are + ; case insensitive. The SafeChar form of VALUE MUST be used. + ; + ; Future types: Any defined types MUST fit within + ; the ABNF specification of VALUE. Specifically, if a type's + ; encoding allows characters other than SafeChars, the quotedString + ; form MUST be used for all values of that type, even for specific + ; values that consist only of SafeChars. + ; + ; Note that there is no way to use the double quote character within + ; a value. + ; + ; Note that SDP disallows whitespace at the beginning of a line, + ; Megaco ABNF allows whitespace before the beginning of the SDP in + ; the Local/Remote descriptor. Parsers should accept whitespace + ; between the LBRKT following the Local/Remote token and the + ; beginning of the SDP. + + 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 ) + + + + +Groves, et al. Standards Track [Page 114] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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) + + 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 ) + + ; "O-" indicates an optional command + ; "W-" indicates a wildcarded response to a command + commandRequestList = ["O-"] ["W-"] commandRequest + *(COMMA ["O-"] ["W-"]commandRequest) + + commandRequest = ( ammRequest / subtractRequest / auditRequest / + notifyRequest / serviceChangeRequest) + + transactionReply = ReplyToken EQUAL TransactionID LBRKT + [ ImmAckRequiredToken COMMA] + ( errorDescriptor / actionReplyList ) RBRKT + + actionReplyList = actionReply *(COMMA actionReply ) + + + + +Groves, et al. Standards Track [Page 115] + +RFC 3525 Gateway Control Protocol June 2003 + + + actionReply = CtxToken EQUAL ContextID LBRKT + ( errorDescriptor / commandReply ) / + (commandReply COMMA errorDescriptor) ) 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 = SubtractToken EQUAL TerminationID + [ LBRKT auditDescriptor RBRKT] + + auditRequest = (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 / + + + +Groves, et al. Standards Track [Page 116] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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".."255" + ; this production, while occurring in RFC2373, is not referenced + ; IPv6prefix = hexpart SLASH 1*2DIGIT + hexpart = hexseq "::" [ hexseq ] / "::" [ hexseq ] / hexseq + + + +Groves, et al. Standards Track [Page 117] + +RFC 3525 Gateway Control Protocol June 2003 + + + hexseq = hex4 *( ":" hex4) + hex4 = 1*4HEXDIG + + portNumber = UINT16 + + ; Addressing structure of mtpAddress: + ; 25 - 15 0 + ; | PC | NI | + ; 24 - 14 bits 2 bits + ; Note: 14 bits are defined for international use. + ; Two national options exist where the point code is 16 or 24 bits. + ; To octet align the mtpAddress the MSBs shall be encoded as 0s. + ; An octet shall be represented by 2 hex digits. + mtpAddress = MTPToken LBRKT 4*8 (HEXDIG) 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 one terminationStateDescriptor + ; and either streamParm(s) or streamDescriptor(s) but not both + mediaParm = (streamParm / streamDescriptor / + terminationStateDescriptor) + + ; at-most-once per item + 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 except for propertyParm + localParm = ( streamMode / propertyParm / reservedValueMode + / reservedGroupMode ) + + + +Groves, et al. Standards Track [Page 118] + +RFC 3525 Gateway Control Protocol June 2003 + + + + 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 + + ; Note - The octet zero is not among the permitted characters in + ; octet string. As the current definition is limited to SDP, and a + ; zero octet would not be a legal character in SDP, this is not a + ; concern. + + 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 except for propertyParm + terminationStateParm = (propertyParm / serviceStates / + eventBufferControl ) + + + + +Groves, et al. Standards Track [Page 119] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 items in package + / ("*" SLASH "*") ; all items 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 + + + + +Groves, et al. Standards Track [Page 120] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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) RBRKT) + + 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 ] + + + +Groves, et al. Standards Track [Page 121] + +RFC 3525 Gateway Control Protocol June 2003 + + + + ;at-most-once eventStream, every eventParameterName at most once + observedEventParameter = eventStream / eventOther + + ; For an AuditCapReply with all events, the RequestID should be ALL. + RequestID = ( UINT32 / "*" ) + + modemDescriptor = ModemToken (( EQUAL modemType) / + (LSBRKT modemType *(COMMA modemType) RSBRKT)) + [ LBRKT propertyParm *(COMMA propertyParm) RBRKT ] + + + ; at-most-once except for extensionParameter + modemType = (V32bisToken / V22bisToken / V18Token / + V22Token / V32Token / V34Token / V90Token / + V91Token / SynchISDNToken / extensionParameter) + + 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 + ; Units are seconds for T, S, and L timers, and hundreds of + ; milliseconds for Z timer. Thus T, S, and L range from 1 to 99 + ; seconds and Z from 100 ms to 9.9 s + 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 modifier + + ;at-most-once, and DigitMapToken and PackagesToken are not allowed + ;in AuditCapabilities command + auditItem = ( MuxToken / ModemToken / MediaToken / + SignalsToken / EventBufferToken / + DigitMapToken / StatsToken / EventsToken / + ObservedEventsToken / PackagesToken ) + + + + + +Groves, et al. Standards Track [Page 122] + +RFC 3525 Gateway Control Protocol June 2003 + + + serviceChangeDescriptor = ServicesToken LBRKT serviceChangeParm + *(COMMA serviceChangeParm) RBRKT + + ; each parameter at-most-once + ; at most one of either serviceChangeAddress or serviceChangeMgcId + ; but not both + ; serviceChangeMethod and serviceChangeReason are REQUIRED + 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 + ; at most one of either serviceChangeAddress or serviceChangeMgcId + ; but not both + servChgReplyParm = (serviceChangeAddress / serviceChangeMgcId / + serviceChangeProfile / serviceChangeVersion / + TimeStamp) + serviceChangeMethod = MethodToken EQUAL (FailoverToken / + ForcedToken / GracefulToken / RestartToken / + DisconnectedToken / HandOffToken / + extensionParameter) + ; A serviceChangeReason consists of a numeric reason code + ; and an optional text description. + ; A serviceChangeReason MUST be encoded using the quotedString + ; form of VALUE. + ; The quotedString SHALL contain a decimal reason code, + ; optionally followed by a single space character and a + ; textual description string. + + + serviceChangeReason = ReasonToken EQUAL VALUE + serviceChangeDelay = DelayToken EQUAL UINT32 + serviceChangeAddress = ServiceChangeAddressToken EQUAL ( mId / + portNumber ) + serviceChangeMgcId = MgcIdToken EQUAL mId + serviceChangeProfile = ProfileToken EQUAL NAME SLASH Version + serviceChangeVersion = VersionToken EQUAL Version + extension = extensionParameter parmValue + + packagesDescriptor = PackagesToken LBRKT packagesItem + *(COMMA packagesItem) RBRKT + + Version = 1*2(DIGIT) + packagesItem = NAME "-" UINT16 + + + +Groves, et al. Standards Track [Page 123] + +RFC 3525 Gateway Control Protocol June 2003 + + + + 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 topologyTriple + *(COMMA topologyTriple) RBRKT + topologyTriple = terminationA COMMA + terminationB COMMA topologyDirection + terminationA = TerminationID + terminationB = TerminationID + topologyDirection = BothwayToken / IsolateToken / OnewayToken + + priority = PriorityToken EQUAL UINT16 + + extensionParameter = "X" ("-" / "+") 1*6(ALPHA / DIGIT) + + ; 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 ) + ; Note - The double-quote character is not allowed in quotedString. + quotedString = DQUOTE *(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 / "+" / "-" / "&" / + "!" / "_" / "/" / "\'" / "?" / "@" / + "^" / "`" / "~" / "*" / "$" / "\" / + "(" / ")" / "%" / "|" / "." + + EQUAL = LWSP %x3D LWSP ; "=" + COLON = %x3A ; ":" + LBRKT = LWSP %x7B LWSP ; "{" + RBRKT = LWSP %x7D LWSP ; "}" + COMMA = LWSP %x2C LWSP ; "," + + + +Groves, et al. Standards Track [Page 124] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 = ";" / "[" / "]" / "{" / "}" / ":" / "," / "#" / + "<" / ">" / "=" + + ; New Tokens added to sigParameter must take the format of SPA* + ; * may be of any form i.e., SPAM + ; New Tokens added to eventParameter must take the form of EPA* + ; * may be of any form i.e., EPAD + + 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" / "EM") + EmergencyToken = ("Emergency" / "EG") + ErrorToken = ("Error" / "ER") + EventBufferToken = ("EventBuffer" / "EB") + EventsToken = ("Events" / "E") + FailoverToken = ("Failover" / "FL") + ForcedToken = ("Forced" / "FO") + GracefulToken = ("Graceful" / "GR") + H221Token = ("H221" ) + H223Token = ("H223" ) + H226Token = ("H226" ) + + + +Groves, et al. Standards Track [Page 125] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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") + + + +Groves, et al. Standards Track [Page 126] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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") + +B.3 Hexadecimal octet coding + + Hexadecimal octet coding is a means for representing a string of + octets as a string of hexadecimal digits, with two digits + representing each octet. This octet encoding should be used when + encoding octet strings in the text version of the protocol. For each + octet, the 8-bit sequence is encoded as two hexadecimal digits. Bit + 0 is the first transmitted; bit 7 is the last. Bits 7-4 are encoded + as the first hexadecimal digit, with Bit 7 as MSB and Bit 4 as LSB. + Bits 3-0 are encoded as the second hexadecimal digit, with Bit 3 as + MSB and Bit 0 as LSB. Examples: + + Octet bit pattern Hexadecimal coding + 00011011 D8 + 11100100 27 + 10000011 10100010 11001000 00001001 C1451390 + +B.4 Hexadecimal octet sequence + + A hexadecimal octet sequence is an even number of hexadecimal digits, + terminated by a character. + + + + + + + +Groves, et al. Standards Track [Page 127] + +RFC 3525 Gateway Control Protocol June 2003 + + +ANNEX C - Tags for media stream properties + + Parameters for Local, Remote and LocalControl descriptors are + specified as tag-value pairs if binary encoding is used for the + protocol. This annex contains the property names (PropertyID), the + tags (Property tag), type of the property (Type) and the values + (Value). Values presented in the Value field when the field contains + references shall be regarded as "information". The reference + contains the normative values. If a value field does not contain a + reference, then the values in that field can be considered as + "normative". + + Tags are given as hexadecimal numbers in this annex. When setting + the value of a property, a MGC may underspecify the value according + to one of the mechanisms specified in 7.1.1. + + It is optional to support the properties in this Annex or any of its + sub-sections. For example, only three properties from C.3 and only + five properties from C.8 might be implemented. + + For type "enumeration" the value is represented by the value in + brackets, e.g., Send(0), Receive(1). Annex C properties with the + types "N bits" or "M Octets" should be treated as octet strings when + encoding the protocol. Properties with "N bit integer" shall be + treated as an integers. "String" shall be treated as an IA5String + when encoding the protocol. + + 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 + + PropertyID Property Type Value + tag + + Media 1001 Enumeration Audio(0), Video(1), Data(2) + + Transmission 1002 Enumeration Send(0), Receive(1), + mode Send&Receive(2) + + Number of 1003 Unsigned 0-255 + Channels integer + + Sampling 1004 Unsigned 0-2^32 + rate integer + + Bitrate 1005 Integer (0..4294967295)NOTE - Units of + 100 bit/s. + + + +Groves, et al. Standards Track [Page 128] + +RFC 3525 Gateway Control Protocol June 2003 + + + ACodec 1006 Octet string Audio Codec Type: + Ref.: ITU-T Q.765 + Non-ITU-T codecs are defined + with the appropriate standards + organization under a defined + Organizational Identifier. + + Samplepp 1007 Unsigned Maximum samples or frames per + integer packet: 0..65535 + + Silencesupp 1008 Boolean Silence Suppression: True/False + + Encrypttype 1009 Octet string Ref.: ITU-T H.245 + + Encryptkey 100A Octet string Encryption key + size Ref.: ITU-T H.235 + (0..65535) + + Echocanc 100B Not Used. See H.248.1 E.13 for + an example of possible Echo + Control properties. + + 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: 0..65535 + integer 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 + + + + + + + + + + + +Groves, et al. Standards Track [Page 129] + +RFC 3525 Gateway Control Protocol June 2003 + + +C.2 Mux properties + + PropertyID Property tag Type Value + + H222 2001 Octet string H222LogicalChannelParameters + Ref.: ITU-T H.245 + + H223 2002 Octet string H223LogicalChannelParameters + Ref.: ITU-T H.245 + + V76 2003 Octet string V76LogicalChannelParameters + Ref.: ITU-T H.245 + + H2250 2004 Octet string H2250LogicalChannelParameters + Ref.: ITU-T H.245 + +C.3 General bearer properties + + PropertyID Property Type Value + tag + + Mediatx 3001 Enumeration Media Transport TypeTDM + Circuit(0), ATM(1), FR(2), + Ipv4(3), Ipv6(4), ... + + BIR 3002 4 octets Value depends on transport + technology + + NSAP 3003 1-20 octets See NSAP. + Ref.: Annex A/X.213 + +C.4 General ATM properties + + PropertyID Property Type Value + tag + + AESA 4001 20 octets ATM End System Address + + VPVC 4002 4 octets: VPCI VPCI/VCI + in first two + least Ref.: ITU-T Q.2931 + significant + octets, VCI in + second two + octets + + + + + + +Groves, et al. Standards Track [Page 130] + +RFC 3525 Gateway Control Protocol June 2003 + + + SC 4003 Enumeration Service Category: 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). + Ref.: ATM Forum UNI 4.0 + + BCOB 4004 5-bit integer Broadband Bearer Class + Ref.: ITU-T Q.2961.2 + + BBTC 4005 7-bit integer Broadband Transfer Capability + Ref.: ITU-T Q.2961.1 + + ATC 4006 Enumeration I.371 ATM Traffic + CapabilityDBR(0), SBR1(1), + SBR2(2), SBR3(3), ABT/IT(4), + ABT/DT(5), ABR(6) + Ref.: ITU-T I.371 + + STC 4007 2 bits Susceptibility to clipping: + Bits + 2 1 + --- + 0 0 not susceptible to + clipping + 0 1 susceptible to + clipping + Ref.: ITU-T Q.2931 + + UPCC 4008 2 bits User Plane Connection + configuration: + Bits + 2 1 + --- + 0 0 point-to-point + 0 1 point-to-multipoint + Ref.: ITU-T Q.2931 + + PCR0 4009 24-bit integer Peak Cell Rate (For CLP = 0) + Ref.: ITU-T Q.2931 + + SCR0 400A 24-bit integer Sustainable Cell Rate (For + CLP = 0) + Ref.: ITU-T Q.2961.1 + + MBS0 400B 24-bit integer Maximum Burst Size (For CLP = + 0) + Ref.: ITU-T Q.2961.1 + + + +Groves, et al. Standards Track [Page 131] + +RFC 3525 Gateway Control Protocol June 2003 + + + PCR1 400C 24-bit integer Peak Cell Rate (For CLP = 0 + + 1) + Ref.: ITU-T Q.2931 + + SCR1 400D 24-bit integer Sustainable Cell Rate (For + CLP = 0 + 1) + Ref.: ITU-T Q.2961.1 + + MBS1 400E 24-bit integer Maximum Burst Size (For CLP = + 0 + 1) + Ref.: ITU-T Q.2961.1 + + BEI 400F Boolean Best Effort Indicator + Value 1 indicates that BEI is + to be included in the ATM + signaling; value 0 indicates + that BEI is not to be + included in the ATM + signaling. + Ref.: ATM Forum UNI 4.0 + + TI 4010 Boolean Tagging Indicator + Value 0 indicates that + tagging is not allowed; value + 1 indicates that tagging is + requested. + Ref.: ITU-T Q.2961.1 + + FD 4011 Boolean Frame Discard + Value 0 indicates that no + frame discard is allowed; + value 1 indicates that frame + discard is allowed. + Ref.: ATM Forum UNI 4.0 + + A2PCDV 4012 24-bit integer Acceptable 2-point CDV + Ref.: ITU-T Q.2965.2 + + C2PCDV 4013 24-bit integer Cumulative 2-point CDV + Ref.: ITU-T Q.2965.2 + + APPCDV 4014 24-bit integer Acceptable P-P CDV + Ref.: ATM Forum UNI 4.0 + + CPPCDV 4015 24-bit integer Cumulative P-P CDV + Ref.: ATM Forum UNI 4.0 + + + + + +Groves, et al. Standards Track [Page 132] + +RFC 3525 Gateway Control Protocol June 2003 + + + ACLR 4016 8-bit integer Acceptable Cell Loss Ratio + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + MEETD 4017 16-bit integer Maximum End-to-end transit + delay + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + CEETD 4018 16-bit integer Cumulative End-to-end transit + delay + Ref.: ITU-T Q.2965.2, ATM + Forum UNI 4.0 + + QosClass 4019 Integer 0-5 QoS Class + + QoS Class Meaning + + 0 Default QoS + associated + with the ATC + as defined + in ITU-T + Q.2961.2 + + 1 Stringent + + 2 Tolerant + + 3 Bi-level + + 4 Unbounded + + 5 Stringent + Bi-level + Ref.: ITU-T Q.2965.1 + + AALtype 401A 1 octet AAL Type + Bits + 8 7 6 5 4 3 2 1 + --------------- + 0 0 0 0 0 0 0 0 AAL for + voice + 0 0 0 0 0 0 0 1 AAL type 1 + 0 0 0 0 0 0 1 0 AAL type 2 + 0 0 0 0 0 0 1 1 AAL type + 3/4 + 0 0 0 0 0 1 0 1 AAL type 5 + + + +Groves, et al. Standards Track [Page 133] + +RFC 3525 Gateway Control Protocol June 2003 + + + 0 0 0 1 0 0 0 0 user- + defined AAL + Ref.: ITU-T Q.2931 + +C.5 Frame Relay + + PropertyID Property Type Value + tag + + DLCI 5001 Unsigned Data link connection + integer id + + 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 + +C.6 IP + + PropertyID Property tag Type Value + + IPv4 6001 32 bits Ipv4Address Ipv4Address + Ref.: IETF RFC 791 + + IPv6 6002 128 bits IPv6 Address + Ref.: IETF RFC 2460 + + Port 6003 Unsigned integer 0..65535 + + Porttype 6004 Enumerated TCP(0), UDP(1), SCTP(2) + + +C.7 ATM AAL2 + + PropertyID Property Type Value + tag + + AESA 7001 20 octets AAL2 service endpoint + address as defined in + the referenced + Recommendation. + ESEANSEA + Ref.: ITU-T Q.2630.1 + + + + +Groves, et al. Standards Track [Page 134] + +RFC 3525 Gateway Control Protocol June 2003 + + + BIR See C.3 4 octets Served user generated + reference as defined in + the referenced + Recommendation. + SUGR + Ref.: ITU-T Q.2630.1 + + ALC 7002 12 octets AAL2 link + characteristics as + defined in the + referenced + Recommendation. + Maximum/Average CPS-SDU + bit rate; + Maximum/Average CPS-SDU + size + Ref.: ITU-T Q.2630.1 + + SSCS 7003 I.366.2: Audio (8 Service specific + octets); Multirate (3 convergence sublayer + octets), or I.366.1: information as defined + SAR-assured (14 in: + octets);SAR-unassured - ITU-T Q.2630.1,and + (7 octets). used in: + - ITU-T I.366.2: + Audio/Multirate; + - ITU-T I.366.1: SAR- + assured/unassured. + Ref.: ITU-T Q.2630.1, + I.366.1 and I.366.2 + + SUT 7004 1..254 octets Served user transport + parameter as defined in + the referenced + Recommendation. + Ref.: ITU-T Q.2630.1 + + TCI 7005 Boolean Test connection + indicator as defined in + the referenced + Recommendation. + Ref.: ITU-T Q.2630.1 + + Timer_CU 7006 32-bit integer Timer-CU + Milliseconds to hold + partially filled cell + before sending. + + + + +Groves, et al. Standards Track [Page 135] + +RFC 3525 Gateway Control Protocol June 2003 + + + MaxCPSSDU 7007 8-bit integer Maximum Common Part + Sublayer Service Data + Unit + Ref.: ITU-T Q.2630.1 + + CID 7008 8 bits subchannel id: 0-255 + Ref.: ITU-T I.363.2 +C.8 ATM AAL1 + + PropertyID Property Type Value + tag + + BIR See table 4-29 octets GIT (Generic Identifier + in C.3 Transport) + Ref.: ITU-T Q.2941.1 + + AAL1ST 8001 1 octet AAL1 Subtype + Bits + 8 7 6 5 4 3 2 1 + --------------- + 0 0 0 0 0 0 0 0 null + 0 0 0 0 0 0 0 1 voiceband + signal transport on 64 kbit/s + 0 0 0 0 0 0 1 0 circuit + transport + 0 0 0 0 0 1 0 0 high-quality + audio signal transport + 0 0 0 0 0 1 0 1 video signal + transport + Ref.: ITU-T Q.2931 + + CBRR 8002 1 octet CBR Rate + Bits + 8 7 6 5 4 3 2 1 + --------------- + 0 0 0 0 0 0 0 1 64 kbit/s + 0 0 0 0 0 1 0 0 1544 kbit/s + 0 0 0 0 0 1 0 1 6312 kbit/s + 0 0 0 0 0 1 1 0 32 064 kbit/s + 0 0 0 0 0 1 1 1 44 736 kbit/s + 0 0 0 0 1 0 0 0 97 728 kbit/s + 0 0 0 1 0 0 0 0 2048 kbit/s + 0 0 0 1 0 0 0 1 8448 kbit/s + 0 0 0 1 0 0 1 0 34 368 kbit/s + 0 0 0 1 0 0 1 1 139 264 kbit/s + 0 1 0 0 0 0 0 0 n x 64 kbit/s + 0 1 0 0 0 0 0 1 n x 8 kbit/s + Ref.: ITU-T Q.2931 + + + +Groves, et al. Standards Track [Page 136] + +RFC 3525 Gateway Control Protocol June 2003 + + + MULT See table Multiplier, or n x 64k/8k/300 + in C.9 Ref.: ITU-T Q.2931 + + SCRI 8003 1 octet Source Clock Frequency Recovery + Method + Bits + 8 7 6 5 4 3 2 1 + --------------- + 0 0 0 0 0 0 0 0 null + 0 0 0 0 0 0 0 1 SRTS + 0 0 0 0 0 0 1 0 ACM + Ref.: ITU-T Q.2931 + + ECM 8004 1 octet Error Correction Method + Bits + 8 7 6 5 4 3 2 1 + --------------- + 0 0 0 0 0 0 0 0 null + 0 0 0 0 0 0 0 1 FEC - Loss + 0 0 0 0 0 0 1 0 FEC - Delay + Ref.: ITU-T Q.2931 + + SDTB 8005 16-bit Structured Data Transfer + integer Blocksize + Block size of SDT CBR service + Ref.: ITU-T I.363.1 + + PFCI 8006 8-bit Partially filled cells identifier + integer 1-47 + Ref.: ITU-T I.363.1 + +C.9 Bearer capabilities + + The table entries referencing Recommendation Q.931 refer to the + encoding in the bearer capability information element of Q.931, not + to the low layer information element. + + PropertyID Tag Type Value + + TMR 9001 1 octet Transmission Medium + Requirement (Q.763) + Bits + 87654321 + -------- + 00000000 speech + 00000001 spare + 00000010 64 kbit/s + unrestricted + + + +Groves, et al. Standards Track [Page 137] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 + + The assigned codepoints + listed below are all for + unrestricted service. + 00000111 2 x 64 kbit/s + 00001000 384 kbit/s + 00001001 1536 kbit/s + 00001010 1920 kbit/s + 00001011 + through + 00001111 spare + 00010000 + through + 00101010: + 3 x 64 kbit/s through + 29 x 64 kbit/s + except + 00010011 spare + 00100101 spare + + 00101011 + through + 11111111 spare + Ref.: ITU-T Q.763 + + TMRSR 9002 1 octet Transmission Medium + Requirement Subrate + 0 unspecified + 1 8 kbit/s + 2 16 kbit/s + 3 32 kbit/s + + Contcheck 9003 Boolean Continuity Check + 0 continuity check not + required on this circuit + 1 continuity check + required on this circuit + Ref.: ITU-T Q.763 + + + +Groves, et al. Standards Track [Page 138] + +RFC 3525 Gateway Control Protocol June 2003 + + + + ITC 9004 5 bits Information Transfer + Capability + Bits + 5 4 3 2 1 + --------- + 0 0 0 0 0 Speech + 0 1 0 0 0 Unrestricted + digital information + 0 1 0 0 1 Restricted + digital information + 1 0 0 0 0 3.1 kHz audio + 1 0 0 0 1 Unrestricted + digital information with + tones/announcements + 1 1 0 0 0 Video + All other values are + reserved. + Ref.: ITU-T Q.763 + + TransMode 9005 2 bits Transfer Mode + Bits + 2 1 + --- + 0 0 Circuit mode + 1 0 Packet mode + Ref.: ITU-T Q.931 + + TransRate 9006 5 bits Transfer Rate + Bits + 5 4 3 2 1 + --------- + 0 0 0 0 0 This code shall + be used for packet mode calls + 1 0 0 0 0 64 kbit/s + 1 0 0 0 1 2 x 64 kbit/s + 1 0 0 1 1 384 kbit/s + 1 0 1 0 1 1536 kbit/s + 1 0 1 1 1 1920 kbit/s + 1 1 0 0 0 Multirate (64 + kbit/s base rate) + Ref.: ITU-T Q.931 + + MULT 9007 7 bits Rate Multiplier + Any value from 2 to n + (maximum number of B- + channels) + Ref.: ITU-T Q.931 + + + +Groves, et al. Standards Track [Page 139] + +RFC 3525 Gateway Control Protocol June 2003 + + + + layer1prot 9008 5 bits User Information Layer 1 + Protocol + Bits + 5 4 3 2 1 + --------- + 0 0 0 0 1 ITU-T + standardized rate adaption + V.110 and X.30. + 0 0 0 1 0 Recommendation + G.711 m-law + 0 0 0 1 1 Recommendation + G.711 A-law + 0 0 1 0 0 Recommendation + G.721 32 kbit/s ADPCM and + Recommendation I.460 + 0 0 1 0 1 Recommendations + H.221 and H.242 + 0 0 1 1 0 Recommendations + H.223 and H.245 + 0 0 1 1 1 Non-ITU-T + standardized rate adaption. + 0 1 0 0 0 ITU-T + standardized rate adaption + V.120. + 0 1 0 0 1 ITU-T + standardized rate adaption + X.31 HDLC flag stuffing + All other values are + reserved. + Ref.: ITU Recommendation + Q.931 + + syncasync 9009 Boolean Synchronous/Asynchronous + 0 Synchronous data + 1 Asynchronous data + Ref.: ITU-T Q.931 + + negotiation 900A Boolean Negotiation + 0 In-band negotiation + possible + 1 In-band negotiation not + possible + Ref.: ITU-T Q.931 + + Userrate 900B 5 bits User Rate + Bits + 5 4 3 2 1 + + + +Groves, et al. Standards Track [Page 140] + +RFC 3525 Gateway Control Protocol June 2003 + + + --------- + 0 0 0 0 0 Rate is + indicated by E-bits specified + in Recommendation I.460 or + may be negotiated in-band + 0 0 0 0 1 0.6 kbit/s + Recommendations V.6 and X.1 + 0 0 0 1 0 1.2 kbit/s + Recommendation V.6 + 0 0 0 1 1 2.4 kbit/s + Recommendations V.6 and X.1 + 0 0 1 0 0 3.6 kbit/s + Recommendation V.6 + 0 0 1 0 1 4.8 kbit/s + Recommendations V.6 and X.1 + 0 0 1 1 0 7.2 kbit/s + Recommendation V.6 + 0 0 1 1 1 8 kbit/s + Recommendation I.460 + 0 1 0 0 0 9.6 kbit/s + Recommendations V.6 and X.1 + 0 1 0 0 1 14.4 kbit/s + Recommendation V.6 + 0 1 0 1 0 16 kbit/s + Recommendation I.460 + 0 1 0 1 1 19.2 kbit/s + Recommendation V.6 + 0 1 1 0 0 32 kbit/s + Recommendation I.460 + 0 1 1 0 1 38.4 kbit/s + Recommendation V.110 + 0 1 1 1 0 48 kbit/s + Recommendations V.6 and X.1 + 0 1 1 1 1 56 kbit/s + Recommendation V.6 + 1 0 0 1 0 57.6 kbit/s + Recommendation V.14 extended + 1 0 0 1 1 28.8 kbit/s + Recommendation V.110 + 1 0 1 0 0 24 kbit/s + Recommendation V.110 + 1 0 1 0 1 0.1345 kbit/s + Recommendation X.1 + 1 0 1 1 0 0.100 kbit/s + Recommendation X.1 + 1 0 1 1 1 0.075/1.2 + kbit/s Recommendations V.6 + and X.1 + + + +Groves, et al. Standards Track [Page 141] + +RFC 3525 Gateway Control Protocol June 2003 + + + 1 1 0 0 0 1.2/0.075 + kbit/s Recommendations V.6 + and X.1 + 1 1 0 0 1 0.050 kbit/s + Recommendations V.6 and X.1 + 1 1 0 1 0 0.075 kbit/s + Recommendations V.6 and X.1 + 1 1 0 1 1 0.110 kbit/s + Recommendations V.6 and X.1 + 1 1 1 0 0 0.150 kbit/s + Recommendations V.6 and X.1 + 1 1 1 0 1 0.200 kbit/s + Recommendations V.6 and X.1 + 1 1 1 1 0 0.300 kbit/s + Recommendations V.6 and X.1 + 1 1 1 1 1 12 kbit/s + Recommendation V.6 + All other values are + reserved. + Ref.: ITU-T Q.931 + INTRATE 900C 2 bits Intermediate Rate + Bits + 2 1 + --- + 0 0 Not used + 0 1 8 kbit/s + 1 0 16 kbit/s + 1 1 32 kbit/s + Ref.: ITU-T Q.931 + + nictx 900D Boolean Network Independent Clock + (NIC) on transmission + 0 Not required to send + data with network independent + clock + 1 Required to send data + with network independent + clock + Ref.: ITU-T Q.931 + + nicrx 900E Boolean Network independent clock + (NIC) on reception + 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 + + + +Groves, et al. Standards Track [Page 142] + +RFC 3525 Gateway Control Protocol June 2003 + + + (i.e., sender does support + this optional procedure) + Ref.: ITU-T Q.931 + + flowconttx 900F Boolean Flow Control on transmission + (Tx) + 0 Not required to send + data with flow control + mechanism + 1 Required to send data + with flow control mechanism + Ref.: ITU-T Q.931 + + flowcontrx 9010 Boolean Flow control on reception + (Rx) + 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) + Ref.: ITU-T Q.931 + + rateadapthdr 9011 Boolean Rate adaption header/no + header + 0 Rate adaption header + not included + 1 Rate adaption header + included + Ref.: ITU-T Q.931 + + multiframe 9012 Boolean Multiple frame establishment + support in data link + 0 Multiple frame + establishment not supported. + Only UI frames allowed + 1 Multiple frame + establishment supported + Ref.: ITU-T Q.931 + + OPMODE 9013 Boolean Mode of operation + 0 Bit transparent mode of + operation + 1 Protocol sensitive mode + of operation + Ref.: ITU-T Q.931 + + + +Groves, et al. Standards Track [Page 143] + +RFC 3525 Gateway Control Protocol June 2003 + + + + llidnegot 9014 Boolean Logical link identifier + negotiation + 0 Default, LLI = 256 only + 1 Full protocol + negotiation + Ref.: ITU-T Q.931 + + assign 9015 Boolean Assignor/assignee + 0 Message originator is + "default assignee" + 1 Message originator is + "assignor only" + Ref.: ITU-T Q.931 + + inbandneg 9016 Boolean In-band/out-band negotiation + 0 Negotiation is done + with USER INFORMATION + messages on a temporary + signalling connection + 1 Negotiation is done in- + band using logical link zero + Ref.: ITU-T Q.931 + + stopbits 9017 2 bits Number of stop bits + Bits + 2 1 + --- + 0 0 Not used + 0 1 1 bit + 1 0 1.5 bits + 1 1 2 bits + Ref.: ITU-T Q.931 + + databits 9018 2 bits Number of data bits excluding + parity bit if present + Bits + 2 1 + --- + 0 0 Not used + 0 1 5 bits + 1 0 7 bits + 1 1 8 bits + Ref.: ITU-T Q.931 + + parity 9019 3 bits Parity information + Bits + 3 2 1 + + + +Groves, et al. Standards Track [Page 144] + +RFC 3525 Gateway Control Protocol June 2003 + + + ------ + 0 0 0 Odd + 0 1 0 Even + 0 1 1 None + 1 0 0 Forced to 0 + 1 0 1 Forced to 1 + All other values are + reserved. + Ref.: ITU-T Q.931 + + duplexmode 901A Boolean Mode duplex + 0 Half duplex + 1 Full duplex + Ref.: ITU-T Q.931 + + modem 901B 6 bits Modem Type + Bits + 6 5 4 3 2 1 + ----------- + 0 0 0 0 0 0 through + 0 0 0 1 0 1 National use + 0 1 0 0 0 1 Rec. V.21 + 0 1 0 0 1 0 Rec. V.22 + 0 1 0 0 1 1 Rec. V.22 bis + 0 1 0 1 0 0 Rec. V.23 + 0 1 0 1 0 1 Rec. V.26 + 0 1 1 0 0 1 Rec. V.26 bis + 0 1 0 1 1 1 Rec. V.26 ter + 0 1 1 0 0 0 Rec. V.27 + 0 1 1 0 0 1 Rec. V.27 bis + 0 1 1 0 1 0 Rec. V.27 ter + 0 1 1 0 1 1 Rec. V.29 + 0 1 1 1 0 1 Rec. V.32 + 0 1 1 1 1 0 Rec. V.34 + 1 0 0 0 0 0 through + 1 0 1 1 1 1 National use + 1 1 0 0 0 0 through + 1 1 1 1 1 1 User specified + Ref.: ITU-T Q.931 + + layer2prot 901C 5 bits User information layer 2 + protocol + Bits + 5 4 3 2 1 + --------- + 0 0 0 1 0 Rec. Q.921/I.441 + 0 0 1 1 0 Rec. X.25, link + layer + + + +Groves, et al. Standards Track [Page 145] + +RFC 3525 Gateway Control Protocol June 2003 + + + 0 1 1 0 0 LAN logical link + control (ISO/IEC 8802 2) + All other values are + reserved. + Ref.: ITU-T Q.931 + + layer3prot 901D 5 bits User information layer 3 + protocol + Bits + 5 4 3 2 1 + --------- + 0 0 0 1 0 ITU-T Q.931 + 0 0 1 1 0 ITU-T X.25, + packet layer + 0 1 0 1 1 ISO/IEC TR 9577 + (Protocol identification in + the network layer) + All other values are + reserved. + Ref.: ITU-T Q.931 + + addlayer3prot 901E Octet Additional User Information + layer 3 protocol + Bits Bits + 4 3 2 1 4 3 2 1 + ------- ------- + 1 1 0 0 1 1 0 0 + Internet Protocol (RFC 791) + (ISO/IEC TR 9577) + 1 1 0 0 1 1 1 1 + Point-to-point Protocol (RFC + 1661) + Ref.: ITU-T Q.931 + + DialledN 901F 30 Dialled Number + octets + + DiallingN 9020 30 Dialling Number + octets + + ECHOCI 9021 Not Used. See H.248.1 E.13 + for an example of possible + Echo Control properties. + + NCI 9022 1 octet Nature of Connection + Indicators + Bits + 2 1 Satellite Indicator + + + +Groves, et al. Standards Track [Page 146] + +RFC 3525 Gateway Control Protocol June 2003 + + + --- + 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 + + Bit + 5 Echo control device + - indicator + 0 outgoing echo control + device not included + 1 outgoing echo control + device included + + Bits + 8 7 6 Spare + Ref.: ITU-T Q.763 + + USI 9023 Octet User Service Information + string Ref.: ITU-T Q.763 Clause 3.57 + +C.10 AAL5 properties + + PropertyID Property Type Value + tag + + FMSDU A001 32-bit Forward Maximum CPCS-SDU Size: + integer Maximum CPCS-SDU size sent in the + direction from the calling user to + the called user. + Ref.: ITU-T Q.2931 + + + + + +Groves, et al. Standards Track [Page 147] + +RFC 3525 Gateway Control Protocol June 2003 + + + BMSDU A002 32-bit Backwards Maximum CPCS-SDU Size: + integer Maximum CPCS-SDU size sent in the + direction from the called user to + the calling user. + Ref.: ITU-T Q.2931 + + SSCS See table See table See table in C.7 + in C.7 in C.7 Additional values: + VPI/VCI + +C.11 SDP equivalents + + PropertyID Property Type Value + tag + + SDP_V B001 String Protocol Version + Ref.: RFC 2327 + + SDP_O B002 String Owner/creator and session ID + Ref.: RFC 2327 + + SDP_S B003 String Session name + Ref.: RFC 2327 + + SDP_I B004 String Session identifier + Ref.: RFC 2327 + + SDP_U B005 String URI of descriptor + Ref.: RFC 2327 + + SDC_E B006 String email address + Ref.: RFC 2327 + + SDP_P B007 String phone number + Ref.: RFC 2327 + + SDP_C B008 String Connection information + Ref.: RFC 2327 + + SDP_B B009 String Bandwidth Information + Ref.: RFC 2327 + + SDP_Z B00A String Time zone adjustment + Ref.: RFC 2327 + + SDP_K B00B String Encryption Key + Ref.: RFC 2327 + + + + +Groves, et al. Standards Track [Page 148] + +RFC 3525 Gateway Control Protocol June 2003 + + + SDP_A B00C String Zero or more session attributes + Ref.: RFC 2327 + + SDP_T B00D String Active Session Time + Ref.: RFC 2327 + + SDP_R B00E String Zero or more repeat times + Reference: RFC 2327 + + SDP_M B00F String Media type, port, transport and format + Ref.: RFC 2327 + +C.12 H.245 + + PropertyID Property Type Value + tag + + OLC C001 Octet The value of H.245 + OpenLogicalChannel structure. + string Ref.: ITU-T H.245 + + OLCack C002 Octet The value of H.245 + string OpenLogicalChannelAck structure. + Ref.: ITU-T H.245 + + OLCcnf C003 Octet The value of H.245 + string OpenLogicalChannelConfirm structure. + Ref.: ITU-T H.245 + + OLCrej C004 Octet The value of H.245 + string OpenLogicalChannelReject structure. + Ref.: ITU-T H.245 + + CLC C005 Octet The value of H.245 + string CloseLogicalChannel structure. + Ref.: ITU-T H.245 + + CLCack C006 Octet The value of H.245 + string CloseLogicalChannelAck structure. + Ref.: ITU-T H.245 + + + + + + + + + + + +Groves, et al. Standards Track [Page 149] + +RFC 3525 Gateway Control Protocol June 2003 + + +ANNEX D - Transport over IP + +D.1 Transport over IP/UDP using Application Level Framing (ALF) + + Protocol messages defined in this RFC may be transmitted over UDP. + When no port is provided by the peer (see 7.2.8), commands should be + sent to the default port number: 2944 for text-encoded operation, or + 2945 for binary-encoded operation. Responses must be sent to the + address and port from which the corresponding commands were sent. + + ALF is a set of techniques that allows an application, as opposed to + a stack, to affect how messages are sent to the other side. A + typical ALF technique is to allow an application to change the order + of messages sent when there is a queue after it has queued them. + There is no formal specification for ALF. The procedures in Annex + D.1 contain a minimum suggested set of ALF behaviours + + 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 + + Messages, being carried over UDP, may be subject to losses. In the + absence of a timely response, commands are repeated. Most commands + are not idempotent. The state of the MG would become unpredictable + if, for example, Add commands were executed several times. The + transmission procedures shall thus provide an "At-Most-Once" + functionality. + + Peer protocol entities are expected to keep in memory a list of the + responses that they sent to recent transactions and a list of the + transactions that are currently outstanding. The transaction + identifier of each incoming message is compared to the transaction + identifiers of the recent responses sent to the same MId. If a match + is found, the entity does not execute the transaction, but simply + repeats the response. If no match is found, the message will be + compared to the list of currently outstanding transactions. If a + match is found in that list, indicating a duplicate transaction, the + entity does not execute the transaction (see D.1.4 for procedures on + sending TransactionPending). + + The procedure uses a long timer value, noted LONG-TIMER in the + following. The timer should be set larger than the maximum duration + of a transaction, which should take into account the maximum number + + + + + + + +Groves, et al. Standards Track [Page 150] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 has been received, through the + "Response Acknowledgement parameter". For transactions that are + acknowledged through this parameter, the entity shall keep a copy of + the transaction-id for LONG-TIMER seconds after the response is + issued, in order to 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 may decide to use a specific number space for each of the + MGs that they manage, or to use the same number space for all MGs + that belong to some arbitrary group. MGCs may decide to share the + load of managing a large MG between several independent processes. + These processes will share the same transaction number space. There + are multiple possible implementations of this sharing, such as having + a centralized allocation of transaction identifiers, or + pre-allocating non-overlapping ranges of identifiers to different + processes. The implementations 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. + + + + +Groves, et al. Standards Track [Page 151] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 A.2), only one transaction is acknowledged. 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 B.2). + +D.1.3 Computing retransmission timers + + It is the responsibility of the requesting entity to provide suitable + timeouts for all outstanding transactions, and to retry transactions + when timeouts have been exceeded. Furthermore, when repeated + transactions fail to be acknowledged, it is the responsibility of the + requesting entity to seek redundant services and/or clear existing or + pending connections. + + The specification purposely avoids specifying any value for the + retransmission timers. These values are typically network dependent. + 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. 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. + + 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 + RFC, in order to guarantee that no repeated packet + would be received by the gateways after LONG-TIMER seconds. A + suggested maximum value is 4 seconds. + + + + + + +Groves, et al. Standards Track [Page 152] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 + + The protocol is organized as a set of transactions, each of which is + composed of a request and a response, commonly referred to as an + acknowledgement. The protocol messages, being carried over UDP, may + be subject to losses. In the absence of a timely response, + transactions are repeated. Entities are expected to keep in memory a + + + + +Groves, et al. Standards Track [Page 153] + +RFC 3525 Gateway Control Protocol June 2003 + + + list of the responses that they sent to recent transactions, i.e., a + list of all the responses they sent over the last LONG-TIMER seconds, + and a list of the transactions that are currently being executed. + + The repetition mechanism is used to guard against three types of + possible errors: + + - transmission errors, when for example a packet is lost due to + noise on a line or congestion in a queue; + + - component failure, when for example an interface to a entity + becomes unavailable; + + - entity failure, when for example an entire entity becomes + unavailable. + + The entities should be able to derive from the past history an + estimate of the packet loss rate due to transmission errors. In a + properly configured system, this loss rate should be kept very low, + typically less than 1%. If a Media Gateway Controller or a Media + Gateway has to repeat a message more than a few times, it is very + legitimate to assume that something else than a transmission error is + occurring. For example, given a loss rate of 1%, the probability + that five consecutive transmission attempts fail is 1 in 100 billion, + an event that should occur less than once every 10 days for a Media + Gateway Controller that processes 1000 transactions per second. + (Indeed, the number of repetition that is considered excessive should + be a function of the prevailing packet loss rate.) We should note + that the "suspicion threshold", which we will call "Max1", is + normally lower than the "disconnection threshold", which should be + set to a larger value. + + A classic retransmission algorithm would simply count the number of + successive repetitions, and conclude that the association is broken + after retransmitting the packet an excessive number of times + (typically between 7 and 11 times.) In order to account for the + possibility of an undetected or in progress "failover", we modify + the classic algorithm so that if the Media Gateway receives a valid + ServiceChange message announcing a failover, it will start + transmitting outstanding commands to that new MGC. Responses to + commands are still transmitted to the source address of the command. + + In order to automatically adapt to network load, this RFC specifies + exponentially increasing timers. If the initial timer is set to 200 + milliseconds, the loss of a fifth retransmission will be detected + after about 6 seconds. This is probably an acceptable waiting delay + to detect a failover. The repetitions should continue after that + delay not only in order to perhaps overcome a transient connectivity + + + +Groves, et al. Standards Track [Page 154] + +RFC 3525 Gateway Control Protocol June 2003 + + + problem, but also in order to allow some more time for the execution + of a failover (waiting a total delay of 30 seconds is probably + acceptable). + + It is, however, important that the maximum delay of retransmissions + be bounded. Prior to any retransmission, it is checked that the time + elapsed since the sending of the initial datagram is no greater than + T-MAX. If more than T-MAX time has elapsed, the MG concludes that + the MGC has failed, and it begins its recovery process as described + in section 11.5. If the MG retries to connect to the current MGC it + shall use a ServiceChange with ServiceChangeMethod set to + Disconnected so that the new MGC will be aware that the MG lost one + or more transactions. The value T-MAX is related to the LONG-TIMER + value: the LONG-TIMER value is obtained by adding to T MAX the + maximum propagation delay in the network. + +D.2 Using TCP + + Protocol messages as defined in this RFC may be transmitted over TCP. + When no port is specified by the other side (see 7.2.8), the commands + should be sent to the default port. The defined protocol has + messages as the unit of transfer, while TCP is a stream-oriented + protocol. TPKT, according to RFC 1006, SHALL be used to delineate + messages within the TCP stream. + + In a transaction-oriented protocol, there are still ways for + transaction requests or responses to be lost. As such, it is + recommended that entities using TCP transport implement application + level timers for each request and each response, similar to those + specified for application level framing over UDP. + +D.2.1 Providing the At-Most-Once functionality + + Messages, being carried over TCP, are not subject to transport + losses, but loss of a transaction request or its reply may + nonetheless be noted in real implementations. In the absence of a + timely response, commands are repeated. Most commands are not + idempotent. The state of the MG would become unpredictable if, for + example, Add commands were executed several times. + + To guard against such losses, it is recommended that entities follow + the procedures in D.1.1. + +D.2.2 Transaction identifiers and three-way handshake + + For the same reasons, it is possible that transaction replies may be + lost even with a reliable delivery protocol such as TCP. It is + recommended that entities follow the procedures in D.1.2.2. + + + +Groves, et al. Standards Track [Page 155] + +RFC 3525 Gateway Control Protocol June 2003 + + +D.2.3 Computing retransmission timers + + With reliable delivery, the incidence of loss of a transaction + request or reply is expected to be very low. Therefore, only simple + timer mechanisms are required. Exponential back-off algorithms + should not be necessary, although they could be employed where, as in + an MGC, the code to do so is already required, since MGCs must + implement ALF/UDP as well as TCP. + +D.2.4 Provisional responses + + As with UDP, executing some transactions may require a long time. + 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 longer + repetition timer for that transaction. + + Entities shall retain Transactions and replies until they are + confirmed. The basic procedure of D.1.4 should be followed, but + simple timer values should be sufficient. There is no need to send + an immediate confirmation upon receipt of a final response. + +D.2.5 Ordering of commands + + TCP provides ordered delivery of transactions. No special procedures + are required. It should be noted that ALF/UDP allows sending entity + to modify its behaviour under congestion, and in particular, could + reorder transactions when congestion is encountered. TCP could not + achieve the same results. + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 156] + +RFC 3525 Gateway Control Protocol June 2003 + + +ANNEX E - Basic packages + + This annex contains definitions of some packages for use with + Recommendation H.248.1. + +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 + + EventsDescriptor parameters: None + + ObservedEvents Descriptor Parameters: + + General Cause + ParameterID: Generalcause (0x0001) + + This parameter groups the failures into six groups, which + the MGC may act upon. + + Type: enumeration + + Possible values: + "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) + + + + +Groves, et al. Standards Track [Page 157] + +RFC 3525 Gateway Control Protocol June 2003 + + + Possible values: OCTET STRING + + Description: The Failure 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. + + Signal Completion + + EventID: sc (0x0002) + + Indicates the termination of a signal for which the + notifyCompletion parameter was set to enable reporting of a + completion event. For further procedural description, see 7.1.1, + 7.1.17 and 7.2.7. + + EventsDescriptor parameters: None + + ObservedEvents Descriptor parameters: + + Signal Identity + ParameterID: SigID (0x0001) + + This parameter identifies the signal which has terminated. + For a signal that is contained in a signal list, the signal + list identity parameter should also be returned indicating + the appropriate list. + + Type: Binary: octet (string), Text: string + + Possible values: a signal which has terminated. A signal + shall be identified using the pkgdName syntax without + wildcarding. + + Termination Method + ParameterID: Meth (0x0002) + + Indicates the means by which the signal terminated. + + Type: enumeration + + Possible values: + "TO" (0x0001) Signal timed out or otherwise completed on + its own + "EV" (0x0002) Interrupted by event + "SD" (0x0003) Halted by new Signals descriptor + "NC" (0x0004) Not completed, other cause + + + + +Groves, et al. Standards Track [Page 158] + +RFC 3525 Gateway Control Protocol June 2003 + + + Signal List ID + ParameterID: SLID (0x0003) + + Indicates to which signal list a signal belongs. The + SignalList ID is only returned in cases where the signal + resides in a signal list. + + Type: integer + + Possible values: any integer + +E.1.3 Signals + + None. + +E.1.4 Statistics + + None. + +E.2 Base Root Package + + PackageID: root (0x0002) + Version: 1 + Extends: None + + Description: + This package defines Gateway wide properties. + +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 + + Characteristics: read only + + MaxTerminationsPerContext + PropertyID: maxTerminationsPerContext (0x0002) + + + + +Groves, et al. Standards Track [Page 159] + +RFC 3525 Gateway Control Protocol June 2003 + + + The maximum number of allowed terminations in a context, see 6.1 + + Type: integer + + Possible values: any integer + + Defined in: TerminationState + + Characteristics: read only + + 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 + + Characteristics: read / write + + 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 + + Characteristics: read / write + + MGProvisionalResponseTimerValue + PropertyId: MGProvisionalResponseTimerValue (0x0005) + + Indicates the time within which the MGC should expect a Pending + Response from the MG if a Transaction cannot be completed. + + Initially set to normalMGExecutionTime plus network delay, but may + be lowered. + + + +Groves, et al. Standards Track [Page 160] + +RFC 3525 Gateway Control Protocol June 2003 + + + Type: Integer + + Possible Values: any integer, represents milliseconds + + Defined in: TerminationState + + Characteristics: read / write + + MGCProvisionalResponseTimerValue + PropertyId: MGCProvisionalResponseTimerValue (0x0006) + + Indicates the time within which the MG should expect a Pending + Response from the MGC if a Transaction cannot be completed. + Initially set to normalMGCExecutionTime plus network delay, but + may be lowered. + + Type: Integer + + Possible Values: any integer, represents milliseconds + + Defined in: TerminationState + + Characteristics: read / write + +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: tonegen (0x0003) + Version: 1 + Extends: None + + + + + + +Groves, et al. Standards Track [Page 161] + +RFC 3525 Gateway Control Protocol June 2003 + + + Description: + + This package defines signals to generate audio tones. This + package does not specify parameter values. It is intended to be + extendable. Generally, tones are defined as an individual signal + with a parameter, ind, representing "interdigit" time delay, and a + tone id to be used with playtones. A tone id should be kept + consistent with any tone generation for the same tone. MGs are + expected to be provisioned with the characteristics of appropriate + tones for the country in which the MG is located. + + Designed to be extended only. + +E.3.1 Properties + + None. + +E.3.2 Events + + None. + +E.3.3 Signals + + Play tone + SignalID: pt (0x0001) + + Plays audio tone over an audio channel + + Signal Type: Brief + + Duration: Provisioned + + Additional parameters: + + Tone id list + ParameterID: tl (0x0001) + + Type: list of tone ids + + List of tones to be played in sequence. The list SHALL + contain one or more tone ids. + + Inter signal duration + ParameterID: ind (0x0002) + + Type: integer + + Timeout between two consecutive tones in milliseconds + + + +Groves, et al. Standards Track [Page 162] + +RFC 3525 Gateway Control Protocol June 2003 + + + + No tone ids are specified in this package. Packages that extend this + package can add possible values for tone id as well as adding + individual tone signals. + +E.3.4 Statistics + + None. + +E.3.5 Procedures + + None. + +E.4 Tone Detection Package + + PackageID: tonedet (0x0004) + Version: 1 + Extends: None + + This Package defines events for audio tone detection. Tones are + selected by name (tone id). MGs are expected to be provisioned with + the characteristics of appropriate tones for the country in which the + MG is located. + + Designed to be extended only: + This package does not specify parameter values. It is intended to + be extendable. + +E.4.1 Properties + + None. + +E.4.2 Events + + Start tone detected + EventID: std, 0x0001 + + Detects the start of a tone. The characteristics of positive tone + detection are implementation dependent. + + EventsDescriptor parameters: + + Tone id list + ParameterID: tl (0x0001) + + Type: list of tone ids + + + + + +Groves, et al. Standards Track [Page 163] + +RFC 3525 Gateway Control Protocol June 2003 + + + Possible values: The only tone id defined in this package is + "wild card" which is "*" in text encoding and 0x0000 in + binary. Extensions to this package would add possible + values for tone id. If tl is "wild card", any tone id is + detected. + + ObservedEventsDescriptor parameters: + + Tone id + ParameterID: tid (0x0003) + + Type: enumeration + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this package + would add additional possible values for tone id. + + End tone detected + EventID: etd, 0x0002 + + Detects the end of a tone. + + EventDescriptor parameters: + + Tone id list + ParameterID: tl (0x0001) + + Type: enumeration or list of enumerated types + + Possible values: No possible values are specified in this + package. Extensions to this package would add possible + values for tone id. + + ObservedEventsDescriptor parameters: + + Tone id + ParameterID: tid (0x0003) + + Type: enumeration + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this + package would add possible values for tone id. + + Duration + ParameterId: dur (0x0002) + + Type: integer, in milliseconds + + + +Groves, et al. Standards Track [Page 164] + +RFC 3525 Gateway Control Protocol June 2003 + + + + This parameter contains the duration of the tone from + first detection until it stopped. + + Long tone detected + EventID: ltd, 0x0003 + + 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 list + + Possible values: "wildcard" as defined above is the only + value defined in this package. Extensions to this package + would add possible values for tone id. + + Duration + ParameterID: dur (0x0002) + + Type: integer, duration to test against + + Possible values: any legal integer, expressed in + milliseconds + + ObservedEventsDescriptor parameters: + + Tone id + ParameterID: tid (0x0003) + + Type: Enumeration + + Possible values: No possible values are specified in this + package. Extensions to this package would add possible + values for tone id. + +E.4.3 Signals + + None. + +E.4.4 Statistics + + None. + + + + +Groves, et al. Standards Track [Page 165] + +RFC 3525 Gateway Control Protocol June 2003 + + +E.4.5 Procedures + + None. + +E.5 Basic DTMF Generator Package + + PackageID: dg (0x0005) + Version: 1 + Extends: tonegen version 1 + + This package defines the basic DTMF tones as signals and 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 + SignalID: d0 (0x0010) + + Generate DTMF 0 tone. The physical characteristic of DTMF 0 is + defined in the gateway. + + Signal Type: Brief + + Duration: Provisioned + + Additional parameters: + + None. + + Additional values: + + d0 (0x0010) is defined as a tone id for playtone + + The other DTMF characters are specified in exactly the same way. A + table with all signal names and signal IDs is included. Note that + each DTMF character is defined as both a signal and a tone id, thus + extending the basic tone generation package. Also note that DTMF + SignalIds are different from the names used in a digit map. + + + + + +Groves, et al. Standards Track [Page 166] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 1 + + This package defines the basic DTMF tones detection. This Package + extends the possible values of tone id in the "start tone detected" + "end tone detected" and "long tone detected" events. + + Additional tone id values are all tone ids described in package dg + (basic DTMF generator package). + + The following table maps DTMF events to digit map symbols as + described in 7.1.14. + + DTMF Event Symbol + + d0 "0" + d1 "1" + d2 "2" + + + +Groves, et al. Standards Track [Page 167] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 defined + in the table found in E.5.3. + + DigitMap Completion Event + EventID: ce, 0x0004 + + Generated when a digit map completes as described in 7.1.14. + + EventsDescriptor parameters: None. + + 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". + + Description: the portion of the current dial string as + described in 7.1.14 which matched part or all of an + alternative event sequence specified in the digit map. + + + + + +Groves, et al. Standards Track [Page 168] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 event + + Description: indicates the reason for generation of the + event. See the procedures in 7.1.14. + +E.6.3 Signals + + None. + +E.6.4 Statistics + + None. + +E.6.5 Procedures + + Digit map processing is activated only if an events descriptor is + activated that contains a digit map completion event as defined in + Section E.6.2 and that digit map completion event contains an eventDM + field in the requested actions as defined in Section 7.1.9. Other + parameters such as KeepActive or embedded events of signals + descriptors may also be present in the events descriptor and do not + affect the activation of digit map processing. + +E.7 Call Progress Tones Generator Package + + PackageID: cg, 0x0007 + Version: 1 + Extends: tonegen version 1 + + This package defines the basic call progress tones as signals and + extends the allowed values of the tl parameter of playtone in + tonegen. + + + + + + +Groves, et al. Standards Track [Page 169] + +RFC 3525 Gateway Control Protocol June 2003 + + +E.7.1 Properties + + None. + +E.7.2 Events + + None. + +E.7.3 Signals + + Dial Tone + SignalID: dt (0x0030) + + Generate dial tone. The physical characteristic of dial tone is + available in the gateway. + + Signal Type: TimeOut + + Duration: Provisioned + + Additional parameters: + + None. + + Additional values: + + dt (0x0030) is defined as a tone id for playtone + + The other tones of this package are defined in exactly the same way. + A table with all signal names and signal IDs is included. Note that + each tone is defined as both a signal and a tone id, thus extending + 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 prt (0x0036) + Call Waiting Tone cw (0x0037) + Caller Waiting Tone cr (0x0038) + +E.7.4 Statistics + + None. + + + +Groves, et al. Standards Track [Page 170] + +RFC 3525 Gateway Control Protocol June 2003 + + +E.7.5 Procedures + + NOTE - The required set of tone ids corresponds to those defined + in Recommendation E.180/Q.35. See Recommendation E.180/Q.35 for + definition of the meanings of these tones. + + +E.8 Call Progress Tones Detection Package + + PackageID: cd (0x0008) + Version: 1 + Extends: tonedet version 1 + + This package defines the basic call progress detection tones. This + package extends the possible values of tone id in the "start tone + detected", "end tone detected" and "long tone detected" events. + + Additional values + + toneID values are defined for start tone detected, end tone + detected and long tone detected with the same values as those in + package cg (call progress tones generation package). + + The required set of tone ids corresponds to Recommendation + E.180/Q.35. See Recommendation E.180/Q.35 for definition of the + meanings of these tones. + +E.8.1 Properties + + None. + +E.8.2 Events + + Events are defined as in the call progress tones generator package + (cg) for the tones listed in the table of E.7.3. + +E.8.3 Signals + + None. + +E.8.4 Statistics + + None. + +E.8.5 Procedures + + None. + + + + +Groves, et al. Standards Track [Page 171] + +RFC 3525 Gateway Control Protocol June 2003 + + +E.9 Analog Line Supervision Package + + PackageID: al, 0x0009 + Version: 1 + Extends: None + + This package defines events and signals for an analog line. + + E.9.1 Properties + + None. + +E.9.2 Events + + onhook + EventID: on (0x0004) + + Detects handset going on hook. Whenever an events descriptor is + activated that requests monitoring for 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 that only an actual hook state transition to + on-hook is to be recognized; + + "state" means that the event is to be recognized either 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: Boolean + + + +Groves, et al. Standards Track [Page 172] + +RFC 3525 Gateway Control Protocol June 2003 + + + Possible values: + + "True" means that the event was reported because the line + was already on-hook when the events descriptor containing + this event was activated; + + "False" means that the event represents an actual state + transition to on-hook. + + offhook + EventID: of (0x0005) + + Detects handset going off hook. Whenever an events descriptor is + activated that requests monitoring for 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 that only an actual hook state transition + to off-hook is to be recognized; + + "state" means that the event is to be recognized either + 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: Boolean + + + + + + + + +Groves, et al. Standards Track [Page 173] + +RFC 3525 Gateway Control Protocol June 2003 + + + Possible values: + + "True" means that the event was reported because the line + was already off-hook when the events descriptor + containing this event was activated; + + "False" means that the event represents an actual state + transition to off-hook. + + flashhook + EventID: fl, 0x0006 + + Detects handset flash. A flash occurs when an onhook is followed + by an offhook between a minimum and maximum duration. + + EventDescriptor parameters: + + Minimum duration + ParameterID: mindur (0x0004) + + Type: integer in milliseconds + + Default value is provisioned. + + Maximum duration + ParameterID: maxdur (0x0005) + + Type: integer in milliseconds + + Default value is provisioned. + + ObservedEventsDescriptor parameters: + + None + +E.9.3 Signals + + ring + SignalID: ri, 0x0002 + + Applies ringing on the line + + Signal Type: TimeOut + + Duration: Provisioned + + + + + + +Groves, et al. Standards Track [Page 174] + +RFC 3525 Gateway Control Protocol June 2003 + + + Additional 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 reponse. + +E.9.6 Error code + + This package defines a new error code: + + 540 - Unexpected initial hook state + + The procedure for use of this code is given in E.9.5. + +E.10 Basic Continuity Package + + PackageID: ct (0x000a) + Version: 1 + Extends: None + + + + +Groves, et al. Standards Track [Page 175] + +RFC 3525 Gateway Control Protocol June 2003 + + + This 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, 0x0005 + + This event detects test completion of 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: TimeOut + + Default value is provisioned + + Additional parameters: + + None. + + Respond + SignalID: rsp (0x0004) + + + + + +Groves, et al. Standards Track [Page 176] + +RFC 3525 Gateway Control Protocol June 2003 + + + The signal is used to respond to a continuity test. See E.10.5 + for further explanation. + + Signal Type: On/Off + + Default 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. + + + + +Groves, et al. Standards Track [Page 177] + +RFC 3525 Gateway Control Protocol June 2003 + + + (Informative Note) Example tones and test procedure details are + given in Q.724 sections 7 and 8, Q.764 section 2.1.8 and Q.1902.4. + +E.11 Network Package + + PackageID: nt (0x000b) + Version: 1 + Extends: None + + This 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 milliseconds + + Possible values: This property is specified in milliseconds. + + Defined in: LocalControlDescriptor + + Characteristics: read/write + +E.11.2 Events + + network failure + EventID: netfail, 0x0005 + + The 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 string + + + + +Groves, et al. Standards Track [Page 178] + +RFC 3525 Gateway Control Protocol June 2003 + + + This parameter may be included with the failure event to + provide diagnostic information on the reason of failure. + + quality alert + EventID: qualert, 0x0006 + + This 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, propagation delay and then indicating this + using a percentage of quality loss. + + EventDescriptor parameters + + Threshold + ParameterId: th (0x0001) + + Type: integer + + Possible values: 0 to 99 + + Description: 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. Event is triggered when calculation exceeds the + threshold. + + ObservedEventsDescriptor parameters + + Threshold + ParameterId: th (0x0001) + + Type: integer + + Possible values: 0 to 99 + + Description: 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. + + + + + + + + + +Groves, et al. Standards Track [Page 179] + +RFC 3525 Gateway Control Protocol June 2003 + + +E.11.4 Statistics + + Duration + StatisticsID: dur (0x0001) + + Description: provides 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 1 + + This package is used to support 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, 0x0001 + + This event detects and notifies when there is a transition of the + RTP payload format from one format to another. + + + +Groves, et al. Standards Track [Page 180] + +RFC 3525 Gateway Control Protocol June 2003 + + + EventDescriptor parameters + + None. + + ObservedEventsDescriptor parameters + + ParameterName: 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) + + Describes the current rate of packet loss on an RTP stream, as + defined in IETF RFC 1889. Packet loss is expressed as percentage + value: number of packets lost in the interval between two + reception reports, divided by the number of packets expected + during that interval. + + Type: double + + Possible values: a 32-bit whole number and a 32-bit fraction. + + + + +Groves, et al. Standards Track [Page 181] + +RFC 3525 Gateway Control Protocol June 2003 + + + Jitter + StatisticID: jit (0x0007) + + Requests the current value of the interarrival jitter on an RTP + stream as defined in IETF RFC 1889. Jitter measures the variation + in interarrival time for RTP data packets. + + Delay + StatisticID:delay (0x0008) + + Requests the current value of packet propagation delay expressed + in timestamp units. Same as average latency. + +E.12.5 Procedures + + None. + +E.13 TDM Circuit Package + + PackageID: tdmc (0x000d) + Version: 1 + Extends: Network Package version 1 + + This package may be used by any termination that supports gain and + echo control. It was originally intended for use on TDM circuits + but may be more widely used. + + + New versions or extensions of this package should take non-TDM use + into account. + +E.13.1 Properties + + Echo Cancellation + PropertyID: ec (0x0008) + + Type: boolean + + Possible values: + + "on" (when the echo cancellation is requested) and + + "off" (when it is turned off.) + + The default is provisioned. + + Defined in: LocalControlDescriptor + + + + +Groves, et al. Standards Track [Page 182] + +RFC 3525 Gateway Control Protocol June 2003 + + + Characteristics: read/write + + Gain Control + PropertyID: gain (0x000a) + + Gain control, or usage of of signal level adaptation and + noise level reduction is used to adapt the level of the signal. + However, it is necessary, for example for modem calls, to turn + off this function. + + Type: 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. + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 183] + +RFC 3525 Gateway Control Protocol June 2003 + + +APPENDIX I EXAMPLE CALL FLOWS (INFORMATIVE) + + All H.248.1 implementors must read the normative part of this RFC + carefully before implementing from it. The examples in this appendix + should not be used as stand-alone explanations of how to create + protocol messages. + + The examples in this appendix use SDP for encoding of the Local and + and Remote stream descriptors. SDP is defined in RFC 2327. If there + is is any discrepancy between the SDP in the examples, and RFC 2327, + the the RFC should be consulted for correctness. Audio profiles used + are are those defined in IETF RFC 1890, and others registered with + IANA. For example, G.711 A-law is called PCMA in SDP, and is + assigned profile 0. G.723.1 is called G723 and is profile 4; H.263 is + called H263 and is profile 34. See also + http://www.iana.org/assignments/rtp-parameters. + +A.1 Residential Gateway to Residential Gateway Call + + This example scenario illustrates the use of the elements of the + protocol to set up a Residential Gateway to Residential Gateway call + over an IP-based network. For simplicity, this example assumes that + both Residential Gateways involved in the call are controlled by the + same Media Gateway Controller. + +A.1.1 Programming Residential GW Analog Line Terminations for Idle + Behavior + + The following illustrates the API invocations from the Media Gateway + Controller and Media Gateways to 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. + + 1. An MG registers with an MGC using the ServiceChange command: + + MG1 to MGC: + + MEGACO/1 [124.124.124.222] Transaction = 9998 { + Context = - { + + + +Groves, et al. Standards Track [Page 184] + +RFC 3525 Gateway Control Protocol June 2003 + + + ServiceChange = ROOT {Services { + Method=Restart, + ServiceChangeAddress=55555, Profile=ResGW/1} + } + } } + + 2. 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} } } } + + 3. The MGC programs a Termination in the NULL context. The + terminationId is A4444, the streamId is 1, the requestId in the + Events descriptor is 2222. The mId is the identifier of the sender + of this message, in this case, it is 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. Local and Remote are + assumed to be provisioned. + + 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 + }, + + } + }, + Events = 2222 {al/of(strict=state)} + } + } } + + + 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). + + + + + +Groves, et al. Standards Track [Page 185] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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. + + 4. The MG1 accepts the Modify with this reply: + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 + + Reply = 9999 { + Context = - {Modify = A4444} } + + 5. 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 + + The following builds upon the previously shown conditions. It + illustrates the transactions from the Media Gateway Controller and + originating Media Gateway (MG1) to get the originating Termination + (A4444) through the stages of digit collection required to initiate a + connection to the terminating Media Gateway (MG2). + + 6. 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(init=false)}} + } } + + 7. And the Notify is acknowledged. + + MGC to MG1: + + MEGACO/1 [123.123.123.4]:55555 Reply = 10000 { + + Context = - {Notify = A4444} } + + + + + + + + + + +Groves, et al. Standards Track [Page 186] + +RFC 3525 Gateway Control Protocol June 2003 + + + 8. 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. + + MGC to MG1: + + MEGACO/1 [123.123.123.4]:55555 Transaction = 10001 { + Context = - { + Modify = A4444 { + Events = 2223 { + al/on(strict=state), dd/ce {DigitMap=Dialplan0} + }, + Signals {cg/dt}, + DigitMap= Dialplan0{ (0| 00|[1- + 7]xxx|8xxxxxxx|Fxxxxxxx|Exx|91xxxxxxxxxx|9011x.)} + } + } } + + 9. And the Modify is acknowledged. + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 Reply = 10001 { + Context = - {Modify = A4444} } + + 10. 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. + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 Transaction = 10002 { + Context = - { + Notify = A4444 {ObservedEvents =2223 { + 19990729T22010001:dd/ce{ds="916135551212",Meth=UM}}} + } } + + 11. And the Notify is acknowledged. + + MGC to MG1: + + MEGACO/1 [123.123.123.4]:55555 Reply = 10002 { + Context = - {Notify = A4444} } + + + 12. The controller then analyses the digits and determines that a + connection needs to be made from MG1 to MG2. Both the TDM + + + +Groves, et al. Standards Track [Page 187] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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. + + 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. + + 13. 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. + + MG1 -> MGC: + + MEGACO/1 [124.124.124.222]:55555 Reply = 10003 { + Context = 2000 { + Add = A4444, + Add=A4445{ + Media { + Stream = 1 { + Local { v=0 o=- 2890844526 2890842807 IN IP4 + 124.124.124.222 s=- t= 0 0 c=IN IP4 124.124.124.222 m=audio 2222 + RTP/AVP 4 a=ptime:30 a=recvonly + } ; RTP profile for G.723.1 is 4 + } + + + +Groves, et al. Standards Track [Page 188] + +RFC 3525 Gateway Control Protocol June 2003 + + + } + } + } } + + 14. 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. + + 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(strict=state)}, + 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.1 is 4 + } + } + } + } } + + 15. 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 [125.125.125.111]:55555 Reply = 50003 { + Context = 5000 { + Add = A5555, + Add = A5556{ + Media { + Stream = 1 { + + + +Groves, et al. Standards Track [Page 189] + +RFC 3525 Gateway Control Protocol June 2003 + + + Local { v=0 o=- 7736844526 7736842807 IN IP4 + 125.125.125.111 s=- t= 0 0 c=IN IP4 125.125.125.111 m=audio 1111 + RTP/AVP 4 } + } ; RTP profile for G723.1 is 4 + } + } + + } } + + 16. 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 o=- 7736844526 7736842807 IN IP4 + 125.125.125.111 s=- t= 0 0 c=IN IP4 125.125.125.111 m=audio 1111 + RTP/AVP 4 + } + } ; RTP profile for G723.1 is 4 + } + } + } } + + + MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 Reply = 10005 { + Context = 2000 {Modify = A4444, Modify = A4445} } + + 17. 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. + + + + + + + + + + + + +Groves, et al. Standards Track [Page 190] + +RFC 3525 Gateway Control Protocol June 2003 + + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 Transaction = 50005 { + Context = 5000 { + + Notify = A5555 {ObservedEvents =1234 { + 19990729T22020002:al/of(init=false)}} + } } + + 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(strict=state)}, + Signals { } ; to turn off ringing + } + } } + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 Reply = 50006 { + Context = 5000 {Modify = A4445} } + + 18. Change mode on MG1 to SendReceive, and stop the ringback. + + 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 { } + } + + + +Groves, et al. Standards Track [Page 191] + +RFC 3525 Gateway Control Protocol June 2003 + + + } } + + from MG1 to MGC: + + MEGACO/1 [124.124.124.222]:55555 Reply = 10006 { + Context = 2000 {Modify = A4445, Modify = A4444}} + + 19. The MGC decides to Audit the RTP termination on MG2. + + MGC -> MG2: + + MEGACO/1 [123.123.123.4]:55555 Transaction = 50007 { + Context = - {AuditValue = A5556{ + Audit{Media, DigitMap, Events, Signals, Packages, Statistics }} + } } + + 20. The MG2 replies. + + MG2 -> MGC: + + 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 o=- 7736844526 7736842807 IN IP4 + 125.125.125.111 s=- t= 0 0 c=IN IP4 125.125.125.111 m=audio 1111 + RTP/AVP 4 a=ptime:30 + }, + Remote { v=0 o=- 2890844526 2890842807 IN IP4 + 124.124.124.222 s=- t= 0 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 + } + + + +Groves, et al. Standards Track [Page 192] + +RFC 3525 Gateway Control Protocol June 2003 + + + } } + + 21. 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. + + From MG2 to MGC: + + MEGACO/1 [125.125.125.111]:55555 Transaction = 50008 { + Context = 5000 { + Notify = A5555 {ObservedEvents =1235 { + 19990729T24020002:al/on(init=false)} + } + } } + + From MGC to MG2: + + MEGACO/1 [123.123.123.4]:55555 Reply = 50008 { + + Context = - {Notify = A5555} } + + 22. 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. + + 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 + + + +Groves, et al. Standards Track [Page 193] + +RFC 3525 Gateway Control Protocol June 2003 + + + 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 + } + } + } } + + 23. 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 194] + +RFC 3525 Gateway Control Protocol June 2003 + + +APPENDIX II Changes From RFC 3015 + + In the following table, "source" indicates when the change was first + approved. It has the following values: + + IG1100: H.248 Implementor's Guide approved in November, 2000 (as TD + Plen-39, Christian Groves, editor). + + IG0601: H.248 Implementor's Guide approved in June, 2001 (as TD + Plen-15, Christian Groves, editor). + + IGDUB: Draft H.248 Implementor's Guide approved at the Q.3 + Rapporteur's meeting held near Dublin, October 2001 (as TD-28, Terry + Anderson, editor). + + GEN0202: added at the Geneva meeting, February 2002, which consented + to H.248 v1 Amendment 1 (as TD Plen-36r1, Marcello Pantaleo, editor). + + ITUPOST: added in post-Geneva editing by the ITU-T. + + TTPOST: added in post-approval editing by the Megaco Chair, Tom + Taylor, who assembled this document for submission. + + Section Source Change + + 1 ITUPOST Reference changed from H.248 to H.248.1. + + 2.1 ITUPOST Reference added for error codes, changed from + H.248 Annex L to H.248.8 (2002). + + 2.1 IG1100 Corrected Q.765 reference to Q.765.5. + + 2.1 GEN0202 Added reference to X.690. + + 2.2 GEN0202 Added reference to H.226. + + 2.2 IGDUB Added informative references to Q.724, Q.764, + and Q.1902.4. + + 4 IG0601 Added expansion of ALF. + + 5 TTPOST Gave priority to IETF conventions (added at + start of document). + + + + + + + + +Groves, et al. Standards Track [Page 195] + +RFC 3525 Gateway Control Protocol June 2003 + + + 6.1.1 IG0601 Added text regarding use of wildcards for + context identifiers. (This information + already appeared in section 8.1.2. The IG + change subsequently disappeared.) + + 6.1.1 IG1100 Added ranking of priority values. + + 6.2 IGDUB Deleted definition of signals. + + 6.2 GEN0202 Expanded text and diagrams describing + multiplexing terminations. + + 6.2 TTPOST Added asterisks to multiplexing diagrams to + indicate centre of context. Added Figure 6a + showing cascading of multiplexes. + + 6.2.2 IG0601 Added text indicating that ALL does not + include ROOT. + + 6.2.3 IG1100 Added text clarifying what must be supported + to claim support of a package. + + 6.2.3 IG1100 Added text indicating what packages a peer can + indicate support for, when some of them are + extensions of others. + + 6.2.4 IG0601 Added text on ability of provisioning to + override default values, and need for MGC to + audit to learn the provisioned defaults. + + 6.2.4 IG0601 Added text indicating effect of omitting + specific properties from Descriptors in + commands modifying a termination. + Contradicted original text saying that omitted + properties retain their prior values (still + true for entirely-omitted Descriptors). + + 6.2.4 GEN0202 Modified above text to restrict it to + read/write properties, allow for default + behaviour in place of default values if so + specified in the property definition. + + 6.2.4 IGDUB Trimmed definition of signals Descriptor in + table and inserted cross-reference to section + 7.1.11. + + 6.2.4 IG1100 Added Topology and Error Descriptors to table. + + + + +Groves, et al. Standards Track [Page 196] + +RFC 3525 Gateway Control Protocol June 2003 + + + 6.2.5 IGDUB Specified error code to return if ROOT used + inappropriately. + + 7.1.1 IG1100 Added qualification to explanation of effect + of missing Audit Descriptor, excepting + Subtract. + + 7.1.3 GEN0202 Changed "inputs" to "bearers" to be consistent + with terminology in 6.2. + + 7.1.4 IG0601 Small change to make clear that more than one + of Local, Remote, and LocalControl can be + included in the default streamId. + + 7.1.7 IG0601 Default value for Mode specified to be + Inactive. + + 7.1.7 GEN0202 Added text requiring processing of media in + any of the reserved formats, where more than + one has been reserved in a given stream. + + 7.1.8 IGDUB Added restriction to at most one m= line per + session description. + + 7.1.9 IG0601 Text added to omit request identifier if the + EventsDescriptor is empty. Further text added + at end to indicate the effects of an empty + EventsDescriptor and an empty + EventBufferDescriptor. + + 7.1.9 IG0601 Fixed typo for destination of a Notify. + + 7.1.9 IG1100 Added note to say event remains active after + it has been notified, so long as it is still + present in the active Events Descriptor. + + 7.1.11 IGDUB Added definition of signals. + + 7.1.11 GEN0202 Modified definition to include example of more + complex signal, and added role of signal in + media preparation for future signals. + + 7.1.11 IGDUB The timeout completion reason was broadened to + include other circumstances where the signal + completed on its own. Text added to indicate + that if default signal type changed to TO, + duration parameter must be provided. + + + + +Groves, et al. Standards Track [Page 197] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7.1.11 GEN0202 Removed reference to BR signal being "so + short" it will stop on its own. Added text + indicating that if the type of a signal is + changed to TO, the Duration parameter must be + supplied. + + 7.1.11 IG1100 Deleted text discussing type of Signals List. + + 7.1.12 GEN0202 Improved wording of introductory paragraph and + added text making content of returned + Descriptor clear. + + 7.1.14.2 GEN0202 Added text indicating that when the start + timer is set to 0, initial digit timing is + disabled and the MG waits indefinitely for + digits. + + 7.1.14.2 GEN0202 Added text pointing out that default digit + timer values should be provisioned, but can be + overridden in the digit map. + + 7.1.14.3 GEN0202 Changed result of long-short digit timer + conflict from undefined to long. + + 7.1.14.6 IG1100 Clarified that the digit map is provided by + the eventDM parameter, which must be present. + + 7.1.14.7 GEN0202 Added text clarifying that events covered by + the digit map completion event have no side- + effects unless separately enabled. + + 7.1.14.8 IG0601 Added requirement that the event specification + include the eventDM parameter. + + 7.1.17 IGDUB Added text to indicate timestamp is optional + and to include observed event parameters in + reported content. + + 7.1.17 GEN0202 Deleted provision that time is expressed in + UTC (since intention was to use format, not + time zone). + + 7.1.18 IGDUB Added text indicating error to return if + topology option not supported. + + + + + + + +Groves, et al. Standards Track [Page 198] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7.1.18 IG1100 Added text clarifying effect of not mentioning + TTPOST a termination in a topology Descriptor, and + default topology for a new termination. (This + text got lost between the Dublin meeting and + the production of H.248 Amendment 1 out of the + Geneva 02/02 meeting. It has been added back + to the present document.) + + 7.1.19 IG1100 New section to describe Error Descriptor. + GEN0202 Slightly edited in Geneva 02/02 meeting. + ITUPOST Reference for error code documentation updated + to H.248.8. + + 7.1.19 IG0601 Added paragraph giving guidance on level at + which errors should be reported. + + 7.2 IG1100 Noted possibility of Error Descriptor in reply + to any command. + + 7.2.1 IG1100 Added EventBufferDescriptor as Add parameter. + + 7.2.1 IG1100 Removed restriction on use of CHOOSE wildcard. + + 7.2.2 IG1100 Added EventBufferDescriptor as Modify + parameter. + + 7.2.2 GEN0202 Added text on side-effects of Modify of a + multiplexing termination. + + 7.2.3 IG1100 Added prohibition against subtracting from the + NULL context. + + 7.2.3 GEN0202 Added text on side-effects of Subtract of a + multiplexing termination. + + 7.2.3 IGDUB Added text clarifying effect of empty + AuditDescriptor in Subtract. + + 7.2.4 IG1100 Added EventBufferDescriptor as Move parameter. + + 7.2.4 GEN0202 Removed misleading statement that Move acts as + subtract from original context. + + 7.2.4 IG1100 Clarified effect of Move on properties of the + moved termination. + + 7.2.4 GEN0202 Added text on side-effects of Move of a + multiplexing termination. + + + +Groves, et al. Standards Track [Page 199] + +RFC 3525 Gateway Control Protocol June 2003 + + + 7.2.5 IG1100 Added examples showing W- wildcard usage. + + 7.2.5 IG1100 Noted that returning a list of all contextIDs + requires that they be returned one per + ActionReply. + + 7.2.5 IG1100 Added table entry (ALL, specific) to determine + context in which termination currently + resides. + + 7.2.6 GEN0202 Added table similar to that in 7.2.5. + + 7.2.7 IG0601 Added TerminationID to API. + + 7.2.7 IGDUB Indicated timestamp was optional in Notify, to + accord with syntax. + + 7.2.7 IG1100 Noted possibility of sending Error Descriptor + in Notify. + + 7.2.8 IG0601 Added text to description of Forced method to + indicate that Forced on ROOT indicates a cold + restart (all context state lost). + + 7.2.8 IGDUB Amplified explanation of Disconnected method + to emphasize return to the previously + controlling MGC. + + 7.2.8 IG0601 Added text for MG use of Failover method when + it detects MGC failure. + + 7.2.8 IG1100 Added notes discouraging use of + ServiceChangeAddress and warning that it could + be either a full address or just a port + number. + + 7.2.8 IG0601 Added text indicating that timestamp does not + necessarily represent absolute time, only + local clock reading. + + 7.2.8 IGDUB Corrected "gateway" to "MGC" in discussion of + returned ServiceChangeMgcId parameter. + + 7.3 IG0601 Removed error code documentation to Annex L + ITUPOST (now H.248.8). + + 8 IG1100 Added requirement that an Action be non-empty. + + + + +Groves, et al. Standards Track [Page 200] + +RFC 3525 Gateway Control Protocol June 2003 + + + 8 GEN0202 Added context properties and context property + audit requests to commands as potential + contents of actions. + + 8.1.2 GEN0202 Added prohibition on using partial contextIDs + with ALL wildcards. + + 8.2.2 IG1100 Added text clarifying when in transaction + processing the requested actions have been + completed and a reply can be sent. + + 8.2.2 IG1100 Added ALL as allowed contextID in + TransactionReply. + + 8.2.2 GEN0202 Provided general reference to section 7.1.19 + for generation of error Descriptors. + + 8.2.2 IG0601 Corrected Actions to Commands when discussing + partially-understood action. + + 8.3 IG0601 Added text specifying that the same MId value + must be used by a given entity throughout the + life of a control association. + + 8.3 IG0601 Added text expanding on independence of + transactions from messages. + + 9 ITUPOST Indicated that additional transports may be + defined in separate Recommendations as well as + annexes to the primary specification. + + 9 IG0601 Gave specific example of "request source + address" for IP. + + 9.1 IG1100 Deleted restriction to one outstanding Notify + command on a termination at one time, since + this is transport-specific. + + 9.1 IG0601 Restored restriction, but noted that it + applied only to transport not guaranteeing + ordered delivery. + + 10.2 IG1100 Corrected length of synthesized address field + from 10 to 20 hex digits and indicated that + calculation should be over entire message, not + just one transaction. + + + + + +Groves, et al. Standards Track [Page 201] + +RFC 3525 Gateway Control Protocol June 2003 + + + 11.2 IG1100 Corrected text in first two paragraphs + describing use of ServiceChangeMgcId + parameter. + + 11.2 IG1100 Corrected "Transaction Accept" to "Transaction + Reply". + + 11.4 IG0601 Noted that support of redundant MGs requires + GEN0202 use of a reliable transport and support in the + MGC. Added more explanation in Geneva. + + 11.5 IG0601 Added text clarifying procedure if MG unable + to establish a control relationship with any + of its eligible MGCs. + + 11.5 IGDUB Added text indicating that when trying to + reestablish contact with the previously + controlling MGC the MG uses the Disconnected + method. + + 11.5 IG1100 Clarified handoff procedure. + + 11.5 GEN0202 Changed text on replies to transactions in + progress during handoff. Replies now + discarded when the service relationship with + the old MGC has ended, rather than sent to the + new MGC. The new MGC could still send replies + to requests sent to the old MGC. + + 12.1.1 GEN0202 Added optional package designation as + "designed to be extended only". + + 12.1.1 IG1100 Made prohibition on overloading of identifiers + in extended packages transitive through all + ancestors of the extended package. + + 12.1.2 IGDUB Clarified the set of types allowed for + properties. + + 12.1.2 GEN0202 Added requirement to specify the base type of + a sub-list. + + 12.1.2 GEN0202 Provided requirements for content of the + "Possible Values" template item, including + specification of default values or behaviour. + + + + + + +Groves, et al. Standards Track [Page 202] + +RFC 3525 Gateway Control Protocol June 2003 + + + 12.1.4 GEN0202 Added requirement to specify the default + signal type, and specify a default duration + for TO signals. Also noted that duration is + meaningless for BR, and that the signal type + might be dependent on the values of other + signal parameters. + + 12.2 GEN0202 Fixed section title (covers only event and + signal parameters, not properties or + statistics). + + 12.2 IG1100 Reserved SPA and EPA prefixes, so they are not + to be used for signal and event parameter + tokens. + + 12.2 IG0601 Expanded list of reserved prefixes. + + 12.2 IGDUB Clarified the set of types allowed for signal + and event parameters. + + 12.2 GEN0202 Added requirement to specify the base type of + a sub-list. + + 12.2 GEN0202 Provided requirements for content of the + "Possible Values" template item, including + specification of default values or behaviour. + + 12.4 IGDUB Corrected to indicate identifiers must start + with alphabetic rather than alphanumeric + character. + + 13.1 IG0601 Changed private range of binary package + identifiers to convenient hex values. + + A GEN0202 Removed versions from X.680 and X.690 + references. + + A.2 IGDUB Added note warning that the syntax alone does + not provide a complete description of the + constraints, but must be supplemented by a + reading of the text and comments. + + A.2 IG0601 Added description of double wrapping of + parameters declared as OCTET STRING. + + + + + + + +Groves, et al. Standards Track [Page 203] + +RFC 3525 Gateway Control Protocol June 2003 + + + A.2 GEN0202 Some editing of double wrapping description to + use ASN.1, BER in their proper places. Added + possibility of encoding strings as UTF8String, + but only if they contain non-ASCII characters. + + A.2 IGDUB Added line in table on double wrapping of true + octet strings. + + A.2 IG1100 Corrected and expanded comments describing + mtpAddress form of MId. Fixed maximum length + of mtpAddress both here and in + ServiceChangeAddress. + + A.2 IG0601 Inserted missing lines in IP4Address + production. + + A.2 IG0601 Modified TransactionResponseAck to allow + acknowledgement of multiple ranges of + transactionIds. + + A.2 IG0601 Corrected numerical value of CHOOSE as a + context identifier. + + A.2 IGDUB Added missing extension marker in + TopologyRequest. + + A.2 IG1100 AuditReply and AuditResult modified to bring + binary functionality into line with text + functionality. + + A.2 IG0601 Removed OPTIONAL tag from terminationID in + NotifyReply. + + A.2 IG0601 Added extraInfo substructure to EventParameter + and SigParameter. + + A.2 IG0601 Modified MediaDescriptor to make it optional + to specify a stream. + + A.2 IG0601 Added OPTIONAL tags to reserveValue and + reserveGroup. + + A.2 IGDUB Added to comments for pkgdName to indicate + applicability to event names, signal names, + and statisticIds as well as property. + + + + + + +Groves, et al. Standards Track [Page 204] + +RFC 3525 Gateway Control Protocol June 2003 + + + A.2 IG0601 RequestID made optional in EventsDescriptor + and SecondEventsDescriptor and comment added + saying it must be present if events are + present. + + A.2 IG1100 Added OPTIONAL tags on RequestActions and + SecondRequestedActions keepActive BOOLEANs. + + A.2 IG1100 Added comment to indicate requestID value to + use in an AuditCapReply. + + A.2 GEN0202 Added comment to DigitMapValue indicating time + units for timers. + + A.2 IG0601 Added comment indicating coding of Value for + GEN0202 ServiceChangeReason. Cleaned up in Geneva to + use ASN.1 and BER in their proper places. + + A.2 IG0601 Inserted missing extension marker in + ServiceChangeParm production. + + A.2 IG0601 Aligned definition of mtpAddress in + ServiceChangeAddress with that in MId. + + A.2 IG0601 Added timestamp to ServiceChangeResParm. + + A.2 IGDUB Changed type of profileName in + ServiceChangeProfile to IA5String. + + A.2 IG0601 Made returned value optional in + statisticsParameter, to support + auditCapability result. + + A.2 GEN0202 Added reference to ISO 8601:1988 for + TimeNotation. + + A.2 IG1100 Value production modified to support the + sublist parameter type. + + A.3 IG1100 Corrected ABNF for digitStringlisT, replacing + "/" with "|". + + A.3 IG1100 Added parentheses to digitMapRange production. + + A.3 IG1100 Replaced more abbreviated syntax for pathName + with fuller definition and constraints copied + from B.2. + + + + +Groves, et al. Standards Track [Page 205] + +RFC 3525 Gateway Control Protocol June 2003 + + + B.2 IGDUB Added note warning that the syntax alone does + not provide a complete description of the + constraints, but must be supplemented by a + reading of the text and comments. + + B.2 IG0601 Added note warning that the interpretation of + symbols is context-dependent. + + B.2 IG1100 Added comment to indicate case insensitivity + of protocol (excepting SDP) and ABNF. + + B.2 IG0601 Expanded upon and capitalized this comment. + + B.2 IG0601 Lengthy note added on the coding of the VALUE + construct. + + B.2 IGDUB Deleted sentence in note suggesting that + packages could add new types for properties, + parameters, or statistics. + + B.2 IG0601 Added note indicating that parsers should + allow for white space preceding the first line + of SDP in Local or Remote. + + B.2 IGDUB Added comments identifying the O- and W- tags. + + B.2 IG1100 Moved wildcard tag up from individual commands + to commandRequestList. + + B.2 GEN0202 Added additional error case to actionReply. + + B.2 IG0601 Modified syntax of auditOther to allow return + of terminationID only. + + B.2 IGDUB Corrected upper limit for V4hex. + + B.2 IG1100 Corrected and expanded comments describing + mtpAddress form of MId. + + B.2 IG0601 Modified comment to mediaParm to make + streamParms and StreamDescriptor mutually + exclusive. + + B.2 GEN0202 Modified comment further to indicate at most + one instance of terminationStateDescriptor. + + B.2 GEN0202 Expanded comment for streamParm to indicate + the restriction on repetition is per item. + + + +Groves, et al. Standards Track [Page 206] + +RFC 3525 Gateway Control Protocol June 2003 + + + B.2 IG0601 Modified "at most once" comments to localParm, + terminationStateParm, and modemType, to allow + multiple instances of propertyParm in the + first two cases and extensionParameter in the + last one. + + B.2 IG0601 Added note before description of Local and + Remote, pointing out that the octet value x00 + is not allowed in octetString. + + B.2 IG0601 Syntax for eventsDescriptor, embedFirst, and + eventBufferDescriptor modified to make + contents beyond token optional. + + B.2 IGDUB Replaced "event" by "item" in comment to + pkgdName because pkgdName applies to + properties, signals, and statistics as well. + + B.2 IG0601 Corrected placement of EQUAL in eventDM + production. + + B.2 IG1100 Added comment and syntax to indicate requestID + value to use in an AuditCapReply. + + B.2 IG1100 Corrected Modem Descriptor to allow package + items as properties. + + B.2 IG0601 Comment to modemType changed to allow multiple + instances of extensionParameter. + + B.2 GEN0202 Comment added to indicate units for Timer. + + B.2 IG1100 Added parentheses to digitMapRange production. + + B.2 IG1100 Added comment to serviceChangeParm, + restricting each parameter to one appearance. + + B.2 IG0601 Added comments making serviceChangeMgcId and + serviceChangeAddress mutually exclusive in + ServiceChangeParm and servChgReplyParm. + + B.2 IGDUB Added comment to serviceChangeParm indicating + that ServiceChangeMethod and + ServiceChangeReason are required. + + B.2 IG0601 Added Timestamp to servChgReplyParm. + + + + + +Groves, et al. Standards Track [Page 207] + +RFC 3525 Gateway Control Protocol June 2003 + + + B.2 IG0601 Added comment indicating coding of Value for + ServiceChangeReason. + + B.2 IG0601 Modified ServiceChangeAddress to use MId + definition for full address. + + B.2 IG1100 Made returned value optional in + statisticsParameter, to support + auditCapability result. + + B.2 IG1100 Changed topologyDescriptor to allow multiple + triples. + + B.2 IG0601 Added comment forbidding use of a double quote + within a quotedString value. + + B.2 IG1100 Reserved prefixes for new tokens added to + signalParameter and eventParameter, to avoid + collision with package names. + + B.2 IG1100 EmbedToken and EmergencyToken changed to + remove clash with EventBufferToken. + + B.3 IG1100 New section describing hexadecimal octet + encoding. + + B.4 IG1100 New section describing hex octet sequence. + + C IG1100 Added permission to use Annex C properties in + LocalControl as well as in Local and Remote. + + C IG0601 Added text making support of all properties of + Annex C optional. + + C IGDUB Added directions to reconcile tabulated + formats with allowed types for properties. + + C.1 IG1100 Corrected Q.765 reference to Q.765.5 for + ACodec. + + C.1 IG1100 Deprecated Echocanc codepoint in favour of + package-defined property. + + C.4 ITUPOST Updated references from Q.2961 to Q.2961.1. + + C.4 IGDUB Added details on format of VPVC. + + C.9 IG1100 Renamed USI to layer1prot. + + + +Groves, et al. Standards Track [Page 208] + +RFC 3525 Gateway Control Protocol June 2003 + + + C.9 IG1100 Deprecated ECHOCI codepoint in favour of + package-defined property. + + C.9 IG1100 Added new USI property. + + C.11 IG1100 Added m= line tag. + + D.1 IG0601 Added explanation of ALF. + + D.1.5 IGDUB Expanded text indicating that when trying to + reestablish contact with the previously + controlling MGC the MG uses the Disconnected + method. + + E.1.2 GEN0202 Added missing EventsDescriptor parameters + lines. + + E.1.2 GEN0202 For the Signal Completion event: + - corrected the description of how it is + enabled + - heavily edited the description of the Signal + Identity observed event parameter and added a + type. + + E.1.2 IGDUB The timeout completion reason for the Signal + Completion event was broadened to include + other circumstances where the signal completed + on its own. + + E.1.2 IG1100 Added signal list ID observed event parameter + to the Signal Completion event. + + E.2.1 IG0601 Added missing read only, read-write + specifications. + + E.2.1 IG0601 Split ProvisionalResponseTimer properties into + one for MG, one for MGC. + + E.3 GEN0202 Added "Designed to be extended only" to + tonegen package description. + + E.4 GEN0202 Added "Designed to be extended only" to + tonedet package description. + + E.4.2 GEN0202 Added type for tone ID observed parameter for + Long Tone Detected event. + + + + + +Groves, et al. Standards Track [Page 209] + +RFC 3525 Gateway Control Protocol June 2003 + + + E.6.2 IG1100 Corrected binary identifier for digit map + completion event to avoid clash with base + package. + + E.6.2 IG1100 Removed procedural text. + + E.6.5 IG1100 Added procedural text indicating where to find + the applicable digit map and indicating the + error to return if the parameter is missing. + + E.6.5 IG0601 Further modified procedural text. + + E.7.3 IG1100 Corrected text identifier for payphone + recognition tone to avoid clash with base + package. + + E.10.5 IGDUB Provided informative references for tones and + procedures for continuity check. + + E.13 GEN0202 Added note that TDM package could also apply + to other transports. + + E.13.1 IG1100 Changed default for echo cancellation from + "on" to provisioned. + + E.13.1 IG0601 Corrected type for gain property. + + Appendix TTPOST Included a number of corrections which were + I not picked up in H.248.1 Amendment 1 but which + do appear in H.248.1 v2. + +Intellectual Property Rights + + The ITU draws attention to the possibility that the practice or + implementation of this RFC may involve the use of a claimed + Intellectual Property Right. The ITU takes no position concerning + the evidence, validity or applicability of claimed Intellectual + Property Rights, whether asserted by ITU members or others outside of + the Recommendation development process. + + As of the date of approval of this RFC, the ITU had received notice + of intellectual property, protected by patents, which may be required + to implement this RFC. However, implementors are cautioned that this + may not represent the latest information and are therefore strongly + urged to consult the TSB patent database. + + + + + + +Groves, et al. Standards Track [Page 210] + +RFC 3525 Gateway Control Protocol June 2003 + + + The IETF has also received notice of intellectual property claims + relating to Megaco/H.248.1. Please consult the IETF IPR + announcements at http://www.ietf.org/ipr.html. + +Acknowledgments + + Megaco/H.248.1 is the result of hard work by many people in both the + IETF and in ITU-T Study Group 16. This section records those who + played a prominent role in ITU-T meetings, on the Megaco list, or + both. + + Megaco/H.248 owes a large initial debt to the MGCP protocol (RFC + 2705), and thus to its authors, Mauricio Arango, Andrew Dugan, Ike + Elliott, Christian Huitema, and Scott Pickett. Flemming Andreasen + does not appear on this list of authors, but was a major contributor + to the development of both MGCP and Megaco/H.248.1. RFC 3435 has an + extensive acknowledgement of many other people who worked on media + gateway control before Megaco got started. + + The authors of the first Megaco RFCs (2805, then 3015) were Fernando + Cuervo, Nancy Greene, Abdallah Rayhan, Christian Huitema, Brian + Rosen, and John Segers. Christian Groves conceived and was editor of + Annex C. The people most active on the Megaco list in the period + leading up to the completion of RFC 2885 were Brian Rosen, Tom + Taylor, Nancy Greene, Christian Huitema, Matt Holdrege, Chip Sharp, + John Segers, Michael Thomas, Henry Sinnreich, and Paul Sijben. The + people who sacrificed sleep and meals to complete the massive amount + of work required in the decisive Study Group 16 meeting of February, + 2000, were Michael Brown, Ranga Dendi, Larry Forni, Glen Freundlich, + Christian Groves, Alf Heidemark, Steve Magnell, Selvam Rengasami, + Rich Rubin, Klaus Sambor, John Segers, Chip Sharp, Tom Taylor, and + Stephen Terrill. + + The most active people on the Megaco list in the period since the + February 2000 have been Tom Taylor, Brian Rosen, Christian Groves, + Madhu Babu Brahmanapally, Troy Cauble, Terry Anderson, Chuong Nguyen, + and Kevin Boyle, but many other people have been regular + contributors. Brian Rosen did tremendous service in putting together + the Megaco interoperability tests. On the Study Group 16 side, the + editorial team for the final revised document in February, 2002 + included Christian Groves, Marcello Pantaleo, Terry Anderson, Peter + Leis, Kevin Boyle, and Tom Taylor. + + Tom Taylor as Megaco Chair managed the day to day operation of the + Megaco list, with Brian Rosen taking an equal share of the burden for + most of the last three years. Glen Freundlich as the Study Group 16 + Rapporteur ran the ITU-T meetings and ensured that all of the work at + hand was completed. Without Glen's determination the Megaco/H.248 + + + +Groves, et al. Standards Track [Page 211] + +RFC 3525 Gateway Control Protocol June 2003 + + + standard would have taken at least half a year longer to produce. + Christian Groves filled in ably as Rapporteur when Glen could no + longer take part. + +Authors' Addresses + + Terry L. Anderson + 24 Hill St + Bernardsville, NJ 07924 + USA + + EMail: tlatla@verizon.net + + + Christian Groves + Ericsson AsiaPacificLab Australia + 37/360 Elizabeth St + Melbourne, Victoria 3000 + Australia + + EMail: Christian.Groves@ericsson.com.au + + + Marcello Pantaleo + Ericsson Eurolab Deuschland + Ericsson Allee 1 + 52134 Herzogenrath, Germany + + EMail: Marcello.Pantaleo@eed.ericsson.se + + + Tom Taylor + Nortel Networks + 1852 Lorraine Ave, + Ottawa, Ontario + Canada K1H 6Z8 + + Phone: +1 613 736 0961 + EMail: taylor@nortelnetworks.com + + + + + + + + + + + + +Groves, et al. Standards Track [Page 212] + +RFC 3525 Gateway Control Protocol June 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). 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. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Groves, et al. Standards Track [Page 213] + diff --git a/lib/megaco/doc/standard/rfc4234.txt b/lib/megaco/doc/standard/rfc4234.txt new file mode 100644 index 0000000000..74d4c44f43 --- /dev/null +++ b/lib/megaco/doc/standard/rfc4234.txt @@ -0,0 +1,899 @@ + + + + + + +Network Working Group D. Crocker, Ed. +Request for Comments: 4234 Brandenburg InternetWorking +Obsoletes: 2234 P. Overell +Category: Standards Track THUS plc. + October 2005 + + + Augmented BNF for Syntax Specifications: ABNF + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + Internet technical specifications often need to define a formal + syntax. Over the years, a modified version of Backus-Naur Form + (BNF), called Augmented BNF (ABNF), has been popular among many + Internet specifications. The current specification documents ABNF. + It balances compactness and simplicity, with reasonable + representational power. The differences between standard BNF and + ABNF involve naming rules, repetition, alternatives, order- + independence, and value ranges. This specification also supplies + additional rule definitions and encoding for a core lexical analyzer + of the type common to several Internet specifications. + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 1] + +RFC 4234 ABNF October 2005 + + +Table of Contents + + 1. INTRODUCTION ....................................................2 + 2. RULE DEFINITION .................................................3 + 2.1. Rule Naming ................................................3 + 2.2. Rule Form ..................................................3 + 2.3. Terminal Values ............................................4 + 2.4. External Encodings .........................................5 + 3. OPERATORS .......................................................6 + 3.1. Concatenation: Rule1 Rule2 ................................6 + 3.2. Alternatives: Rule1 / Rule2 ...............................6 + 3.3. Incremental Alternatives: Rule1 =/ Rule2 ...................7 + 3.4. Value Range Alternatives: %c##-## .........................7 + 3.5. Sequence Group: (Rule1 Rule2) .............................8 + 3.6. Variable Repetition: *Rule ................................8 + 3.7. Specific Repetition: nRule ................................9 + 3.8. Optional Sequence: [RULE] .................................9 + 3.9. Comment: ; Comment ........................................9 + 3.10. Operator Precedence .......................................9 + 4. ABNF DEFINITION OF ABNF ........................................10 + 5. SECURITY CONSIDERATIONS ........................................11 + 6. References .....................................................11 + 6.1. Normative References ......................................11 + 6.2. Informative References ....................................11 + Appendix A. ACKNOWLEDGEMENTS .....................................13 + Appendix B. APPENDIX - CORE ABNF OF ABNF .........................13 + B.1. Core Rules ...............................................13 + B.2. Common Encoding ..........................................14 + +1. INTRODUCTION + + Internet technical specifications often need to define a formal + syntax and are free to employ whatever notation their authors deem + useful. Over the years, a modified version of Backus-Naur Form + (BNF), called Augmented BNF (ABNF), has been popular among many + Internet specifications. It balances compactness and simplicity, + with reasonable representational power. In the early days of the + Arpanet, each specification contained its own definition of ABNF. + This included the email specifications, [RFC733] and then [RFC822], + which came to be the common citations for defining ABNF. The current + document separates those definitions to permit selective reference. + Predictably, it also provides some modifications and enhancements. + + The differences between standard BNF and ABNF involve naming rules, + repetition, alternatives, order-independence, and value ranges. + Appendix B supplies rule definitions and encoding for a core lexical + analyzer of the type common to several Internet specifications. It + is provided as a convenience and is otherwise separate from the meta + + + +Crocker & Overell Standards Track [Page 2] + +RFC 4234 ABNF October 2005 + + + language defined in the body of this document, and separate from its + formal status. + + Changes since [RFC2234]: + + In Section 3.7, the phrase: "That is, exactly occurrences of + ." was corrected to: "That is, exactly occurrences of + ." + + Some continuation comment lines needed to be corrected to begin + with comment character (";"). + +2. RULE DEFINITION + +2.1. Rule Naming + + The name of a rule is simply the name itself; that is, a sequence of + characters, beginning with an alphabetic character, and followed by a + combination of alphabetics, digits, and hyphens (dashes). + + NOTE: + + Rule names are case-insensitive + + The names , , , and all + refer to the same rule. + + Unlike original BNF, angle brackets ("<", ">") are not required. + However, angle brackets may be used around a rule name whenever their + presence facilitates in discerning the use of a rule name. This is + typically restricted to rule name references in free-form prose, or + to distinguish partial rules that combine into a string not separated + by white space, such as shown in the discussion about repetition, + below. + +2.2. Rule Form + + A rule is defined by the following sequence: + + name = elements crlf + + where is the name of the rule, is one or more rule + names or terminal specifications, and is the end-of-line + indicator (carriage return followed by line feed). The equal sign + separates the name from the definition of the rule. The elements + form a sequence of one or more rule names and/or value definitions, + combined according to the various operators defined in this document, + such as alternative and repetition. + + + +Crocker & Overell Standards Track [Page 3] + +RFC 4234 ABNF October 2005 + + + For visual ease, rule definitions are left aligned. When a rule + requires multiple lines, the continuation lines are indented. The + left alignment and indentation are relative to the first lines of the + ABNF rules and need not match the left margin of the document. + +2.3. Terminal Values + + Rules resolve into a string of terminal values, sometimes called + characters. In ABNF, a character is merely a non-negative integer. + In certain contexts, a specific mapping (encoding) of values into a + character set (such as ASCII) will be specified. + + Terminals are specified by one or more numeric characters, with the + base interpretation of those characters indicated explicitly. The + following bases are currently defined: + + b = binary + + d = decimal + + x = hexadecimal + + Hence: + + CR = %d13 + + CR = %x0D + + respectively specify the decimal and hexadecimal representation of + [US-ASCII] for carriage return. + + A concatenated string of such values is specified compactly, using a + period (".") to indicate a separation of characters within that + value. Hence: + + CRLF = %d13.10 + + ABNF permits the specification of literal text strings directly, + enclosed in quotation-marks. Hence: + + command = "command string" + + Literal text strings are interpreted as a concatenated set of + printable characters. + + + + + + + +Crocker & Overell Standards Track [Page 4] + +RFC 4234 ABNF October 2005 + + + NOTE: + + ABNF strings are case-insensitive and the character set for these + strings is us-ascii. + + Hence: + + rulename = "abc" + + and: + + rulename = "aBc" + + will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and + "ABC". + + To specify a rule that IS case SENSITIVE, specify the characters + individually. + + For example: + + rulename = %d97 %d98 %d99 + + or + + rulename = %d97.98.99 + + will match only the string that comprises only the lowercased + characters, abc. + +2.4. External Encodings + + External representations of terminal value characters will vary + according to constraints in the storage or transmission environment. + Hence, the same ABNF-based grammar may have multiple external + encodings, such as one for a 7-bit US-ASCII environment, another for + a binary octet environment, and still a different one when 16-bit + Unicode is used. Encoding details are beyond the scope of ABNF, + although Appendix A (Core) provides definitions for a 7-bit US-ASCII + environment as has been common to much of the Internet. + + By separating external encoding from the syntax, it is intended that + alternate encoding environments can be used for the same syntax. + + + + + + + + +Crocker & Overell Standards Track [Page 5] + +RFC 4234 ABNF October 2005 + + +3. OPERATORS + +3.1. Concatenation: Rule1 Rule2 + + A rule can define a simple, ordered string of values (i.e., a + concatenation of contiguous characters) by listing a sequence of rule + names. For example: + + foo = %x61 ; a + + bar = %x62 ; b + + mumble = foo bar foo + + So that the rule matches the lowercase string "aba". + + LINEAR WHITE SPACE: Concatenation is at the core of the ABNF parsing + model. A string of contiguous characters (values) is parsed + according to the rules defined in ABNF. For Internet specifications, + there is some history of permitting linear white space (space and + horizontal tab) to be freely and implicitly interspersed around major + constructs, such as delimiting special characters or atomic strings. + + NOTE: + + This specification for ABNF does not provide for implicit + specification of linear white space. + + Any grammar that wishes to permit linear white space around + delimiters or string segments must specify it explicitly. It is + often useful to provide for such white space in "core" rules that are + then used variously among higher-level rules. The "core" rules might + be formed into a lexical analyzer or simply be part of the main + ruleset. + +3.2. Alternatives: Rule1 / Rule2 + + Elements separated by a forward slash ("/") are alternatives. + Therefore, + + foo / bar + + will accept or . + + + + + + + + +Crocker & Overell Standards Track [Page 6] + +RFC 4234 ABNF October 2005 + + + NOTE: + + A quoted string containing alphabetic characters is a special form + for specifying alternative characters and is interpreted as a + non-terminal representing the set of combinatorial strings with + the contained characters, in the specified order but with any + mixture of upper and lower case. + +3.3. Incremental Alternatives: Rule1 =/ Rule2 + + It is sometimes convenient to specify a list of alternatives in + fragments. That is, an initial rule may match one or more + alternatives, with later rule definitions adding to the set of + alternatives. This is particularly useful for otherwise, independent + specifications that derive from the same parent rule set, such as + often occurs with parameter lists. ABNF permits this incremental + definition through the construct: + + oldrule =/ additional-alternatives + + So that the rule set + + ruleset = alt1 / alt2 + + ruleset =/ alt3 + + ruleset =/ alt4 / alt5 + + is the same as specifying + + ruleset = alt1 / alt2 / alt3 / alt4 / alt5 + +3.4. Value Range Alternatives: %c##-## + + A range of alternative numeric values can be specified compactly, + using dash ("-") to indicate the range of alternative values. Hence: + + DIGIT = %x30-39 + + is equivalent to: + + DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" / + + "7" / "8" / "9" + + Concatenated numeric values and numeric value ranges cannot be + specified in the same string. A numeric value may use the dotted + notation for concatenation or it may use the dash notation to specify + + + +Crocker & Overell Standards Track [Page 7] + +RFC 4234 ABNF October 2005 + + + one value range. Hence, to specify one printable character between + end of line sequences, the specification could be: + + char-line = %x0D.0A %x20-7E %x0D.0A + +3.5. Sequence Group: (Rule1 Rule2) + + Elements enclosed in parentheses are treated as a single element, + whose contents are STRICTLY ORDERED. Thus, + + elem (foo / bar) blat + + matches (elem foo blat) or (elem bar blat), and + + elem foo / bar blat + + matches (elem foo) or (bar blat). + + NOTE: + + It is strongly advised that grouping notation be used, rather than + relying on the proper reading of "bare" alternations, when + alternatives consist of multiple rule names or literals. + + Hence, it is recommended that the following form be used: + + (elem foo) / (bar blat) + + It will avoid misinterpretation by casual readers. + + The sequence group notation is also used within free text to set off + an element sequence from the prose. + +3.6. Variable Repetition: *Rule + + The operator "*" preceding an element indicates repetition. The full + form is: + + *element + + where and are optional decimal values, indicating at least + and at most occurrences of the element. + + Default values are 0 and infinity so that * allows any + number, including zero; 1* requires at least one; + 3*3 allows exactly 3 and 1*2 allows one or two. + + + + + +Crocker & Overell Standards Track [Page 8] + +RFC 4234 ABNF October 2005 + + +3.7. Specific Repetition: nRule + + A rule of the form: + + element + + is equivalent to + + *element + + That is, exactly occurrences of . Thus, 2DIGIT is a 2- + digit number, and 3ALPHA is a string of three alphabetic characters. + +3.8. Optional Sequence: [RULE] + + Square brackets enclose an optional element sequence: + + [foo bar] + + is equivalent to + + *1(foo bar). + +3.9. Comment: ; Comment + + A semi-colon starts a comment that continues to the end of line. + This is a simple way of including useful notes in parallel with the + specifications. + +3.10. Operator Precedence + + The various mechanisms described above have the following precedence, + from highest (binding tightest) at the top, to lowest (loosest) at + the bottom: + + Strings, Names formation + + Comment + + Value range + + Repetition + + Grouping, Optional + + Concatenation + + Alternative + + + +Crocker & Overell Standards Track [Page 9] + +RFC 4234 ABNF October 2005 + + + Use of the alternative operator, freely mixed with concatenations, + can be confusing. + + Again, it is recommended that the grouping operator be used to + make explicit concatenation groups. + +4. ABNF DEFINITION OF ABNF + + NOTES: + + 1. This syntax requires a formatting of rules that is relatively + strict. Hence, the version of a ruleset included in a + specification might need preprocessing to ensure that it can be + interpreted by an ABNF parser. + + 2. This syntax uses the rules provided in Appendix B (Core). + + rulelist = 1*( rule / (*c-wsp c-nl) ) + + rule = rulename defined-as elements c-nl + ; continues if next line starts + ; with white space + + rulename = ALPHA *(ALPHA / DIGIT / "-") + + defined-as = *c-wsp ("=" / "=/") *c-wsp + ; basic rules definition and + ; incremental alternatives + + elements = alternation *c-wsp + + c-wsp = WSP / (c-nl WSP) + + c-nl = comment / CRLF + ; comment or newline + + comment = ";" *(WSP / VCHAR) CRLF + + alternation = concatenation + *(*c-wsp "/" *c-wsp concatenation) + + concatenation = repetition *(1*c-wsp repetition) + + repetition = [repeat] element + + repeat = 1*DIGIT / (*DIGIT "*" *DIGIT) + + + + + +Crocker & Overell Standards Track [Page 10] + +RFC 4234 ABNF October 2005 + + + element = rulename / group / option / + char-val / num-val / prose-val + + group = "(" *c-wsp alternation *c-wsp ")" + + option = "[" *c-wsp alternation *c-wsp "]" + + char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE + ; quoted string of SP and VCHAR + ; without DQUOTE + + num-val = "%" (bin-val / dec-val / hex-val) + + bin-val = "b" 1*BIT + [ 1*("." 1*BIT) / ("-" 1*BIT) ] + ; series of concatenated bit values + ; or single ONEOF range + + dec-val = "d" 1*DIGIT + [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ] + + hex-val = "x" 1*HEXDIG + [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ] + + prose-val = "<" *(%x20-3D / %x3F-7E) ">" + ; bracketed string of SP and VCHAR + ; without angles + ; prose description, to be used as + ; last resort + +5. SECURITY CONSIDERATIONS + + Security is truly believed to be irrelevant to this document. + +6. References + +6.1. Normative References + + [US-ASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + +6.2. Informative References + + [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + + + + +Crocker & Overell Standards Track [Page 11] + +RFC 4234 ABNF October 2005 + + + [RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson, + "Standard for the format of ARPA network text messages", + RFC 733, November 1977. + + [RFC822] Crocker, D., "Standard for the format of ARPA Internet + text messages", STD 11, RFC 822, August 1982. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 12] + +RFC 4234 ABNF October 2005 + + +Appendix A. ACKNOWLEDGEMENTS + + The syntax for ABNF was originally specified in RFC 733. Ken L. + Harrenstien, of SRI International, was responsible for re-coding the + BNF into an augmented BNF that makes the representation smaller and + easier to understand. + + This recent project began as a simple effort to cull out the portion + of RFC 822 that has been repeatedly cited by non-email specification + writers, namely the description of augmented BNF. Rather than simply + and blindly converting the existing text into a separate document, + the working group chose to give careful consideration to the + deficiencies, as well as benefits, of the existing specification and + related specifications made available over the last 15 years, and + therefore to pursue enhancement. This turned the project into + something rather more ambitious than was first intended. + Interestingly, the result is not massively different from that + original, although decisions, such as removing the list notation, + came as a surprise. + + This "separated" version of the specification was part of the DRUMS + working group, with significant contributions from Jerome Abela, + Harald Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom + Harsch, Dan Kohn, Bill McQuillan, Keith Moore, Chris Newman, Pete + Resnick, and Henning Schulzrinne. + + Julian Reschke warrants a special thanks for converting the Draft + Standard version to XML source form. + +Appendix B. APPENDIX - CORE ABNF OF ABNF + + This Appendix is provided as a convenient core for specific grammars. + The definitions may be used as a core set of rules. + +B.1. Core Rules + + Certain basic rules are in uppercase, such as SP, HTAB, CRLF, DIGIT, + ALPHA, etc. + + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + + BIT = "0" / "1" + + CHAR = %x01-7F + ; any 7-bit US-ASCII character, + ; excluding NUL + + + + + +Crocker & Overell Standards Track [Page 13] + +RFC 4234 ABNF October 2005 + + + CR = %x0D + ; carriage return + + CRLF = CR LF + ; Internet standard newline + + CTL = %x00-1F / %x7F + ; controls + + DIGIT = %x30-39 + ; 0-9 + + DQUOTE = %x22 + ; " (Double Quote) + + HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" + + HTAB = %x09 + ; horizontal tab + + LF = %x0A + ; linefeed + + LWSP = *(WSP / CRLF WSP) + ; linear white space (past newline) + + OCTET = %x00-FF + ; 8 bits of data + + SP = %x20 + + VCHAR = %x21-7E + ; visible (printing) characters + + WSP = SP / HTAB + ; white space + +B.2. Common Encoding + + Externally, data are represented as "network virtual ASCII" (namely, + 7-bit US-ASCII in an 8-bit field), with the high (8th) bit set to + zero. A string of values is in "network byte order", in which the + higher-valued bytes are represented on the left-hand side and are + sent over the network first. + + + + + + + +Crocker & Overell Standards Track [Page 14] + +RFC 4234 ABNF October 2005 + + +Authors' Addresses + + Dave Crocker (editor) + Brandenburg InternetWorking + 675 Spruce Dr. + Sunnyvale, CA 94086 + US + + Phone: +1.408.246.8253 + EMail: dcrocker@bbiw.net + + + Paul Overell + THUS plc. + 1/2 Berkeley Square + 99 Berkeley Street + Glasgow + G3 7HR + UK + + EMail: paul.overell@thus.net + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 15] + +RFC 4234 ABNF October 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM 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. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Crocker & Overell Standards Track [Page 16] + diff --git a/lib/megaco/doc/standard/rfc4566.txt b/lib/megaco/doc/standard/rfc4566.txt new file mode 100644 index 0000000000..776e62200b --- /dev/null +++ b/lib/megaco/doc/standard/rfc4566.txt @@ -0,0 +1,2747 @@ + + + + + + +Network Working Group M. Handley +Request for Comments: 4566 UCL +Obsoletes: 2327, 3266 V. Jacobson +Category: Standards Track Packet Design + C. Perkins + University of Glasgow + July 2006 + + + SDP: Session Description Protocol + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + This memo defines the Session Description Protocol (SDP). SDP is + intended for describing multimedia sessions for the purposes of + session announcement, session invitation, and other forms of + multimedia session initiation. + +Table of Contents + + 1. Introduction ....................................................3 + 2. Glossary of Terms ...............................................3 + 3. Examples of SDP Usage ...........................................4 + 3.1. Session Initiation .........................................4 + 3.2. Streaming Media ............................................4 + 3.3. Email and the World Wide Web ...............................4 + 3.4. Multicast Session Announcement .............................4 + 4. Requirements and Recommendations ................................5 + 4.1. Media and Transport Information ............................6 + 4.2. Timing Information .........................................6 + 4.3. Private Sessions ...........................................7 + 4.4. Obtaining Further Information about a Session ..............7 + 4.5. Categorisation .............................................7 + 4.6. Internationalisation .......................................7 + + + + + +Handley, et al. Standards Track [Page 1] + +RFC 4566 SDP July 2006 + + + 5. SDP Specification ...............................................7 + 5.1. Protocol Version ("v=") ...................................10 + 5.2. Origin ("o=") .............................................11 + 5.3. Session Name ("s=") .......................................12 + 5.4. Session Information ("i=") ................................12 + 5.5. URI ("u=") ................................................13 + 5.6. Email Address and Phone Number ("e=" and "p=") ............13 + 5.7. Connection Data ("c=") ....................................14 + 5.8. Bandwidth ("b=") ..........................................16 + 5.9. Timing ("t=") .............................................17 + 5.10. Repeat Times ("r=") ......................................18 + 5.11. Time Zones ("z=") ........................................19 + 5.12. Encryption Keys ("k=") ...................................19 + 5.13. Attributes ("a=") ........................................21 + 5.14. Media Descriptions ("m=") ................................22 + 6. SDP Attributes .................................................24 + 7. Security Considerations ........................................31 + 8. IANA Considerations ............................................33 + 8.1. The "application/sdp" Media Type ..........................33 + 8.2. Registration of Parameters ................................34 + 8.2.1. Media Types ("media") ..............................34 + 8.2.2. Transport Protocols ("proto") ......................34 + 8.2.3. Media Formats ("fmt") ..............................35 + 8.2.4. Attribute Names ("att-field") ......................36 + 8.2.5. Bandwidth Specifiers ("bwtype") ....................37 + 8.2.6. Network Types ("nettype") ..........................37 + 8.2.7. Address Types ("addrtype") .........................38 + 8.2.8. Registration Procedure .............................38 + 8.3. Encryption Key Access Methods .............................39 + 9. SDP Grammar ....................................................39 + 10. Summary of Changes from RFC 2327 ..............................44 + 11. Acknowledgements ..............................................45 + 12. References ....................................................45 + 12.1. Normative References .....................................45 + 12.2. Informative References ...................................46 + + + + + + + + + + + + + + + + +Handley, et al. Standards Track [Page 2] + +RFC 4566 SDP July 2006 + + +1. Introduction + + When initiating multimedia teleconferences, voice-over-IP calls, + streaming video, or other sessions, there is a requirement to convey + media details, transport addresses, and other session description + metadata to the participants. + + SDP provides a standard representation for such information, + irrespective of how that information is transported. SDP is purely a + format for session description -- it does not incorporate a transport + protocol, and it is intended to use different transport protocols as + appropriate, including the Session Announcement Protocol [14], + Session Initiation Protocol [15], Real Time Streaming Protocol [16], + electronic mail using the MIME extensions, and the Hypertext + Transport Protocol. + + SDP is intended to be general purpose so that it can be used in a + wide range of network environments and applications. However, it is + not intended to support negotiation of session content or media + encodings: this is viewed as outside the scope of session + description. + + This memo obsoletes RFC 2327 [6] and RFC 3266 [10]. Section 10 + outlines the changes introduced in this memo. + +2. Glossary of Terms + + The following terms are used in this document and have specific + meaning within the context of this document. + + Conference: A multimedia conference is a set of two or more + communicating users along with the software they are using to + communicate. + + Session: A multimedia session is a set of multimedia senders and + receivers and the data streams flowing from senders to receivers. + A multimedia conference is an example of a multimedia session. + + Session Description: A well-defined format for conveying sufficient + information to discover and participate in a multimedia session. + + 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 RFC 2119 [3]. + + + + + + + +Handley, et al. Standards Track [Page 3] + +RFC 4566 SDP July 2006 + + +3. Examples of SDP Usage + +3.1. Session Initiation + + The Session Initiation Protocol (SIP) [15] is an application-layer + control protocol for creating, modifying, and terminating sessions + such as Internet multimedia conferences, Internet telephone calls, + and multimedia distribution. The SIP messages used to create + sessions carry session descriptions that allow participants to agree + on a set of compatible media types. These session descriptions are + commonly formatted using SDP. When used with SIP, the offer/answer + model [17] provides a limited framework for negotiation using SDP. + +3.2. Streaming Media + + The Real Time Streaming Protocol (RTSP) [16], is an application-level + protocol for control over the delivery of data with real-time + properties. RTSP provides an extensible framework to enable + controlled, on-demand delivery of real-time data, such as audio and + video. An RTSP client and server negotiate an appropriate set of + parameters for media delivery, partially using SDP syntax to describe + those parameters. + +3.3. Email and the World Wide Web + + Alternative means of conveying session descriptions include + electronic mail and the World Wide Web (WWW). For both email and WWW + distribution, the media type "application/sdp" is used. This enables + the automatic launching of applications for participation in the + session from the WWW client or mail reader in a standard manner. + + Note that announcements of multicast sessions made only via email or + the WWW do not have the property that the receiver of a session + announcement can necessarily receive the session because the + multicast sessions may be restricted in scope, and access to the WWW + server or reception of email is possible outside this scope. + +3.4. Multicast Session Announcement + + In order to assist the advertisement of multicast multimedia + conferences and other multicast sessions, and to communicate the + relevant session setup information to prospective participants, a + distributed session directory may be used. An instance of such a + session directory periodically sends packets containing a description + of the session to a well-known multicast group. These advertisements + are received by other session directories such that potential remote + participants can use the session description to start the tools + required to participate in the session. + + + +Handley, et al. Standards Track [Page 4] + +RFC 4566 SDP July 2006 + + + One protocol used to implement such a distributed directory is the + Session Announcement Protocol (SAP) [14]. SDP provides the + recommended session description format for such session + announcements. + +4. Requirements and Recommendations + + The purpose of SDP is to convey information about media streams in + multimedia sessions to allow the recipients of a session description + to participate in the session. SDP is primarily intended for use in + an internetwork, although it is sufficiently general that it can + describe conferences in other network environments. Media streams + can be many-to-many. Sessions need not be continually active. + + Thus far, multicast-based sessions on the Internet have differed from + many other forms of conferencing in that anyone receiving the traffic + can join the session (unless the session traffic is encrypted). In + such an environment, SDP serves two primary purposes. It is a means + to communicate the existence of a session, and it is a means to + convey sufficient information to enable joining and participating in + the session. In a unicast environment, only the latter purpose is + likely to be relevant. + + An SDP session description includes the following: + + o Session name and purpose + + o Time(s) the session is active + + o The media comprising the session + + o Information needed to receive those media (addresses, ports, + formats, etc.) + + As resources necessary to participate in a session may be limited, + some additional information may also be desirable: + + o Information about the bandwidth to be used by the session + + o Contact information for the person responsible for the session + + In general, SDP must convey sufficient information to enable + applications to join a session (with the possible exception of + encryption keys) and to announce the resources to be used to any + non-participants that may need to know. (This latter feature is + primarily useful when SDP is used with a multicast session + announcement protocol.) + + + + +Handley, et al. Standards Track [Page 5] + +RFC 4566 SDP July 2006 + + +4.1. Media and Transport Information + + An SDP session description includes the following media information: + + o The type of media (video, audio, etc.) + + o The transport protocol (RTP/UDP/IP, H.320, etc.) + + o The format of the media (H.261 video, MPEG video, etc.) + + In addition to media format and transport protocol, SDP conveys + address and port details. For an IP multicast session, these + comprise: + + o The multicast group address for media + + o The transport port for media + + This address and port are the destination address and destination + port of the multicast stream, whether being sent, received, or both. + + For unicast IP sessions, the following are conveyed: + + o The remote address for media + + o The remote transport port for media + + The semantics of this address and port depend on the media and + transport protocol defined. By default, this SHOULD be the remote + address and remote port to which data is sent. Some media types may + redefine this behaviour, but this is NOT RECOMMENDED since it + complicates implementations (including middleboxes that must parse + the addresses to open Network Address Translation (NAT) or firewall + pinholes). + +4.2. Timing Information + + Sessions may be either bounded or unbounded in time. Whether or not + they are bounded, they may be only active at specific times. SDP can + convey: + + o An arbitrary list of start and stop times bounding the session + + o For each bound, repeat times such as "every Wednesday at 10am for + one hour" + + This timing information is globally consistent, irrespective of local + time zone or daylight saving time (see Section 5.9). + + + +Handley, et al. Standards Track [Page 6] + +RFC 4566 SDP July 2006 + + +4.3. Private Sessions + + It is possible to create both public sessions and private sessions. + SDP itself does not distinguish between these; private sessions are + typically conveyed by encrypting the session description during + distribution. The details of how encryption is performed are + dependent on the mechanism used to convey SDP; mechanisms are + currently defined for SDP transported using SAP [14] and SIP [15], + and others may be defined in the future. + + If a session announcement is private, it is possible to use that + private announcement to convey encryption keys necessary to decode + each of the media in a conference, including enough information to + know which encryption scheme is used for each media. + +4.4. Obtaining Further Information about a Session + + A session description should convey enough information to decide + whether or not to participate in a session. SDP may include + additional pointers in the form of Uniform Resource Identifiers + (URIs) for more information about the session. + +4.5. Categorisation + + When many session descriptions are being distributed by SAP, or any + other advertisement mechanism, it may be desirable to filter session + announcements that are of interest from those that are not. SDP + supports a categorisation mechanism for sessions that is capable of + being automated (the "a=cat:" attribute; see Section 6). + +4.6. Internationalisation + + The SDP specification recommends the use of the ISO 10646 character + sets in the UTF-8 encoding [5] to allow many different languages to + be represented. However, to assist in compact representations, SDP + also allows other character sets such as ISO 8859-1 to be used when + desired. Internationalisation only applies to free-text fields + (session name and background information), and not to SDP as a whole. + +5. SDP Specification + + An SDP session description is denoted by the media type + "application/sdp" (See Section 8). + + An SDP session description is entirely textual using the ISO 10646 + character set in UTF-8 encoding. SDP field names and attribute names + use only the US-ASCII subset of UTF-8, but textual fields and + attribute values MAY use the full ISO 10646 character set. Field and + + + +Handley, et al. Standards Track [Page 7] + +RFC 4566 SDP July 2006 + + + attribute values that use the full UTF-8 character set are never + directly compared, hence there is no requirement for UTF-8 + normalisation. The textual form, as opposed to a binary encoding + such as ASN.1 or XDR, was chosen to enhance portability, to enable a + variety of transports to be used, and to allow flexible, text-based + toolkits to be used to generate and process session descriptions. + However, since SDP may be used in environments where the maximum + permissible size of a session description is limited, the encoding is + deliberately compact. Also, since announcements may be transported + via very unreliable means or damaged by an intermediate caching + server, the encoding was designed with strict order and formatting + rules so that most errors would result in malformed session + announcements that could be detected easily and discarded. This also + allows rapid discarding of encrypted session announcements for which + a receiver does not have the correct key. + + An SDP session description consists of a number of lines of text of + the form: + + = + + where MUST be exactly one case-significant character and + is structured text whose format depends on . In + general, is either a number of fields delimited by a single + space character or a free format string, and is case-significant + unless a specific field defines otherwise. Whitespace MUST NOT be + used on either side of the "=" sign. + + An SDP session description consists of a session-level section + followed by zero or more media-level sections. The session-level + part starts with a "v=" line and continues to the first media-level + section. Each media-level section starts with an "m=" line and + continues to the next media-level section or end of the whole session + description. In general, session-level values are the default for + all media unless overridden by an equivalent media-level value. + + Some lines in each description are REQUIRED and some are OPTIONAL, + but all MUST appear in exactly the order given here (the fixed order + greatly enhances error detection and allows for a simple parser). + OPTIONAL items are marked with a "*". + + + + + + + + + + + +Handley, et al. Standards Track [Page 8] + +RFC 4566 SDP July 2006 + + + Session description + v= (protocol version) + o= (originator and session identifier) + s= (session name) + i=* (session information) + u=* (URI of description) + e=* (email address) + p=* (phone number) + c=* (connection information -- not required if included in + all media) + b=* (zero or more bandwidth information lines) + One or more time descriptions ("t=" and "r=" lines; see below) + z=* (time zone adjustments) + k=* (encryption key) + a=* (zero or more session attribute lines) + Zero or more media descriptions + + Time description + t= (time the session is active) + r=* (zero or more repeat times) + + Media description, if present + m= (media name and transport address) + i=* (media title) + c=* (connection information -- optional if included at + session level) + b=* (zero or more bandwidth information lines) + k=* (encryption key) + a=* (zero or more media attribute lines) + + The set of type letters is deliberately small and not intended to be + extensible -- an SDP parser MUST completely ignore any session + description that contains a type letter that it does not understand. + The attribute mechanism ("a=" described below) is the primary means + for extending SDP and tailoring it to particular applications or + media. Some attributes (the ones listed in Section 6 of this memo) + have a defined meaning, but others may be added on an application-, + media-, or session-specific basis. An SDP parser MUST ignore any + attribute it doesn't understand. + + An SDP session description may contain URIs that reference external + content in the "u=", "k=", and "a=" lines. These URIs may be + dereferenced in some cases, making the session description non-self- + contained. + + + + + + + +Handley, et al. Standards Track [Page 9] + +RFC 4566 SDP July 2006 + + + The connection ("c=") and attribute ("a=") information in the + session-level section applies to all the media of that session unless + overridden by connection information or an attribute of the same name + in the media description. For instance, in the example below, each + media behaves as if it were given a "recvonly" attribute. + + An example SDP description is: + + v=0 + o=jdoe 2890844526 2890842807 IN IP4 10.47.16.5 + s=SDP Seminar + i=A Seminar on the session description protocol + u=http://www.example.com/seminars/sdp.pdf + e=j.doe@example.com (Jane Doe) + c=IN IP4 224.2.17.12/127 + t=2873397496 2873404696 + a=recvonly + m=audio 49170 RTP/AVP 0 + m=video 51372 RTP/AVP 99 + a=rtpmap:99 h263-1998/90000 + + Text fields such as the session name and information are octet + strings that may contain any octet with the exceptions of 0x00 (Nul), + 0x0a (ASCII newline), and 0x0d (ASCII carriage return). The sequence + CRLF (0x0d0a) is used to end a record, although parsers SHOULD be + tolerant and also accept records terminated with a single newline + character. If the "a=charset" attribute is not present, these octet + strings MUST be interpreted as containing ISO-10646 characters in + UTF-8 encoding (the presence of the "a=charset" attribute may force + some fields to be interpreted differently). + + A session description can contain domain names in the "o=", "u=", + "e=", "c=", and "a=" lines. Any domain name used in SDP MUST comply + with [1], [2]. Internationalised domain names (IDNs) MUST be + represented using the ASCII Compatible Encoding (ACE) form defined in + [11] and MUST NOT be directly represented in UTF-8 or any other + encoding (this requirement is for compatibility with RFC 2327 and + other SDP-related standards, which predate the development of + internationalised domain names). + +5.1. Protocol Version ("v=") + + v=0 + + The "v=" field gives the version of the Session Description Protocol. + This memo defines version 0. There is no minor version number. + + + + + +Handley, et al. Standards Track [Page 10] + +RFC 4566 SDP July 2006 + + +5.2. Origin ("o=") + + o= + + + The "o=" field gives the originator of the session (her username and + the address of the user's host) plus a session identifier and version + number: + + is the user's login on the originating host, or it is "-" + if the originating host does not support the concept of user IDs. + The MUST NOT contain spaces. + + is a numeric string such that the tuple of , + , , , and forms a + globally unique identifier for the session. The method of + allocation is up to the creating tool, but it has been + suggested that a Network Time Protocol (NTP) format timestamp be + used to ensure uniqueness [13]. + + is a version number for this session description. Its + usage is up to the creating tool, so long as is + increased when a modification is made to the session data. Again, + it is RECOMMENDED that an NTP format timestamp is used. + + is a text string giving the type of network. Initially + "IN" is defined to have the meaning "Internet", but other values + MAY be registered in the future (see Section 8). + + is a text string giving the type of the address that + follows. Initially "IP4" and "IP6" are defined, but other values + MAY be registered in the future (see Section 8). + + is the address of the machine from which the + session was created. For an address type of IP4, this is either + the fully qualified domain name of the machine or the dotted- + decimal representation of the IP version 4 address of the machine. + For an address type of IP6, this is either the fully qualified + domain name of the machine or the compressed textual + representation of the IP version 6 address of the machine. For + both IP4 and IP6, the fully qualified domain name is the form that + SHOULD be given unless this is unavailable, in which case the + globally unique address MAY be substituted. A local IP address + MUST NOT be used in any context where the SDP description might + leave the scope in which the address is meaningful (for example, a + local address MUST NOT be included in an application-level + referral that might leave the scope). + + + + +Handley, et al. Standards Track [Page 11] + +RFC 4566 SDP July 2006 + + + In general, the "o=" field serves as a globally unique identifier for + this version of this session description, and the subfields excepting + the version taken together identify the session irrespective of any + modifications. + + For privacy reasons, it is sometimes desirable to obfuscate the + username and IP address of the session originator. If this is a + concern, an arbitrary and private MAY be + chosen to populate the "o=" field, provided that these are selected + in a manner that does not affect the global uniqueness of the field. + +5.3. Session Name ("s=") + + s= + + The "s=" field is the textual session name. There MUST be one and + only one "s=" field per session description. The "s=" field MUST NOT + be empty and SHOULD contain ISO 10646 characters (but see also the + "a=charset" attribute). If a session has no meaningful name, the + value "s= " SHOULD be used (i.e., a single space as the session + name). + +5.4. Session Information ("i=") + + i= + + The "i=" field provides textual information about the session. There + MUST be at most one session-level "i=" field per session description, + and at most one "i=" field per media. If the "a=charset" attribute + is present, it specifies the character set used in the "i=" field. + If the "a=charset" attribute is not present, the "i=" field MUST + contain ISO 10646 characters in UTF-8 encoding. + + A single "i=" field MAY also be used for each media definition. In + media definitions, "i=" fields are primarily intended for labelling + media streams. As such, they are most likely to be useful when a + single session has more than one distinct media stream of the same + media type. An example would be two different whiteboards, one for + slides and one for feedback and questions. + + The "i=" field is intended to provide a free-form human-readable + description of the session or the purpose of a media stream. It is + not suitable for parsing by automata. + + + + + + + + +Handley, et al. Standards Track [Page 12] + +RFC 4566 SDP July 2006 + + +5.5. URI ("u=") + + u= + + A URI is a Uniform Resource Identifier as used by WWW clients [7]. + The URI should be a pointer to additional information about the + session. This field is OPTIONAL, but if it is present it MUST be + specified before the first media field. No more than one URI field + is allowed per session description. + +5.6. Email Address and Phone Number ("e=" and "p=") + + e= + p= + + The "e=" and "p=" lines specify contact information for the person + responsible for the conference. This is not necessarily the same + person that created the conference announcement. + + Inclusion of an email address or phone number is OPTIONAL. Note that + the previous version of SDP specified that either an email field or a + phone field MUST be specified, but this was widely ignored. The + change brings the specification into line with common usage. + + If an email address or phone number is present, it MUST be specified + before the first media field. More than one email or phone field can + be given for a session description. + + Phone numbers SHOULD be given in the form of an international public + telecommunication number (see ITU-T Recommendation E.164) preceded by + a "+". Spaces and hyphens may be used to split up a phone field to + aid readability if desired. For example: + + p=+1 617 555-6011 + + Both email addresses and phone numbers can have an OPTIONAL free text + string associated with them, normally giving the name of the person + who may be contacted. This MUST be enclosed in parentheses if it is + present. For example: + + e=j.doe@example.com (Jane Doe) + + The alternative RFC 2822 [29] name quoting convention is also allowed + for both email addresses and phone numbers. For example: + + e=Jane Doe + + + + + +Handley, et al. Standards Track [Page 13] + +RFC 4566 SDP July 2006 + + + The free text string SHOULD be in the ISO-10646 character set with + UTF-8 encoding, or alternatively in ISO-8859-1 or other encodings if + the appropriate session-level "a=charset" attribute is set. + +5.7. Connection Data ("c=") + + c= + + The "c=" field contains connection data. + + A session description MUST contain either at least one "c=" field in + each media description or a single "c=" field at the session level. + It MAY contain a single session-level "c=" field and additional "c=" + field(s) per media description, in which case the per-media values + override the session-level settings for the respective media. + + The first sub-field ("") is the network type, which is a + text string giving the type of network. Initially, "IN" is defined + to have the meaning "Internet", but other values MAY be registered in + the future (see Section 8). + + The second sub-field ("") is the address type. This allows + SDP to be used for sessions that are not IP based. This memo only + defines IP4 and IP6, but other values MAY be registered in the future + (see Section 8). + + The third sub-field ("") is the connection + address. OPTIONAL sub-fields MAY be added after the connection + address depending on the value of the field. + + When the is IP4 and IP6, the connection address is defined + as follows: + + o If the session is multicast, the connection address will be an IP + multicast group address. If the session is not multicast, then + the connection address contains the unicast IP address of the + expected data source or data relay or data sink as determined by + additional attribute fields. It is not expected that unicast + addresses will be given in a session description that is + communicated by a multicast announcement, though this is not + prohibited. + + o Sessions using an IPv4 multicast connection address MUST also have + a time to live (TTL) value present in addition to the multicast + address. The TTL and the address together define the scope with + which multicast packets sent in this conference will be sent. TTL + values MUST be in the range 0-255. Although the TTL MUST be + specified, its use to scope multicast traffic is deprecated; + + + +Handley, et al. Standards Track [Page 14] + +RFC 4566 SDP July 2006 + + + applications SHOULD use an administratively scoped address + instead. + + The TTL for the session is appended to the address using a slash as a + separator. An example is: + + c=IN IP4 224.2.36.42/127 + + IPv6 multicast does not use TTL scoping, and hence the TTL value MUST + NOT be present for IPv6 multicast. It is expected that IPv6 scoped + addresses will be used to limit the scope of conferences. + + Hierarchical or layered encoding schemes are data streams where the + encoding from a single media source is split into a number of layers. + The receiver can choose the desired quality (and hence bandwidth) by + only subscribing to a subset of these layers. Such layered encodings + are normally transmitted in multiple multicast groups to allow + multicast pruning. This technique keeps unwanted traffic from sites + only requiring certain levels of the hierarchy. For applications + requiring multiple multicast groups, we allow the following notation + to be used for the connection address: + + [/]/ + + If the number of addresses is not given, it is assumed to be one. + Multicast addresses so assigned are contiguously allocated above the + base address, so that, for example: + + c=IN IP4 224.2.1.1/127/3 + + would state that addresses 224.2.1.1, 224.2.1.2, and 224.2.1.3 are to + be used at a TTL of 127. This is semantically identical to including + multiple "c=" lines in a media description: + + c=IN IP4 224.2.1.1/127 + c=IN IP4 224.2.1.2/127 + c=IN IP4 224.2.1.3/127 + + Similarly, an IPv6 example would be: + + c=IN IP6 FF15::101/3 + + which is semantically equivalent to: + + c=IN IP6 FF15::101 + c=IN IP6 FF15::102 + c=IN IP6 FF15::103 + + + + +Handley, et al. Standards Track [Page 15] + +RFC 4566 SDP July 2006 + + + (remembering that the TTL field is not present in IPv6 multicast). + + Multiple addresses or "c=" lines MAY be specified on a per-media + basis only if they provide multicast addresses for different layers + in a hierarchical or layered encoding scheme. They MUST NOT be + specified for a session-level "c=" field. + + The slash notation for multiple addresses described above MUST NOT be + used for IP unicast addresses. + +5.8. Bandwidth ("b=") + + b=: + + This OPTIONAL field denotes the proposed bandwidth to be used by the + session or media. The is an alphanumeric modifier giving + the meaning of the figure. Two values are defined in + this specification, but other values MAY be registered in the future + (see Section 8 and [21], [25]): + + CT If the bandwidth of a session or media in a session is different + from the bandwidth implicit from the scope, a "b=CT:..." line + SHOULD be supplied for the session giving the proposed upper limit + to the bandwidth used (the "conference total" bandwidth). The + primary purpose of this is to give an approximate idea as to + whether two or more sessions can coexist simultaneously. When + using the CT modifier with RTP, if several RTP sessions are part + of the conference, the conference total refers to total bandwidth + of all RTP sessions. + + AS The bandwidth is interpreted to be application specific (it will + be the application's concept of maximum bandwidth). Normally, + this will coincide with what is set on the application's "maximum + bandwidth" control if applicable. For RTP-based applications, AS + gives the RTP "session bandwidth" as defined in Section 6.2 of + [19]. + + Note that CT gives a total bandwidth figure for all the media at all + sites. AS gives a bandwidth figure for a single media at a single + site, although there may be many sites sending simultaneously. + + A prefix "X-" is defined for names. This is intended for + experimental purposes only. For example: + + b=X-YZ:128 + + + + + + +Handley, et al. Standards Track [Page 16] + +RFC 4566 SDP July 2006 + + + Use of the "X-" prefix is NOT RECOMMENDED: instead new modifiers + SHOULD be registered with IANA in the standard namespace. SDP + parsers MUST ignore bandwidth fields with unknown modifiers. + Modifiers MUST be alphanumeric and, although no length limit is + given, it is recommended that they be short. + + The is interpreted as kilobits per second by default. + The definition of a new modifier MAY specify that the + bandwidth is to be interpreted in some alternative unit (the "CT" and + "AS" modifiers defined in this memo use the default units). + +5.9. Timing ("t=") + + t= + + The "t=" lines specify the start and stop times for a session. + Multiple "t=" lines MAY be used if a session is active at multiple + irregularly spaced times; each additional "t=" line specifies an + additional period of time for which the session will be active. If + the session is active at regular times, an "r=" line (see below) + should be used in addition to, and following, a "t=" line -- in which + case the "t=" line specifies the start and stop times of the repeat + sequence. + + The first and second sub-fields give the start and stop times, + respectively, for the session. These values are the decimal + representation of Network Time Protocol (NTP) time values in seconds + since 1900 [13]. To convert these values to UNIX time, subtract + decimal 2208988800. + + NTP timestamps are elsewhere represented by 64-bit values, which wrap + sometime in the year 2036. Since SDP uses an arbitrary length + decimal representation, this should not cause an issue (SDP + timestamps MUST continue counting seconds since 1900, NTP will use + the value modulo the 64-bit limit). + + If the is set to zero, then the session is not bounded, + though it will not become active until after the . If + the is also zero, the session is regarded as permanent. + + User interfaces SHOULD strongly discourage the creation of unbounded + and permanent sessions as they give no information about when the + session is actually going to terminate, and so make scheduling + difficult. + + The general assumption may be made, when displaying unbounded + sessions that have not timed out to the user, that an unbounded + session will only be active until half an hour from the current time + + + +Handley, et al. Standards Track [Page 17] + +RFC 4566 SDP July 2006 + + + or the session start time, whichever is the later. If behaviour + other than this is required, an end-time SHOULD be given and modified + as appropriate when new information becomes available about when the + session should really end. + + Permanent sessions may be shown to the user as never being active + unless there are associated repeat times that state precisely when + the session will be active. + +5.10. Repeat Times ("r=") + + r= + + "r=" fields specify repeat times for a session. For example, if a + session is active at 10am on Monday and 11am on Tuesday for one hour + each week for three months, then the in the + corresponding "t=" field would be the NTP representation of 10am on + the first Monday, the would be 1 week, the would be 1 hour, and the offsets would be zero and 25 + hours. The corresponding "t=" field stop time would be the NTP + representation of the end of the last session three months later. By + default, all fields are in seconds, so the "r=" and "t=" fields might + be the following: + + t=3034423619 3042462419 + r=604800 3600 0 90000 + + To make description more compact, times may also be given in units of + days, hours, or minutes. The syntax for these is a number + immediately followed by a single case-sensitive character. + Fractional units are not allowed -- a smaller unit should be used + instead. The following unit specification characters are allowed: + + d - days (86400 seconds) + h - hours (3600 seconds) + m - minutes (60 seconds) + s - seconds (allowed for completeness) + + Thus, the above session announcement could also have been written: + + r=7d 1h 0 25h + + Monthly and yearly repeats cannot be directly specified with a single + SDP repeat time; instead, separate "t=" fields should be used to + explicitly list the session times. + + + + + + +Handley, et al. Standards Track [Page 18] + +RFC 4566 SDP July 2006 + + +5.11. Time Zones ("z=") + + z= .... + + To schedule a repeated session that spans a change from daylight + saving time to standard time or vice versa, it is necessary to + specify offsets from the base time. This is required because + different time zones change time at different times of day, different + countries change to or from daylight saving time on different dates, + and some countries do not have daylight saving time at all. + + Thus, in order to schedule a session that is at the same time winter + and summer, it must be possible to specify unambiguously by whose + time zone a session is scheduled. To simplify this task for + receivers, we allow the sender to specify the NTP time that a time + zone adjustment happens and the offset from the time when the session + was first scheduled. The "z=" field allows the sender to specify a + list of these adjustment times and offsets from the base time. + + An example might be the following: + + z=2882844526 -1h 2898848070 0 + + This specifies that at time 2882844526, the time base by which the + session's repeat times are calculated is shifted back by 1 hour, and + that at time 2898848070, the session's original time base is + restored. Adjustments are always relative to the specified start + time -- they are not cumulative. Adjustments apply to all "t=" and + "r=" lines in a session description. + + If a session is likely to last several years, it is expected that the + session announcement will be modified periodically rather than + transmit several years' worth of adjustments in one session + announcement. + +5.12. Encryption Keys ("k=") + + k= + k=: + + If transported over a secure and trusted channel, the Session + Description Protocol MAY be used to convey encryption keys. A simple + mechanism for key exchange is provided by the key field ("k="), + although this is primarily supported for compatibility with older + implementations and its use is NOT RECOMMENDED. Work is in progress + to define new key exchange mechanisms for use with SDP [27] [28], and + it is expected that new applications will use those mechanisms. + + + + +Handley, et al. Standards Track [Page 19] + +RFC 4566 SDP July 2006 + + + A key field is permitted before the first media entry (in which case + it applies to all media in the session), or for each media entry as + required. The format of keys and their usage are outside the scope + of this document, and the key field provides no way to indicate the + encryption algorithm to be used, key type, or other information about + the key: this is assumed to be provided by the higher-level protocol + using SDP. If there is a need to convey this information within SDP, + the extensions mentioned previously SHOULD be used. Many security + protocols require two keys: one for confidentiality, another for + integrity. This specification does not support transfer of two keys. + + The method indicates the mechanism to be used to obtain a usable key + by external means, or from the encoded encryption key given. The + following methods are defined: + + k=clear: + + The encryption key is included untransformed in this key field. + This method MUST NOT be used unless it can be guaranteed that + the SDP is conveyed over a secure channel. The encryption key + is interpreted as text according to the charset attribute; use + the "k=base64:" method to convey characters that are otherwise + prohibited in SDP. + + k=base64: + + The encryption key is included in this key field but has been + base64 encoded [12] because it includes characters that are + prohibited in SDP. This method MUST NOT be used unless it can + be guaranteed that the SDP is conveyed over a secure channel. + + k=uri: + + A Uniform Resource Identifier is included in the key field. + The URI refers to the data containing the key, and may require + additional authentication before the key can be returned. When + a request is made to the given URI, the reply should specify + the encoding for the key. The URI is often an Secure Socket + Layer/Transport Layer Security (SSL/TLS)-protected HTTP URI + ("https:"), although this is not required. + + k=prompt + + No key is included in this SDP description, but the session or + media stream referred to by this key field is encrypted. The + user should be prompted for the key when attempting to join the + session, and this user-supplied key should then be used to + + + + +Handley, et al. Standards Track [Page 20] + +RFC 4566 SDP July 2006 + + + decrypt the media streams. The use of user-specified keys is + NOT RECOMMENDED, since such keys tend to have weak security + properties. + + The key field MUST NOT be used unless it can be guaranteed that the + SDP is conveyed over a secure and trusted channel. An example of + such a channel might be SDP embedded inside an S/MIME message or a + TLS-protected HTTP session. It is important to ensure that the + secure channel is with the party that is authorised to join the + session, not an intermediary: if a caching proxy server is used, it + is important to ensure that the proxy is either trusted or unable to + access the SDP. + +5.13. Attributes ("a=") + + a= + a=: + + Attributes are the primary means for extending SDP. Attributes may + be defined to be used as "session-level" attributes, "media-level" + attributes, or both. + + A media description may have any number of attributes ("a=" fields) + that are media specific. These are referred to as "media-level" + attributes and add information about the media stream. Attribute + fields can also be added before the first media field; these + "session-level" attributes convey additional information that applies + to the conference as a whole rather than to individual media. + + Attribute fields may be of two forms: + + o A property attribute is simply of the form "a=". These are + binary attributes, and the presence of the attribute conveys that + the attribute is a property of the session. An example might be + "a=recvonly". + + o A value attribute is of the form "a=:". For + example, a whiteboard could have the value attribute "a=orient: + landscape" + + Attribute interpretation depends on the media tool being invoked. + Thus receivers of session descriptions should be configurable in + their interpretation of session descriptions in general and of + attributes in particular. + + Attribute names MUST use the US-ASCII subset of ISO-10646/UTF-8. + + + + + +Handley, et al. Standards Track [Page 21] + +RFC 4566 SDP July 2006 + + + Attribute values are octet strings, and MAY use any octet value + except 0x00 (Nul), 0x0A (LF), and 0x0D (CR). By default, attribute + values are to be interpreted as in ISO-10646 character set with UTF-8 + encoding. Unlike other text fields, attribute values are NOT + normally affected by the "charset" attribute as this would make + comparisons against known values problematic. However, when an + attribute is defined, it can be defined to be charset dependent, in + which case its value should be interpreted in the session charset + rather than in ISO-10646. + + Attributes MUST be registered with IANA (see Section 8). If an + attribute is received that is not understood, it MUST be ignored by + the receiver. + +5.14. Media Descriptions ("m=") + + m= ... + + A session description may contain a number of media descriptions. + Each media description starts with an "m=" field and is terminated by + either the next "m=" field or by the end of the session description. + A media field has several sub-fields: + + is the media type. Currently defined media are "audio", + "video", "text", "application", and "message", although this list + may be extended in the future (see Section 8). + + is the transport port to which the media stream is sent. The + meaning of the transport port depends on the network being used as + specified in the relevant "c=" field, and on the transport + protocol defined in the sub-field of the media field. + Other ports used by the media application (such as the RTP Control + Protocol (RTCP) port [19]) MAY be derived algorithmically from the + base media port or MAY be specified in a separate attribute (for + example, "a=rtcp:" as defined in [22]). + + If non-contiguous ports are used or if they don't follow the + parity rule of even RTP ports and odd RTCP ports, the "a=rtcp:" + attribute MUST be used. Applications that are requested to send + media to a that is odd and where the "a=rtcp:" is present + MUST NOT subtract 1 from the RTP port: that is, they MUST send the + RTP to the port indicated in and send the RTCP to the port + indicated in the "a=rtcp" attribute. + + For applications where hierarchically encoded streams are being + sent to a unicast address, it may be necessary to specify multiple + transport ports. This is done using a similar notation to that + used for IP multicast addresses in the "c=" field: + + + +Handley, et al. Standards Track [Page 22] + +RFC 4566 SDP July 2006 + + + m= / ... + + In such a case, the ports used depend on the transport protocol. + For RTP, the default is that only the even-numbered ports are used + for data with the corresponding one-higher odd ports used for the + RTCP belonging to the RTP session, and the + denoting the number of RTP sessions. For example: + + m=video 49170/2 RTP/AVP 31 + + would specify that ports 49170 and 49171 form one RTP/RTCP pair + and 49172 and 49173 form the second RTP/RTCP pair. RTP/AVP is the + transport protocol and 31 is the format (see below). If non- + contiguous ports are required, they must be signalled using a + separate attribute (for example, "a=rtcp:" as defined in [22]). + + If multiple addresses are specified in the "c=" field and multiple + ports are specified in the "m=" field, a one-to-one mapping from + port to the corresponding address is implied. For example: + + c=IN IP4 224.2.1.1/127/2 + m=video 49170/2 RTP/AVP 31 + + would imply that address 224.2.1.1 is used with ports 49170 and + 49171, and address 224.2.1.2 is used with ports 49172 and 49173. + + The semantics of multiple "m=" lines using the same transport + address are undefined. This implies that, unlike limited past + practice, there is no implicit grouping defined by such means and + an explicit grouping framework (for example, [18]) should instead + be used to express the intended semantics. + + is the transport protocol. The meaning of the transport + protocol is dependent on the address type field in the relevant + "c=" field. Thus a "c=" field of IP4 indicates that the transport + protocol runs over IP4. The following transport protocols are + defined, but may be extended through registration of new protocols + with IANA (see Section 8): + + * udp: denotes an unspecified protocol running over UDP. + + * RTP/AVP: denotes RTP [19] used under the RTP Profile for Audio + and Video Conferences with Minimal Control [20] running over + UDP. + + * RTP/SAVP: denotes the Secure Real-time Transport Protocol [23] + running over UDP. + + + + +Handley, et al. Standards Track [Page 23] + +RFC 4566 SDP July 2006 + + + The main reason to specify the transport protocol in addition to + the media format is that the same standard media formats may be + carried over different transport protocols even when the network + protocol is the same -- a historical example is vat Pulse Code + Modulation (PCM) audio and RTP PCM audio; another might be TCP/RTP + PCM audio. In addition, relays and monitoring tools that are + transport-protocol-specific but format-independent are possible. + + is a media format description. The fourth and any subsequent + sub-fields describe the format of the media. The interpretation + of the media format depends on the value of the sub-field. + + If the sub-field is "RTP/AVP" or "RTP/SAVP" the + sub-fields contain RTP payload type numbers. When a list of + payload type numbers is given, this implies that all of these + payload formats MAY be used in the session, but the first of these + formats SHOULD be used as the default format for the session. For + dynamic payload type assignments the "a=rtpmap:" attribute (see + Section 6) SHOULD be used to map from an RTP payload type number + to a media encoding name that identifies the payload format. The + "a=fmtp:" attribute MAY be used to specify format parameters (see + Section 6). + + If the sub-field is "udp" the sub-fields MUST + reference a media type describing the format under the "audio", + "video", "text", "application", or "message" top-level media + types. The media type registration SHOULD define the packet + format for use with UDP transport. + + For media using other transport protocols, the field is + protocol specific. Rules for interpretation of the sub- + field MUST be defined when registering new protocols (see Section + 8.2.2). + +6. SDP Attributes + + The following attributes are defined. Since application writers may + add new attributes as they are required, this list is not exhaustive. + Registration procedures for new attributes are defined in Section + 8.2.4. + + a=cat: + + This attribute gives the dot-separated hierarchical category of + the session. This is to enable a receiver to filter unwanted + sessions by category. There is no central registry of + categories. It is a session-level attribute, and it is not + dependent on charset. + + + +Handley, et al. Standards Track [Page 24] + +RFC 4566 SDP July 2006 + + + a=keywds: + + Like the cat attribute, this is to assist identifying wanted + sessions at the receiver. This allows a receiver to select + interesting session based on keywords describing the purpose of + the session; there is no central registry of keywords. It is a + session-level attribute. It is a charset-dependent attribute, + meaning that its value should be interpreted in the charset + specified for the session description if one is specified, or + by default in ISO 10646/UTF-8. + + a=tool: + + This gives the name and version number of the tool used to + create the session description. It is a session-level + attribute, and it is not dependent on charset. + + a=ptime: + + This gives the length of time in milliseconds represented by + the media in a packet. This is probably only meaningful for + audio data, but may be used with other media types if it makes + sense. It should not be necessary to know ptime to decode RTP + or vat audio, and it is intended as a recommendation for the + encoding/packetisation of audio. It is a media-level + attribute, and it is not dependent on charset. + + a=maxptime: + + This gives the maximum amount of media that can be encapsulated + in each packet, expressed as time in milliseconds. The time + SHALL be calculated as the sum of the time the media present in + the packet represents. For frame-based codecs, the time SHOULD + be an integer multiple of the frame size. This attribute is + probably only meaningful for audio data, but may be used with + other media types if it makes sense. It is a media-level + attribute, and it is not dependent on charset. Note that this + attribute was introduced after RFC 2327, and non-updated + implementations will ignore this attribute. + + a=rtpmap: / [/] + + This attribute maps from an RTP payload type number (as used in + an "m=" line) to an encoding name denoting the payload format + to be used. It also provides information on the clock rate and + encoding parameters. It is a media-level attribute that is not + dependent on charset. + + + +Handley, et al. Standards Track [Page 25] + +RFC 4566 SDP July 2006 + + + Although an RTP profile may make static assignments of payload + type numbers to payload formats, it is more common for that + assignment to be done dynamically using "a=rtpmap:" attributes. + As an example of a static payload type, consider u-law PCM + coded single-channel audio sampled at 8 kHz. This is + completely defined in the RTP Audio/Video profile as payload + type 0, so there is no need for an "a=rtpmap:" attribute, and + the media for such a stream sent to UDP port 49232 can be + specified as: + + m=audio 49232 RTP/AVP 0 + + An example of a dynamic payload type is 16-bit linear encoded + stereo audio sampled at 16 kHz. If we wish to use the dynamic + RTP/AVP payload type 98 for this stream, additional information + is required to decode it: + + m=audio 49232 RTP/AVP 98 + a=rtpmap:98 L16/16000/2 + + Up to one rtpmap attribute can be defined for each media format + specified. Thus, we might have the following: + + m=audio 49230 RTP/AVP 96 97 98 + a=rtpmap:96 L8/8000 + a=rtpmap:97 L16/8000 + a=rtpmap:98 L16/11025/2 + + RTP profiles that specify the use of dynamic payload types MUST + define the set of valid encoding names and/or a means to + register encoding names if that profile is to be used with SDP. + The "RTP/AVP" and "RTP/SAVP" profiles use media subtypes for + encoding names, under the top-level media type denoted in the + "m=" line. In the example above, the media types are + "audio/l8" and "audio/l16". + + For audio streams, indicates the number + of audio channels. This parameter is OPTIONAL and may be + omitted if the number of channels is one, provided that no + additional parameters are needed. + + For video streams, no encoding parameters are currently + specified. + + Additional encoding parameters MAY be defined in the future, + but codec-specific parameters SHOULD NOT be added. Parameters + added to an "a=rtpmap:" attribute SHOULD only be those required + for a session directory to make the choice of appropriate media + + + +Handley, et al. Standards Track [Page 26] + +RFC 4566 SDP July 2006 + + + to participate in a session. Codec-specific parameters should + be added in other attributes (for example, "a=fmtp:"). + + Note: RTP audio formats typically do not include information + about the number of samples per packet. If a non-default (as + defined in the RTP Audio/Video Profile) packetisation is + required, the "ptime" attribute is used as given above. + + a=recvonly + + This specifies that the tools should be started in receive-only + mode where applicable. It can be either a session- or media- + level attribute, and it is not dependent on charset. Note that + recvonly applies to the media only, not to any associated + control protocol (e.g., an RTP-based system in recvonly mode + SHOULD still send RTCP packets). + + a=sendrecv + + This specifies that the tools should be started in send and + receive mode. This is necessary for interactive conferences + with tools that default to receive-only mode. It can be either + a session or media-level attribute, and it is not dependent on + charset. + + If none of the attributes "sendonly", "recvonly", "inactive", + and "sendrecv" is present, "sendrecv" SHOULD be assumed as the + default for sessions that are not of the conference type + "broadcast" or "H332" (see below). + + a=sendonly + + This specifies that the tools should be started in send-only + mode. An example may be where a different unicast address is + to be used for a traffic destination than for a traffic source. + In such a case, two media descriptions may be used, one + sendonly and one recvonly. It can be either a session- or + media-level attribute, but would normally only be used as a + media attribute. It is not dependent on charset. Note that + sendonly applies only to the media, and any associated control + protocol (e.g., RTCP) SHOULD still be received and processed as + normal. + + a=inactive + + This specifies that the tools should be started in inactive + mode. This is necessary for interactive conferences where + users can put other users on hold. No media is sent over an + + + +Handley, et al. Standards Track [Page 27] + +RFC 4566 SDP July 2006 + + + inactive media stream. Note that an RTP-based system SHOULD + still send RTCP, even if started inactive. It can be either a + session or media-level attribute, and it is not dependent on + charset. + + a=orient: + + Normally this is only used for a whiteboard or presentation + tool. It specifies the orientation of a the workspace on the + screen. It is a media-level attribute. Permitted values are + "portrait", "landscape", and "seascape" (upside-down + landscape). It is not dependent on charset. + + a=type: + + This specifies the type of the conference. Suggested values + are "broadcast", "meeting", "moderated", "test", and "H332". + "recvonly" should be the default for "type:broadcast" sessions, + "type:meeting" should imply "sendrecv", and "type:moderated" + should indicate the use of a floor control tool and that the + media tools are started so as to mute new sites joining the + conference. + + Specifying the attribute "type:H332" indicates that this + loosely coupled session is part of an H.332 session as defined + in the ITU H.332 specification [26]. Media tools should be + started "recvonly". + + Specifying the attribute "type:test" is suggested as a hint + that, unless explicitly requested otherwise, receivers can + safely avoid displaying this session description to users. + + The type attribute is a session-level attribute, and it is not + dependent on charset. + + a=charset: + + This specifies the character set to be used to display the + session name and information data. By default, the ISO-10646 + character set in UTF-8 encoding is used. If a more compact + representation is required, other character sets may be used. + For example, the ISO 8859-1 is specified with the following SDP + attribute: + + a=charset:ISO-8859-1 + + + + + + +Handley, et al. Standards Track [Page 28] + +RFC 4566 SDP July 2006 + + + This is a session-level attribute and is not dependent on + charset. The charset specified MUST be one of those registered + with IANA, such as ISO-8859-1. The character set identifier is + a US-ASCII string and MUST be compared against the IANA + identifiers using a case-insensitive comparison. If the + identifier is not recognised or not supported, all strings that + are affected by it SHOULD be regarded as octet strings. + + Note that a character set specified MUST still prohibit the use + of bytes 0x00 (Nul), 0x0A (LF), and 0x0d (CR). Character sets + requiring the use of these characters MUST define a quoting + mechanism that prevents these bytes from appearing within text + fields. + + a=sdplang: + + This can be a session-level attribute or a media-level + attribute. As a session-level attribute, it specifies the + language for the session description. As a media-level + attribute, it specifies the language for any media-level SDP + information field associated with that media. Multiple sdplang + attributes can be provided either at session or media level if + multiple languages in the session description or media use + multiple languages, in which case the order of the attributes + indicates the order of importance of the various languages in + the session or media from most important to least important. + + In general, sending session descriptions consisting of multiple + languages is discouraged. Instead, multiple descriptions + SHOULD be sent describing the session, one in each language. + However, this is not possible with all transport mechanisms, + and so multiple sdplang attributes are allowed although NOT + RECOMMENDED. + + The "sdplang" attribute value must be a single RFC 3066 + language tag in US-ASCII [9]. It is not dependent on the + charset attribute. An "sdplang" attribute SHOULD be specified + when a session is of sufficient scope to cross geographic + boundaries where the language of recipients cannot be assumed, + or where the session is in a different language from the + locally assumed norm. + + a=lang: + + This can be a session-level attribute or a media-level + attribute. As a session-level attribute, it specifies the + default language for the session being described. As a media- + level attribute, it specifies the language for that media, + + + +Handley, et al. Standards Track [Page 29] + +RFC 4566 SDP July 2006 + + + overriding any session-level language specified. Multiple lang + attributes can be provided either at session or media level if + the session description or media use multiple languages, in + which case the order of the attributes indicates the order of + importance of the various languages in the session or media + from most important to least important. + + The "lang" attribute value must be a single RFC 3066 language + tag in US-ASCII [9]. It is not dependent on the charset + attribute. A "lang" attribute SHOULD be specified when a + session is of sufficient scope to cross geographic boundaries + where the language of recipients cannot be assumed, or where + the session is in a different language from the locally assumed + norm. + + a=framerate: + + This gives the maximum video frame rate in frames/sec. It is + intended as a recommendation for the encoding of video data. + Decimal representations of fractional values using the notation + "." are allowed. It is a media-level + attribute, defined only for video media, and it is not + dependent on charset. + + a=quality: + + This gives a suggestion for the quality of the encoding as an + integer value. The intention of the quality attribute for + video is to specify a non-default trade-off between frame-rate + and still-image quality. For video, the value is in the range + 0 to 10, with the following suggested meaning: + + 10 - the best still-image quality the compression scheme can + give. + 5 - the default behaviour given no quality suggestion. + 0 - the worst still-image quality the codec designer thinks + is still usable. + + It is a media-level attribute, and it is not dependent on + charset. + + a=fmtp: + + This attribute allows parameters that are specific to a + particular format to be conveyed in a way that SDP does not + have to understand them. The format must be one of the formats + specified for the media. Format-specific parameters may be any + set of parameters required to be conveyed by SDP and given + + + +Handley, et al. Standards Track [Page 30] + +RFC 4566 SDP July 2006 + + + unchanged to the media tool that will use this format. At most + one instance of this attribute is allowed for each format. + + It is a media-level attribute, and it is not dependent on + charset. + +7. Security Considerations + + SDP is frequently used with the Session Initiation Protocol [15] + using the offer/answer model [17] to agree on parameters for unicast + sessions. When used in this manner, the security considerations of + those protocols apply. + + SDP is a session description format that describes multimedia + sessions. Entities receiving and acting upon an SDP message SHOULD + be aware that a session description cannot be trusted unless it has + been obtained by an authenticated transport protocol from a known and + trusted source. Many different transport protocols may be used to + distribute session description, and the nature of the authentication + will differ from transport to transport. For some transports, + security features are often not deployed. In case a session + description has not been obtained in a trusted manner, the endpoint + SHOULD exercise care because, among other attacks, the media sessions + received may not be the intended ones, the destination where media is + sent to may not be the expected one, any of the parameters of the + session may be incorrect, or the media security may be compromised. + It is up to the endpoint to make a sensible decision taking into + account the security risks of the application and the user + preferences and may decide to ask the user whether or not to accept + the session. + + One transport that can be used to distribute session descriptions is + the Session Announcement Protocol (SAP). SAP provides both + encryption and authentication mechanisms, but due to the nature of + session announcements it is likely that there are many occasions + where the originator of a session announcement cannot be + authenticated because the originator is previously unknown to the + receiver of the announcement and because no common public key + infrastructure is available. + + On receiving a session description over an unauthenticated transport + mechanism or from an untrusted party, software parsing the session + should take a few precautions. Session descriptions contain + information required to start software on the receiver's system. + Software that parses a session description MUST NOT be able to start + other software except that which is specifically configured as + appropriate software to participate in multimedia sessions. It is + normally considered inappropriate for software parsing a session + + + +Handley, et al. Standards Track [Page 31] + +RFC 4566 SDP July 2006 + + + description to start, on a user's system, software that is + appropriate to participate in multimedia sessions, without the user + first being informed that such software will be started and giving + the user's consent. Thus, a session description arriving by session + announcement, email, session invitation, or WWW page MUST NOT deliver + the user into an interactive multimedia session unless the user has + explicitly pre-authorised such action. As it is not always simple to + tell whether or not a session is interactive, applications that are + unsure should assume sessions are interactive. + + In this specification, there are no attributes that would allow the + recipient of a session description to be informed to start multimedia + tools in a mode where they default to transmitting. Under some + circumstances it might be appropriate to define such attributes. If + this is done, an application parsing a session description containing + such attributes SHOULD either ignore them or inform the user that + joining this session will result in the automatic transmission of + multimedia data. The default behaviour for an unknown attribute is + to ignore it. + + In certain environments, it has become common for intermediary + systems to intercept and analyse session descriptions contained + within other signalling protocols. This is done for a range of + purposes, including but not limited to opening holes in firewalls to + allow media streams to pass, or to mark, prioritize, or block traffic + selectively. In some cases, such intermediary systems may modify the + session description, for example, to have the contents of the session + description match NAT bindings dynamically created. These behaviours + are NOT RECOMMENDED unless the session description is conveyed in + such a manner that allows the intermediary system to conduct proper + checks to establish the authenticity of the session description, and + the authority of its source to establish such communication sessions. + SDP by itself does not include sufficient information to enable these + checks: they depend on the encapsulating protocol (e.g., SIP or + RTSP). + + Use of the "k=" field poses a significant security risk, since it + conveys session encryption keys in the clear. SDP MUST NOT be used + to convey key material, unless it can be guaranteed that the channel + over which the SDP is delivered is both private and authenticated. + Moreover, the "k=" line provides no way to indicate or negotiate + cryptographic key algorithms. As it provides for only a single + symmetric key, rather than separate keys for confidentiality and + integrity, its utility is severely limited. The use of the "k=" line + is NOT RECOMMENDED, as discussed in Section 5.12. + + + + + + +Handley, et al. Standards Track [Page 32] + +RFC 4566 SDP July 2006 + + +8. IANA Considerations + +8.1. The "application/sdp" Media Type + + One media type registration from RFC 2327 is to be updated, as + defined below. + + To: ietf-types@iana.org + Subject: Registration of media type "application/sdp" + + Type name: application + + Subtype name: sdp + + Required parameters: None. + + Optional parameters: None. + + Encoding considerations: + SDP files are primarily UTF-8 format text. The "a=charset:" + attribute may be used to signal the presence of other + character sets in certain parts of an SDP file (see + Section 6 of RFC 4566). Arbitrary binary content cannot + be directly represented in SDP. + + Security considerations: + See Section 7 of RFC 4566 + + Interoperability considerations: + See RFC 4566 + + Published specification: + See RFC 4566 + + Applications which use this media type: + Voice over IP, video teleconferencing, streaming media, instant + messaging, among others. See also Section 3 of RFC 4566. + + Additional information: + + Magic number(s): None. + File extension(s): The extension ".sdp" is commonly used. + Macintosh File Type Code(s): "sdp " + + Person & email address to contact for further information: + Mark Handley + Colin Perkins + IETF MMUSIC working group + + + +Handley, et al. Standards Track [Page 33] + +RFC 4566 SDP July 2006 + + + Intended usage: COMMON + + Author/Change controller: + Authors of RFC 4566 + IETF MMUSIC working group delegated from the IESG + +8.2. Registration of Parameters + + There are seven field names that may be registered with IANA. Using + the terminology in the SDP specification Backus-Naur Form (BNF), they + are "media", "proto", "fmt", "att-field", "bwtype", "nettype", and + "addrtype". + +8.2.1. Media Types ("media") + + The set of media types is intended to be small and SHOULD NOT be + extended except under rare circumstances. The same rules should + apply for media names as for top-level media content types, and where + possible the same name should be registered for SDP as for MIME. For + media other than existing top-level media content types, a Standards + Track RFC MUST be produced for a new top-level content type to be + registered, and the registration MUST provide good justification why + no existing media name is appropriate (the "Standards Action" policy + of RFC 2434 [8]. + + This memo registers the media types "audio", "video", "text", + "application", and "message". + + Note: The media types "control" and "data" were listed as valid in + the previous version of this specification [6]; however, their + semantics were never fully specified and they are not widely used. + These media types have been removed in this specification, although + they still remain valid media type capabilities for a SIP user agent + as defined in RFC 3840 [24]. If these media types are considered + useful in the future, a Standards Track RFC MUST be produced to + document their use. Until that is done, applications SHOULD NOT use + these types and SHOULD NOT declare support for them in SIP + capabilities declarations (even though they exist in the registry + created by RFC 3840). + +8.2.2. Transport Protocols ("proto") + + The "proto" field describes the transport protocol used. This SHOULD + reference a standards-track protocol RFC. This memo registers three + values: "RTP/AVP" is a reference to RTP [19] used under the RTP + Profile for Audio and Video Conferences with Minimal Control [20] + + + + + +Handley, et al. Standards Track [Page 34] + +RFC 4566 SDP July 2006 + + + running over UDP/IP, "RTP/SAVP" is a reference to the Secure Real- + time Transport Protocol [23], and "udp" indicates an unspecified + protocol over UDP. + + If other RTP profiles are defined in the future, their "proto" name + SHOULD be specified in the same manner. For example, an RTP profile + whose short name is "XYZ" would be denoted by a "proto" field of + "RTP/XYZ". + + New transport protocols SHOULD be registered with IANA. + Registrations MUST reference an RFC describing the protocol. Such an + RFC MAY be Experimental or Informational, although it is preferable + that it be Standards Track. Registrations MUST also define the rules + by which their "fmt" namespace is managed (see below). + +8.2.3. Media Formats ("fmt") + + Each transport protocol, defined by the "proto" field, has an + associated "fmt" namespace that describes the media formats that may + be conveyed by that protocol. Formats cover all the possible + encodings that might want to be transported in a multimedia session. + + RTP payload formats under the "RTP/AVP" and "RTP/SAVP" profiles MUST + use the payload type number as their "fmt" value. If the payload + type number is dynamically assigned by this session description, an + additional "rtpmap" attribute MUST be included to specify the format + name and parameters as defined by the media type registration for the + payload format. It is RECOMMENDED that other RTP profiles that are + registered (in combination with RTP) as SDP transport protocols + specify the same rules for the "fmt" namespace. + + For the "udp" protocol, new formats SHOULD be registered. Use of an + existing media subtype for the format is encouraged. If no media + subtype exists, it is RECOMMENDED that a suitable one be registered + through the IETF process [31] by production of, or reference to, a + standards-track RFC that defines the transport protocol for the + format. + + For other protocols, formats MAY be registered according to the rules + of the associated "proto" specification. + + Registrations of new formats MUST specify which transport protocols + they apply to. + + + + + + + + +Handley, et al. Standards Track [Page 35] + +RFC 4566 SDP July 2006 + + +8.2.4. Attribute Names ("att-field") + + Attribute field names ("att-field") MUST be registered with IANA and + documented, because of noticeable issues due to conflicting + attributes under the same name. Unknown attributes in SDP are simply + ignored, but conflicting ones that fragment the protocol are a + serious problem. + + New attribute registrations are accepted according to the + "Specification Required" policy of RFC 2434, provided that the + specification includes the following information: + + o contact name, email address, and telephone number + + o attribute name (as it will appear in SDP) + + o long-form attribute name in English + + o type of attribute (session level, media level, or both) + + o whether the attribute value is subject to the charset attribute + + o a one-paragraph explanation of the purpose of the attribute + + o a specification of appropriate attribute values for this attribute + + The above is the minimum that IANA will accept. Attributes that are + expected to see widespread use and interoperability SHOULD be + documented with a standards-track RFC that specifies the attribute + more precisely. + + Submitters of registrations should ensure that the specification is + in the spirit of SDP attributes, most notably that the attribute is + platform independent in the sense that it makes no implicit + assumptions about operating systems and does not name specific pieces + of software in a manner that might inhibit interoperability. + + IANA has registered the following initial set of attribute names + ("att-field" values), with definitions as in Section 6 of this memo + (these definitions update those in RFC 2327): + + + + + + + + + + + +Handley, et al. Standards Track [Page 36] + +RFC 4566 SDP July 2006 + + + Name | Session or Media level? | Dependent on charset? + ----------+-------------------------+---------------------- + cat | Session | No + keywds | Session | Yes + tool | Session | No + ptime | Media | No + maxptime | Media | No + rtpmap | Media | No + recvonly | Either | No + sendrecv | Either | No + sendonly | Either | No + inactive | Either | No + orient | Media | No + type | Session | No + charset | Session | No + sdplang | Either | No + lang | Either | No + framerate | Media | No + quality | Media | No + fmtp | Media | No + +8.2.5. Bandwidth Specifiers ("bwtype") + + A proliferation of bandwidth specifiers is strongly discouraged. + + New bandwidth specifiers ("bwtype" fields) MUST be registered with + IANA. The submission MUST reference a standards-track RFC specifying + the semantics of the bandwidth specifier precisely, and indicating + when it should be used, and why the existing registered bandwidth + specifiers do not suffice. + + IANA has registered the bandwidth specifiers "CT" and "AS" with + definitions as in Section 5.8 of this memo (these definitions update + those in RFC 2327). + +8.2.6. Network Types ("nettype") + + New network types (the "nettype" field) may be registered with IANA + if SDP needs to be used in the context of non-Internet environments. + Although these are not normally the preserve of IANA, there may be + circumstances when an Internet application needs to interoperate with + a non-Internet application, such as when gatewaying an Internet + telephone call into the Public Switched Telephone Network (PSTN). + The number of network types should be small and should be rarely + extended. A new network type cannot be registered without + registering at least one address type to be used with that network + + + + + +Handley, et al. Standards Track [Page 37] + +RFC 4566 SDP July 2006 + + + type. A new network type registration MUST reference an RFC that + gives details of the network type and address type and specifies how + and when they would be used. + + IANA has registered the network type "IN" to represent the Internet, + with definition as in Sections 5.2 and 5.7 of this memo (these + definitions update those in RFC 2327). + +8.2.7. Address Types ("addrtype") + + New address types ("addrtype") may be registered with IANA. An + address type is only meaningful in the context of a network type, and + any registration of an address type MUST specify a registered network + type or be submitted along with a network type registration. A new + address type registration MUST reference an RFC giving details of the + syntax of the address type. Address types are not expected to be + registered frequently. + + IANA has registered the address types "IP4" and "IP6" with + definitions as in Sections 5.2 and 5.7 of this memo (these + definitions update those in RFC 2327). + +8.2.8. Registration Procedure + + In the RFC documentation that registers SDP "media", "proto", "fmt", + "bwtype", "nettype", and "addrtype" fields, the authors MUST include + the following information for IANA to place in the appropriate + registry: + + o contact name, email address, and telephone number + + o name being registered (as it will appear in SDP) + + o long-form name in English + + o type of name ("media", "proto", "fmt", "bwtype", "nettype", or + "addrtype") + + o a one-paragraph explanation of the purpose of the registered name + + o a reference to the specification for the registered name (this + will typically be an RFC number) + + IANA may refer any registration to the IESG for review, and may + request revisions to be made before a registration will be made. + + + + + + +Handley, et al. Standards Track [Page 38] + +RFC 4566 SDP July 2006 + + +8.3. Encryption Key Access Methods + + The IANA previously maintained a table of SDP encryption key access + method ("enckey") names. This table is obsolete, since the "k=" line + is not extensible. New registrations MUST NOT be accepted. + +9. SDP Grammar + + This section provides an Augmented BNF grammar for SDP. ABNF is + defined in [4]. + + ; SDP Syntax + session-description = proto-version + origin-field + session-name-field + information-field + uri-field + email-fields + phone-fields + connection-field + bandwidth-fields + time-fields + key-field + attribute-fields + media-descriptions + + proto-version = %x76 "=" 1*DIGIT CRLF + ;this memo describes version 0 + + origin-field = %x6f "=" username SP sess-id SP sess-version SP + nettype SP addrtype SP unicast-address CRLF + + session-name-field = %x73 "=" text CRLF + + information-field = [%x69 "=" text CRLF] + + uri-field = [%x75 "=" uri CRLF] + + email-fields = *(%x65 "=" email-address CRLF) + + phone-fields = *(%x70 "=" phone-number CRLF) + + connection-field = [%x63 "=" nettype SP addrtype SP + connection-address CRLF] + ;a connection field must be present + ;in every media description or at the + ;session-level + + + + +Handley, et al. Standards Track [Page 39] + +RFC 4566 SDP July 2006 + + + bandwidth-fields = *(%x62 "=" bwtype ":" bandwidth CRLF) + + time-fields = 1*( %x74 "=" start-time SP stop-time + *(CRLF repeat-fields) CRLF) + [zone-adjustments CRLF] + + repeat-fields = %x72 "=" repeat-interval SP typed-time + 1*(SP typed-time) + + zone-adjustments = %x7a "=" time SP ["-"] typed-time + *(SP time SP ["-"] typed-time) + + key-field = [%x6b "=" key-type CRLF] + + attribute-fields = *(%x61 "=" attribute CRLF) + + media-descriptions = *( media-field + information-field + *connection-field + bandwidth-fields + key-field + attribute-fields ) + + media-field = %x6d "=" media SP port ["/" integer] + SP proto 1*(SP fmt) CRLF + + ; sub-rules of 'o=' + username = non-ws-string + ;pretty wide definition, but doesn't + ;include space + + sess-id = 1*DIGIT + ;should be unique for this username/host + + sess-version = 1*DIGIT + + nettype = token + ;typically "IN" + + addrtype = token + ;typically "IP4" or "IP6" + + ; sub-rules of 'u=' + uri = URI-reference + ; see RFC 3986 + + + + + + +Handley, et al. Standards Track [Page 40] + +RFC 4566 SDP July 2006 + + + ; sub-rules of 'e=', see RFC 2822 for definitions + email-address = address-and-comment / dispname-and-address + / addr-spec + address-and-comment = addr-spec 1*SP "(" 1*email-safe ")" + dispname-and-address = 1*email-safe 1*SP "<" addr-spec ">" + + ; sub-rules of 'p=' + phone-number = phone *SP "(" 1*email-safe ")" / + 1*email-safe "<" phone ">" / + phone + + phone = ["+"] DIGIT 1*(SP / "-" / DIGIT) + + ; sub-rules of 'c=' + connection-address = multicast-address / unicast-address + + ; sub-rules of 'b=' + bwtype = token + + bandwidth = 1*DIGIT + + ; sub-rules of 't=' + start-time = time / "0" + + stop-time = time / "0" + + time = POS-DIGIT 9*DIGIT + ; Decimal representation of NTP time in + ; seconds since 1900. The representation + ; of NTP time is an unbounded length field + ; containing at least 10 digits. Unlike the + ; 64-bit representation used elsewhere, time + ; in SDP does not wrap in the year 2036. + + ; sub-rules of 'r=' and 'z=' + repeat-interval = POS-DIGIT *DIGIT [fixed-len-time-unit] + + typed-time = 1*DIGIT [fixed-len-time-unit] + + fixed-len-time-unit = %x64 / %x68 / %x6d / %x73 + + ; sub-rules of 'k=' + key-type = %x70 %x72 %x6f %x6d %x70 %x74 / ; "prompt" + %x63 %x6c %x65 %x61 %x72 ":" text / ; "clear:" + %x62 %x61 %x73 %x65 "64:" base64 / ; "base64:" + %x75 %x72 %x69 ":" uri ; "uri:" + + base64 = *base64-unit [base64-pad] + + + +Handley, et al. Standards Track [Page 41] + +RFC 4566 SDP July 2006 + + + base64-unit = 4base64-char + base64-pad = 2base64-char "==" / 3base64-char "=" + base64-char = ALPHA / DIGIT / "+" / "/" + + ; sub-rules of 'a=' + attribute = (att-field ":" att-value) / att-field + + att-field = token + + att-value = byte-string + + ; sub-rules of 'm=' + media = token + ;typically "audio", "video", "text", or + ;"application" + + fmt = token + ;typically an RTP payload type for audio + ;and video media + + proto = token *("/" token) + ;typically "RTP/AVP" or "udp" + + port = 1*DIGIT + + ; generic sub-rules: addressing + unicast-address = IP4-address / IP6-address / FQDN / extn-addr + + multicast-address = IP4-multicast / IP6-multicast / FQDN + / extn-addr + + IP4-multicast = m1 3( "." decimal-uchar ) + "/" ttl [ "/" integer ] + ; IPv4 multicast addresses may be in the + ; range 224.0.0.0 to 239.255.255.255 + + m1 = ("22" ("4"/"5"/"6"/"7"/"8"/"9")) / + ("23" DIGIT ) + + IP6-multicast = hexpart [ "/" integer ] + ; IPv6 address starting with FF + + ttl = (POS-DIGIT *2DIGIT) / "0" + + FQDN = 4*(alpha-numeric / "-" / ".") + ; fully qualified domain name as specified + ; in RFC 1035 (and updates) + + + + +Handley, et al. Standards Track [Page 42] + +RFC 4566 SDP July 2006 + + + IP4-address = b1 3("." decimal-uchar) + + b1 = decimal-uchar + ; less than "224" + + ; The following is consistent with RFC 2373 [30], Appendix B. + IP6-address = hexpart [ ":" IP4-address ] + + hexpart = hexseq / hexseq "::" [ hexseq ] / + "::" [ hexseq ] + + hexseq = hex4 *( ":" hex4) + + hex4 = 1*4HEXDIG + + ; Generic for other address families + extn-addr = non-ws-string + + ; generic sub-rules: datatypes + text = byte-string + ;default is to interpret this as UTF8 text. + ;ISO 8859-1 requires "a=charset:ISO-8859-1" + ;session-level attribute to be used + + byte-string = 1*(%x01-09/%x0B-0C/%x0E-FF) + ;any byte except NUL, CR, or LF + + non-ws-string = 1*(VCHAR/%x80-FF) + ;string of visible characters + + token-char = %x21 / %x23-27 / %x2A-2B / %x2D-2E / %x30-39 + / %x41-5A / %x5E-7E + + token = 1*(token-char) + + email-safe = %x01-09/%x0B-0C/%x0E-27/%x2A-3B/%x3D/%x3F-FF + ;any byte except NUL, CR, LF, or the quoting + ;characters ()<> + + integer = POS-DIGIT *DIGIT + + ; generic sub-rules: primitives + alpha-numeric = ALPHA / DIGIT + + POS-DIGIT = %x31-39 ; 1 - 9 + + + + + + +Handley, et al. Standards Track [Page 43] + +RFC 4566 SDP July 2006 + + + decimal-uchar = DIGIT + / POS-DIGIT DIGIT + / ("1" 2*(DIGIT)) + / ("2" ("0"/"1"/"2"/"3"/"4") DIGIT) + / ("2" "5" ("0"/"1"/"2"/"3"/"4"/"5")) + + ; external references: + ; ALPHA, DIGIT, CRLF, SP, VCHAR: from RFC 4234 + ; URI-reference: from RFC 3986 + ; addr-spec: from RFC 2822 + +10. Summary of Changes from RFC 2327 + + The memo has been significantly restructured, incorporating a large + number of clarifications to the specification in light of use. With + the exception of those items noted below, the changes to the memo are + intended to be backward-compatible clarifications. However, due to + inconsistencies and unclear definitions in RFC 2327 it is likely that + some implementations interpreted that memo in ways that differ from + this version of SDP. + + The ABNF grammar in Section 9 has been extensively revised and + updated, correcting a number of mistakes and incorporating the RFC + 3266 IPv6 extensions. Known inconsistencies between the grammar and + the specification text have been resolved. + + A media type registration for SDP is included. Requirements for the + registration of attributes and other parameters with IANA have been + clarified and tightened (Section 8). It is noted that "text" and + "message" are valid media types for use with SDP, but that "control" + and "data" are under-specified and deprecated. + + RFC 2119 terms are now used throughout to specify requirements + levels. Certain of those requirements, in particular in relation to + parameter registration, are stricter than those in RFC 2327. + + The "RTP/SAVP" RTP profile and its "fmt" namespace are registered. + + The attributes "a=inactive" and "a=maxptime" have been added. + + RFC 2327 mandated that either "e=" or "p=" was required. Both are + now optional, to reflect actual usage. + + The significant limitations of the "k=" field are noted, and its use + is deprecated. + + Most uses of the "x-" prefix notation for experimental parameters are + disallowed and the other uses are deprecated. + + + +Handley, et al. Standards Track [Page 44] + +RFC 4566 SDP July 2006 + + +11. Acknowledgements + + Many people in the IETF Multiparty Multimedia Session Control + (MMUSIC) working group have made comments and suggestions + contributing to this document. In particular, we would like to thank + Eve Schooler, Steve Casner, Bill Fenner, Allison Mankin, Ross + Finlayson, Peter Parnes, Joerg Ott, Carsten Bormann, Steve Hanna, + Jonathan Lennox, Keith Drage, Sean Olson, Bernie Hoeneisen, Jonathan + Rosenberg, John Elwell, Flemming Andreasen, Jon Peterson, and Spencer + Dawkins. + +12. References + +12.1. Normative References + + [1] Mockapetris, P., "Domain names - concepts and facilities", STD + 13, RFC 1034, November 1987. + + [2] Mockapetris, P., "Domain names - implementation and + specification", STD 13, RFC 1035, November 1987. + + [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [4] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [5] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD + 63, RFC 3629, November 2003. + + [6] Handley, M. and V. Jacobson, "SDP: Session Description + Protocol", RFC 2327, April 1998. + + [7] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, + January 2005. + + [8] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA + Considerations Section in RFCs", BCP 26, RFC 2434, October + 1998. + + [9] Alvestrand, H., "Tags for the Identification of Languages", BCP + 47, RFC 3066, January 2001. + + [10] Olson, S., Camarillo, G., and A. Roach, "Support for IPv6 in + Session Description Protocol (SDP)", RFC 3266, June 2002. + + + + + +Handley, et al. Standards Track [Page 45] + +RFC 4566 SDP July 2006 + + + [11] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", RFC + 3490, March 2003. + + [12] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", + RFC 3548, July 2003. + +12.2. Informative References + + [13] Mills, D., "Network Time Protocol (Version 3) Specification, + Implementation", RFC 1305, March 1992. + + [14] Handley, M., Perkins, C., and E. Whelan, "Session Announcement + Protocol", RFC 2974, October 2000. + + [15] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., + Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: + Session Initiation Protocol", RFC 3261, June 2002. + + [16] Schulzrinne, H., Rao, A., and R. Lanphier, "Real Time Streaming + Protocol (RTSP)", RFC 2326, April 1998. + + [17] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with + Session Description Protocol (SDP)", RFC 3264, June 2002. + + [18] Camarillo, G., Eriksson, G., Holler, J., and H. Schulzrinne, + "Grouping of Media Lines in the Session Description Protocol + (SDP)", RFC 3388, December 2002. + + [19] Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson, + "RTP: A Transport Protocol for Real-Time Applications", STD 64, + RFC 3550, July 2003. + + [20] Schulzrinne, H. and S. Casner, "RTP Profile for Audio and Video + Conferences with Minimal Control", STD 65, RFC 3551, July 2003. + + [21] Casner, S., "Session Description Protocol (SDP) Bandwidth + Modifiers for RTP Control Protocol (RTCP) Bandwidth", RFC 3556, + July 2003. + + [22] Huitema, C., "Real Time Control Protocol (RTCP) attribute in + Session Description Protocol (SDP)", RFC 3605, October 2003. + + [23] Baugher, M., McGrew, D., Naslund, M., Carrara, E., and K. + Norrman, "The Secure Real-time Transport Protocol (SRTP)", RFC + 3711, March 2004. + + + + + +Handley, et al. Standards Track [Page 46] + +RFC 4566 SDP July 2006 + + + [24] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Indicating + User Agent Capabilities in the Session Initiation Protocol + (SIP)", RFC 3840, August 2004. + + [25] Westerlund, M., "A Transport Independent Bandwidth Modifier for + the Session Description Protocol (SDP)", RFC 3890, September + 2004. + + [26] International Telecommunication Union, "H.323 extended for + loosely coupled conferences", ITU Recommendation H.332, + September 1998. + + [27] Arkko, J., Carrara, E., Lindholm, F., Naslund, M., and K. + Norrman, "Key Management Extensions for Session Description + Protocol (SDP) and Real Time Streaming Protocol (RTSP)", RFC + 4567, July 2006. + + [28] Andreasen, F., Baugher, M., and D. Wing, "Session Description + Protocol (SDP) Security Descriptions for Media Streams", RFC + 4568, July 2006. + + [29] Resnick, P., "Internet Message Format", RFC 2822, April 2001. + + [30] Hinden, R. and S. Deering, "IP Version 6 Addressing + Architecture", RFC 2373, July 1998. + + [31] Freed, N. and J. Klensin, "Media Type Specifications and + Registration Procedures", BCP 13, RFC 4288, December 2005. + + + + + + + + + + + + + + + + + + + + + + + +Handley, et al. Standards Track [Page 47] + +RFC 4566 SDP July 2006 + + +Authors' Addresses + + Mark Handley + University College London + Department of Computer Science + Gower Street + London WC1E 6BT + UK + + EMail: M.Handley@cs.ucl.ac.uk + + + Van Jacobson + Packet Design + 2465 Latham Street + Mountain View, CA 94040 + USA + + EMail: van@packetdesign.com + + + Colin Perkins + University of Glasgow + Department of Computing Science + 17 Lilybank Gardens + Glasgow G12 8QQ + UK + + EMail: csp@csperkins.org + + + + + + + + + + + + + + + + + + + + + + +Handley, et al. Standards Track [Page 48] + +RFC 4566 SDP July 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM 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. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Handley, et al. Standards Track [Page 49] + -- cgit v1.2.3