path: root/doc/rfc/rfc3149.txt

Network Working Group                                         A. Srinath
Request for Comments: 3149                                   G. Levendel
Category: Informational                                         K. Fritz
                                                        Sylantro Systems
                                                           R. Kalyanaram
                                                           Wipro Systems
                                                          September 2001


                      MGCP Business Phone Packages

Status of this Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

Abstract

   This document describes a collection of MGCP (Media Gateway Control
   Protocol) packages that can be used to take advantage of the feature
   keys and displays on digital business phones and IP-Phones.

IESG Note

   This document is being published for the information of the
   community.  It describes a non-IETF protocol that is currently being
   deployed in a number of products.  Implementers should be aware that
   the IETF Megaco working group and the ITU-T Study Group 16 have
   produced a standards track RFC "Megaco Protocol Version 1.0" (RFC
   3015, also published as ITU recommendation H.248) which addresses the
   same problem space and are developing extensions to that protocol for
   functions of this type.

Table of Contents

   1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . 3
       1.1 General Information. . . . . . . . . . . . . . . . . . 4
       1.2 Objectives . . . . . . . . . . . . . . . . . . . . . . 5
   2. MGCP Packages for Business Phones . . . . . . . . . . . . . 5
       2.1 Feature Key Package. . . . . . . . . . . . . . . . . . 6
       2.2 Business Phone Package . . . . . . . . . . . . . . . . 9
       2.3 Display XML Package. . . . . . . . . . . . . . . . . . 9




Srinath, et al.              Informational                      [Page 1]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   3. Endpoint Naming and Phone Type Determination. . . . . . . .10
   4. Functions that should be Locally Implemented. . . . . . . .11
       4.1 Volume Control . . . . . . . . . . . . . . . . . . . .11
       4.2 Audio Path . . . . . . . . . . . . . . . . . . . . . .11
       4.3 Microphone mute button and light . . . . . . . . . . .11
   5. XML Package Support . . . . . . . . . . . . . . . . . . . .12
       5.1 XML Documents. . . . . . . . . . . . . . . . . . . . .12
       5.2 XML Requests . . . . . . . . . . . . . . . . . . . . .13
       5.3 XML Request History. . . . . . . . . . . . . . . . . .15
       5.4 XML Events . . . . . . . . . . . . . . . . . . . . . .15
       5.5 XML Tags . . . . . . . . . . . . . . . . . . . . . . .15
       5.5.1 XML Tag. . . . . . . . . . . . . . . . . . . . . . .17
       5.5.2 Card Tag . . . . . . . . . . . . . . . . . . . . . .18
       5.5.3 P Tag. . . . . . . . . . . . . . . . . . . . . . . .18
       5.5.4 Select Tag . . . . . . . . . . . . . . . . . . . . .18
       5.5.5 Option Tag . . . . . . . . . . . . . . . . . . . . .19
       5.5.6 Input Tag. . . . . . . . . . . . . . . . . . . . . .20
       5.5.7 Echo Tag . . . . . . . . . . . . . . . . . . . . . .20
       5.5.8 Calltimer Tag. . . . . . . . . . . . . . . . . . . .21
       5.5.9 Time Tag . . . . . . . . . . . . . . . . . . . . . .21
       5.5.10 Timer Tag . . . . . . . . . . . . . . . . . . . . .21
       5.5.11 Do Tag. . . . . . . . . . . . . . . . . . . . . . .22
       5.5.12 Go Tag. . . . . . . . . . . . . . . . . . . . . . .22
       5.5.13 Prev Tag. . . . . . . . . . . . . . . . . . . . . .23
   6. Security Considerations . . . . . . . . . . . . . . . . . .23
   7. Acknowledgements. . . . . . . . . . . . . . . . . . . . . .23
   8. References. . . . . . . . . . . . . . . . . . . . . . . . .23
   9. Authors' Addresses. . . . . . . . . . . . . . . . . . . . .24
   Appendix A: BNF description of XML grammar . . . . . . . . . .25
   Appendix B: Sample XML Documents, Renderings and Events. . . .27
       B.1 Sample Deck 1 (Itemized List Box). . . . . . . . . . .27
       B.2 Sample Deck 2 (Enumerated List Box). . . . . . . . . .28
       B.3 Sample Deck 3 (Text Box) . . . . . . . . . . . . . . .29
       B.4 Sample Deck 4 (Echo Box) . . . . . . . . . . . . . . .30
       B.5 Sample Deck 5 (Input Box). . . . . . . . . . . . . . .31
       B.6 Sample Deck 6 (Timers) . . . . . . . . . . . . . . . .32
   Appendix C: Example usage of MGCP extension packages . . . . .33
       C.1 Setting Labels on Phone. . . . . . . . . . . . . . . .33
       C.2 Activating a Feature on a Feature Key. . . . . . . . .33
       C.3 Generating a Call using Feature Key as a Line Key. . .35
       C.4 Determining Make and Model of a Phone. . . . . . . . .38
   Appendix D: BNF Description of X-UA Parameter. . . . . . . . .39
   Full Copyright Statement . . . . . . . . . . . . . . . . . . .41








Srinath, et al.              Informational                      [Page 2]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


1. Introduction

   The Media Gateway Control Protocol (MGCP) Version 1.0 defines a
   protocol for controlling Voice over IP Telephony Gateways from
   external call control elements.  As defined, it supports external
   call control elements called Media Gateway Controllers and assumes
   that these Gateways can support collections of endpoints.  The
   endpoint type known as an "analog line" can be used as a client
   interface to provide service to a basic analog telephone unit.  The
   packages that are currently defined to handle events and signals
   allow for only a basic level of audio connection and signaling to
   such endpoints.  To handle more advanced capabilities commonly found
   on business phones such as feature keys, speaker phones and displays,
   it is necessary to define additional packages as extensions to the
   MGCP protocol.

   These packages, when used in conjunction with the packages currently
   defined in RFC 2705 (Media Gateway Control Protocol Version 1.0) [1],
   allow an MGCP Call Agent to control business phone endpoints.

   The MGCP extension packages defined here are as follows:

      - Feature Key Package

         o  Groups events and signals associated with the additional
            keys available on business phones that are non-DTMF and not
            locally-implemented.  These include:

            -  Feature Key event to allow mapping of key numbers to
               features.
            -  Key State signal to indicate the state of feature keys.
            -  Set Label signal to display a label on the LCD next to a
               feature key.

      -  Business Phone Package

         o  Groups signals that are not related to feature keys,
            including:

            -  Force Off-hook and Force On-hook signals to allow
               application integration with speaker phone capabilities.
            -  Beep signal to play a beep on the phone.

      - Display XML Package

         o  Used to convey XML [2] script data to and from the phone to
            control the display and assign functions to the display
            soft-keys for event reporting.  These include:



Srinath, et al.              Informational                      [Page 3]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


            -  XML event to report user input or selection.
            -  XML signal to render text to the LCD display.

   An MGCP experimental parameter is also defined here:

      -  User Agent Parameter

         o  Used to determine the make and model of a phone

