3 Event Handling
The VoiceXML interpreter can throw a number of predefined events based on errors, telephone disconnects or user requests. You can also throw events you define that are specific to your application. When an event is thrown, the associated event handler, if it exists, is invoked. Then execution resumes in the element that was being executed when the event was thrown.
This chapter describes:
Predefined Events
The following standard events are predefined:
| Event |
Description |
exit
|
The user asked to exit.
|
help
|
The user asked for help.
|
noinput
|
The user did not provide timely input.
|
nomatch
|
The user did not provide meaningful input.
|
cancel
|
The user asked to cancel the prompt that is being played.
|
connection.disconnect.hangup
|
The user hung up. New in VoiceXML 2.0.
|
connection.disconnect.transfer
|
The user's call was transferred. New in VoiceXML 2.0.
|
The following additional events are defined as BeVocal VoiceXML extensions:
| Event |
Description |
goback
|
User wants to retract the last response and go back to an earlier part of the interaction. See Chapter 7, Go-Back Facility.
|
connection.far_end.busy
|
The number for an outbound telephone call was busy.
|
connection.far_end.disconnect
|
An outbound telephone was disconnected because the called third party hung up. Outbound telephone calls are described in Chapter 6, Controlling Outbound Calls.
|
connection.far_end.disconnect.timeout
|
An outbound telephone exceeded its maximum allowed duration.
|
connection.far_end.noanswer
|
An outbound telephone call was not answered within the time allowed for making the connection.
|
The following standard errors are predefined:
| Event |
Description |
error.badfetch
|
An error occurred while the interpreter was fetching a document or resource.
|
error.noauthorization
|
The user is not authorized to perform the requested action.
|
error.semantic
|
A runtime error occurred in the VoiceXML code.
|
error.connection.baddestination
|
The destination URI for an outbound telephone call was invalid.
|
error.connection.noauthorization
|
An attempt was made to place an unauthorized outbound telephone call, for example, one that exceeds the maximum allowed duration.
|
error.connection.noresource
|
An audio input or output resource is unavailable.
|
error.noresource
|
An audio input or output resource is unavailable.
|
error.unsupported.format
|
The requested resource format is not supported.
|
error.unsupported.element
|
The requested element is not supported (for example, error.unsupported.subdialog).
|
The following additional errors are defined as BeVocal VoiceXML extensions:
| Event |
Description |
error.internal
|
A serious internal error occurred in the interpreter.
|
error.bevocal.maxdialogerrors_exceeded
|
The maximum number of speech errors was exceeded in a particular execution of a particular form.
|
error.bevocal.maxerrors_exceeded
|
The maximum number of speech errors was exceeded during the call.
|
Note: In a VoiceXML 2.0 document (when the value of the version attribute of the vxml tag is 2.0), the telephone.disconnect.* and error.telephone.* events have been changed to connection.disconnect.* and error.connection.*. See above.
Backward Compatibility with VoiceXML 1.0.
The following predefined events are still supported in VoiceXML 1.0:
| Event |
Description |
telephone.disconnect.hangup
|
The user hung up.
|
telephone.disconnect.transfer
|
The user's call was transferred.
|
The following predefined errors are still supported in VoiceXML 1.0:
| Event |
Description |
error.telephone.baddestination
|
The destination URI for an outbound telephone call was invalid.
|
error.telephone.noauthorization
|
An attempt was made to place an unauthorized outbound telephone call, for example, one that exceeds the maximum allowed duration.
|
error.telephone.noresource
|
A telephone resource is unavailable, for example because the application tried to make an outbound telephone call while another outbound call was active.
|
Default Event Handlers
The BeVocal interpreter provides the following default event handlers for the predefined events and errors:
| Event Handler |
Description |
exit
|
Exit the interpreter.
|
help
|
Play a default audio help message and reprompt. The help message says: "No help available right now."
|
noinput
|
Play a default audio message and reprompt. The message says: "I'm sorry, I didn't hear you."
|
nomatch
|
Play a default audio message and reprompt. The says: "I'm sorry, I didn't understand you."
|
cancel
|
Stop playing audio.
|
error
|
Exit the interpreter.
|
connection.disconnect.hangup
|
Exit the interpreter. New in VoiceXML 2.0.
|
goback
|
Undo whatever actions resulted from the last response, then prompt the user for a new response.
|
All others
|
Play a default audio error message and exit the interpreter.
|
Backward Compatibility with VoiceXML 1.0:
The following predefined events handler is still supported for VoiceXML 1.0.
| Event Handler |
Description |
telephone.disconnect.hangup
|
Exit the interpreter.
|
Application-Defined Event Handlers
Although the system provides default handlers for the predefined events, you can override these handlers by providing your own event handlers in any element that can throw an event. The <catch>, <error>, <help>, <noinput>, and <nomatch> elements are event handlers.
An element in which an event may be thrown also inherits event handlers defined in its ancestor elements. For example, an event thrown within a field element may be caught by a handler in that element, or in its form, or in its document, or in its application. This inheritance of event handlers allows you to provide consistency in event handling by defining handlers at a higher level.
The method by which event handlers are inherited from ancestor elements is called as if by copy semantics in the VoiceXML 2.0 specification. It helps to think of the appropriate event-handler literally being copied into the scope of where the event was thrown. Variable references are resolved relative to the scope of the element where the event was thrown. And URL references are resolved relative to the document from which the event was thrown. For example, if you have a <catch> handler in an application root document, which is in a different directory from the main document which threw the event, URLs in the handler will be resolved to the directory of the main document. The change to URL resolution to the originating document is considered 2.0 behavior and applies only when the <vxml> tag's version attribute is set to "2.0" or greater.
Form items contain event counters that let you respond differently if the same event is thrown multiple times. For example, you may want to provide more details each time the user asks for help. The event counters are reset on each form invocation.
When an event occurs, its counter is used to select applicable event handlers:
| 1. | All handlers in the scope in which the event occurred and its containing scopes are considered. |
| 2. | A handler for the event is eligible if its count attribute is less than or equal to the event's counter. |
| 3. | Those eligible handlers with the highest count are selected as applicable (more than one handler may have the same highest count). |
| 4. | The applicable handlers are ordered by scope, with the innermost event handlers first; within a given scope, the applicable handlers are examined in the order in which the occur in the VoiceXML document. The first applicable handler in this ordering is selected to handle the event. |
You can set up event handlers that catch all events with a given prefix (for example, error.unsupported). Note, however, that the interpreter selects a handler based on count, scope, and document order only. A more specific handler does not take precedence. For example, if an error.unsupported.format event is thrown and the first applicable handler is for all events beginning with the prefix error.unsupported, that handler will be invoked even if the next applicable handler is for the specific event error.unsupported.format.
Within an event handler, the _event variable contains the name of the event currently being handled; the _message variable contains the message string that provides additional information about the event. If no message was supplied when the event was thrown, the _message variable is undefined.
|
|
Tips:
|
| • | Always set up default <help>, <nomatch>, and <noinput> messages of your own, at top level scope. For example: |
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<help>
I'm sorry. There's no help available here. <reprompt/>
</help>
<noinput>
I'm sorry. I didn't hear anything. <reprompt/>
</noinput>
<nomatch>
I didn't get that. <reprompt/>
</nomatch>
...
| • | If you want to execute both an event handler in an inner scope and a handler for the same event in an outer scope, the inner handler can use a <rethrow> element to rethrow the event. |
|
Events in Subdialogs
A subdialog must catch any event that is thrown while the subdialog is being executed. If no handler for the event is found in the subdialog's execution context, a fatal error occurs, causing the interpreter to exit.
(VoiceXML 1.0 only) In VoiceXML 1.0, when a subdialog throws an event, the result depends on whether the subdialog is modal. Subdialogs are modal by default; a subdialog can be made non-modal by setting the modal attribute to false.
| • | If an event is thrown within a modal subdialog and no handler for the event is found in the subdialog's execution context, a fatal error occurs, causing the interpreter to exit. |
| • | If an event is thrown within a non-modal subdialog and no handler for the event is found in the subdialog's execution context, the interpreter causes the subdialog's context to return and rethrows the event in the calling context, restarting the search for the event handler in that context. |
Note: In VoiceXML 2.0, all subdialogs are modal.
Throwing Events
An application can throw events as follows:
| • | A <throw> element throws an event; it can occur within executable content, that is, in a block or <filled> element, or an event handler. |
| • | A <link> element can specify an event to be thrown when the link's grammar is matched. |
| • | A <choice> element in a menu can specify an event to be thrown when the choice's grammar is matched. |
| • | A <return> element in a subdialog can specify an event to be thrown after control returns to the calling dialog. |
Application-Defined Events
An application can define additional events implicitly. If a tag that throws an event specifies an event other than one of the predefined events, it implicitly defines the specified event. For example, the following tag implicitly defines an event named myEvent and throws that event.
<throw event="myEvent"/>
An application can use a <catch> element to catch and handle an application-defined-event. For example:
<catch event="myEvent">
...
</catch>
[Show Frames] [FIRST] [PREVIOUS] [NEXT]
