tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 5022

 
 
 

Media Server Control Markup Language (MSCML) and Protocol

Part 3 of 4, p. 43 to 62
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 43 
7.  Call Leg Events

   MSCML defines event notifications that are scoped to a specific SIP
   dialog or call leg.  These events allow a client to be notified of
   individual, asynchronous DTMF keypresses, as well as of various call
   progress signals.  The subscription, event detection, and
   notifications for call leg events occur in the same SIP dialog.  This
   is different from the conference level active talker events described
   earlier.  The subscription and notifications for active talker events
   occur on the conference control leg, but the actual event detection
   occurs on one or more participant legs.

   Subscriptions for call leg events are made by sending an MSCML
   <configure_leg> request on the desired SIP dialog.  Call leg events
   may be used with the MSCML conferencing or IVR services.  When used
   with the IVR service, the <configure_leg> request SHOULD NOT include
   any conference-related attributes.  The media server MUST ignore
   these if present.  Call leg event subscriptions MUST NOT be made on
   the conference control leg, since it has no actual RTP media to
   process for event detection.  The media server MUST reject a
   <configure_leg> request sent on the conference control leg.

   The <configure_leg> request contains the child elements <subscribe>
   and <events>.  The <events> element may contain two child elements
   that control subscriptions to call leg events.  These are <keypress>
   and <signal>.  A <configure_leg> request MUST contain at most one
   <keypress> element but MAY contain multiple <signal> elements that
   request notification of different call progress events.

7.1.  Keypress Events

   Keypress events are used when the client wishes to receive
   notifications of individual DTMF events that are not tied to a
   specific <playcollect> request.  One use of this facility is to
   monitor conference legs for DTMF inputs that require application
   intervention; for example, to notify the moderator that the caller
   wishes to speak.  Keypress events are also used when the application
   desires complete control of grammars and timing constraints.

Top      Up      ToC       Page 44 
   When used in a subscription context, the <keypress> element has two
   attributes, 'report' and 'maskdigits', which are detailed in the list
   below.

   Keypress Subscription Attributes:

   o  report - required, no default value: Possible values are
      'standard', 'long', 'both', and 'none'.  'Standard' means that
      detected digits should be reported.  'Long' means that long digits
      should be reported.  'Long' digits are defined as a single key
      press held down for more than one second, or two distinct key
      presses (a "double") of the same digit that occur within two
      seconds of each other with no other intervening digits.  'Both'
      means that both 'standard' and 'long' digit events should be
      reported.  As a 'long' digit consists of one or more "normal"
      digits, a single long duration key press will generate one
      standard event and one 'long' event.  A "double" will produce two
      standard events and one 'long' event.  'None' means that no
      keypress events should be reported; it disables keypress event
      reporting if enabled.

   o  maskdigits - optional, default value "no": Controls whether user
      DTMF inputs are captured in media server log files.  The possible
      values for this attribute are "yes" and "no".

   The media server sends an MSCML response to the subscription
   immediately upon receiving the request.  Notifications are sent to
   the client when the specified events are detected.

   When used in a notification context, the <keypress> element has
   several attributes that are used to convey details of the event that
   was detected.  It also contains a child element, <status>, that
   provides information on any MSCML request that was in progress when
   the event occurred.  The details of these notification attributes are
   described in the list below.

   Keypress Notification Attributes:

   o  digit - required, no default value: Specifies the DTMF digit
      detected.  Possible values are [0-9], [A-D], '#', or '*'.

   o  length - required, no default value: Specifies the duration class
      of the DTMF input.  Possible values are 'standard' or 'long'.

   o  method - required, no default value: Specifies the keypress
      detection method that generated the notification.  Possible values
      are 'standard', 'long', and 'double'.

Top      Up      ToC       Page 45 
   o  interdigittime - required, no default value: Specifies the elapsed
      time, as a time value (Section 4.2.1), between the current event
      detection and the previous one.