1.1     General Information

   A generic business phone typically includes a number of features that
   provide access to additional functionality useful in a business
   environment.  Beyond the basic handset and dial pad, a business phone
   may optionally include a number of fixed buttons, line keys and
   programmable feature keys, along with an LCD display and soft-keys.

   Specific examples of items that may be included on a business phone
   are:

   - Speaker phone microphone and speaker
   - Speaker phone button and light
   - Messages button and light
   - Redial button
   - Volume up and down buttons
   - Hold button and light
   - Transfer button and light
   - Forward button and light
   - Conference button and light
   - Microphone mute button and light
   - Multiple feature keys with lights
   - Multi-line LCD Display
   - Multiple soft-keys next to the LCD display
   - Navigation keys

   Examples of fixed buttons functionality are 'hold', 'transfer',
   'redial', 'conference', 'call-logs', 'directories', and 'messages'.
   Fixed buttons may vary from phone to phone.  While the packages
   described here would allow these to be reported to a Call Agent, the
   Call Agent would also need to determine which feature key number
   corresponds to a particular pre-assigned function.

   Since MGCP assumes a call control architecture where the call control
   "intelligence" is outside the Gateways and handled by external call
   control elements, the programming of the feature keys would be
   resident in the Call Agent.  If the user were to press the 'hold'
   button, the phone would simply report the key number, and the burden




Srinath, et al.              Informational                      [Page 4]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   of recognizing that this feature key is assigned to the 'hold'
   function, and providing such functionality, is left to the Call
   Agent.

1.2 Objectives

   The high level objectives that were considered in generating the
   packages described here are:

   -  Provide a minimum set of extension packages to the MGCP Version
      1.0 protocol to allow applications to take advantage of generic
      business phone capabilities.

   -  Provide event and control extensions at a sufficiently low level
      for an application to implement generic business phone functions
      without generating excessive or redundant data traffic.  (e.g.,
      sending feature key information on both press and release would be
      a "don't care" for a Call Agent.  All it cares about is that the
      key was pressed.)

   -  Provide a mechanism to interface with LCD displays and allow the
      flexibility to accommodate a variety of application needs and the
      different types of displays available.

2. MGCP Packages for Business Phones

   The following packages should be implemented for business phones.
   The G,D,L, and H packages are defined in RFC 2705 [1].  Packages KY,
   BP and XML are defined in this specification.

    ______________________________________________________
   | Package                      |   Name  | Defined     |
   |______________________________|_________|_____________|
   | Generic Media Package        |   G     |in RFC 2705  |
   | DTMF package                 |   D     |in RFC 2705  |
   | Line Package                 |   L     |in RFC 2705  |
   | Handset Package              |   H     |in RFC 2705  |
   | Feature Key Package          |   KY    |in this spec |
   | Business Phone Package       |   BP    |in this spec |
   | Display XML Package          |   XML   |in this spec |
   |______________________________|_________|_____________|

   In the tables of events for each package, there are five columns:

   Symbol: the unique symbol used for the event
   Definition: a short description of the event





Srinath, et al.              Informational                      [Page 5]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   R: an x appears in this column if the event can be requested by the
      Call Agent.

   S: if nothing appears in this column for an event, then the event
      cannot be signalled on command by the Call Agent.  Otherwise, the
      following symbols identify the type of signal:

      OO On/Off signal.  The signal is turned on until requested by the
         Call Agent to turn it off, and vice versa.

      TO Timeout signal.  The signal lasts for a given duration unless
         it is superseded by a new signal.

      BR Brief signal.  The event has a short, known duration.

      Duration: specifies the duration of TO signals.

2.1 Feature Key Package

   Package Name: KY

   The Feature Key Package groups events and signals that are associated
   with the additional keys that are available on business phones.

 ____________________________________________________________________
| Symbol   |   Definition               |   R |   S      Duration    |
|__________|____________________________|_____|______________________|
| fk1-fk99 | Feature Key                |   x |                      |
| ks       | Key State                  |     |   OO                 |
| ls       | Set Label                  |     |   OO                 |
|__________|____________________________|_____|______________________|

   Feature Key (fk1-fk99)

      These events map to all the keys on the phone that are not DTMF
      keys or locally implemented functions (such as volume).  The
      mapping of fk number to key is expected to vary between phones.

      Note: Some have suggested parameterizing the fk event, i.e.,
      sending an RQNT with "R: KY/fk" and an NTFY with "O: KY/fk(1)",
      but this is problematic;  It is desirable to request only the keys
      that can be pressed in a given state, to eliminate the chance that
      a mis-pressed button will cancel a timeout signal, as well as to
      reduce message traffic.  This is not possible within the confines
      of MGCP, as requested events cannot be parameterized.






Srinath, et al.              Informational                      [Page 6]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Key State (ks)

      This signal is used to indicate the state of a feature key.  It
      should be ignored by phones without this capability.

      This signal has two parameters: key number and state.  The key
      number maps directly to the feature key number.  The state is a
      high level description of the state of the key.  This allows
      different phones to implement different indications of state.  For
      example, Phone A may have a multi-color LED associated with
      feature keys that can blink at different cadences.  Phone B might
      have an LCD beside the keys that can display text or icons.  It is
      up to each phone vendor to determine how to present the state
      indication.

      The following states are used:

       ______________________
      | State | Definition   |
      |_______|______________|
      |  en   | enabled      |
      |  db   | disabled     |
      |  id   | idle         |
      |  dt   | dial tone    |
      |  cn   | connected    |
      |  dc   | disconnected |
      |  rg   | ringing      |
      |  rb   | ringback     |
      |  ho   | holding      |
      |  he   | held         |
      |_______|______________|

      For example: an RQNT with "S: KY/ks(5,en)" will cause an indicator
      corresponding to fk5 to indicate that it is enabled.  An RQNT with
      "S: KY/ks(2,rg)" will cause an indicator corresponding to fk2 to
      indicate that it is ringing.

   "en" state

      The associated feature is enabled.  Used for keys that turn a
      feature on or off, such as "Do Not Disturb."

   "db" state

      The associated feature is disabled.  Used for keys that turn a
      feature on or off, such as "Do Not Disturb."





Srinath, et al.              Informational                      [Page 7]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   "id" state

      The specified line appearance is in the idle state, available for
      a call.

   "dt" state

      The specified line appearance is providing dial-tone.

   "cn" state

      The specified line appearance is actively in a call, in the
      connected state.

   "dc" state

      The specified line appearance is disconnected, but the
      corresponding line is still active (the user is still offhook).

   "rg" state

      The specified line appearance is terminating an incoming call, in
      the ringing state.

   "rb" state

      The specified line appearance is originating an outgoing call, in
      the ringing-back state.

   "ho" state

      The specified line appearance is in the holding state, with the
      far end held.

   "he" state

      The specified line appearance is in the held state, with the far
      end holding.

   Set Label (ls)

      This signal is used to set the label on a key.  This is used for
      phones that have an LCD next to the feature keys.  It should be
      ignored by phones without this capability.

      This signal has 2 parameters: key number and label.  The key
      number maps directly to the feature key number.  The label is free
      form text, restricted to the capabilities of the phone.



Srinath, et al.              Informational                      [Page 8]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


      For example, an RQNT with "S: KY/ls(1,2200)" sets the label next
      to the fk1 feature key to the string "2200" (a phone extension).

2.2 Business Phone Package

   Package Name: BP

   The Business Phone Package groups signals other than those related to
   feature keys and displays.

 ____________________________________________________________________
