dt_setevtmsk( )

Description | Cautions | Example | Errors | See Also

Name:	dt_setevtmsk(devh,event,bitmask,action)
Inputs:	int devh	Digital Network Interface logical board or Digital Network Interface logical time slot device handle
	int event	event to be enabled/disabled
	unsigned short bitmask	bitmask for events
	int action	set, add, or subtract bitmask
Returns:	0 on success -1 on failure
Includes:	srllib.h dtilib.h
Category:	Parameter Setting
Mode:	synchronous

Description

The dt_setevtmsk( ) function enables and disables notification for events that occur on a Digital Network Interface logical board or time slot device. This function allows the application to set and alter a bitmask of transition events. The bitmask determines which transitions will cause an event to be generated.

The event can be retrieved by using the event management functions included in the Standard Runtime Library (refer to Appendix A - Standard Runtime Library for more information on the SRL). The current bitmask can be examined by using the dt_getevtmsk( ) function.

Parameter	Description
devh:	Specifies the valid Digital Network Interface logical board or Digital Network Interface logical time slot device handle returned by a call to dt_open( ).
event:	Specifies the type of event to be enabled or disabled on the device specified by devh:
	DTG_T1ERREVT - T-1 error events (T-1 compatible Digital Network Interface logical board device handles only). Several T-1 error events can be monitored. Specific T-1 error events are enabled or disabled by setting the bitmask parameter.
	DTG_E1ERREVT - E-1 error events (E-1 compatible Digital Network Interface logical board device handles only). Several E-1 error events can be monitored. Specific E-1 error events are enabled or disabled by setting the bitmask parameter.
	DTG_SIGEVT - Signaling bit transition events (time slot device handles only). Specific signaling events are enabled or disabled by setting the bitmask parameter.
	DTG_PDIGEVT - pulse digit events (D/xxxSC time slot device handles only).
	NOTE: For D/xxxSC products, you must enable both the ON and OFF transitions on a specified bit to get events on that bit. For example, AON and AOFF must be enabled to detect events on the A bit.
bitmask:	Specifies the event to be enabled or disabled by setting the bitmask for that event.
	Multiple transition events may be enabled or disabled with one function call if the bitmask values are logically ORed together.
	The bitmask values for each event parameter are described in Table 5, found in the dt_getevtmsk( ) function description.
action:	Specifies how the signaling bit transition event mask is changed. Events can be added to or subtracted from those specified in bitmask, or events can replace the existing ones. The possible values for the action parameter are:
	DTA_SETMSK - enable notification of events specified in bitmask and disable notification of previously set events.
	DTA_ADDMSK - enable notification of events specified in bitmask in addition to previously set events. (Not valid for DTG_PDIGEVT.)
	DTA_SUBMSK - disable notification of events specified in bitmask.

For example, to enable event notification:

1. Specify the events to enable in the bitmask field.
2. Specify the DTA_SETMSK bitmask in the action field.

This enables notification of the events specified in the bitmask parameter and disables notification of previously set events.

To enable an additional event:

1. Specify the events in bitmask.
2. Specify DTA_ADDMSK in the action field.

This adds the notification of events specified in bitmask without disabling the currently enabled events.

To disable events, use the following procedure:

1. Specify the events in bitmask.
2. Specify DTA_SUBMSK in the action field.

This disables the event in bitmask without disabling any other events.

To disable all currently enabled events:

1. Specify 0 in bitmask.
2. Specify DTA_SETMSK in the action field.

Event Notification and Handling

NOTE:

Event handling operations vary with the mode type (i.e., callback, polled, synchronous, etc.) used by your application. For more information on application development models, refer to the Standard Runtime Library Programmer's Guide (for Linux or Windows - part of the Voice Software Reference for Linux or Windows).

To trap and handle a specified Digital Network Interface event, follow these steps in the order listed:

1. Call sr_enbhdlr( ) - This function specifies the event and the application defined event handler that is called when this event occurs.
2. Call dt_setevtmsk( ) - This specifies the list of events for which the application should be notified.

NOTE:

When the DTG_T1ERREVT, DTG_E1ERREVT, or DTG_SIGEVT event is generated, call the sr_getevtdatap( ) function in the event handler to get a pointer to the event value. The pointer should be cast to an unsigned short pointer and the event retrieved as an unsigned short value.

Refer to Appendix A - Standard Runtime Library for more information on SRL data structures and functions.

Cautions

1. This function will fail under the following conditions:
   • An invalid time slot or an invalid Digital Network Interface logical board device handle is specified.
   • The event specified is invalid.
   • The action specified is invalid.
2. For the application to process an event, the SRL sr_enbhdlr( ) Event Management function should be called prior to calling the dt_setevtmsk( ) function.
3. When a wink event occurs, the signaling bits associated with the wink will be reported to the application. Therefore, your application's signaling event handlers must make sure that any transition of the selected wink signaling bit is not part of a wink event.

Example

#include <windows.h>      /* For Windows applications only */  
#include <srllib.h>  
#include <dtilib.h>  
#include <errno.h>  
   
main()  
{  
   int devh;              /* Time slot device handle */  
   /*  
    * Open board 1 time slot 1 device  
    */  
   if ( ( devh = dt_open( "dtiB1T1", 0 ) ) == -1 ) {  
      printf( "Cannot open device dtiB1T1.  errno = %d", errno );  
      exit( 1 );  
   }  
   
   /*  
    * Enable an event handler to catch AON and AOFF events  
    */  
              .  
              .  
              .  
   
   /*  
    * Enable AON and AOFF signaling transition events  
    */  
   if ( dt_setevtmsk(devh, DTG_SIGEVT, DTMM_AON | DTMM_AOFF, DTA_SETMSK )  
         ts== -1 ) {  
      printf( "Error message = %s.",ATDV_ERRMSGP( devh ) );  
      exit( 1 );  
   }  
              .  
              .  
              .  
}

Errors

If the function returns -1, use the SRL Standard Attribute function ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive error message. See Appendix A - Standard Runtime Library for more information on SRL functions. The error codes returned by ATDV_LASTERR( ) are:

• EDT_BADBRDERR - Digital Network Interface missing or defective
• EDT_BADCMDERR - invalid or undefined command to driver
• EDT_DATTO - data reception timed out
• EDT_FWERR - firmware returned an error
• EDT_INVBD - invalid Digital Network Interface logical board device handle
• EDT_INVTS - invalid Digital Network Interface logical time slot device handle
• EDT_NOMEMERR - cannot map or allocate memory in driver
• EDT_PARAMERR - invalid parameter
• EDT_RANGEERR - bad/overlapping physical memory range
• EDT_SIZERR - message too big or too small
• EDT_SKIPRPLYERR - a required reply was skipped
• EDT_SYSTEM - system error. Check the global variable errno for more information about the error.
• EDT_TMOERR - timed out waiting for reply from firmware

Error defines can be found in the file dtilib.h.

See Also

• dt_getevtmsk( )
• sr_enbhdlr( )
• sr_dishdlr( )

Click here to contact Dialogic Customer Engineering