7.1.1.  Keypress Subscription Examples

   The following examples of MSCML payloads depict a subscription for
   standard keypress events and disabling keypress reporting.

   Figure 21 shows a subscription for standard keypress events.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <configure_leg>
         <subscribe>
           <events>
             <keypress report="standard"/>
           </events>
         </subscribe>
       </configure_leg>
     </request>
   </MediaServerControl>

   Figure 21: Standard Digit Events Subscription

   Figure 22 shows a client disabling keypress event notifications.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <configure_leg>
         <subscribe>
           <events>
             <keypress report="none"/>
           </events>
         </subscribe>
       </configure_leg>
     </request>
   </MediaServerControl>

   Figure 22: Disabling Keypress Event Reporting

7.1.2.  Keypress Notification Examples

   The following MSCML payloads depict keypress event notifications
   caused by various types of DTMF input.

Top      Up      ToC       Page 46 
   Figure 23 shows a notification generated by the detection of a
   standard "4" DTMF digit.  In this example, this is the first digit
   detected.  Thus, the 'interdigittime' attribute has a value of '0'.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <notification>
       <keypress digit="4" length="standard" method="standard"
         interdigittime="0">
         <status command="play" duration="10"/>
       </keypress>
     </notification>
   </MediaServerControl>

   Figure 23: Standard Keypress Notification

   Figure 24 shows a notification generated by detection of a long pound
   (#).

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <notification>
       <keypress digit="#" length="long" method="long"
         interdigittime="200">
         <status command="idle" duration="4"/>
       </keypress>
     </notification>
   </MediaServerControl>

   Figure 24: Long Keypress Notification

7.2.  Signal Events

   MSCML supports notification of certain call progress tones through
   the <signal> element.  When used in a subscription context, the
   <signal> element has two attributes, 'type' and 'report', and no
   child elements.  These attributes are detailed in the list below.

   Signal Subscription Attributes:

   o  report - required, no default value: Controls whether the
      specified signal is reported.  Possible values are 'yes' and 'no'.
      When set to 'yes', the media server invokes the required signal
      detection code and reports detected events.  When it is set to
      'no', the media server disables the associated signal detection
      code and does not report events.

Top      Up      ToC       Page 47 
   o  type - required, no default value: Specifies the type of call
      progress signal to detect.  Possible values are 'busy', 'ring',
      'CED', 'CNG', and '400', which correspond to busy tone, ring tone,
      fax CED, fax CNG, and 400 Hz tone, respectively.

      NOTE: The details of media server provisioning required to support
      country-specific variants of 'busy' and 'ring' is not covered by
      this specification.

   As stated previously, a single <configure_leg> request MAY contain
   multiple <signal> elements that request notification of different
   call progress tones.  A single <configure_leg> request SHOULD NOT
   contain multiple <signal> elements that have the same 'type'
   attribute value.  If the media server receives such a request, it
   SHOULD honor the last element specifying that type that appears in
   the request.

   The media server generates an immediate response to the
   <configure_leg> subscription request and sends notifications when the
   specified signals are detected.  A single notification is sent as
   soon as the specified signal has been reliably detected.  If the
   signal persists continuously, additional notifications will not be
   sent.  If the signal is interrupted and then resumes, additional
   notifications will be sent.

   Signal notifications have a single attribute, "type", as described in
   the list below.

   Signal Notification Attribute:

   o  type - required, no default value: Specifies the type of call
      progress signal that was detected.  Possible values are 'busy',
      'ring', 'CED', 'CNG', and '400', which correspond to busy tone,
      ring tone, fax CED, fax CNG, and 400 Hz tone, respectively.

7.2.1.  Signal Event Examples

   The following MSCML payloads show a signal event subscription (Figure
   25) and notification (Figure 26).

Top      Up      ToC       Page 48 
   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <configure_leg>
         <subscribe>
           <events>
             <signal type="busy" report="yes"/>
           </events>
         </subscribe>
       </configure_leg>
     </request>
   </MediaServerControl>

   Figure 25: Signal Event Subscription

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <notification>
       <signal type="busy"/>
     </notification>
   </MediaServerControl>

   Figure 26: Signal Event Notification

8.  Managing Content <managecontent>

   MSCML uses the <managecontent> request to move recorded content from
   the media server to remote locations using the HTTP protocol.  This
   is a store-and-forward model, which requires the completion of local
   temporary recording before the media server can send it to the web
   server.  This facility is useful in applications such as voice
   messaging, where a message may be reviewed by the caller prior to
   being committed to persistent storage.

   The <managecontent> request contains no child elements and has the
   attributes described in the list below.

   Managecontent Attributes:

   o  src - required, no default value: Specifies the local source URL
      of the content.  The URL scheme MUST be "file://".

   o  dest - required (see note), no default value: Specifies the
      destination URL.  The URL scheme MUST be "http://".  Note: If the
      selected action is 'delete', this attribute is optional; otherwise
      it is required.

Top      Up      ToC       Page 49 
   o  action - optional, default value "move": Specifies the operation
      for the media server to execute.  Values can be either 'move' or
      'delete'.  The 'delete' action operates on the local source file.
      After a successful move or delete, the media server deletes the
      source file from its local storage.  If the request is
      unsuccessful, the source file is not deleted, which gives the
      client complete control of the retry strategy.

   o  httpmethod - optional, default value "post": HTTP protocol method
      for the media server to use in the HTTP request.  The only values
      are 'post' or 'put'.

   o  name - required (see note), no default value: Specifies the field
      name for the content in the form when using the 'post' method.
      This is not to be confused with the "src" or "dest" attributes.
      Note: This attribute is required when the "htttpmethod" has the
      value "post" and is optional otherwise.

   o  fetchtimeout - optional, default value "10000ms": Specifies the
      maximum time allowed for the transfer to complete.  Expressed as a
      time value (Section 4.2.1) from 1ms onwards.

   o  mimetype - required (see note), no default value: Specifies the
      MIME type that the media server will use for the content transfer.
      If it is not provided, the media server MUST try to infer it from
      the content file extension based on a platform specific mapping
      table.  A non-normative, example mapping table is shown in Table
      3.  To avoid ambiguity, we RECOMMEND that clients explicitly set
      this attribute.  Note: If the MIME type of the content cannot be
      inferred from the file extension, this attribute is required.

   Table 3 shows common audio and video MIME types and possible file
   extension mappings.

Top      Up      ToC       Page 50 
                    +-----------+--------------------+
                    | Extension | MIME Type          |
                    +-----------+--------------------+
                    | alaw      | audio/x-alaw-basic |
                    | ulaw      | audio/basic        |
                    | msgsm     | audio/ms-gsm       |
                    | wav       | audio/x-wav        |
                    | tif       | image/tiff         |
                    | tiff      | image/tiff         |
                    | mov       | video/quicktime    |
                    | qt        | video/quicktime    |
                    | 3gp       | video/3gpp         |
                    | 3gpp      | video/3gpp         |
                    +-----------+--------------------+

           Table 3: Example File Extension to MIME Type Mappings

   <Managecontent> is purely a transport operation; the underlying
   content is not changed by it.  Therefore clients MUST ensure that the
   source and destination file name extensions and MIME types are the
   same.  Failure to do so could result in content that is unreadable.

   The ability to move or delete any local file presents a potential
   risk to the security of the media server system.  For this reason, we
   STRONGLY RECOMMEND that implementers limit local file system access
   when using <managecontent>.  For example, we encourage limiting
   access as based on file ownership and/or specific directories.

8.1.  Managecontent Example

   The following is an example (Figure 27) showing a local file on the
   media server being transferred to an HTTP URL using the "put" method.
   The client sends the following request.

   <?xml version="1.0"?>
   <MediaServerControl version="1.0">
     <request>
       <managecontent id="102"
       src="file:////var/mediaserver/rec/6A5GH49B.ulaw"
       dest="http://www.example.com/recordings/myrecording.ulaw"
       mimetype="audio/basic" action="move" httpmethod="put"
       fetchtimeout="5000"/>
     </request>
   </MediaServerControl>

   Figure 27: Managecontent Example

Top      Up      ToC       Page 51 
   Note that the client can change the temporary file name assigned by
   the media server as part of this operation as shown.

   If the request is ambiguous, the media server MUST return a status
   code of "400" and text "Bad Request."  If the media server is unable
   to execute a syntactically correct and unambiguous request, it MUST
   return a "500" status code with the text "Server Error."  For
   example, the local file system access restrictions may prevent
   deletion of the specified file.  In this case, the "reason" attribute
   in the response conveys additional details on the server error that
   occurred.  If there is a network or remote server error, the media
   server provides detailed error information in the <error_info>
   element contained in the media server response.  Additional
   information regarding <managecontent> responses is provided in
   Section 10.7.

9.  Fax Processing

9.1.  Recording a Fax <faxrecord>

   The <faxrecord> request directs the media server to process a fax in
   answer mode.  The reason for a request separate from <playrecord> is
   that the media server needs to know to process the T.30 [18] or T.38
   [19] fax protocols.

   The <faxrecord> request has multiple attributes and one child
   element, <prompt>.  Its attributes are described in the list below.

   Attributes of <faxrecord>:

   o  lclid - optional, default value "" (the empty string): A string
      that identifies the called station.

   o  prompturl - optional, no default value: The URL of the fax content
      to be retrieved and played.  The target may be a local or remote
      (NFS) "file://" scheme URL or an "http://" or "https://" scheme
      URL.  NOTE: Use of this attribute is deprecated.

   o  promptencoding - optional, no default value: Specifies the content
      encoding for files that do not have a 'tif' or 'tiff' extension.
      The only allowable value is 'tiff'.  This attribute only affects
      "file://" scheme URLs.  NOTE: Use of this attribute is deprecated.

   o  recurl - optional, no default value: Specifies the target URL for
      the recorded content.

   o  rmtid - optional, no default value: Specifies the calling station
      identifier of the remote terminal.  If present, the media server

Top      Up      ToC       Page 52 
      MUST reject transactions with the remote terminal if the remote
      terminal's identifier does not match the value of 'rmtid'.

   Clients SHOULD use the more flexible <prompt> mechanism for
   specifying fax content.  Use of the 'prompturl' attribute is
   deprecated and may not be supported in future MSCML versions.  The
   <prompt> element is described in Section 6.1.1.  A <prompt> element
   sent in a <faxrecord> request MUST NOT contain <variable> elements.

   Media servers MUST support local and remote (NFS) "file://" scheme
   URLs in the "recurl" attribute.  MSCML supports "http://" and
   "https://" scheme URLs indirectly through the <managecontent>
   (Section 8) request.

   The <faxrecord> request operates in one of three modes: receive,
   poll, and turnaround poll.  The combination of <prompt> or
   'prompturl' attribute and 'recurl' attribute define the mode.  Table
   4 describes these modes in detail.  The 'prompt' column in the table
   has the value 'yes' if the request has either a <prompt> element or a
   'prompturl' attribute.

   +--------+--------+---------+---------------------------------------+
   | prompt | recurl | Mode    | Operation                             |
   +--------+--------+---------+---------------------------------------+
   | no     | no     | Invalid | Request fails.                        |
   | no     | yes    | Receive | Record the fax to the target URL      |
   |        |        |         | specified in 'recurl'.                |
   | yes    | no     | Poll    | Send fax from source specified in the |
   |        |        |         | <prompt> element or 'prompturl'       |
   |        |        |         | attribute.  If there is a 'rmtid', it |
   |        |        |         | MUST match the remote terminal's      |
   |        |        |         | identifier, or the request will fail. |
   | yes    | yes    | TP      | Turnaround Poll (TP) mode. If the     |
   |        |        |         | remote terminal wishes to transmit,   |
   |        |        |         | the media server records the fax to   |
   |        |        |         | the target URL specified in 'recurl'. |
   |        |        |         | If the remote terminal wishes to      |
   |        |        |         | receive, the media server sends the   |
   |        |        |         | fax from the source URL contained in  |
   |        |        |         | <prompt> or 'prompturl'.  If there is |
   |        |        |         | a 'rmtid', it MUST match remote       |
   |        |        |         | terminal's identifier, or the send    |
   |        |        |         | request will fail.  A receive         |
   |        |        |         | operation will still succeed,         |
   |        |        |         | however.                              |
   +--------+--------+---------+---------------------------------------+

                        Table 4: Fax Receive Modes

Top      Up      ToC       Page 53 
   In receive mode, the media server receives the fax and writes the fax
   data to the target URL specified by the 'recurl' attribute.

   In poll mode, the media server sends a fax, but as a polled (called)
   device.

   In turnaround poll mode, the media server will record a fax that the
   remote machine sends.  If the remote machine requests a transmission,
   then the media server will send the fax.

   When transmitting a fax, the media server will advertise that it can
   receive faxes in the DIS message.  Likewise, when receiving a fax,
   the media server will advertise that it can send faxes in the DIS
   message.

   The media server MUST flush any quarantined digits when it receives a
   <faxrecord> request.

9.2.  Sending a Fax <faxplay>

   The <faxplay> request directs the media server to process a fax in
   originate mode.  The reason for a request separate from <play> is
   that the media server needs to know to process the T.30 [18] or T.38
   [19] fax protocols.

   The <faxplay> request has multiple attributes and one child element,
   <prompt>.  Its attributes are described in the list below.

   Attributes of <faxplay>:

   o  lclid - optional, default value "" (the empty string): A string
      that identifies the called station.

   o  prompturl - optional, no default value: The URL of the content to
      be retrieved and played.  The target may be a local or remote
      (NFS) "file://" scheme URL or an "http://" or "https://" scheme
      URL.  NOTE: Use of this attribute is deprecated.

   o  promptencoding - optional, no default value: Specifies the content
      encoding for files that do not have a 'tif' or 'tiff' extension.
      The only allowable value is 'tiff'.  This attribute only affects
      "file://" scheme URLs.  NOTE: Use of this attribute is deprecated.

   o  recurl - optional, no default value: Specifies the target URL for
      the recorded content.

   o  rmtid - optional, no default value: Specifies the calling station
      identifier of the remote terminal.  If present, the media server

Top      Up      ToC       Page 54 
      MUST reject transactions with the remote terminal if the remote
      terminal's identifier does not match the value of 'rmtid'.

   Clients SHOULD use the more flexible <prompt> mechanism for
   specifying fax content.  Use of the 'prompturl' attribute is
   deprecated and may not be supported in future MSCML versions.  The
   <prompt> element is described in Section 6.1.1.  A <prompt> element
   sent in a <faxrecord> request MUST NOT contain <variable> elements.

   Media servers MUST support local and remote (NFS) "file://" scheme
   URLs in the "recurl" attribute.  MSCML supports "http://" and
   "https://" scheme URLs indirectly through the <managecontent>
   (Section 8) request.

   The <faxplay> request operates in one of three modes: send, remote
   poll, and turnaround poll.  The combination of <prompt> or
   'prompturl' attribute and 'recurl' attribute define the mode.  Table
   5 describes these modes in detail.  The 'prompt' column in the table
   has the value 'yes' if the request has either a <prompt> element or a
   'prompturl' attribute.

Top      Up      ToC       Page 55 
   +--------+--------+---------+---------------------------------------+
   | prompt | recurl | Mode    | Operation                             |
   +--------+--------+---------+---------------------------------------+
   | no     | no     | Invalid | Request fails.                        |
   | yes    | no     | Send    | Send fax from source specified in the |
   |        |        |         | <prompt> element or 'prompturl'       |
   |        |        |         | attribute. If there is a 'rmtid', it  |
   |        |        |         | MUST match the remote terminal's      |
   |        |        |         | identifier, or the request will fail. |
   | no     | yes    | Poll    | Send fax from source specified in the |
   |        |        |         | <prompt> element or 'prompturl'       |
   |        |        |         | attribute, assuming the remote        |
   |        |        |         | terminal specifies it can receive a   |
   |        |        |         | fax in its DIS message. If the remote |
   |        |        |         | terminal does not support reverse     |
   |        |        |         | polling, the request will fail. If    |
   |        |        |         | 'rmtid' is specified, it MUST match   |
   |        |        |         | remote terminal's identifier, or the  |
   |        |        |         | request will fail.                    |
   | yes    | yes    | TP      | Turnaround Poll (TP) mode. If the     |
   |        |        |         | remote terminal wishes to transmit,   |
   |        |        |         | the media server records the fax to   |
   |        |        |         | the target URL specified in 'recurl'. |
   |        |        |         | If the remote terminal wishes to      |
   |        |        |         | receive, the media server sends the   |
   |        |        |         | fax from the source URL contained in  |
   |        |        |         | <prompt> or 'prompturl'. If there is  |
   |        |        |         | a 'rmtid', it MUST match remote       |
   |        |        |         | terminal's identifier, or the send    |
   |        |        |         | request will fail. A receive          |
   |        |        |         | operation will still succeed,         |
   |        |        |         | however.                              |
   +--------+--------+---------+---------------------------------------+

                          Table 5: Fax Send Modes

   In send mode, the media server sends the fax.

   In remote poll mode, the client places a call on behalf of the media
   server.  The media server requests a fax transmission from the remote
   fax terminal.

   In turnaround poll mode, the media server will record a fax that the
   remote machine sends.  If the remote machine requests a transmission,
   then the media server will send the fax.

   When transmitting a fax, the media server will advertise that it can
   receive faxes in the DIS message.  Likewise, when receiving a fax,

Top      Up      ToC       Page 56 
   the media server will advertise that it can send faxes in the DIS
   message.

   The media server MUST flush any quarantined digits when it receives a
   <faxplay> request.

10.  MSCML Response Attributes and Elements

10.1.  Mechanism

   The media server acknowledges receipt of a client MSCML request sent
   in a SIP INVITE by sending a response of either 200 OK or 415 Bad
   Media Type.  The media server responds with 415 when the SIP request
   contains a content type other than "application/sdp" or "application/
   mediaservercontrol+xml".

   The media server acknowledges receipt of a client MSCML request sent
   in a SIP INFO with a 200 OK or 415 Bad Media Type.  The media server
   responds with 415 if the INFO request contains a content type other
   than "application/mediaservercontrol+xml".

   The media server transports the MSCML <response> message in a SIP
   INFO request.

   If there is an error in the request or the media server cannot
   complete the request, the media server sends the <response> message
   very shortly after receiving the request.  If the request is able to
   proceed, the <response> contains final status information as
   described below.

10.2.  Base <response> Attributes

   All MSCML responses have the basic attributes defined in the list
   below.

   Basic MSCML Response Attributes:

   o  id - optional, no default value: Echoes the client-defined ID
      contained in the request.

   o  request - required, no default value: Specifies the MSCML request
      type that generated the response.  Allowable values are
      "configure_conference", "configure_leg", "play", "playcollect",
      "playrecord", "stop", "faxplay", "faxrecord", and "managecontent".

Top      Up      ToC       Page 57 
   o  code - required, no default value: The final status code for the
      request.  MSCML uses a subset of the status classes defined in RFC
      3261 [4].  In MSCML, 2XX responses indicate success, 4XX responses
      indicate client error, and 5XX responses indicate an error on the
      media server.  There are no 1XX, 3XX, or 6XX status codes in
      MSCML.

   o  text - required, no default value: The human readable reason
      phrase associated with the status code.

   Responses to <configure_conference> and <stop> requests contain only
   the attributes above.  MSCML responses to other requests MAY contain
   additional request-specific attributes and elements.  These are
   described in the following sections.

10.3.  Response Attributes and Elements for <configure_leg>

   Responses to <configure_leg> requests have only the base response
   attributes defined in Section 10.2.  However, when the request
   contains a <configure_team> element, the response includes a <team>
   element describing the teammate configuration for that leg.  The
   attributes of the <team> element are shown in the list below.

   Attributes of <team>:

   o  id - required, no default value: The client-defined unique
      identifier for the conference leg.

   o  numteam - required, no default value: The number of team members
      for the leg.

   Additional information on each team member is conveyed by child
   <teammate> elements contained within <team>.  Each teammate is
   represented by a single element in the list.  The <teammate> element
   has a single attribute, as described below.

   Attributes of <teammate>:

   o  id - required, no default value: The client-defined unique
      identifier for the teammate leg.

10.4.  Response Attributes and Elements for <play>

   In addition to the base response attributes defined in Section 10.2,
   responses to <play> requests have the additional attributes described
   in the list below.

Top      Up      ToC       Page 58 
   MSCML Response Attributes for <play>:

   o  reason - optional, no default value: For requests that are not
      completed immediately, the "reason" attribute conveys additional
      information regarding why the command was completed.  Possible
      values are "stopped", indicating that an explicit or implicit
      <stop> request was received, and "EOF", indicating that the end of
      the specified sequence of URLs was reached.

   o  playduration - required, no default value: A time value (Section
      4.2.1) that returns the duration of the associated content
      playout.

   o  playoffset - required, no default value: A time value (Section
      4.2.1) that returns the time offset into the specified content
      sequence where play was terminated.  If the initial "offset" value
      in the sequence was "0", then "playduration" and "playoffset" are
      equal.  However, if the initial offset had some other value,
      "playoffset" serves as a bookmark for the client to resume play in
      a subsequent request.

10.4.1.  Reporting Content Retrieval Errors

   If the associated request set "stoponerror=yes" in <prompt> and an
   error occurred while retrieving the specified content the response
   will include an <error_info> element detailing the problem.  This
   element contains the response information received from the remote
   content server.  The <error_info> element has the attributes
   described in the list below.

   Attributes of <error_info>:

   o  code - required, no default value: The status code returned by the
      remote content server.  For example, a web server might return 404
      to indicate that the requested content was not found.

   o  text - required, no default value: The human-readable reason
      phrase returned by the remote content server.  For example, the
      reason phrase "Not Found" would be returned if the requested
      content was not found.

   o  context - required, no default value: Contains the content URL
      that was being fetched when the retrieval error occurred.  This
      enables the client to know precisely which URL in a sequence
      caused the problem.

   An <error_info> element MAY be present in the response to any request
   that contains a child <prompt> element.

Top      Up      ToC       Page 59 
10.5.  Response Attributes and Elements for <playcollect>

   In addition to the base response attributes defined in Section 10.2,
   responses to <playcollect> requests have the additional attributes
   described in the list below.

   MSCML Response Attributes for <playcollect>:

   o  reason - optional, no default value: For requests that are not
      completed immediately, the "reason" attribute conveys additional
      information regarding why the command was completed.  Possible
      values are "stopped", indicating that an explicit or implicit
      <stop> request was received; "match", meaning that a DTMF grammar
      was matched; "timeout", indicating that no DTMF input was received
      before one of the collection timers expired; and "returnkey" or
      "escapekey", meaning the DTMF digit mapped to that key was
      detected and the return key or escape key terminated the
      operation, respectively.

   o  playduration - required, no default value: A time value (Section
      4.2.1) that returns the duration of the associated content
      playout.  If the caller barged the prompt, this value will reflect
      the play duration up to that event.

   o  playoffset - required, no default value: A time value (Section
      4.2.1) that returns the time offset into the specified content
      sequence where play was terminated.  If the initial "offset" value
      in the sequence was "0", then "playduration" and "playoffset" are
      equal.  However, if the initial offset had some other value,
      "playoffset" serves as a bookmark for the client to resume play in
      a subsequent request.  If the caller barged the prompt this value
      will reflect the time offset at which barge-in occurred.

   o  digits - required, no default value: Contains the collected DTMF
      input characters.  If no DTMF input was collected, this attribute
      is set to the empty string ("").

   o  name - required (see note), no default value: The client-defined
      name of the DTMF grammar that was matched.  Note: This attribute
      is required if the "name" attribute was set in the matching DTMF
      grammar.

   Responses to <playcollect> requests MAY include an <error_info>
   element, as described in Section 10.4.1.

Top      Up      ToC       Page 60 
10.6.  Response Attributes and Elements for <playrecord>

   In addition to the base response attributes defined in Section 10.2,
   responses to <playrecord> requests have the additional attributes
   described in the list below.

   o  reason - optional, no default value: For requests that are not
      completed immediately, the "reason" attribute conveys additional
      information regarding why the command was completed.  Possible
      values are "stopped", indicating that an explicit or implicit
      <stop> request was received; "digit", meaning that a DTMF digit
      was detected and that the prompt phase was barged; "init_silence",
      meaning the recording terminated because of no input;
      "end_silence", meaning that the recording was terminated because
      the "endsilence" timer elapsed; "max_duration", indicating that
      the maximum time for the recording was reached; "escapekey",
      indicating that the DTMF input mapped to "escapekey" was detected,
      thus terminating the recording; and "error", indicating a general
      operation failure.

   o  playduration - required, no default value: A time value (Section
      4.2.1) that returns the duration of the associated content
      playout.  If the caller barged the prompt, this value will reflect
      the play duration up to that event.

   o  playoffset - required, no default value: A time value (Section
      4.2.1) that returns the time offset into the specified content
      sequence where play was terminated.  If the initial "offset" value
      in the sequence was "0", then "playduration" and "playoffset" are
      equal.  However, if the initial offset had some other value,
      "playoffset" serves as a bookmark for the client to resume play in
      a subsequent request.  If the caller barged the prompt this value
      will reflect the time offset at which barge-in occurred.

   o  digits - required, no default value: Contains the DTMF digit that
      terminated the recording.  If no DTMF input was detected, this
      attribute is set to the empty string ("").

   o  reclength - required, no default value: The length of the recorded
      content, in bytes.

   o  recduration - required, no default value: A time value (Section
      4.2.1) indicating the elapsed duration of the recording.

   Responses to <playrecord> requests MAY include an <error_info>
   element, as described in Section 10.4.1.

Top      Up      ToC       Page 61 
10.7.  Response Attributes and Elements for <managecontent>

   Responses to <managecontent> requests have only the base response
   attributes defined in Section 10.2.  If a content transfer error
   occurs while executing the request the response will also contain an
   <error_info> element as described in Section 10.4.1.

10.8.  Response Attributes and Elements for <faxplay> and <faxrecord>

   In addition to the base response attributes defined in Section 10.2,
   responses to <faxplay> and <faxrecord> requests have the additional
   attributes described in the list below.

   o  reason - required, no default value: For requests that are not
      completed immediately, the "reason" attribute conveys additional
      information regarding why the command was completed.  Possible
      values are "stopped", indicating that an explicit or implicit
      <stop> request was received; "complete", indicating successful
      completion, even if there were bad lines or minor negotiation
      problems (e.g., a DCN was received); "disconnect", meaning that
      the session was disconnected; and "notfax", indicating that no DIS
      or DCS was received on the connection.

   o  pages_received - required (see note), no default value: Indicates
      the number of fax pages received.  Note: This attribute is
      required if any pages were received.

   o  pages_sent - required (see note), no default value: Indicates the
      number of fax pages sent.  Note: This attribute is required if any
      pages were sent.

   o  faxcode - required, no default value: The value of the "faxcode"
      attribute is the binary-or of the bit patterns defined in Table 6.

Top      Up      ToC       Page 62 
              +------+--------------------------------------+
              | Mask | description                          |
              +------+--------------------------------------+
              | 0    | Operation Failed                     |
              | 1    | Operation Succeeded                  |
              | 2    | Partial Success                      |
              | 4    | Image received and placed in recurl  |
              | 8    | Image sent from specified source URL |
              | 16   | rmtid did not match                  |
              | 32   | Error reading source URL             |
              | 64   | Error writing recurl                 |
              | 128  | Negotiation failure on send phase    |
              | 256  | Negotiation failure on receive phase |
              | 512  | Reserved                             |
              | 1024 | Irrecoverable IP packet loss         |
              | 2048 | Line errors in received image        |
              +------+--------------------------------------+

                           Table 6: Faxcode Mask

   Responses to <faxplay> and <faxrecord> requests MAY include an
   <error_info> element, as described in Section 10.4.1.



(page 62 continued on part 4)

Next RFC Part