| Symbol   |   Definition               |   R |   S      Duration    |
|__________|____________________________|_____|______________________|
| hd       | Force Offhook              |     |   OO                 |
| hu       | Force Onhook               |     |   OO                 |
| beep     | Beep                       |     |   BR                 |
|__________|____________________________|_____|______________________|

   Force Offhook (hd)

      This signal is used to force the phone offhook.  If the phone has
      a speaker phone, it should be activated.  This signal can be
      negated by the user by hanging up.

      This can be used if a feature key causes a call to be initiated.
      See the sample call flow in Appendix C.

      This can also be used for application integration.  For example, a
      user could select a number in an application on their PC, and the
      phone would be forced offhook and a call initiated.

   Force Onhook (hu)

      This signal forces the phone onhook.  This can be used when the
      far-end disconnects, or if a feature key causes a call to be
      terminated.

   Beep (beep)

      Play a beep on the phone.

2.3 Display XML Package

   Package Name: XML

   The XML Package contains one event/signal that is used to convey XML
   data to and from the phone.




Srinath, et al.              Informational                      [Page 9]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


 _____________________________________________________________________
| Symbol   |   Definition               |   R |   S      Duration    |
|__________|____________________________|_____|______________________|
| xml      | XML Data                   |   x |   OO                 |
|__________|____________________________|_____|______________________|

   XML Data (xml)

      As an event, if this event is requested in an RQNT with "R:
      XML/xml", any posts of data from an XML script are returned in an
      NTFY with "O: XML/xml(post data here)".

      As a signal, the parameterized data indicates a URL to an XML
      script (possibly local), as well as substitution values that
      depend on the XML script selected.  See section 5 for more
      information.

3. Endpoint Naming and Phone Type Determination

   Because the display state can be asynchronous from the signaling
   state of the phone, it is desirable to address the display as a
   separate MGCP endpoint.

   For example, suppose a call is presented to the phone, and a display
   is presented that gives the user the option of redirecting the caller
   immediately to voice-mail.  Selecting the option via the display
   would cause an XML post to occur, cancelling any timeout signals (the
   ringing).

   In order to simplify the handling of such scenarios, it is expected
   that the related display have a different MGCP endpoint name, created
   by inserting a prefix before the phone endpoint name.  The prefix
   used shall be "disp/".

   For example, if the phone endpoint has the name
   "ep1@foo.whatever.net", the display endpoint would be named
   "disp/ep1@foo.whatever.net".

   The Call Agent must be able to determine which feature key number
   corresponds to a particular pre-assigned function.  For example, one
   phone may have the pre-assigned functions of 'redial' and 'hold'
   mapped to feature keys numbered fk1 and fk23, respectively. Another
   phone may not report fk23 at all, and have the pre-assigned function
   of 'transfer' mapped to fk1.  Also, since the programming of feature
   keys would be resident in the Call Agent, a user-interface that






Srinath, et al.              Informational                     [Page 10]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   allows the programming of these keys must know the keys supported on
   the phone, in order for the Call Agent to request the appropriate
   feature keys.

   Determination of such basic capabilities must occur at the moment
   when the phone sends its first RSIP message to a Call Agent.  While
   it might be possible to define packages with events and signals that
   allow for an exhaustive discovery of the layout of a particular
   phone, a simpler and more reasonable approach would be for the Call
   Agent to discover the make and model of the phone, and thus determine
   the capabilities of the phone.  To this end, an experimental
   parameter, "X-UA" has been introduced for use in the Requested-Info
   field (F:) of the AUEP method.  The response to the "X-UA" is
   expected to be a string that uniquely identifies the make and model
   of the phone.  Note that per RFC 2705, a Gateway must ignore
   experimental parameters prefixed as "X-" that it cannot support,
   versus respond with an error code such as 511 (Unrecognized
   extension).  See the sample call flow in Appendix C.

4. Functions that should be Locally Implemented

   Some functions should be implemented locally on the Gateway.  These
   are listed in the following sections.

4.1 Volume Control

   Volume for ringing, handset, and speaker phone should be implemented
   locally on the Gateway.

4.2 Audio Path

   If the phone includes a speaker phone, activating the speaker phone
   from the idle state should generate an offhook (L/hd) event.  The
   user should then be able to switch to handset mode by lifting the
   handset, and be able to switch back to speaker phone mode without any
   interaction with the Call Agent.  De-activating the speaker phone
   with the handset on-hook should generate an onhook (L/hu) event.

4.3 Microphone mute button and light

   If the phone includes a microphone mute button and (optionally) an
   associated indicator (e.g., light), the functionality of these items
   should be implemented locally on the Gateway.








Srinath, et al.              Informational                     [Page 11]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


5. XML Package Support

   Not all business phones have the same display and keypad
   capabilities.  To support these varying devices in a consistent
   manner, this section outlines an XML framework that is used to drive
   the phone.  In this framework, the Call Agent pushes XML requests to
   the Gateway using MGCP signals.  These XML requests indicate the XML
   document that is to be rendered on the phone.

   When a user inputs data or makes a selection from a display, the
   Gateway "posts" an XML request to the Call Agent using MGCP events.

5.1 XML Documents

   When an XML signal request is sent to an endpoint, it indicates the
   XML documents that the endpoint must process.  These documents
   contain tags that are a subset of the Wireless Markup Language (WML)
   [3] plus some non-WML additions.  These tags specify items to be
   displayed as well as XML events that may be reported as the result of
   user input.

   Each XML document, known as a card, defines a user interaction.  A
   group of cards is called a deck.  One or more decks define an
   application.  The cards define soft key behavior as well as display
   behavior, and are mapped to components that implement the behavior of
   a basic graphical user interface on the display phone.  Based on the
   available requirements, the components needed are:

      - Input box:

        allows user input, including editing capabilities, via the
        keypad.

      - Enumerated list box:

        allows the user to select one of a list of items.

      - Itemized list box:

        allows the user to select an item using a soft key.

      - Text box:

        displays read-only text to the user.

      - Echo box:

        displays but does not process user input.



Srinath, et al.              Informational                     [Page 12]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   A card may have the following properties.

      1. Timed content (e.g., card expiration)
      2. Static content  (e.g., text)
      3. Dynamic content (e.g., call timers/time)

   Additionally, cards may also contain variables to be substituted for
   values that are specified in an XML request.  See section 5.2 for
   details on variable substitution.

   There are cases where the XML scripts handling the display need to
   use keys that are also used by the phone.  For example, the display
   could present an enumerated list, where a particular item is selected
   by pressing the associated number on the dial pad.  All user key
   presses must be routed through the XML component layer.  The display
   layer either consumes the key presses or passes them on to the phone
   layer for consumption.

   The code handling key presses should thus present a key press to the
   display code first.  If the display code does not "use" the key
   press, then the key press should be presented to the phone code.
   This gives precedence to the XML scripts for key presses.

5.2 XML Requests

   The XML framework uses MGCP as its transport for making requests to
   the display phone.  MGCP is also used to receive asynchronous events
   from the display phone (e.g., an item has been selected, or the user
   has entered text).

   An XML request is made to an endpoint using the XML/xml signal.  The
   signal has the following format:

   S: XML/xml(<url>?<card>?$<variable1>=<value1>?$<variable2>=<value2>)

   The first component of the signal parameter is a URL to the deck.  If
   no scheme is indicated, the deck is assumed to be local to the phone.
   Here are some examples:

   ftp://server.company.com/deck1?card1?$var1=val1
   http://www.company.com/deck1?card1?$var1=val1
   file://deck1?card1?$var1=val1
   deck1?card1?$var1=val1

   A card identifier and a list of variable/value pairs follow the URL.
   The card identifier indicates the card within the deck to display.





