dx_setevtmsk( )

Description | Cautions | synchronous processing | asynchronous processing | Errors | See Also

Name:	int dx_setevtmsk(chdev,mask)
Inputs:	int chdev	valid Dialogic channel device handle
	unsigned int mask	event mask of events to enable
Returns:	0 if successful
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
Category:	Call Status Transition Event

Description

The dx_setevtmsk( ) function enables detection of Call Status Transition (CST) events. When you enable detection of a CST event and the event occurs, it will be placed on the event queue. You can collect the event by getting it or waiting for it with an event handling function, such as sr_waitevt( ), sr_waitevtEx( ), or dx_getevt( ). The dx_setevtmsk( ) function can be used by synchronous or asynchronous applications waiting for a CST event.

NOTES:

1. This function can enable detection for all CST events except user-defined tone detection. See dx_addtone( ) and dx_enbtone( ) for information.

2. The dx_wtring( ) function also affects the CST events that are enabled. It enables detection of the DM_RINGS event and disables detection of other events.

The function parameters are defined as follows:

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
mask	specifies the events to enable. To enable multiple events, perform an OR operation on the bit masks of the events you want to enable. The first enabled CST event to occur will be returned. If an event is not specified in the mask, the event will be disabled. If an event is enabled, it will remain enabled until it is disabled through another function call. (Exception: See DM_DIGITS and DM_DIGOFF.) One or more of the following values can be specified:
	DM_LCOFF	wait for loop current to be off
	DM_LCON	wait for loop current to be on
	DM_RINGS	wait for rings; see also dx_wtring( )
	DM_RNGOFF	wait for ring to drop (hang-up)
	DM_SILOF	wait for non-silence
	DM_SILON	wait for silence
	DM_WINK	wait for wink to occur on an E&M line. If DM_WINK is not specified in the mask parameter and DM_RINGS is specified, a wink may be interpreted as an incoming call, depending upon the setting of the DXBD_R_ON parameter.
	DM_DIGITS	enable digit reporting on the event queue (each detected digit is reported as a separate event on the event queue) When the event mask is set with DM_DIGITS, a digits flag is set that causes individual digit events to queue until this flag is turned off by the DM_DIGOFF equate. Setting the event mask for DM_DIGITS and then subsequently resetting the event mask without DM_DIGITS does not disable the queueing of digit events. Digit events will remain in the queue until collected by an event handling function such as sr_waitevt( ), sr_waitevtEx( ), or dx_getevt( ). The event queue is not affected by dx_getdig( ) calls. Example of enabling DM_DIGITS: /* Set event mask to collect digits */ if (dx_setevtmsk(chdev, DM_DIGITS) == -1) {
	DM_DIGOFF	disable digit reporting on the event queue (as enabled by DM_DIGITS). This is the only way to disable DM_DIGITS. Example of disabling DM_DIGITS: dx_setevtmsk(DM_DIGOFF); dx_clrdigbuf(chdev); /*Clear out queue*/
	DM_LCREV	wait for flow of current to reverse (D/41ESC and D/160SC-LS boards only). On the D/21E, D/41E, or D/160SC-LS board, when the DM_LCREV bit is enabled, a DE_LCREV event message is queued when the flow of current over the line is reversed.

The following table outlines the synchronous or asynchronous handling of CST events:

Synchronous	Asynchronous
Call dx_setevtmsk( ) to enable CST events	Call dx_setevtmsk( ) to enable CSTevents
Call dx_getevt( ) to wait for CST events. Events are returned to the DX_EBLK structure.	Use SRL to asynchronously wait for for TDX_CST events.
	Use sr_getevtdatap( ) to retrieve DX_CST structure.

Cautions

If you call this function on a busy device, and specify DM_DIGITS as the mask argument, the function will fail.

synchronous processing

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int chdev;  
   DX_EBLK eblk;  
   .  
   .  
   /* open a channel with chdev as descriptor */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   .  
   .  
   /* Set event mask to receive ring events */  
   if (dx_setevtmsk(chdev, DM_RINGS) == -1) {  
     /* error setting event */  
   }  
   .  
   .  
   /* check for ring event, timeout set to 20 seconds */  
   if (dx_getevt(chdev,&eblk,20) == -1) {  
     /* error timeout */  
   }  
   
   if(eblk.ev_event==DE_RINGS) {  
      printf("Ring event occurred\n");  
   }  
   .  
   .  
}

asynchronous processing

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define MAXCHAN 24  
   
int cst_handler();  
   
main()  
{  
   int chdev[MAXCHAN];  
   char *chname;  
   int i, srlmode;  
   
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
   
   for (i=0; i<MAXCHAN; i++) {  
   
      /* Set chname to the channel name, e.g., dxxxB1C1, dxxxB1C2,... */  
   
      /* Open the device using dx_open( ).  chdev[i] has channel device  
       * descriptor.  
       */  
       if ((chdev[i] = dx_open(chname,NULL)) == -1)   {  
          /* process error */  
       }  
   
      /* Use dx_setevtmsk() to enable call status transition events  
       * on this channel.  
       */  
       if (dx_setevtmsk(chdev[i],   
           DM_LCOFF|DM_LCON|DM_RINGS|DM_SILOFF|DM_SILON|DM_WINK) == -1) {  
          /* process error */  
       }  
   
      /* Using sr_enbhdlr(), set up handler function to handle call status  
       * transition events on this channel.  
       */  
       if (sr_enbhdlr(chdev[i], TDX_CST, cst_handler) == -1) {  
          /* process error */  
       }  
      /* Use sr_waitevt to wait for call status transition event.  
       * On receiving the transition event, TDX_CST, control is transferred  
       * to the handler function previously established using sr_enbhdlr().  
       */  
                   .  
                   .  
   }  
}  
   
int cst_handler()  
{  
   DX_CST *cstp;  
   
  /* sr_getevtdatap() points to the event that caused the call status  
   * transition.  
   */  
   cstp = (DX_CST *)sr_getevtdatap();  
   
   switch (cstp->cst_event) {  
     case DE_RINGS:  
      printf("Ring event occurred on channel %s\n",   
              ATDX_NAMEP(sr_getevtdev()));  
      break;  
     case DE_WINK:  
      printf("Wink event occurred on channel %s\n",   
              ATDX_NAMEP(sr_getevtdev()));  
      break;  
     case DE_LCON:  
      printf("Loop current ON event occurred on channel %s\n",   
              ATDX_NAMEP(sr_getevtdev()));  
      break;  
     case DE_LCOFF:  
               .  
               .  
   }  
   
   /* Kick off next function in the state machine model. */  
   .  
   .  
   
   return 0;  
}

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons:

EDX_BADPARM	Invalid Parameter
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

See Also

CST Event Handling and Retrieval:

• dx_getevt( ) - synchronous operation
• sr_getevtdatap( ) - asynchronous operation
• DX_CST data structure

Enabling User-Defined Tone Detection:

• dx_addtone( )

Click here to contact Dialogic Customer Engineering