Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 5022

Media Server Control Markup Language (MSCML) and Protocol

Pages: 81
Informational
Errata
Obsoletes:  4722
Part 3 of 4 – Pages 43 to 62
First   Prev   Next

Top   ToC   RFC5022 - Page 43   prevText

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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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   ToC   RFC5022 - 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 Section