Srinath, et al.              Informational                     [Page 13]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   The variable/value pairs are substituted into the deck before it is
   rendered to the display.  This means that the variables are deck-
   scoped, and variables not defined in the requested card must be
   populated in other cards in the same deck if defined therein.

   For example, a deck may contain the following cards:

   <card id="one">
   <p>$line1</p>
   <timer value="2"/>
   <do type="ontimer">
   <go href="#two"/>
   </do>
   </card>

   <card id="two">
   <p>$line2</p>
   </card>

   And an XML request may look like:

   S: XML/xml(deck?one?$line1=abc$line2=xyz)

   After variable substitution, the deck will look like:

   <card id="one">
   <p>abc</p>
   </card>

   <card id="two">
   <p>$line2</p>
   </card>

   Once variable substitution is complete, the card is rendered.  If a
   parameter variable does not exist anywhere in the deck it should be
   ignored.

   When card two is invoked from card1 in response to the timeout
   action, card two's variables are substituted with the variables
   values passed as a request to card one.  Card two will look like:

   <card id="two">
   <p>xyz</p>
   </card>







Srinath, et al.              Informational                     [Page 14]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


5.3 XML Request History

   In order to support navigation through a request history such as when
   a user cancels a card, the XML layer must maintain a last-in-first-
   out history of requests made for the endpoint.  (See the <prev> tag
   definition in section 5.5.13.)

5.4 XML Events

   Whenever the XML layer determines that an event has occurred, it
   reports the event using the MGCP observed event field:

   O:
   XML/xml(post?<deck>?<card>?<variable1>=<value1>?<variable2>=<value2>)

   Here, the event parameter contains the deck and card that generated
   the event, as well as data that is to be processed by the Call Agent.
   The data being posted is in the form of a list of variable/value
   pairs.

   In order for the Gateway to properly generate the XML event, it is
   necessary for the Call Agent to request the event using the requested
   events field:

   R: XML/xml

   This requested event should be combined with the signal request in an
   RQNT.

5.5 XML Tags

   Any XML implementation must at a minimum support the XML tags listed
   in the table that follows.  All tags have a terminator tag of the
   form </tag> to indicate the end of the tag.  See the XML grammar in
   Appendix A.
















Srinath, et al.              Informational                     [Page 15]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


 _____________________________________________________________________
|  Name         |  Usage                                              |
|_______________|_____________________________________________________|
|  <xml>        |  Marks the beginning of a deck.                     |
|_______________|_____________________________________________________|
|  <card>       |  Marks the beginning of a card.                     |
|_______________|_____________________________________________________|
|  <p>          |  Marks the beginning of a paragraph.                |
|_______________|_____________________________________________________|
|  <select>     |  Defines a list of items that may be selected (an   |
|               |  enumerated or itemized list box).                  |
|_______________|_____________________________________________________|
|  <option>     |  Used in conjunction with the <select> tag to       |
|               |  specify an individual item that may be selected.   |
|_______________|_____________________________________________________|
|  <input>      |  Marks the beginning of user input (an input box).  |
|_______________|_____________________________________________________|
|  <echo>       |  Marks the beginning of an echo box.                |
|_______________|_____________________________________________________|
|  <calltimer>  |  Call Timer. An incremental timer usually used to   |
|               |  maintain the duration of a call.                   |
|_______________|_____________________________________________________|
|  <timer>      |  Card timer. Allows an event to be generated when   |
|               |  the timer expires.                                 |
|_______________|_____________________________________________________|
|  <time>       |  A tag indicating the current time.                 |
|_______________|_____________________________________________________|
|  <do>         |  Event consumer.                                    |
|_______________|_____________________________________________________|
|  <go>         |  Used in conjunction with the <do> tag to indicate  |
|               |  a new page to be displayed.                        |
|_______________|_____________________________________________________|
|  <prev>       |  Used in conjunction with the <do> tag to indicate  |
|               |  that the previous card in the history should be    |
|               |  displayed.                                         |
|_______________|_____________________________________________________|















Srinath, et al.              Informational                     [Page 16]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Most of these tags have attributes. Each attribute has one of the
   following types: String, Time, Enum, Align, Action or URL:

 _______________ _____________________________________________________
|  Type         |  Format                                             |
|_______________|_____________________________________________________|
|  String       |  Any string. May not contain any white spaces       |
|               | (tab, space or newline).                            |
|_______________|_____________________________________________________|
|  Time         |  A string of the format hh:mm:ss where hh indicates |
|               |  the hour (24-hour format), mm indicates the        |
|               |  minutes and ss indicates the seconds.              |
|_______________|_____________________________________________________|
|  Enum         |  Enumeration. A list of acceptable string values.   |
|_______________|_____________________________________________________|
|  Align        |  Indicates text alignment (left justified, centered |
|               |  or right justified). Valid values are: left,       |
|               |  center, right.  The default value is: left.        |
|_______________|_____________________________________________________|
|  Action       |  Defines a string to be sent to the Call Agent.     |
|               |  This string has the format:                        |
|               |        post?%var1[=%val1[?%var2[=%val2]]]           |
|               |  where variables that should be substituted before  |
|               |  sending the string to the Call Agent begin         |
|               |  with a '%'.                                        |
|               |  The tags that make up the card determine what      |
|               |  variables are available to this string. See the    |
|               |  following sections for variables that are defined  |
|               |  for each tag.                                      |
|_______________|_____________________________________________________|
|  URL          |  The URL may have take several forms:               |
|               |     1. #<card> to indicate another card within      |
|               |        the same deck                                |
|               |     2. A string of type Action                      |
|               |     3. #<prev> to indicate the previous card in     |
|               |        the history                                  |
|_______________|_____________________________________________________|

5.5.1 XML Tag

   The <xml> tag must be the first tag specified in the deck.  It
   indicates the beginning of the deck.

   This tag has no attributes.







Srinath, et al.              Informational                     [Page 17]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


5.5.2 Card Tag

   The <card> tag marks the beginning of a new card.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name |  Values             | Usage                         |
|_______________|_____________________|_______________________________|
|  Id           |  String             | Defines the card identifier.  |
|               |                     | This identifier is referenced |
|               |                     | in XML requests.              |
|_______________|_____________________|_______________________________|

5.5.3 P Tag

   The <p> tag marks the beginning of a new paragraph.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name |  Values (default)   | Usage                         |
|_______________|_____________________|_______________________________|
|Mode           |  Enum: wrap/nowrap  | Specifies whether the         |
|               |        (wrap)       | paragraph wraps or is         |
|               |                     | truncated when it extends past|
|               |                     | the display width.            |
|_______________|_____________________|_______________________________|
| Align         |  Align              | Specifies alignment of the    |
|               |                     | paragraph.                    |
|_______________|_____________________|_______________________________|

5.5.4 Select Tag

   The <select> tag marks the beginning of a list of items that may be
   selected.  Each item is defined using an <option> tag described in
   section 5.5.5.
















Srinath, et al.              Informational                     [Page 18]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values (default)    | Usage                         |
|_______________|_____________________|_______________________________|
| type          | Enum: item/enum     | Specifies the type of list:   |
|               |       (enum)        | itemized or enumerated.  An   |
|               |                     | itemized list maps options to |
|               |                     | soft keys.                    |
|_______________|_____________________|_______________________________|
| name          | String              | Specifies name of the list.   |
|               |                     | This attribute is available to|
|               |                     | any Action string in the card |
|               |                     | by using the %name variable.  |
|_______________|_____________________|_______________________________|
| iname         | String              | Defines an index variable with|
|               |                     | the specified name.  This     |
|               |                     | variable is used in the       |
|               |                     | <option> tag to specify the   |
|               |                     | index of an item that is      |
|               |                     | selected.  The value of this  |
|               |                     | attribute is available to any |
|               |                     | Action string in the card by  |
|               |                     | using the %iname variable. The|
|               |                     | value of the index variable is|
|               |                     | available by using the        |
|               |                     | %<string value> variable.     |
|               |                     | See examples below.           |
|_______________|_____________________|_______________________________|

