gc_SetEvtMsk( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetEvtMsk(linedev, mask, action)
Inputs:	LINEDEV linedev	Global Call line device handle
	unsigned long mask	bitmask or events
	int action	action to be taken on the mask bit
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	synchronous
Platform and Technology:	Springware: T-1/E-1†, ISDN†, Analog DM3: T-1/E-1, ISDN†, Analog SS7 IP (embedded stack) †See the Global Call Technology User's Guides for additional information.

Description

Note: For technologies that support the gc_SetConfigData( ) function, it is recommended that the gc_SetConfigData( ) function be used instead of the gc_SetEvtMsk( ) function to set event masks. See the gc_SetConfigData( ) function description for more information.

The gc_SetEvtMsk( ) function sets the event mask associated with a specified line device. If an event mask parameter is cleared, the event will be disabled and will not be sent to the application. The default is to enable all events.

The linedev parameter may represent a network interface trunk or an individual channel, for example, a time slot. See the appropriate Global Call Technology User's Guide to determine the level of the event masks needed.

Parameter	Description
linedev	Global Call line device handle
mask	specifies the events to be enabled or disabled by setting the bitmask. Multiple transition events may be enabled or disabled with one function call if the bitmask values are bitwise ORed. Possible mask values are listed in Table 15.
action	application may either set or reset the mask bit(s) as specified in mask. Possible actions are: GCACT_SETMSK enables notification of events specified in bitmask parameter and disables notification of any event not specified. GCACT_ADDMSK adds notification of events specified in bitmask parameter to previously enabled events. GCACT_SUBMSK disables notification of events specified in bitmask parameter.

Table 15. mask Parameter Values 

Type	Description	Default
GCMSK_ALERTING	Set mask for the GCEV_ALERTING event.	Enabled
GCMSK_BLOCKED	Set mask for the GCEV_BLOCKED event.	Enabled
GCMSK_DETECTED	Set mask for the GCEV_DETECTED event.	Disabled
GCMSK_DIALING	Set mask for the GCEV_DIALING event.	Disabled
GCMSK_DIALTONE	Set mask for the GCEV_DIALTONE event.	Disabled
GCMSK_REQMOREINFO	Set mask for the GCEV_REQMOREINFO event.	Disabled
GCMSK_PROCEEDING	Set mask for the GCEV_PROCEEDING event.	Disabled
GCMSK_UNBLOCKED	Set mask for the GCEV_UNBLOCKED event.	Enabled
Note: Not all events are supported by each technology, for example, the GCEV_DIALING event is supported in applications that use PDKRT protocols but is not supported in applications that use ICAPI protocols.

The GCEV_BLOCKED and GCEV_UNBLOCKED events are maskable on a line device representing a trunk or a time slot level. The application may disable (mask) the event on any line device so that the event is not sent to that line device. For example, when a trunk alarm occurs, this alarm is reported via the GCEV_BLOCKED event. If the application has not masked (disabled) the GCEV_BLOCKED event on some or all of the opened time-slot level line devices on the trunk, the GCEV_BLOCKED event will be sent to each of the line devices on the trunk. Also, if this GCEV_BLOCKED event is not disabled on the board-level line device, the alarm is sent to the board.

The GCEV_ALERTING event is maskable as described above except that this event is always call related and always associated with a time-slot level line device. The time-slot level line device should be passed to the gc_SetEvtMsk( ) function.

See the appropriate Global Call Technology User's Guide for additional details.

Termination Events

None

Cautions

In the event of a failure, it is possible that there may be partial success; that is, some masks may be set or reset while others are not.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).

Example

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
/*
 * Assume the following has been done:
 *    1. The line device has been opened.
 */
int set_event_mask(LINEDEV ldev)
{
    GC_INFO  gc_error_info;   /* GlobalCall error information data */ 
    /*
     * Set the event Detected and Dialing event masks to enable
     * for this application.
     */
    /*
     * Enable the Detected and Dialing events.
     */
    if (gc_SetEvtMsk(ldev, (GCMSK_DETECTED | GCMSK_DIALING), GCACT_ADDMSK)
        != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetEvtMsk() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s,
                CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                ldev, gc_error_info.gcValue, gc_error_info.gcMsg, 
                gc_error_info.ccLibId, gc_error_info.ccLibName,
                gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue);
    } 
       /*
     * Proceed to generate or accept calls on this line device.
     */ 
    /*
     * Now disable notification of Detected and Dialing events,
     * and enable notification of Alerting event, without
     * affecting any other event masks which may have been set.
     */ 
    if (gc_SetEvtMsk(ldev, (GCMSK_DETECTED | GCMSK_DIALING), GCACT_SUBMSK)
        != GC_SUCCESS) {
        /* Process error */
    }
    if (gc_SetEvtMsk(ldev, GCMSK_ALERTING, GCACT_ADDMSK) != GC_SUCCESS) {
        /* Process error */
    }
    return (0);
} 

See Also

• gc_SetConfigData( )
• gc_SetParm( )

Click here to contact Telecom Support Resources