sr_enbhdlr( )

Description | Cautions | Example | Errors | See Also

Name:	long sr_enbhdlr(dev, evt_type, handler)
Inputs:	long dev	Dialogic device handle
	long evt_type	event type
	long (*handler)(unsigned long parm)	event handling function
Returns:	0 if success
	-1 if failure
Includes:	srllib.h
Type:	Event Handling function

Description

The sr_enbhdlr( ) function enables the handler function, handler( ), for the device/event pair. A handler is a user-defined function called by SRL to handle an event that occurs on a device.

The function parameters are described as follows:

Parameter	Description
dev	Specifies the valid device handle obtained when the device was opened using an xx_open( ) function, where xx is the prefix identifying the device to be opened. Specify EV_ANYDEV to be notified of an event on any device.
evt_type	Specifies the event for which the application is waiting, for example:
	Specify the specific event. Refer to the appropriate technology-specific Programmer's Guide for a list of possible event types. Specify EV_ANYEVT in evt_type and the device in the dev parameter to be notified of any event on a specific device Specify EV_ANYEVT in evt_type and EV_ANYDEV in the dev parameter to be notified of any event on any device.
Handler	Points to an application-defined event handler function that processes the event.

If more than one handler is enabled for an event when the event is detected, SRL calls all specified handlers. Also, more general handlers can be enabled that handle any event on a given device, or handlers can be enabled to handle any event on any device.

The following actions are valid from within a handler:

• Calling a technology-specific atomic function
• Initiating any technology-specific multitasking function asynchronously
• Opening or closing a device
• Enabling an event handler
• Disabling an event handler, including the current one

The following actions are not valid from within a handler:

• Initiating any technology-specific multitasking function synchronously
• Calling the sr_waitevt( ) function

Handlers must return 1 to advise SRL to keep the event, or 0 to advise SRL to release the event. If a handler returns 0 and the event is released, sr_waitevt( ) does not return for that event. See Section 2.5. SRL Extended Asynchronous Programming for the hierarchy in which SRL calls handlers.

The handler is called from within the function sr_waitevt( ). For details, see the appropriate technology-specific Programmer's Guide.

You can enable a handler from within another handler because SRL's event handling is fully re-entrant. For the same reason, you can open and close devices inside handlers. However, you cannot call handlers from within handlers because you cannot call sr_waitevt( ) from within a handler. Control must return to the main thread before sr_waitevt( ) can be called again.

Handlers return 0 if the event is to be removed and will not be returned by sr_waitevt( ).

Cautions

If two handlers are enabled for the same event on the same device, the order in which they are called cannot be controlled.

If a second handler is enabled for the current event from within the first handler, the second handler is also called before sr_waitevt( ) returns.

If a device with outstanding events is closed within a handler, none of its handlers are called. All handlers enabled on that device are disabled; no further events are serviced on that device.

If more than one handler is enabled for a given event and the first handler is released, all handlers for the event are called before the event is deleted.

For more information, see the appropriate technology-specific Programmer's Guide.

Example

#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>

  
long int dx_handler(unsigned long evhandle)  
{  
     printf( "dx_handler() called, event is 0x%x\n", sr_getevttype(evhandle));  
     return( 0 );                           }
  
main()  
{  
   int dxxxdev;  
     int mode = SR_POLLMODE;
  
   /* open dxxx channel device */  
   if(( dxxxdev = dx_open( "dxxxB1C1", 0 )) == -1 ){  
        printf( "dx_open failed\n" );  
        exit( 1 );  
   }
  
   /* Enable a handler for all events on dxxxdev */  
   if( sr_enbhdlr( dxxxdev, EV_ANYEVT, dx_handler ) == -1 ){  
      printf( "Error: could not enable handler\n)  
      exit( 1 );  
   }  
}

Errors

If this function returns -1 to indicate failure, obtain the reason for the error by calling the SRL standard attribute function ATDV_LASTERR(SRL_DEVICE) or ATDV_ERRMSGP(SRL_DEVICE) to retrieve either the error code or a pointer to the error description, respectively. One of the following errors may be returned:

ESR_SYS

Error from operating system; use dx_fileerrno( ) to obtain error value.

See Also

• sr_dishdlr( )
• The appropriate technology-specific Programmer's Guide

Click here to contact Dialogic Customer Engineering