5.5.5 Option Tag

   When used in conjunction with the <select> tag, the <option> tag
   specifies an individual item that may be selected from a list.


















Srinath, et al.              Informational                     [Page 19]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values              | Usage                         |
|_______________|_____________________|_______________________________|
| value         | String              | Defines the value of the item.|
|               |                     | This is used when reporting an|
|               |                     | event to the Call Agent.  The |
|               |                     | value of this attribute is    |
|               |                     | available to any Action string|
|               |                     | in the card by using the      |
|               |                     | %value variable.              |
|_______________|_____________________|_______________________________|
| onpick        | Action              | Defines the string to be sent |
|               |                     | to the Call Agent when the    |
|               |                     | item is selected.             |
|_______________|_____________________|_______________________________|

5.5.6 Input Tag

   The <input> tag specifies that user input is required.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values              | Usage                         |
|_______________|_____________________|_______________________________|
| name          | String              | Specifies the name of the     |
|               |                     | input tag.  The value of this |
|               |                     | attribute is available to any |
|               |                     | Action string in the card by  |
|               |                     | using the %name variable.     |
|_______________|_____________________|_______________________________|
| type          | Enum: password/text | Specifies whether the input   |
|               |       (text)        | box is in password mode       |
|               |                     | (password) or normal mode     |
|               |                     | (text). When in password mode,|
|               |                     | user input should be masked.  |
|_______________|_____________________|_______________________________|

5.5.7 Echo Tag

   The <echo> tag indicates that user input is required.  Any keypad
   activity is reported to the XML layer but not consumed when this tag
   is used.








Srinath, et al.              Informational                     [Page 20]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values (default)    | Usage                         |
|_______________|_____________________|_______________________________|
| mode          | Enum: on/off (on)   | Specifies whether the echo box|
|               |                     | is in password mode (off) or  |
|               |                     | normal mode (on).  When in    |
|               |                     | password mode, user input     |
|               |                     | should be masked.             |
|_______________|_____________________|_______________________________|
| align         | Align               | Specifies the alignment of the|
|               |                     | echo tag.                     |
|_______________|_____________________|_______________________________|

5.5.8 Calltimer Tag

   The <calltimer> tag is used to indicate that an incrementing timer is
   to be displayed.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values              | Usage                         |
|_______________|_____________________|_______________________________|
| value         | Time                | Specifies the initial value of|
|               |                     | the call timer.               |
|_______________|_____________________|_______________________________|
| align         |Align                | Specifies the alignment of the|
|               |                     | call timer.                   |
|_______________|_____________________|_______________________________|

5.5.9 Time Tag

   The <time> tag is used to display the current time on the phone.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values              | Usage                         |
|_______________|_____________________|_______________________________|
| align         | Align               | Specifies the alignment of the|
|               |                     | time.                         |
|_______________|_____________________|_______________________________|

5.5.10 Timer Tag

   The <timer> tag is used to define a timeout for the card.  When the
   timeout occurs, the XML Layer looks for the appropriate <do> tag to
   take appropriate action.




Srinath, et al.              Informational                     [Page 21]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values              | Usage                         |
|_______________|_____________________|_______________________________|
| Value         | Time                | Specifies the initial value of|
|               |                     | the timer.  The timer will    |
|               |                     | decrement the time until it   |
|               |                     | reaches zero at which point   |
|               |                     | the <do> tag is consulted.    |
|_______________|_____________________|_______________________________|

5.5.11 Do Tag

   The <do> tag indicates an action to be performed when the specified
   event occurs.

   Currently, the <do> tag can process three events: prev, ontimer and
   accept.  The prev event indicates that the user has requested to
   cancel the current card.

   The ontimer event indicates that the timer defined using the <timer>
   tag has expired.

   The accept event indicates that the user has completed inputting from
   the keypad.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values (default)    | Usage                         |
|_______________|_____________________|_______________________________|
|Type           | Enum:               | Indicates the event on which  |
|               | prev/ontimer/accept | the tag operates.             |
|_______________|_____________________|_______________________________|

5.5.12 Go Tag

   The <go> tag is used in conjunction with the <do> tag to specify a
   URL to be loaded when the event occurs.

   This tag has the following attributes:
 _______________ _____________________ _______________________________
|Attribute Name | Values (default)    | Usage                         |
|_______________|_____________________|_______________________________|
| href          | URL                 | Defines the URL of the next   |
|               |                     | XML page.                     |
|_______________|_____________________|_______________________________|





Srinath, et al.              Informational                     [Page 22]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


5.5.13 Prev Tag

   The <prev> tag is used in conjunction with the <do> tag to indicate
   that the previous page in the display history should be rendered.

   This tag has no attributes.

6. Security Considerations

   This extension introduces no new security considerations beyond those
   discussed in RFC 2705 [1].

7. Acknowledgements

   Thanks to the following companies and individuals for contributing
   their experience and thoughts for inclusion in this document.

   Arnie Chencinski, Sylantro Systems
   Bill Foster,      Cisco Systems
   Howard Holgate,   Cisco Systems
   John Weald,       Sylantro Systems
   Michael Chack,    Sylantro Systems
   Naga Surendran,   Sylantro Systems
   Sunil Veluvali,   Sylantro Systems

8. References

   [1]   Arango, M., Dugan A., Elliot, I., Huitema, C. and S. Pickett,
         "Media Gateway Control Protocol (MGCP)" RFC 2705, October 1999.

   [2]   Bray, T., Paoli, J. and C. Sperberg-McQueen, "Extensible Markup
         Language (XML) 1.0", W3C Proposed Recommendation, February 10,
         1998.

   [3]   "Wireless Application Protocol Wireless Markup Language
         Specification Version 1.2", WAP Forum, November 1999.















Srinath, et al.              Informational                     [Page 23]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


9. Authors' Addresses

   Ashok Srinath
   Sylantro Systems
   910 E. Hamilton Avenue
   Campbell, Ca. 95008

   EMail: Ashok.Srinath@sylantro.com


   Gil Levendel
   Sylantro Systems
   910 E. Hamilton Avenue
   Campbell, Ca. 95008

   EMail: Gil.Levendel@sylantro.com


   Kent Fritz
   Sylantro Systems
   910 E. Hamilton Avenue
   Campbell, Ca. 95008

   EMail: Kent.Fritz@sylantro.com


   Raghuraman Kalyanaram
   Wipro Systems
   Keonics Electronic City
   Hosur Road, Bangalore-561 229, India

   EMail: Raghuraman.Kal@wipro.com



















Srinath, et al.              Informational                     [Page 24]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


Appendix A: BNF description of XML grammar

   The parser is case sensitive.  In this section we will use the
   following conventions:

   1. Small letters means terminals.
   2. Capital strings are non-terminals.
   3. [A | B] means either A or B must appear in this place.
   4. \t, \n, \r, blank space are separators.

 ______________ _ ____________________________________________________
