Media Gateway Control (Megaco) Michael Brown Internet Draft Peter Blatherwick Document: draft-ietf-megaco-h248g-00.txt Nortel Networks Category: Standards Track July 2000 H.248 Annex G (Pre-Decision White Document) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [1]. 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. 1. Abstract This document reproduces the content of the ITU-T Study Group 16 White Document draft of H.248 Annex G, which is scheduled for decision in Geneva in November 2000. H.248 Annex G provides packages for "User Interface Elements and Actions". Specifically, the packages in Annex G include: - Display - Key - Keypad - Label key - Function key - Indicator - Soft key - Ancillary input This document is submitted for IETF comment prior to ITU-T decision, in accordance with procedures currently being negotiated between ITU-T Study Group and ISOC on behalf of the IETF. Brown Standards Track - Expires January 2001 1 H.248 Annex G (White Document draft) July 2000 2. 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 [2]. 3. Introduction The following packages define a framework for specifying capabilities associated with user interface elements, such as text display, keys, dynamically labeled keys, indicators and alphanumeric input. In addition, specific extension packages for telephone keypads and telephone function keys are defined. 4. Proposed Packages 4.1 Display Package PackageID: dis, 0x0014 Version: 1 Extends: None This package defines properties and signals associated with text display user interface elements. See Procedures for details of operation. 4.1.1 Properties Number of rows PropertyID: nrows (0x0001) Description: Maximum number of rows on the display Type: integer Defined in: TerminationState. Characteristics: read only. Number of columns PropertyID: ncols (0x0002) Description: Maximum number of columns on the display Type: integer Defined in: TerminationState. Characteristics: read only. Supported unicode code pages PropertyID: cdpgs (0x0003) Description: a list of supported unicode pages Type: list of enumerated type Defined in: TerminationState. Characteristics: read only. Brown Standards Track - Expires January 2000 2 H.248 Annex G (White Document draft) July 2000 Example: if the text display element supports U+2500 ->U+25ff, U+2600 ->U+26ff and U+2700 -> U+277f, this property would return "250, 258, 260, 268, 270" in cdpgs. Unicode page U+0000 -> U+00ff shall be supported in all implementations. Cursor row position PropertyID: cr (0x0004) Type: integer Defined in: TerminationState. Characteristics: read and write: Cursor column position PropertyID: cc (0x0005) Type: integer Defined in: TerminationState. Characteristics: read and write. Note: row and column numbering begin at 0. A display's origin is row 0, column 0. The origin is at the top left corner 4.1.2 Events None 4.1.3 Signals 4.1.3.1 Display SignalID: di (0x0001) Description: Display text. Parameters: Row ParameterID: r (0x0001) Type: Integer Insertion point row, relative to 0,0. Default is current cursor position. Column ParameterID: c (0x0002) Type: Integer Insertion point column, relative to 0,0. Default is current cursor position. String ParameterID: str (0x0003) Type: String Brown Standards Track - Expires January 2000 3 H.248 Annex G (White Document draft) July 2000 Default is empty string (moves cursor position). Attribute ParameterID: a (0x0004) Type: enumerated or list of enumerated Possible values: plain (0x0001), blink (0x0002), invert (0x0003), underline (0x0004) Default Value: Plain 4.1.3.2 Clear Display SignalID: cld, 0x0002 Description: This signal clears the entire display and resets the current cursor position to the origin (row 0, column 0). Parameters: None 4.1.4 Statistics None 4.1.5 Procedures Unicode is supported to provide for multiple languages. The Unicode Standard, Version 2.0 or ISO/IEC 10646-1:1993 [xxx] shall be the definitive standard intended when the term Unicode is used within the context of this document. All text display elements shall at least support the Unicode pages U+0000 -> U+00ff as the basic character set. All text strings shall be encoded using UTF-8 as defined in ISO/IEC 10646 AM1 [xxx]. In the Display signal, text will be inserted beginning at the row and column given in the signal parameters, relative to 0,0. If no row and column parameters are given, the text will be inserted starting at the current cursor position. The current cursor position will always be advanced to the position immediately after the last character inserted. Carriage return is supported in-string, and moves the text input to the beginning of the next line, clearing the remainder (if any) of the current line. Text wrapping is not provided. A string will not word wrap to the next row. If a string cannot fit into the current row, it will be truncated without warning. The attribute parameter applies to all characters contained in the current signal. If no attribute is provided, plain text will be displayed. For example, to turn on an attribute in the middle of a Brown Standards Track - Expires January 2000 4 H.248 Annex G (White Document draft) July 2000 string, one would send a signal with a beginning sub-string of plain text, follow by a signal with the desired attribute(s) for the middle sub-string, and finishing with the signal containing the remaining sub-string of plain text. 4.2 Key Package PackageID: key, 0x0015 Version: 1 Extends: none This package defines the basic behavior of key user interface elements. Specific key IDs are selected by name (keyid) from the list of keys. This package does not specify parameter values for keys. Intended to be extended by other packages which have key behavior. 4.2.1 Properties None. 4.2.2 Events 4.2.2.1 keydown EventID: kd (0x0001) Detects key was pressed. EventDescriptor parameters: None. ObservedEventDescriptor parameters: Key name ParameterId: keyid (0x0001) Type: Enumeration Possible values: No values are specified in this package. Extensions to this package add possible values for keyid. 4.2.2.2 keyup EventID: ku (0x0002) Detects key up. EventDescriptor parameters: None. ObservedEventDescriptor parameters: Key name Brown Standards Track - Expires January 2000 5 H.248 Annex G (White Document draft) July 2000 ParameterId: keyid (0x0001) Type: Enumeration Possible values: No possible values are specified in this package. Extensions to this package would add possible values for keyid. Duration ParameterId: duration (0x0002) Type: Integer Units: miliseconds Description: Key press duration (key down to key up). 4.2.3 Signals None 4.2.4 Statistics None 4.2.5 Procedures None. 4.3 Keypad Package PackageID: kp, 0x0016 Version: 1 Extends: key version 1 This package defines the keypad user interface element. The keypad package is used to represent a standard 10 digit key pad plus the '*', '#', A, B, C, and D keys. Keypad may be used in conjunction with digit maps, similar to dtmf tone detection package. Keypad entry can be directed to provide audio and/or display feedback to other user interface terminations, for example to automatically provide audible feedback of keypad touches to the user or to automatically update display. Additional Keyid values, and mapping to DigitMap symbols (as described in Megaco/H.248 Protocol, section 7.1.14): Name Description DigitMap Symbol k0 (0x0001) Keypad digit 0 `0' k1 (0x0002) Keypad digit 1 `1' k2 (0x0003) Keypad digit 2 `2' k3 (0x0004) Keypad digit 3 `3' k4 (0x0005) Keypad digit 4 `4' Brown Standards Track - Expires January 2000 6 H.248 Annex G (White Document draft) July 2000 k5 (0x0006) Keypad digit 5 `5' k6 (0x0007) Keypad digit 6 `6' k7 (0x0008) Keypad digit 7 `7' k8 (0x0009) Keypad digit 8 `8' k9 (0x000a) Keypad digit 9 `9' ks (0x000b) Keypad digit * `E' or `e' ko (0x000c) Keypad digit # `F' or `f' kA (0x000d) Keypad digit A `A' or `a' kB (0x000e) Keypad digit B `B' or `b' kC (0x000f) Keypad digit C `C' or `c' kD (0x0010) Keypad digit D `D' or `d' 4.3.1 Properties None. 4.3.2 Events 4.3.2.1 DigitMap Completion Event EventID: ce (0x0001) Generated when a digit map completes as described in Megaco/H.248 Protocol section 7.1.14. Form of this event is identical to its definition in DTMF Detection Package (dd), Megaco/H.248 Protocol section E.6.2. EventsDescriptor parameters: Digit map processing is activated only if a digit map parameter is present, specifying a digit map by name or by value. Other parameters such as a KeepActive flag or embedded Events or Signals Descriptors may be present. ObservedEventsDescriptor parameters: DigitString ParameterID: ds (0x0001) Type: String of digit map symbols (possibly empty) returned as a quotedString. Possible values: a sequence of the characters "0" through "9", "A" through "F", and the long duration modifier "Z". Description: the portion of the current dial string as described in Megaco/H.248 Protocol section 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 Brown Standards Track - Expires January 2000 7 H.248 Annex G (White Document draft) July 2000 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 Megaco/H.248 Protocol section 7.1.14. 4.3.3 Signals None. 4.3.4 Procedures None. 4.4 Label Key Package PackageID: labelkey, 0x0017 Version: 1 Extends: key version 1 This package defines the basic behavior of labeled key user interface elements. Key labels may be used, for example, to provide information to the MGC regarding pre-configured telephone key assignments, allowing telephone moves and changes outside the initial administrative domain without requiring re-configuration of keys. May also be used to provide static label information on the telephone user interface, identifying key function to the user without the need for manual labeling. Specific keys are addressed by name (keyid) from the list of keys. This package does not specify parameter values for keys. Intended to be extended by other packages which have key behavior. 4.4.1 Properties Key List Property ID: keylist (0x0001) Type: String, using the following format {{keyid, label, label_size}, ...} Description: Keylist property allows auditing and setting of keyid/label mapping. Label size is also given. This package defines syntax only; no specific keys are defined. See derived packages for the actual keyid lists. Defined in: TerminationState Characteristics: read and write Brown Standards Track - Expires January 2000 8 H.248 Annex G (White Document draft) July 2000 4.4.2 Events None. 4.4.3 Signals None. 4.4.4 Procedures None. 4.5 Function Key Package PackageID: kf, 0x0018 Version: 1 Extends: labelkey version 1 Common telephone function keys are defined in this package. This allows, for example, line keys and other function keys to be implemented without specific knowledge of the physical layout of the telephone. Additional keyid values in keyup and keydown events and keylist property: Name Description kh (0x0011) Hookswitch kl (0x0012) Hold kc (0x0013) Conference kt (0x0014) Transfer l001 - l999 (0x0015-0x03fb) Set of line keys f001 - f999 (0x03fc-0x07e2) Set of assignable function keys 4.5.1 Procedures Function keys may have well known names (keyid) associated with function, for example "hookswitch", "hold", etc. These well know names identify the purpose of the particular key on the actual device. Function keys may also be assigned a label identifier by the MGC. This approach avoids assumptions and/or the requirement for application level knowledge of device-specific configuration of the physical resources to derive intended function of keys. Function Keys can be co-related with physically associated Indicators using Function Key keyid and Indicator indid. If the IDs are identical, the MGC application can safely assume that the key and indicator are physically (or otherwise) associated on the actual device. Again, this avoids assumptions and/or the requirement for Brown Standards Track - Expires January 2000 9 H.248 Annex G (White Document draft) July 2000 application level knowledge of device-specific layout of the physical resources. See also the Indicator package (ind). NOTE: The key sense of hookswitch (keyid=kh) is a special case. Key up indicates the hookswitch is depressed (i.e. handset is nominally on hook). Key down indicates the hookswitch is lifted (i.e. handset is nominally off hook). This allows for sensible use of the duration parameter in the keyup event which will normally give the duration the handset was off-hook. 4.6 Indicator Package PackageID: ind, 0x0019 Version: 1 Extends: None This package defines the basic behavior of indicator user interface elements. Specific indicators are addressed by name (indid) from the list of indicators. Indicators may have well- known names (indid) associated with function, for example "message waiting", "hold", "line active", etc. This allows, for example, indicators to be implemented without specific knowledge of the physical layout of the telephone. Intended to be possible to extend by other packages which have indicator behavior. 4.6.1 Properties Indicator List Property ID: indlist (0x0001) Type: String, using the following format {{indid, label, label_size}, ...} Description: Indicator List property allows auditing and setting of indid/label mapping. Label size is also given. This package defines syntax only; no specific indicators are defined. See derived packages for the actual indid lists. Defined in: TerminationState. Characteristics: read and write. 4.6.2 Events None 4.6.3 Signals 4.6.3.1 SetIndactor SignalID: is (0x0001) Set indicator state. Brown Standards Track - Expires January 2000 10 H.248 Annex G (White Document draft) July 2000 Parameters: Indicator name ParameterId: Indid (0x0001) Type: Enumeration. Possible values: Name Description il (0x0001) Hold ic (0x0002) Conference l001-l999 (0x0003- Set of line indicators 0x03f9) f001-f999 (0x03fa- Set of assignable 0x07e0) function indicators ir (0x07e1) Ringer/Alerter indication im (0x07e2) Message waiting indicator Indicator state ParameterId: state (0x0002) Type: Enumeration. Possible values: On (0x0001), off (0x0002), blink (0x0003), fast_blink (0x0004), slow_blink (0x0005). Default is off. 4.6.4 Statistics None 4.6.5 Procedures Indicators can be co-related with physically associated Function Keys using Indicator indid and Function Key keyid. If the IDs are identical, the MGC application can safely assume that the key and indicator are physically (or otherwise) associated on the actual device. This avoids assumptions and/or the requirement for application level knowledge of device-specific layout of the physical resources. See also the Function Keys package (kf). 4.7 Soft Key Package PackageID: ks, 0x001a Version: 1 Extends: labelkey version 1 Brown Standards Track - Expires January 2000 11 H.248 Annex G (White Document draft) July 2000 Softkeys are a combination of a function key and a display user interface element, sharing some behavior of each. Softkeys are intended to be dynamically updated by the MGC, based on the current state and context of the application controlling the MG. Since the display aspect and the key aspect are explicitely bound together, this avoids assumptions and/or the requirement for application level knowledge of device-specific layout of the physical resources. See Procedures for details. 4.7.1 Properties Number of softkeys PropertyID: nskeys (0x0001) PropertyType: Integer Characteristics: read only Defined in: TerminationState Description: Maximum number of individual soft keys. Display size PropertyID: sz (0x0002) Type: Integer Characteristics: read only Defined in: TerminationState Description: Maximum number of characters that can be displayed in each softkey. Supported unicode code pages PropertyID: cdpgs (0x0003) Description: a list of supported unicode pages Type: list of enumerated type Defined in: TerminationState. Characteristics: read only 4.7.2 Signals 4.7.2.1 SetDisplay SignalID: sd (0x0001) Description: Set softkey dynamic display content. Parameters: keyid Parameter ID: k (0x0001) Type: Enumeration Possible values: sk1-sk999 (0x0001-0x03e7) Brown Standards Track - Expires January 2000 12 H.248 Annex G (White Document draft) July 2000 displayContent Parameter ID: d (0x0002) Type: String 4.7.3 Procedures The display aspect is a subset of the Display (dis) package. Unicode is supported to provide for multiple languages [xxx], and all SoftKey elements shall at least support the Unicode pages U+0000 -> U+00ff as the basic character set. All text strings shall be encoded using UTF-8. If a string cannot fit into the display area, it will be truncated without warning. The key aspect, including Events and labeling, derives directly from Label Key and Key packages. Softkey identifiers (keyid) are indexed 1,2...N. N (nskeys) is the maximum number of softkeys supported by the MG implementation. Refer to the Label Key (labelkey) and Key (key) packages for further details. 4.8 Ancillary Input Package PackageID: anci, 0x001b Version: 1 Extends: none The ancillary input package is used to enter user alphanumeric information such as text input or scan data, which is forwarded to the MGC for processing. The information is presented as a Unicode character encoded in UTF-8 format [xxx]. 4.8.1 Properties None. 4.8.2 Events 4.8.2.1 Character input EventID: ch (0x0001) Description: A character has been input. EventDescriptor parameters: None ObservedEventDescriptor parameters: Input character ParameterId: id (0x0001) Type: Character (UTF-8 character) Brown Standards Track - Expires January 2000 13 H.248 Annex G (White Document draft) July 2000 4.8.3 Signals None. 4.8.4 Statistics None. 4.8.5 Procedures None. 5. Security Considerations Security considerations regarding media gateway control are discussed in section 10 of [3]. 6. References 1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. 2 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 3 ITU-T Recommendation H.248, "Gateway Control Protocol", Geneva, June 2000. Also to appear as RFC xxxx (currently draft-ietf- megaco-merged-01.txt). 7. Acknowledgments This document reflects the work of the TIA (Telecommunications Industry Association) TR-41.3.4 subcommittee under the leadership of Phil Holland. 8. Authors' Addresses C. Michael Brown (editor) Peter Blatherwick (editor) Nortel Networks Nortel Networks 4008 Chapel Hill Road P.O. Box 3511, Stn C Research Triangle Park, Ottawa, Ontario, NC USA 27709 Canada K1Y 4H7 Phone: (919) 991-7767 Phone: (613) 763-7539 Email: Email: C.Michael.Brown@nortelnetworks.com blather@nortelnetworks.com Brown Standards Track - Expires January 2000 14