RFC 5022
Media Server Control Markup Language (MSCML) and Protocol
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.
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'.
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.
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 Notification7.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.
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).
<?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 Notification8. 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.
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.
+-----------+--------------------+ | 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
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
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
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
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.
+--------+--------+---------+---------------------------------------+ | 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,
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".
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.
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.
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.
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.
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.
+------+--------------------------------------+ | 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)
