4. Advanced SRL Programming Concepts for Dialogic Products

• 4.1.1. Setting Up Event Handlers
• 4.1.2. Event Handler Guidelines
• 4.1.3. Hierarchy of Event Handlers
• 4.1.4. SRL Callback Thread Behavior
• Using an SRL Handler Thread for SRL Callback
• Using an Application-Handler Thread

4.1. SRL Event Handler Programming

The following information is provided in this section:

• Guidelines for programming SRL event handlers (Section 4.1)
• Uses of Asynchronous with Windows callback programming (Section 4.2)
• Uses of Asynchronous with Win32 synchronization programming (Section 4.3)

An event handler is a user-defined function called by the SRL to handle a specified event that occurs on a specified device.

4.1.1. Setting Up Event Handlers

To manage many asynchronous events more simply, you can set up event handlers to act as application-level interrupt service routines. You can set up event handlers to be invoked for:

• A single event on any device.
• Any event on a specified device.
• Combinations of events on combinations of devices. Where overlap occurs, the SRL calls all applicable event handlers.

For details about how to use event handlers in asynchronous programming, see the following sections:

• 4.1.4. SRL Callback Thread Behavior
• 5.3. Asynchronous with SRL Callback Model

4.1.2. Event Handler Guidelines

The following guidelines apply to event handlers:

• You can enable more than one handler for any event. The SRL calls all specified handlers when a thread detects the event.
• You can enable or disable handlers from any thread.
• You can enable general handlers that handle all events on a specified device.
• You can enable a handler for any event on any device.
• You cannot call synchronous functions in a handler.

By default, on the first call to sr_enbhdlr( ), the SRL creates an internal thread, the SRL handler thread, that services event handlers. The SRL handler thread exists as long as one handler is still enabled. (See also the sr_dishdlr( ) function.)

Handlers are called from the context of the SRL handler thread. Therefore, if the main thread is blocked in a non-Dialogic function and an asynchronous event, such as a hang-up, occurs on a device being controlled by the main thread, the handler is called immediately within the context of the SRL handler thread that has been created to service handlers.

Control this SRL handler thread creation through the SRL parameter SR_MODELTYPE, specified in the Asynchronous with SRL Callback model.

As explained in Section 4.1.4. SRL Callback Thread Behavior, the Asynchronous with SRL Callback model lets your application execute event handlers through the following threads:

• An SRL handler thread, which the SRL creates
• The application-handler thread, which you create

To execute event handlers through the SRL handler thread, enable the creation of the SRL handler thread by setting SR_MODELTYPE to SR_MTASYNC (default mode); to execute event handlers through the application-handler thread, disable creation of the SRL handler thread by setting SR_MODELTYPE to SR_STASYNC.

Another use of the SR_MODELTYPE parameter, and an alternate way for an application to service handlers in a multithreaded application, is to create one thread for each Dialogic device, then create a separate thread that calls sr_waitevt( ). The handlers are called within the context of this thread. If your application uses this scenario, you should also set the SR_MODELTYPE parameter to SR_STASYNC to prevent creation of the SRL handler thread.

4.1.3. Hierarchy of Event Handlers

The SRL calls handlers according to a hierarchy based on device/event parings as follows:

1. Device/event-specific handlers. Handlers enabled for a specific event on a specific device are called when the event occurs on the device.
2. Device specific/event non-specific handlers. Handlers enabled for any event on a specific device are called only if no device/event specific handlers are enabled for the event.
3. Device non-specific/event non-specific or device non-specific/event-specific handlers (also called "backup" or "fallback" handlers). Handlers enabled for any event, or for a specific event on any device, are called only if no higher-ranked handler has been called. This allows these handlers to act as contingencies for events that might not have been handled by device/event-specific handlers.

The function prototype for user-supplied event handler functions is as follows (shown in ANSI C format):

long usr_hdlr(unsigned long evhandle);

4.1.4. SRL Callback Thread Behavior

The Asynchronous with SRL Callback model lets your application execute event handers through the following threads:

• An SRL handler thread, which SRL creates
• The application-handler thread, which you create

Using an SRL Handler Thread for SRL Callback

You can use an SRL handler thread to execute an event handler. Enable an event handler by calling the sr_enbhdlr( ) function from within any application thread. You can set up separate event handlers for separate events for separate devices.

The first call to the sr_enbhdlr( ) function automatically creates the SRL handler thread that services the event handler. You do not need to call the sr_waitevt( ) function from anywhere within the application; the sr_enbhdlr( ) thread already calls the sr_waitevt( ) function to get events. Each call to the sr_enbhdlr( ) function allows the Dialogic events to be serviced when Windows schedules the SRL handler thread for execution.

Call each event handler from the context of the SRL handler thread. The event handler must not call sr_waitevt( ) or any synchronous Dialogic function.

The state machine is driven by the event handlers. If the event handler returns a 1, the event is kept. The next general handler in the hierarchy is notified.

Note: You can use the SRL handler thread in some UNIX applications that require porting.

Using an Application-Handler Thread

To create your own application thread, with which you can distribute your workload and gain more control over program structure, you can use the application-handler thread to make calls to the sr_waitevt( ) function and execute event handlers. To avoid the creation of the SRL handler thread, you must set SR_MODELTYPE to SR_STASYNC. The thread must not call any synchronous functions.

After initiation of the asynchronous function, the application thread can perform other tasks but cannot receive solicited or unsolicited events until the sr_waitevt( ) function is called.

If a handler returns a non-zero value, the sr_waitevt( ) function returns in the application thread.

Note: A solicited event is an expected event specified using an asynchronous function contained in the device library, such as a "play complete" after issuing a dx_play( ) function. An unsolicited event is an event that occurs without prompting, such as a silence-on or silence-off event in a device.

Click here to contact Dialogic Customer Engineering