|ACTION        |:|<go href="HREFSTRING"/> | <prev/>                   |
|______________|_|____________________________________________________|
|ALIGN         |:|Align=["left" | "right" ]                           |
|______________|_|____________________________________________________|
|CALLTIMER     |:|<calltimer CALLTIMERATTRS/>                         |
|______________|_|____________________________________________________|
|CALLTIMERATTRS|:|CALLTIMERATTR | CALLTIMERATTR CALLTIMERATTRS        |
|______________|_|____________________________________________________|
|CALLTIMERATTR |:|value=STRING | ALIGN                                |
|______________|_|____________________________________________________|
|CARDS         |:|CARD | CARD CARDS                                   |
|______________|_|____________________________________________________|
|CARD          |:|<card id=STRING> CLUSTERS </card>                   |
|______________|_|____________________________________________________|
|CARDREFERENCE |:|#STRING                                             |
|______________|_|____________________________________________________|
|CLUSTERS      |:|CLUSTER | CLUSTER CLUSTERS                          |
|______________|_|____________________________________________________|
|CLUSTER       |:|CONTROL | TIMER | ECHO  | PARAGRAPH COMPONENTS </p> |
|______________|_|____________________________________________________|
|COMPONENTS    |:|COMPONENT | COMPONENT COMPONENTS                    |
|______________|_|____________________________________________________|
|COMPONENT     |:|TEXT | INPUTBOX | SELECTBOX | STIME | CALLTIMER     |
|______________|_|____________________________________________________|
|CONTROL       |:|<do CONDITION> ACTION </do>                         |
|______________|_|____________________________________________________|
|CONDITION     | |type=["accept" | "prev" | "ontimer"] label=STRING | |
|              | |type=["accept" | "prev" |"ontimer"]                 |
|______________|_|____________________________________________________|
|DIGITS        |:|DIGIT | DIGIT DIGITS                                |
|______________|_|____________________________________________________|
|DIGIT         |:|0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9               |
|______________|_|____________________________________________________|
|DECK          |:|<xml id=STRING> CARDS </xml>                        |
|______________|_|____________________________________________________|
|ECHO          |:|<echo/> | <echo ECHOMODE/>                          |
|______________|_|____________________________________________________|



Srinath, et al.              Informational                     [Page 25]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


|ECHOMODE      |:|mode=["on" | "off"]                                 |
|______________|_|____________________________________________________|
|HREFSTRING    |:|CARDREFERENCE | POSTSTRING                          |
|______________|_|____________________________________________________|
|INPUTBOX      |:|<input INPUTATTRS/>                                 |
|______________|_|____________________________________________________|
|INPUTATTRS    |:|INPUTATTR | INPUTATTR INPUTATTRS                    |
|______________|_|____________________________________________________|
|INPUTATTR     |:|name=STRING  | type=["text" | "password"] |         |
|              | | value=STRING                                       |
|______________|_|____________________________________________________|
|NAMEVALUES    |:|NAMEVALUE | NAMEVALUE?NAMEVALUES                    |
|______________|_|____________________________________________________|
|NAMEVALUE     |:|NAMEVALUEELEM | NAMEVALUEELEM=NAMEVALUELEM          |
|______________|_|____________________________________________________|
|NAMEVALUELEM  |:|%TEXT | TEXT                                        |
|______________|_|____________________________________________________|
|OPTIONS       |:|OPTION | OPTION OPTIONS                             |
|______________|_|____________________________________________________|
|OPTION        |:|<option value=STRING onpick=HREFSTRING> TEXT        |
|              | | </option>                                          |
|______________|_|____________________________________________________|
|PARAGRAPH     |:|<p TXTFORMAT>  | <p>                                |
|______________|_|____________________________________________________|
|POSTSTRING    |:|post?%deck?%id?NAMEVALUES | post?NAMEVALUES         |
|______________|_|____________________________________________________|
|SELECTBOX     |:|<select SELECTATTRS> OPTIONS </select>              |
|______________|_|____________________________________________________|
|SELECTATTRS   |:|SELECTATTR | SELECTATTR SELECTATTRS                 |
|______________|_|____________________________________________________|
|SELECTATTR    |:|name=STRING  | iname=STRING | type="item"           |
|______________|_|____________________________________________________|
|STIME         |:|<time STIMEATTRS/>                                  |
|______________|_|____________________________________________________|
|STIMEATTRS    |:|STIMEATTR | STIMEATTR STIMEATTRS                    |
|______________|_|____________________________________________________|
|STIMEATTR     |:|value=STRING | format=STRING | ALIGN                |
|______________|_|____________________________________________________|
|STRING        |:|Any string enclosed in a pair of quotes ("")        |
|______________|_|____________________________________________________|
|TEXT          |:|TEXTELEM | TEXTELEM TEXT                            |
|______________|_|____________________________________________________|
|TEXTELEM      |:|any string outside of the < .. > and which consists |
|              | |of any symbols except '<' and '\n'                  |
|______________|_|____________________________________________________|
|TIMER         |:|<timer value="DIGITS"/>                             |
|______________|_|____________________________________________________|




Srinath, et al.              Informational                     [Page 26]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


|TXTFORMAT     |:|ALIGN | TXTMODE | ALIGN TXTMODE | TXTMODE ALIGN     |
|______________|_|____________________________________________________|
|TXTMODE       |:|mode=["wrap" | "nowrap"]                            |
|______________|_|____________________________________________________|

 ______________ _ ____________________________________________________
|              | |\t, \n, \r, blank space are separators.             |
|______________|_|____________________________________________________|

Appendix B:  Sample XML Documents, Renderings and Events

   This section presents some sample XML documents and details how they
   are translated to a business phone with a simple LCD display.

B.1 Sample Deck 1 (Itemized List Box)

   Below is a simple deck containing one card that defines a simple main
   menu interface using an itemized list box:

   <xml>
   <card id="home">
   <p mode="nowrap">$dn <time align="right"></time>
   <select type="item" name="Menu" iname="StrMenu">
   <option value="1" onpick="post?%deck?%id?%name=%value">MENU</option>
   </select>
   </p>
   </card>
   </xml>

   The card (home) contains three components:

      1. A paragraph (<p>).  The paragraph contains a variable ($dn)
         that shows the phone's extension.
      2. A clock (<time>).  The clock is aligned to the right.
      3. An itemized list (<select>) containing one item (MENU).

   An XML request for this deck and card might look like:

   S: XML/xml(deck?home?$dn=2344)

   After variable substitution, the phone may render the XML to the
   display as follows:

   --------------------
   |2344         11:59|
   | MENU             |
   --------------------
     [XX]  [XX]  [XX]



Srinath, et al.              Informational                     [Page 27]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Here, MENU maps to the first soft key below the display.  If the user
   presses the first soft key, the following event will be generated:

   O: XML/xml(post?basic?home?Menu=1).

B.2 Sample Deck 2 (Enumerated List Box)

   The next sample deck defines a simple enumerated list box card:

   <xml>
   <card id="gelist">
   <p>$title
   <select name="x-name" iname="x-iname">
   <option value="$value1"
   onpick="post?%deck?%id?%name=%value?%iname=%x-iname">$opt1
   </option>
   <option value="$value2"
   onpick="post?%deck?%id?%name=%value?%iname=%x-iname">$opt2
   </option>
   <option value="$value3"
   onpick="post?%deck?%id?%name=%value?%iname=%x-iname">$opt3
   </option>
   <option value="$value4"
   onpick="post?%deck?%id?%name=%value?%iname=%x-iname">$opt4
   </option>
   <option value="$value5"
   onpick="post?%deck?%id?%name=%value?%iname=%x-iname">$opt5
   </option>
   </select>
   </p>
   <do type="prev">
   <prev></prev>
   </do>
   </card>
   </xml>

   The card (gelist) contains four components:

      1. A paragraph (<p>).  The paragraph contains a title variable
         describing the list contents.
      2. An enumerated list (<select>) containing five items.  When an
         item is selected, the XML layer sends the XML/xml event to the
         Call Agent.
      3. A do tag (<do>) indicating that when a "previous" event has
         occurred, to go to the previous page (<prev>).






