ms_setevtmsk( )

---

Cautions | Errors | Example | See Also

Name:	ms_setevtmsk (devh, event, bitmask, action)
Inputs:	int devh	MSI station 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 msilib.h
Category:	Configuration
Mode:	synchronous
Platform:	DI, HDSI, Springware

Description

The ms_setevtmsk( ) function changes transition event masks and enables and disables messages from a station.

Parameter	Description
devh	the valid station device handle returned by a call to ms_open( )
event	one type of transition event to be enabled or disabled: MSEV_SIGMSK Hook switch transition event. Notification of specific signaling events is enabled or disabled by setting the bitmask parameter.
bitmask	the event to be enabled by setting the bitmask for that event. Multiple transition events may be enabled or disabled with one function call if the bitmasks are ORed together. The possible values for the bitmask parameter are: MSMM_OFFHOOK enables off-hook detection MSMM_ONHOOK enables on-hook detection MSMM_HOOKFLASH enables hook flash detection
action	specifies how the transition event mask is changed. Events can be added to or subtracted from those specified in bitmask. The possible values for the action parameter are: DTA_SETMSK enables notification of events specified in bitmask and disables notification of previously set events DTA_ADDMSK enables messages from the channel specified in bitmask, in addition to previously set events DTA_SUBMSK disables messages from the channel specified in bitmask

For example, to enable notification of the events specified in the bitmask parameter and disable notification of previously set events:

• Specify the events to enable in the bitmask field
• Specify the DTA_SETMSK bitmask in the action field

To enable an additional event specified in bitmask without disabling the currently enabled events:

• Specify the events in bitmask
• Specify DTA_ADDMSK in the action field

To disable events in bitmask without disabling any other events:

• Specify the events in bitmask
• Specify DTA_SUBMSK in the action field

To disable all currently enabled events:

• Specify 0 in bitmask
• Specify DTA_SETMSK in the action field

Table 6. MSI Events and Event Types 

Event Type	Event	Description
MSEV_SIGEVT	MSMM_ONHOOK	Line device has gone on-hook.
	MSMM_OFFHOOK	Line device has gone off-hook.
	MSMM_HOOKFLASH	Line device detected hookflash.
MSEV_RING	MSMM_RNGOFFHK	Solicited off-hook was detected.
	MSMM_RNGSTOP	Ringing was stopped by ms_stopfn( ).
	MSMM_TERM	Ringing was terminated.
	E_MSBADRNGSTA	Station was off-hook when the ring was attempted.
MSEV_NORING	MSMM_RNGOFFHK	Solicited off-hook was detected.
	MSMM_RNGSTOP	Ringing was stopped by ms_stopfn( ).
	MSMM_TERM	Ringing was terminated.
	E_MSBADRNGSTA	Station was off-hook when the ring was attempted.

Processing an Event

When a hook switch transition event occurs, the application receives an MSEV_SIG event as the event type. The associated event data will contain the bitmask of the specific transition that caused the event. To enable an event handler for a specified event, follow these steps:

• Call sr_enbhdlr( ). This function specifies the event and the application defined event handler that is called from a signal handler.
• Call ms_setevtmsk( ). This function specifies the list of events the application should be notified of.
• For an event to be handled, it must be specified in both sr_enbhdlr( ) and ms_setevtmsk( ).
• The event data is retrieved using the sr_getevtdatap( ) function. Refer to the Modular Station Interface API Programming Guide for more information.

Cautions

This function fails when:

• The device handle is invalid
• The event specified is invalid
• The action specified is invalid

Errors

If this function returns -1 to indicate failure, obtain the reason for the error by calling the SRL standard attribute function ATDV_LASTERR( ) or ATDV_ERRMSGP( ) to retrieve either the error code or a pointer to the error description, respectively.

Refer to the error type tables found in Chapter 5, "Error Codes". Error defines can be found in dtilib.h or msilib.h.

Example

#include <windows.h>         /* For Windows applications only */
#include <errno.h>
#include "srllib.h"
#include "dtilib.h"
#include "msilib.h"  
/* Basic error handler */
do_error( devh, funcname )
   int devh;
   char *funcname;
{
   int errorval = ATDV_LASTERR( devh );  
   printf( "Error while calling function %s.\n", funcname );
   printf( "Error value = %d.", errorval );
   printf( "\n" );
}  
main()
{
   int tsdev;       /* Channel device descriptor variable */  
   /* Open board 1 time slot 1 device */
   if ( ( tsdev = ms_open( "msiB1C1", 0 ) ) == -1 ) {
      printf( "Cannot open device msiB1C1. errno = %d", errno );
      exit( 1 );
   }  
   /* Enable signaling transition events (off-hook event) */
   if ( ms_setevtmsk( tsdev, MSEV_SIGMSK, MSMM_OFFHOOK, DTA_SETMSK ) == -1 ){
      do_error( tsdev, "ms_setevtmsk()" );
      exit( 1 );
   }  
   /*
    *   Continue processing
    *          .
    *          .
    *          .
    */  
   /* Done processing - close device  */
   if ( ms_close( tsdev ) == -1 ) {
      printf( "Cannot close board msiB1C1. errno = %d", errno );
   }
}  

See Also

• ms_getevtmsk( )

Click here to contact Telecom Support Resources