Runtime control overview

Runtime control (RTC) within the Natural Access development environment enables Natural Access services on a context to take actions based upon events generated by other services on the context.

This topic presents:

• Conditions and actions

• RTC function summary

• Program flow

Conditions and actions

Natural Access runtime control is orchestrated by the dispatcher, which receives all events generated by service managers. A service (the consumer service) can register with the dispatcher to receive RTC notification whenever another service (the provider service) generates an event that matches a condition specified by the consumer service. With each condition, the consumer registers a corresponding action to perform when the condition is met.

Note: All services that generate events are automatically provider services. A service does not need to take any other specific action to become a provider service.

The condition can be any of the following:

• The dispatcher receives a specific event from the provider service with a specific reason code

• The dispatcher receives a specific event from the provider service with any reason code

• The dispatcher receives any event from the provider service

• The dispatcher receives an event associated with a registered alias

The dispatcher stores the condition and action pairs in a database:

Condition and action pairs stored in database

Whenever the dispatcher receives an event, it consults the database. If the event matches a condition stored there, the dispatcher tells the registering service manager to perform the corresponding action:

Action sent to consumer service

Once it has registered its condition and action pairs in the RTC database, the consumer service does not need to take any further RTC-specific actions (except unregistering its condition and action pairs at the end of the session).

Actual runtime control operations in response to the provider service's events involve only the dispatcher and the consumer service managers. The application is not involved in RTC at all, and does not need to know that runtime control operations are taking place.

Note: Service roles (provider or consumer) are assigned on a per-event basis: a service can issue events (making it a provider service) and then receive RTC notifications (making it a consumer service) within the same session.

RTC function summary

The following dispatcher service functions are directly involved in RTC notification:

The following table lists optional binding functions for service managers that can be provided to Natural Access when a service manager is registered with the system. The dispatcher invokes both functions. The service writer determines the actions taken by the provider service when these functions are called.

Program flow

To register a condition and associated action, the consumer service manager invokes the dispatcher function dispAddRTC. With dispAddRTC, the service manager passes pointers to structures specifying the condition and action. Each successful invocation of dispAddRTC adds one condition and action pair to the RTC database. The service manager can register as many pairs as necessary. It can also register multiple actions to perform for a single condition. Any event or set of events from a provider service can be registered.

The dispatcher directs services to take actions by issuing Natural Access commands. If the service you are creating is to receive RTC notifications, the service must define one or more action identifier values of type CTA_CODE_COMMAND.

Note: Condition and action pairs are registered on a context-by-context basis. Conditions and actions specified within one context do not apply to other contexts. Also, all services must be located within the same Natural Access server.

Service managers can register for RTC notification at any time: during the initialization of the service or as a result of a function call made by an application. For example, the service manager can register for RTC notification in response to an indication from an application (through a call parameter) that voice play should be stopped on barge-in.

If RTC notifications are set up during service initialization, the consumer service typically makes its invocations of dispAddRTC when the dispatcher invokes xxxOpenService to open the consumer service. The provider service does not need to be open for the dispAddRTC invocation to succeed.

Note: If RTC notifications are set up during service initialization, these requests are typically also removed when xxxCloseService is invoked (using the dispatcher function dispRemoveRTC).

dispAddRTC

When the provider service specified in the dispAddRTC invocation is opened, the dispatcher invokes xxxAddRTC. xxxAddRTC is an optional binding function. The service writer determines the actions taken by the service when this function is called. Then CTAEVN_OPEN_SERVICES_DONE is returned on the client side:

xxxAddRTC

When a provider service places an event in the event queue that satisfies an RTC condition, the dispatcher consults the database to determine the consumer services to notify and the commands to send to which services. The dispatcher invokes a consumer service's xxxProcessCommand function to direct the service to perform an action. During processing of the action, the consumer service can optionally pass events to the dispatcher, which passes them to the client side. When all commands are complete, the original trigger event generated by the provider service is passed to the client side.

xxxProcessCommand is synchronous. It is the responsibility of the consumer service to return to the dispatcher as soon as possible so that performance is not adversely affected by its RTC action processing.

Action sent in response to event

The order in which services receive RTC action notifications from the dispatcher is independent of the order in which they invoke dispAddRTC. The order is also independent of the order in which services are listed in the ctaOpenServices call.

The action command sent to the service manager with xxxProcessCommand is in the form of a generic DISP_COMMAND structure. The trigger event (DISP_EVENT) is mapped into DISP_COMMAND in the following way:

1. The event ID and value are mapped into an RTC_EVT_CMD_DATA structure:

/* RTC "DISP_EVENT" to "DISP_COMMAND" data */
typedef struct
{
    DWORD Size;       /* Size RTC_EVT_CMD_DATA         */
    DWORD EventId;    /* "id" field from DISP_EVENT    */
    DWORD EventValue; /* "value" field from DISP_EVENT */
} RTC_EVT_CMD_DATA;

2. A pointer to the RTC_EVT_CMD_DATA structure is sent in the DISP_COMMAND structure along with other information, as follows:

If addr.destination is RTC_BROADCAST, the event sent in DISP_EVENT is not propagated up to the application level. This process enables services to pass informational events to one another using RTC notification without involving the application.