rfc3149.txt

RFC 的详细文档！

   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]

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]

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]

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]

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]

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]

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|