Srinath, et al.              Informational                     [Page 28]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   An XML request for this deck and card might look like:

   S: XML/xml(list?gelist?$title=Select a Car?
   $value1=Item1?$opt1=Porsche?
   $value2=Item2?$opt2=Chevrolet?
   $value3=Item3?$opt3=Toyota?
   $value4=Item4?$opt4=Daewoo?
   $value5=Item5?$opt5=Yugo)

   After variable substitution, the phone may render the XML to the
   display as follows:

   --------------------
   |SELECT A CAR      |
   |1. Porsche       v|
   --------------------
     [XX]  [XX]  [XX]

   Here, the display may be scrolled to reveal the additional items that
   may be selected and the keypad '1', '2', etc may be used to select
   the item.  These details are phone-specific.  For instance, on a
   larger 4-line display containing navigation keys, the XML may be
   rendered as follows:

   --------------------
   |SELECT A CAR      |
   |=>Porsche<=       |
   |  Chevrolet       |
   |  Toyota         v|
   --------------------

   When the user selects item 1, the following message will be sent to
   the Call Agent:

   O: XML/xml(post?list?gelist?x-name=Item1?x-iname=1)

B.3 Sample Deck 3 (Text Box)

   This sample shows how to implement a simple text box:

   <xml>
   <card id="generic">
   <p>$cldpty</p>
   <p>CALL FAILED</p>
   </card>
   </xml>





Srinath, et al.              Informational                     [Page 29]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   The card (generic) contains two paragraphs.  The absence of a
   selectable list, input box or echo box indicates that this is a text
   box.

   An XML request for this deck and card might look like:

   S: XML/xml(deck?generic?$cldpty=John Doe)

   After variable substitution, the phone may render the XML to the
   display as follows:

   --------------------
   |JOHN DOE          |
   |CALL FAILED       |
   --------------------
     [XX]  [XX]  [XX]

B.4 Sample Deck 4 (Echo Box)

   This sample show how to implement a simple echo box.  The XML layer
   does not consume any keystrokes.

   <xml>
   <card id="getdigits">
   <p>Dial Number:</p>
   <echo mode="$mode" align="left"/>
   </card>
   </xml>

   The card (getdigits) contains a paragraph of text and an echo box.

   An XML request for this deck and card might look like:

   S: XML/xml(deck?getdigits?$mode=on)

   After variable substitution, the phone may render the XML to the
   display as follows:

   --------------------
   |DIAL NUMBER:      |
   |                  |
   --------------------
     [XX]  [XX]  [XX]

   All user input is displayed but not consumed by the XML layer.






Srinath, et al.              Informational                     [Page 30]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


B.5 Sample Deck 5 (Input Box)

   This sample implements a basic input box:

   <xml>
   <card id="ginput">
   <p>$title
   <input name="x-name"/>
   </p>
   <do type="accept">
   <go href="post?%deck?%id?%name=%value"/>
   </do>
   <do type="prev">
   <prev></prev>
   </do>
   </card>
   </xml>

   The card (ginput) contains:

      1. A paragraph <p>.  The paragraph contains a title.
      2. An input box <input>.  The input box consumes keypad events and
         reports them when input is complete.
      3. Two event handlers <do>.  The first handles the accept event.
         This event indicates that the user has completed keypad input
         and posts an observed event to the Call Agent.  The second
         handles the prev event.  This event indicates that the user has
         requested to revert back to the previous card.

   An XML request for this deck and card might look like:

   S: XML/xml(deck?ginput?$title=Enter Digits:)

   After variable substitution, the phone may render the XML to the
   display as follows:

   --------------------
   |ENTER DIGITS:     |
   |_                 |
   --------------------
     [XX]  [XX]  [XX]

   It is up to the individual business phone implementation to determine
   which soft keys or keypad keys map to functions such as "backspace",
   "reset line", etc.






Srinath, et al.              Informational                     [Page 31]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


B.6 Sample Deck 6 (Timers)

   To illustrate timers and deck-scoped variable substitution, a two-
   card deck is provided:

   <xml>
   <card id="connected1">
   <timer value="$tvalue"/>
   <p mode="nowrap">$cldpty
   <select type="item" name="x-name" iname="x-iname">
   <option value="1"
   onpick="post?TRNSINIT">TRNS
   </option>
   <option value="2"
   onpick="post?CONFINIT">CONF
   </option>
   <option value="3"
   onpick="post?%deck?%card?%name=%value">MENU
   </option>
   </select>
   </p>
   <do type="ontimer">
   <go href="#connected2"/>
   </do>
   </card>

   <card id="connected2">
   <p mode="nowrap">
   <calltimer value="$calltimer" align="right"/>
   <select type="item" name="x-name">
   <option value="1"
   onpick="post?TRNSINIT">TRNS
   </option>
   <option value="2"
   onpick="post?CONFINIT">CONF
   </option>
   <option value="3"
   onpick="post?%deck?%card?%name=%value" >MENU
   </option>
   </select>
   </p>
   </card>
   </xml>

   In this example, when the timer expires in card connected1, it
   generates an ontimer event.  This event is consumed by the <do> tag
   and causes the XML layer to load card with the identifier connected2.




Srinath, et al.              Informational                     [Page 32]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   An XML request for these cards might look like:

   S: XML/xml(deck?connected1?$tvalue=00:00:05?$cldpty=John
   Doe?$calltimer=00:00:00)

   And might be rendered as:

   --------------------
   |JOHN DOE          |
   | TRNS  CONF  MENU |
   --------------------
     [XX]  [XX]  [XX]

   Once the timer expires, the XML layer loads the referenced page:

   --------------------
   |          00:00:05|
   | TRNS  CONF  MENU |
   --------------------
     [XX]  [XX]  [XX]

Appendix C: Example usage of MGCP extension packages

C.1 Setting Labels on a Phone

   Step 1. Call Agent sets labels on several used keys.  Should be done
   at startup.  The first 2 keys are line appearance keys.  fk8 is a Do
   Not Disturb function.

      RQNT 1876 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ls(1,2315), KY/ls(2,2315), KY/ls(8,DND)
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hd
      T: L/hu
      K: 1873

   Step 2. Gateway responds.

         200 1876 OK

C.2 Activating a Function on a Feature Key

   This example shows a feature key that is assigned to "Do Not Disturb"
   being activated and deactivated.

   Step 1. User presses DND key, which is assigned to fk8.  Gateway
   sends NTFY to Call Agent.



