RFC 4722
Media Server Control Markup Language (MSCML) and Protocol
6. Interactive Voice Response (IVR)
In the IVR model, the media server acts as a media-processing proxy for the UAC. This is particularly useful when the UAC is a media gateway or other device with limited media processing capability. The typical use case for MSCML is when there is an application server that is the MSCML client. The client can use the SIP Service URI concept (RFC 3087) to initiate a service. The client then uses RFC 4240 [2] to initiate a MSCML session on a media server. These relationships are shown in Figure 14. SIP +--------------+ Service URI | Application | /----------------| Server | /(e.g., RFC 3087) +--------------+ / | MSCML / SIP | Session / +--------------+ +-----+/ RTP | | | UAC |======================| Media Server | +-----+ | | +--------------+ Figure 14: IVR Model The IVR service supports basic Interactive Voice Response functions, playing announcements, collecting DTMF digits, and recording, based on Media Server Control Markup Language (MSCML) directives added to the message body of a SIP request. The major MSCML IVR requests are <play>, <playcollect>, and <playrecord>. Multifunction media servers MUST use the URI conventions described in RFC 4240 [2]. The service indicator for MSCML IVR MUST be set to "ivr", as shown in the following example: sip:ivr@ms.example.net The VoiceXML IVR service indicator is "dialog". This service indicator MUST NOT be used for any other interactive voice response control mechanism. The media server MUST accept MSCML IVR payloads in INFO requests and MUST NOT accept MSCML IVR payloads in the initial or subsequent INVITEs. The INFO method reduces certain timing issues that occur with INVITEs and requires less processing on both the client and media server.
The media server notifies the client that the command has completed through a <response> message containing final status information and associated data such as collected DTMF digits. The media server does not queue IVR requests. If the media server receives a new IVR request while another is in progress, the media server stops the first operation and it carries out the new request. The media server generates a <response> message for the first request and returns any data collected up to that point. If a client wishes to stop a request in progress but does not wish to initiate another operation, it issues a <stop> request. This also causes the media server to generate a <response> message. The media server treats a SIP re-INVITE that modifies the established SDP parameters as an implicit <stop> request. Examples of such SDP modifications include receiving hold SDP or removing an audio or video stream. When this occurs, the media server immediately terminates the running <play>, <playcollect>, or <playrecord> request and sends a <response> indicating "reason=stopped".6.1. Specifying Prompt Content
The MSCML IVR requests support two methods of specifying content to be delivered to the user. These are the <prompt> element and the prompturl attribute. Clients MUST NOT utilize both methods in a single IVR request. Clients SHOULD use the more flexible <prompt> mechanism. Use of the prompturl attribute is deprecated and may not be supported in future MSCML versions.6.1.1. Use of the Prompt Element
The <prompt> element MAY be included in the body of a <play>, <playcollect>, or <playrecord> request to specify a prompt sequence to be delivered to the caller. The prompt sequence consists of one or more references to physical content files, spoken variables, or dynamic URLs that return a sub-sequence of files or variables. In addition, the <prompt> element has several attributes that control playback of the included content. These are described in the list below. Attributes of <prompt>: o baseurl - optional, no default value: For notational convenience, as well as reducing the MSCML payload size, the "baseurl" attribute is used to specify a base URL that is prepended to any other URLs in the sequence that are not fully qualified.
o delay - optional, default value "0": The "delay" attribute to the
prompt element specifies the time to pause between repetitions of
the <prompt> sequence. It has no effect on the first iteration of
the sequence. Expressed as a time value (Section 4.2.1) from 0
onwards.
o duration - optional, default value "infinite": The "duration"
attribute to the prompt element controls the maximum amount of
time that may elapse while the media server repeats the sequence.
This allows the client to set an upper bound on the length of
play. Expressed as a time value (Section 4.2.1) from 1ms onwards
or the strings "immediate" and "infinite". "Immediate" directs
the media server to end play immediately, whereas "infinite"
indicates that the media server imposes no limit.
o gain - optional, default value "0": Sets the absolute gain to be
applied to the content contained in <prompt>. The value of this
attribute is specified in units of dB. The media server MAY
silently cap values that exceed the gain limits imposed by the
platform. The level reverts back to its original value when
playback of the content contained in <prompt> has been completed.
o gaindelta - optional, default value "0": Sets the relative gain to
be applied to the content contained in <prompt>. The value of
this attribute is specified in units of dB. The media server MAY
silently cap values which exceed the gain limits imposed by the
platform. The level reverts back to its original value when
playback of the content contained in <prompt> has been completed.
o rate - optional, default value "0": Specifies the absolute
playback rate of the content relative to normal as either a
positive percentage (faster) or a negative percentage (slower).
Any value that attempts to set the rate above the maximum allowed
or below the minimum allowed silently sets the rate to the maximum
or minimum. The rate reverts back to its original value when
playback of the content contained in <prompt> has been completed.
o ratedelta - optional, default value "0": Specifies the playback
rate of the content relative to it's current rate as either a
positive percentage (faster) or negative percentage (slower). Any
value that attempts to set the rate above the maximum allowed or
below the minimum allowed silently sets the rate to the maximum or
minimum. The rate reverts back to its original value when
playback of the content contained in <prompt> has completed.
o locale - optional, no default value: Specifies the language and
country variant used for resolving spoken variables. The language
is defined as a two-letter code per ISO 639. The country variant
is also defined as a two-letter code per ISO 3166. These codes
are concatenated with a single underscore (%x5F) character.
o offset - optional, default value "0": A time value (Section 4.2.1)
which specifies the time from the beginning of the sequence at
which play is to begin. Offset only applies to the first
repetition; subsequent repetitions begin play at offset 0.
Allowable values are positive time values from 0 onwards. When
the sequence consists of multiple content files, the offset may
select any point in the sequence. If the offset value is greater
than the total time of the sequence, it will "wrap" to the
beginning and continue from there until the media server reaches
the specified offset.
o repeat - optional, default value "1": The "repeat" attribute to
the prompt element controls the number of times the media server
plays the sequence in the <prompt> element. Allowable values are
integers from 0 on and the string "infinite", which indicates that
repetition should occur indefinitely. For example, "repeat=2"
means that the sequence will be played twice, and "repeat=0",
which is allowed, means that the sequence is not played.
o stoponerror - optional, default value "no": Controls media server
handling and reporting of errors encountered when retrieving
remote content. If set to "yes", content play will end if a fetch
error occurs, and the response will contain details regarding the
failure. If set to "no", the media server will silently move on
to the next URL in the sequence if a fetch failure occurs.
Clients MUST NOT include both 'gain' and 'gaindelta' attributes
within a single <prompt> element.
When the client explicitly controls the output gain on a conference
leg, as described in Section 5.3, the 'gain' and 'gaindelta'
attributes SHOULD interact with the conference leg output gain
settings in the following manner.
o Conference leg output gain set to <fixed>: The operation of the
'gain' and 'gaindelta' attributes are unchanged. However, the
baseline gain value before any playback changes are applied is the
value specified for the conference leg.
o Conference leg output gain set to <auto>: When playback gain
controls are used, the automatic gain control settings for the leg
are suspended for the duration of the playback operation. The
operation of the 'gain' and 'gaindelta' attributes are unchanged.
The automatic gain control settings are reinstated when playback
has finished.
Media servers SHOULD support rate controls for content. However,
media servers MAY silently ignore rate change requests if content
limitations do not allow the request to be honored. Clients MUST NOT
include both 'rate' and 'ratedelta' attributes within a single
<prompt> element.
Figure 16 shows a sample prompt block.
<prompt stoponerror="yes"
baseurl="file:////var/mediaserver/prompts/"
locale="en_US" offset="0" gain="0" rate="0"
delay="0" duration="infinite" repeat="1">
<audio url="num_dialed.raw" encoding="ulaw"/>
<variable type="dig" subtype="ndn" value="3014170700"/>
<audio url="num_invalid.wav"/>
<audio url="please_check.wav"/>
</prompt>
Figure 16: Prompt Block Example
6.1.1.1. <audio> and <variable> Elements
Clients compose prompt sequences using the <audio> and <variable>
elements. An <audio> element MAY refer to content that contains
audio, video, or both; the generic name is preserved for backwards
compatibility. The <audio> element has the attributes described in
the list below.
Attributes of <audio>:
o url - required, 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. If
the URL is not fully qualified and a "baseurl" attribute was set,
the value of the "baseurl" attribute will be prepended to this
value to generate the target URL.
o encoding - optional, default value "ulaw": Specifies the content
encoding for file formats that are not self-describing (e.g.,
.WAV). Allowable values are "ulaw", "alaw", and "msgsm". This
attribute only affects "file://" scheme URLs.
o gain - optional, default value "0": Sets the absolute gain to be
applied to the content URL. The value of this attribute is
specified in units of dB. The media server MAY silently cap
values that exceed the gain limits imposed by the platform. The
level reverts back to its original value when playback of the
content URL has been completed.
o gaindelta - optional, default value "0": Sets the relative gain to
be applied to the content URL. The value of this attribute is
specified in units of dB. The media server MAY silently cap
values that exceed the gain limits imposed by the platform. The
level reverts back to its original value when playback of the
content URL has been completed.
o rate - optional, default value "0": Specifies the absolute
playback rate of the content relative to normal as either a
positive percentage (faster) or a negative percentage (slower).
Any value that attempts to set the rate above the maximum allowed
or below the minimum allowed silently sets the rate to the maximum
or minimum. The rate reverts back to its original value when
playback of the content URL has been completed.
o ratedelta - optional, default value "0": Specifies the playback
rate of the content relative to it's current rate as either a
positive percentage (faster) or a negative percentage (slower).
Any value that attempts to set the rate above the maximum allowed
or below the minimum allowed silently sets the rate to the maximum
or minimum. The rate reverts back to its original value when
playback of the content URL has been completed.
Clients MUST NOT include both 'gain' and 'gaindelta' attributes
within a single <audio> element.
When the client explicitly controls the output gain on a conference
leg, as described in Section 5.3, the 'gain' and 'gaindelta'
attributes SHOULD interact with the conference leg output gain
settings in the following manner.
o Conference leg output gain set to <fixed>: The operation of the
'gain' and 'gaindelta' attributes are unchanged. However, the
baseline gain value before any playback changes are applied is the
value specified for the conference leg.
o Conference leg output gain set to <auto>: When playback gain
controls are used, the automatic gain control settings for the leg
are suspended for the duration of the playback operation. The
operation of the 'gain' and 'gaindelta' attributes are unchanged.
The automatic gain control settings are reinstated when playback
has finished.
Media servers SHOULD support rate controls for content. However,
media servers MAY silently ignore rate change requests if content
limitations do not allow the request to be honored. Clients MUST NOT
include both 'rate' and 'ratedelta' attributes within a single
<audio> element.
Media servers MUST support local and remote (NFS) "file://" scheme
URLs and "http://" and "https://" scheme URLs for content retrieval.
NOTE: The provisioning of NFS mount points and their mapping to
the "file://" schema is purely a local matter at the media server.
MSCML also supports "http://" and "https://" scheme URLS that return
a list of physical URLs using the "text/uri-list" MIME type. This
facility provides flexibility for applications to dynamically
generate prompt sequences at execution time and enables separation of
this function from the client and media server.
Spoken variables are specified using the <variable> element. This
element has the attributes described in the list below. MSCML's
spoken variables are based on those described in Audio Server
Protocol [17].
Attributes of <variable>:
o type - required, no default value: Specifies the major type format
of the spoken variable to be played. Allowable values are "dat"
(date), "dig" (digit), "dur" (duration), "mth" (month), "mny"
(money), "num" (number), "sil" (silence), "str" (string), "tme"
(time), and "wkd" (weekday).
o subtype - optional, no default value: Specifies the minor type
format of the spoken variable to be played. Allowable values
depend on the value of the corresponding "type" attribute.
Possible values are "mdy", "ymd", and "dmy" for dates, "t12" and
"t24" for times, "gen", "ndn", "crd", and "ord" for digits, and
"USD" for money.
o value - required, no default value: A string that will be
interpreted based on the formatting information specified in the
"type" and "subtype" attributes and the "locale" attribute of the
parent <prompt> element to render the spoken variable.
If the "locale" attribute was not specified in <prompt>, the media
server SHOULD make a selection based on platform configuration. If
the precise "locale" requested cannot be honored, the media server
SHOULD select the closest match based on the available content.
IVR applications normally require specialized prompt content that is authored by the application provider. To deliver a quality user interaction, the specialized prompts and spoken variables must be generated by the same speaker. Since the media server inherently supports multiple simultaneous applications, it is extremely difficult to provision all the necessary application prompts and matching spoken variable content locally on the media server. Therefore, we STRONGLY RECOMMEND that clients employ the dynamic URL mechanism described earlier to generate spoken variables using an external web server that returns "text/uri-list" content.6.2. Multimedia Processing for IVR
MSCML IVR requests implicitly support multimedia content. Multimedia capabilities are controlled by the audio and video media negotiated for the dialog and the content specified by the client for play and record operations. If the content specified for delivery contains both audio and video tracks and the dialog has audio and video streams, both tracks are streamed to the caller. Likewise, if the dialog has both audio and video streams and the content format specified supports both (e.g., .3gp files) the media server records both streams to the file. If there is a mismatch between the real time media and specified content, the media server MUST play or record the appropriate content tracks rather than failing the request. For example, if the client has requested playback of content with audio and video tracks but only audio media has been established for the dialog, the media server should play the audio track. If the dialog has both audio and video media but the content is audio-only, the media server MAY stream a pre-provisioned video track to the caller. Media servers SHOULD implement video transcoding functions to minimize incompatibilities between real time media and content. The media server MUST begin recording video media only when it receives a refresh video frame. A refresh frame contains all the video information required to decode that frame (i.e., there is no dependency on data from previous video frames). Refresh frames are large and generally sent infrequently to conserve network bandwidth. The media server MUST implement standard mechanisms to request that the caller (video encoder) transmit a refresh frame to ensure video recording begins quickly. The media server MUST begin recording the audio track immediately while waiting to receive the video refresh frame.
6.3. Playing Announcements <play>
The client issues a <play> request to play an announcement without interruption and with no digit collection. One use, for example, is to announce the name of a new participant to the entire conference. The <play> request has the attributes described in the list below. Attributes of <play>: o id - optional, no default value: Specifies a client-defined ID for purposes of matching requests and responses. o offset - optional, default value "0": Specifies the time from the beginning of the URL specified in the 'prompturl' attribute at which play will begin. Expressed as a time value (Section 4.2.1) from 0 onwards. If the offset value is greater than the total time of the content, it will "wrap" to the beginning and continue from there until the media server reaches the specified offset. NOTE: Use of this attribute is deprecated. o promptencoding - optional, no default value: Specifies the content encoding for file formats that are not self-describing (e.g., .WAV). Allowable values are "ulaw", "alaw", and "msgsm". This attribute only affects "file://" scheme URLs. NOTE: Use of this attribute is deprecated. 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. The <play> request has one child element defined, <prompt>. Use of <prompt> is described in Section 6.1.1. The client MUST NOT use both the <prompt> element and "prompturl" attribute in a single request. As previously discussed, the "prompturl" attribute is supported for backwards compatibility with older MSCML applications, but its use is deprecated. The more flexible <prompt> element SHOULD be used instead. The following play request (Figure 17) example shows the delivery of a complex prompt sequence consisting of content accessed via NFS and spoken variables.
<?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <play id="332985001"> <prompt stoponerror="yes" baseurl="file:////var/mediaserver/prompts/" locale="en_US" offset="0" gain="0" rate="0" delay="0" duration="infinite" repeat="1"> <audio url="num_dialed.raw" encoding="ulaw"/> <variable type="dig" subtype="ndn" value="3014170700"/> <audio url="num_invalid.wav"/> <audio url="please_check.wav"/> </prompt> </play> </request> </MediaServerControl> Figure 17: <Play> Request Example When the announcement has finished playing, the media server sends a <response> payload to the client in a SIP INFO message. Details regarding the format of <play> responses are provided in Section 10.4.6.4. Prompt and Collect <playcollect>
The client issues a <playcollect> request to play an announcement (optional) and collect digits. The <playcollect> request is executed in two phases, prompt and collect. If the client specifies prompt content to be played, using the <prompt> element or prompturl attribute, the media server plays the content before starting the collection phase. If no prompt content is specified, the collect phase begins immediately. The basic attributes of <playcollect> are the same as those of <play>, which were described in Section 6.3. In addition to these basic attributes, <playcollect> defines others which control digit buffering and barge-in behavior, collection timers, special purpose DTMF key functions, and logging of user DTMF input. Each functional category and its attributes are described below.
6.4.1. Control of Digit Buffering and Barge-In
Whenever the media server is processing a call that specifies an MSCML service (i.e., "conf" and "ivr"), the media server continuously looks for DTMF digits and places them in a quarantine buffer. The quarantine buffer is examined when a <playcollect> request is received. The media server compares any previously buffered digits for barge-in, and to look for matches with DTMF grammars or special purpose keys. This provides the type-ahead behavior for menu traversal and other types of IVR interactions. Attributes for Control of Digit Buffering and Barge-In: o cleardigits - optional, default value "no": Specifies whether previous user input should be considered or ignored for barge-in purposes and DTMF matching. When it is set to "yes", any previously buffered digits are removed, so prior user input is ignored. If it is set to "no", previously buffered digits will be considered. If "cleardigits" is set to "no" and barge-in is enabled, previously buffered digits will immediately terminate the prompt phase. In this case, the prompt is not played, and digit collection begins immediately. o barge - optional, default value "yes": Specifies whether user input will barge the prompt and force transition to the collect phase. When it is set to "yes", a DTMF input will barge the prompt. When it is set to "no", the prompt phase cannot be barged, and any user input during the prompt is placed in the quarantine buffer for inspection during the collect phase. Note that if the "barge" attribute is set to "no", the "cleardigits" attribute implicitly has a value of "yes". This ensures that the media server does not leave DTMF input that occurred prior to the current collection in the quarantine buffer after the request is completed.6.4.2. Mapping DTMF Keys to Special Functions
The client can define mappings between DTMF digits and special functions. The media server invokes the special function if the associated DTMF digit is detected. MSCML has two attributes that define mappings that affect termination of the collect phase. These attributes are described in the list below.
DTMF Key Mappings for <playcollect>:
o escapekey - optional, default value "*": Specifies a DTMF key that
indicates that the user wishes to terminate the current operation
without saving any input collected to that point. Detection of
the mapped DTMF key terminates the request immediately and
generates a response.
o returnkey - optional, default value "#": Specifies a DTMF key that
indicates that the user has completed input and wants to return
all collected digits to the client. When the media server detects
the returnkey, it immediately terminates collection and returns
the collected digits to the client in the <response> message.
MSCML defines three additional mappings to enable video cassette
recorder (VCR) type controls while playing a prompt sequence. Media
servers SHOULD support VCR controls. However, if the media server
does not support VCR controls, it MUST silently ignore DTMF inputs
mapped to VCR functions and complete the <playcollect> request. The
VCR control attributes are described in the list below.
Attributes for VCR Controls:
o skipinterval - optional, default value "6s": The "skipinterval"
attribute indicates how far the media server should skip backwards
or forwards when the rewind key (rwkey) or fast forward key
(ffkey) is pressed, specified as a time value (Section 4.2.1).
o ffkey - optional, no default value: The "ffkey" attribute maps a
DTMF key to a fast forward operation equal to the value of the
"skipinterval" attribute.
o rwkey - optional, no default value: The "rwkey" attribute maps a
DTMF key to a rewind action equal to the value of the
"skipinterval" attribute.
Clients MUST NOT map the same DTMF digit to both the "rwkey" and
"ffkey" attributes in a single <playcollect> request.
VCR control operations are bounded by the beginning and end of the
prompt sequence. A rewind action that moves the offset before the
beginning of the sequence results in playback starting at the
beginning of the sequence (i.e., offset=0). A fast forward action
that moves the offset past the end of the sequence results in the
media server's treating the sequence as complete.
6.4.3. Collection Timers
MSCML defines several timer attributes that control how long the media server waits for digits in the input sequence. All timer settings are time values (Section 4.2.1). The list below describes these attributes and their use. Collection Timer Attributes: o firstdigittimer - optional, default value "5000ms": Specifies how long the media server waits for the initial DTMF input before terminating the collection. Expressed as a time value (Section 4.2.1) from 1ms onwards or the strings "immediate" and "infinite." The value "immediate" indicates that the timer should fire immediately whereas "infinite" indicates that the timer will never fire. o interdigittimer - optional, default value "2000ms": Specifies how long the media server waits between DTMF inputs. Expressed as a time value (Section 4.2.1) from 1ms onwards or the strings "immediate" and "infinite." The value "immediate" indicates that the timer should fire immediately, whereas "infinite" indicates that the timer will never fire. o extradigittimer - optional, default value "1000ms": Specifies how long the media server waits for additional user input after the specified number of digits has been collected. Expressed as a time value (Section 4.2.1) from 1ms onwards or the strings "immediate" and "infinite." The value "immediate" indicates that the timer should fire immediately, whereas "infinite" indicates that the timer will never fire. o interdigitcriticaltimer - optional, defaults to the value of the interdigittimer attribute: Specifies how long the media server waits after a grammar has been matched for a subsequent digit that may cause a longer match. Expressed as a time value (Section 4.2.1) from 1ms onwards or the strings "immediate" and "infinite." The value "immediate" results in "shortest match first" behavior, whereas "infinite" means to wait indefinitely for additional input. If not explicitly specified otherwise, this attribute is set to the value of the 'interdigittimer' attribute. The extradigittimer setting enables the "returnkey" input to be associated with the current collection. For example, if maxdigits is set to 3 and returnkey is set to #, the user may enter either "x#", "xx#", or "xxx#", where x represents a DTMF digit.
If the media server detects the "returnkey" pattern during the "extradigit" interval, the media server returns the collected digits to the client and removes the "returnkey" from the digit buffer. If this were not the case, the example would return "xxx" to the client and leave the terminating "#" in the digit buffer. At the next <playcollect> request, the media server would process the '#'. This might result in the termination of the following prompt, which is clearly not what the user intended. The extradigittimer has no effect unless returnkey has been set.6.4.4. Logging Caller DTMF Input
Standard SIP mechanisms, such as those discussed in Security Considerations (Section 14), protect MSCML protocol exchanges and the information they contain. These protections do not apply to data captured in media server log files. In general, media server logging is platform specific and therefore is not covered by this specification. However, one aspect of logging, the capture of sensitive information (such as personal identification numbers or credit card numbers), is relevant. The media server has no means to determine whether the DTMF input it receives may be sensitive, as that is in the purview of the client. Recognizing this, MSCML includes a per- request mechanism to suppress logging of captured DTMF to be enabled by clients as needed. The "maskdigits" attribute controls whether detected DTMF digits appear in the log output. Clients use this attribute when the media server collects sensitive information that should not be accessible through the log files. Maskdigits Attribute: 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".6.4.5. Specifying DTMF Grammars
MSCML supports four methods for specifying DTMF grammars: the "maxdigits" attribute, which provides a simple mechanism for collecting any number of digits up to the maximum, regular expressions, MGCP [5] digit maps, and H.248.1 [6] digit maps. A media server MUST support the maxdigits and regular expression methods for specifying DTMF grammars and SHOULD support MGCP and H.248.1 methods. A client MUST NOT mix DTMF grammar types in a single <playcollect> request.
Following is a description of the "maxdigits" attribute.
Maxdigits Attribute:
o maxdigits - optional, no default value: Specifies the maximum
number of DTMF digits to be collected.
The <pattern> element specifies a digit pattern or patterns for the
media server to look for. This element may contain three different
child elements that specify the type of DTMF grammar used in the
expression. The <pattern> element has no attributes.
<regex> Use regular expressions to define DTMF patterns to match.
The complete regular expression syntax used in MSCML is described
in Appendix A.
<mgcpdigitmap> Use digit maps as specified in MGCP [5].
<megacodigitmap> Use digit maps as specified in H.248.1 [6].
At least one <regex> element MUST be present in <pattern> when regex
grammars are used. Multiple <regex> elements MAY be present. When
<mgcpdigitmap> or <megacodigitmap> grammars are used, <pattern> MUST
contain only one grammar element.
The DTMF grammar elements <regex>, <mgcpdigitmap>, and
<megacodigitmap> have the attributes described in the list below.
Attributes of DTMF Grammar Elements:
o value - required, no default value: Specifies a string
representing a DTMF grammar matching the parent element type
(e.g., regex). Regex values represent a single DTMF grammar.
MGCP and MEGACO digit maps allow multiple grammars to be described
in a single string.
o name - optional, no default value: Associates a client defined
name for the grammar that is sent back in the <playcollect>
response. This attribute is most useful with regex type grammars
as each grammar element can have a unique name.
6.4.6. Playcollect Response
When the <playcollect> has finished, the media server sends a
<response> payload to the client in a SIP INFO message.
Details of the <playcollect> response are described in Section 10.5.
6.4.7. Playcollect Example
The following <playcollect> request (Figure 18) example depicts use of the "maxdigits" attribute to control digit collection. <?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <playcollect id="332986004" maxdigits="6" firstdigittimer="10000" interdigittimer="5000" extradigittimer="1000" interdigitcriticaltimer="1000" returnkey="#" escapekey="*" cleardigits="no" barge="yes" maskdigits="no"> <prompt baseurl="http://www.example.com/prompts/"> <audio url="generic/en_US/enter_pin.wav"/> </prompt> </playcollect> </request> </MediaServerControl> Figure 18: <Playcollect> Request Example Using the Maxdigits Attribute6.5. Prompt and Record <playrecord>
The <playrecord> request directs the media server to convert and possibly to transcode the RTP payloads it receives and store them to the specified URL using the requested content codec(s) and file format. This request proceeds in two phases; prompt and record. The <playrecord> request shares the basic attributes of <play> and <playcollect> as described in Section 6.3. MSCML also defines other attributes that control the behavior of the prompt and recording phases. These phases and the attributes that control them are described in the text and tables below.6.5.1. Prompt Phase
The presence or absence of a "prompturl" attribute or child <prompt> element controls whether a prompt is played before recording begins. As previously noted, use of the "prompturl" attribute is deprecated, and clients SHOULD use <prompt> instead. When the client requests that the media server prompt the caller before recording audio, <playrecord> has two stages. The first is equivalent to a <playcollect> operation. The client may set the prompt phase to be interruptible by DTMF input (barge) and may specify an escape key that will terminate the <playrecord> request before the recording phase begins.
The list below describes the attributes of <playrecord> that specify
the behavior of the prompt phase of the request.
Playrecord Attributes for the Prompt Phase:
o barge - optional, default value "yes": Specifies whether user
input will barge the prompt and force transition to the record
phase. When it is set to "yes", a DTMF input will barge the
prompt. When it is set to "no", the prompt phase cannot be
barged, and any user input during the prompt is placed in the
quarantine buffer for inspection during the collect phase. Note
that if the "barge" attribute is set to "no", the "cleardigits"
attribute implicitly has a value of "yes". This ensures that the
media server does not leave DTMF input that occurred prior to the
current collection in the quarantine buffer after the request
completes.
o cleardigits - optional, default value "no": Specifies whether
previous user input should be considered or ignored for barge-in
purposes. When it is set to "yes", any previously buffered digits
are removed, so prior user input is ignored. If it is set to
"no", previously buffered digits will be considered. If
"cleardigits" is set to "no" and barge-in is enabled, previously
buffered digits will terminate the prompt phase immediately. In
this case, the prompt is not played, and recording begins
immediately.
o escapekey - optional, default value "*": Specifies a DTMF key that
indicates the user wishes to terminate the current operation
without saving any input recorded to that point. Detection of the
mapped DTMF key terminates the request immediately and generates a
response.
Detection of the escape key generates a response message, and the
operation returns immediately. If the user presses any other keys
and if the prompt is interruptible (barge="yes"), then the play stops
immediately, and the recording phase begins.
6.5.2. Record Phase
If the request proceeds to the recording phase, the media server
discards any digits from the collect phase from the quarantine buffer
to eliminate unintended termination of the recording. The following
attributes control recording behavior.
Playrecord Attributes for the Record Phase:
o recurl - required, no default value: Specifies the target URL for
the recorded content.
o recencoding - optional, default value "ulaw": Specifies the
encoding of the recorded content if it cannot be inferred from the
recurl. Possible values are "ulaw", "alaw", and "msgsm."
o mode - optional, default value "overwrite": Specifies whether the
recording should overwrite or be appended to the target URL.
Allowable values are "overwrite" and "append."
o duration - optional, default value "infinite": Specifies the
maximum allowable duration for the recording. Expressed as a time
value (Section 4.2.1) from 1 onwards or the strings "immediate"
and "infinite." The value "immediate" indicates that recording
will end immediately, whereas "infinite" indicates recording
should continue indefinitely. If the maximum duration is reached,
the <playrecord> request will terminate and generate a response.
o beep - optional, default value "yes": Specifies whether a beep
should be played to the caller immediately prior to the start of
the recording phase. Allowable values are "yes" and "no."
o initsilence - optional, default value "3000ms": Specifies how long
to wait for initial speech input before terminating (canceling)
the recording. Expressed as a time value (Section 4.2.1) from 1ms
onwards or the strings "immediate" and "infinite." The value
"immediate" indicates that the timer should fire immediately,
whereas "infinite" directs the media server to wait indefinitely.
o endsilence - optional, default value "4000ms": Specifies how long
the media server waits after speech has ended to stop the
recording. Expressed as a time value (Section 4.2.1) from 1ms
onwards or the strings "immediate" and "infinite." When set to
"infinite", the recording will continue indefinitely after speech
has ended and will only terminate due to a DTMF keypress or
because the input has reached the maximum desired duration.
o recstopmask - optional, default value "0123456789ABCD#*":
Specifies a list of individual DTMF characters that, if detected,
will cause the recording to be terminated. To ensure that the
input of a specific key does not cause the recording to stop,
remove the DTMF key from the list.
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 media server buffers and returns any digits collected in the prompt phase, with the exception of those contained in the "recstopmask" attribute, in the response. The media server compares digits detected during the recording phase to the digits specified in the "recstopmask" to determine whether they indicate a recording termination request. The media server ignores digits not present in the recstopmask and passes them into the recording. If DTMF input terminates the recording, the media server returns the collected digit to the client in the <response>. Once recording has begun, the media server writes the received media to the specified recurl URL no matter what DTMF events the media server detects. It is the responsibility of the client to examine the DTMF input returned in the <response> message to determine whether the audio file should be saved or deleted and, potentially, re-recorded. If the endsilence timer expires, the media server trims the end of the recorded audio by an amount equal to the value of the "endsilence" attribute. When the recording is finished, the media server generates a <response> message and sends it to the client in a SIP INFO message. Details of the <playrecord> response are described in Section 10.6.6.5.3. Playrecord Example
The recording example (Figure 19) plays a prompt and records it to the destination specified in the "recurl" attribute encoded as MS-GSM in wave format.
<?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <playrecord id="5556123" recurl="file:////nfs.example.com/rec/name.wav" recencoding="msgsm" initsilence="5000" endsilence="3000" duration="30000" barge="yes" beep="yes" mode="overwrite" cleardigits="no" escapekey="*" recstopmask="0123456789#*"> <prompt> <audio url="http://www.example.com/prompts/recordname.wav"/> </prompt> </playrecord> </request> </MediaServerControl> Figure 19: Recording Example6.6. Stop Request <stop>
The client issues a <stop> request when the objective is to stop a request in progress and not to initiate another operation. This request generates a <response> message from the media server. The only attribute is id, which is optional. The client-defined request id correlates the asynchronous response with its original request and echoes back to the client in the media server's response. The following MSCML payload (Figure 20) depicts an example <stop> request. <?xml version="1.0"?> <MediaServerControl version="1.0"> <request> <stop id="4578903"/> </request> </MediaServerControl> Figure 20: Stop Example The format of a response to a <stop> request is detailed in Section 10.2.
As discussed previously, the media server treats a SIP re-INVITE that modifies the established SDP parameters as an implicit <stop> request. Examples of such SDP modifications include receiving hold SDP or removing an audio or video stream. When this occurs, the media server immediately terminates the running <play>, <playcollect>, or <playrecord> request and sends a <response> indicating "reason=stopped".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.
(page 56 continued on part 3)