Srinath, et al.              Informational                     [Page 33]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


      NTFY 957 d003@da-003.syltrx.com MGCP 1.0
      K: 956
      N: cs@sage.syltrx.com:2427
      X: 45
      O: KY/fk8

   Step 2. Call Agent responds.

      200 957 OK

   Step 3. Call Agent sends new RQNT, indicating that DND indicator be
   activated.  Note that the Call Agent also re-sends the state of fk1,
   which is not actually necessary.  The Call Agent requests
   notification of several of the feature keys: fk1 and fk2 are line
   keys, fk8 is DND, fk22 is redial, and fk23 is messages.

      RQNT 2822 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ks(1,id), KY/ks(8,en)
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hd
      T: L/hu
      K: 2743-2744

   Step 4. Gateway responds.

      200 2822 OK

   Step 5. User presses DND key again to de-activate DND.  Gateway sends
   NTFY to Call Agent.

      NTFY 958 d003@da-003.syltrx.com MGCP 1.0
      K: 957
      N: cs@sage.syltrx.com:2427
      X: 45
      O: KY/fk8

   Step 6. Call Agent responds.

      200 958 OK











Srinath, et al.              Informational                     [Page 34]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Step 7. Call Agent sends new RQNT, DND indicator is de-activated.

      RQNT 2823 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ks(1,id), KY/ks(8,db)
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hd
      T: L/hu
      K: 2822

   Step 8. Gateway responds.

      200 2823 OK

C.3 Generating a Call using a Feature Key as a Line Key

   This example shows the MGCP messages for dialing an extension after
   pressing a feature key that is configured as a line appearance key.

   Step 1. User presses fk1, which is configured as a line key.

      NTFY 959 d003@da-003.syltrx.com MGCP 1.0
      K: 958
      N: cs@sage.syltrx.com:2427
      X: 45
      O: KY/fk1

   Step 2. Call Agent responds.

      200 959 OK

   Step 3. Call Agent puts the line key in the "dial tone" state and
   forces the phone offhook.

      RQNT 2833 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427

      X: 45
      S: KY/ks(1,dt), BP/hd
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hu
      T: L/hd
      K: 2823

   Step 4. Gateway responds.

      200 2833 OK





Srinath, et al.              Informational                     [Page 35]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Step 5. Call Agent applies dial-tone.

      RQNT 2834 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: L/dl, KY/ks(1,dt)
      R: D/[0-9*#T](D), KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hu
      T: L/hd
      D: (*xx|[1-7]xxx|9)

   Step 6. Gateway responds.

      200 2834 OK

   Step 7. User dials 2362.  Gateway sends NTFY.

      NTFY 960 d003@da-003.syltrx.com MGCP 1.0
      K: 959
      N: cs@sage.syltrx.com:2427
      X: 45
      O: D/2,D/3,D/6,D/2

   Step 8. Call Agent responds.

      200 960 OK

   Step 9. Call Agent puts line in the ringback state.  Ringback not
   applied yet.

      RQNT 2836 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ks(1,rb)
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hu
      T: L/hd
      K: 2833, 2834

   Step 10. Gateway responds.

      200 2836 OK

   Step 11. Call Agent creates connection.

      CRCX 2838 d003@da-003.syltrx.com MGCP 1.0
      C: 10B
      M: RECVONLY





Srinath, et al.              Informational                     [Page 36]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Step 12. Gateway responds.

      200 2838 OK
      I: 101

      v=0
      o=- 998557784 998557784 IN IP4 38.187.114.41
      s=MGCP RTP Session
      c=IN IP4 172.16.130.32
      t=0 0
      m=audio 1108 RTP/AVP 0
      a=rtpmap:0 PCMU/8000

   Step 13. Call Agent applies ringback.

      RQNT 2841 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ks(1,rb), G/rt
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hu
      T: L/hd

   Step 14. Gateway responds.

      200 2841 OK

   Step 15. Call Agent modifies connection.

      MDCX 2848 d003@da-003.syltrx.com MGCP 1.0
      C: 10B
      I: 101
      M: SENDRECV
      K: 2841-2842

      v=0
      o=- 7960 7960 IN IP4 38.187.114.215
      s=MGCP Call
      c=IN IP4 172.16.130.31
      t=0 0
      m=audio 1124 RTP/AVP 0

   Step 16. Gateway responds.

      200 2848 OK







Srinath, et al.              Informational                     [Page 37]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Step 17. Call Agent puts line in connected state.  Added requested
   events looking for hold (fk21) and conference/transfer (fk24).

      RQNT 2849 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427
      X: 45
      S: KY/ks(1,cn)
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk21, KY/fk24, L/hu
      T: L/hd
      K: 2842

   Step 18. Gateway responds.

      200 2849 OK

   Step 19. Far end disconnects.  Call Agent deletes connection.

      DLCX 2873 d003@da-003.syltrx.com MGCP 1.0
      C: 10B
      I: 101
      K: 2848, 2849

   Step 20. Gateway responds.

      250 2873 Connection Deleted

   Step 21. Call Agent forces endpoint onhook/idle.

      RQNT 2876 d003@da-003.syltrx.com MGCP 1.0
      N: cs@sage.syltrx.com:2427

      X: 45
      S: KY/ks(1,id), BP/hu
      R: KY/fk1, KY/fk2, KY/fk8, KY/fk22, KY/fk23, L/hd
      T: L/hu
      K: 2873

   Step 22. Gateway responds.

      200 2876 OK

C.4 Determining the Make and Model of a Phone

   Step 1. Gateway restarts.

      RSIP 1 *@alpha175.sylantro.com MGCP 1.0
      RM: restart




Srinath, et al.              Informational                     [Page 38]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


   Step 2. Call Agent responds.

      200 1 OK

   Step 3. Call Agent audits the Gateway to determine list of endpoints

      AUEP 1000 *@alpha175.sylantro.com MGCP 1.0

   Step 4. Gateway responds.

      200 1000 OK
      Z: a004@alpha175.sylantro.com
      Z: d001@alpha175.sylantro.com
      Z: d002@alpha175.sylantro.com
      Z: d003@alpha175.sylantro.com

   Step 5. For each endpoint, Call Agent determines capabilities and
   user-agent (phone-type)

      AUEP 1040 d003@alpha175.sylantro.com MGCP 1.0
      K: 1039
      F: A,X-UA

   Step 6. Gateway responds.

      200 1040 OK
      A: v:D;L;KY;X-BP;G;BP
      X-UA: Sylantro/DKT2010-CA204#CA010

Appendix D: BNF Description of X-UA Parameter

   Since parts of the X-UA parameter must be parseable in order for a
   Call Agent to treat similar phones in a similar manner, a formal
   grammar for this parameter is provided.

















Srinath, et al.              Informational                     [Page 39]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


 ______________ _ ____________________________________________________
|X-UA          |:|ENDPOINTINFO                                        |
|______________|_|____________________________________________________|
|ENDPOINTINFO  |:|MAKE/MODEL[-VENDORINFO]                             |
|______________|_|____________________________________________________|
|MAKE          |:|1*32 MAKECHAR                                       |
|______________|_|____________________________________________________|
|MODEL         |:|1*32 MODELCHAR                                      |
|______________|_|____________________________________________________|
|VENDORINFO    |:|1*32 VENDORCHAR                                     |
|______________|_|____________________________________________________|
|MAKECHAR      |:|ALPHA | DIGIT                                       |
|______________|_|____________________________________________________|
|MODELCHAR     |:|ALPHA | DIGIT                                       |
|______________|_|____________________________________________________|
|VENDORCHAR    |:|ALPHA | DIGIT | OTHER                               |
|______________|_|____________________________________________________|


































Srinath, et al.              Informational                     [Page 40]
^L
RFC 3149              MGCP Business Phone Packages        September 2001


Full Copyright Statement

   Copyright (C) The Internet Society (2001).  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.



















Srinath, et al.              Informational                     [Page 41]
^L