Global Call API Library Reference: gc

gc_SetAlarmNotifyAll( )

Termination Events | Cautions | Errors | Example | See Also

Name: int gc_SetAlarmNotifyAll(linedev, aso_id, value)

Inputs:
LINEDEV linedev

line device

unsigned long aso_id

alarm source object ID

int value

notification value to set

Returns:
0 if successful

<0 if failure

Includes:
gclib.h

gcerr.h

Category:
GCAMS

Mode:
synchronous

Platform and Technology:
Springware: T-1/E-1, ISDN

DM3: T-1/E-1, ISDN

IP (host-based stack)

Description

The gc_SetAlarmNotifyAll( ) function sets the notification attribute of all alarms originating from a specified alarm source object.

The gc_SetAlarmNotifyAll( ) function can be used as a shortcut for changing the notify attribute, instead of using the gc_GetAlarmConfiguration( ) function to retrieve the list of all alarms and then setting their notify attribute using the gc_SetAlarmConfiguration( ) function.

The gc_SetAlarmNotifyAll( ) function can also be used to determine if an alarm exists on a line device when the device is opened. After calling gc_OpenEx( ), enable alarm notification for the line device. If any alarms are already active on the line device, the application will be notified with one or more applicable GCEV_ALARM events, depending on the current value of the alarm flow control.

Parameter

Description

linedev line device. The linedev parameter must be set to NULL to set the notification attribute for alarm source objects. Setting linedev to NULL changes the default behavior for any device opened after the function call.

aso_id alarm source object (ASO) ID. Use the gc_AlarmSourceObjectNameToID( ) function to obtain the ASO ID for the desired alarm source object. ALARM_SOURCE_ID_NETWORK_ID can be used if the network ASO ID is not known.

value performs two roles. The first role is to set the alarm notification attribute. Possible values are:

ALARM_NOTIFY

notify the application of all alarms in alarm_list

ALARM_NONOTIFY

do not notify the application of alarms in alarm_list

The second role is to define whether the notification attribute is to be set for all boards or time slots associated with the ASO or for a specific board associated with the ASO, allowing users to control the extent of the changes. The following flags, which may be ORed in, can be used to define whether which ASO IDs, boards, or time slots are to be configured:

ALARM_CONFIGURE_BOARDS

configure all the boards for the specified ASO ID

ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS

configure all the boards and time slots for the specified ASO ID

ALARM_CONFIGURE_TIMESLOTS

configure the time slots for the specified board

See Table 13 for more information about setting these flags. Only one of the three flags may be set at a time.

Table 13. Possible Flag Settings for value Parameter

Object(s) to Configure:

alarm_config_type Flag Setting†

linedev Setting

ASO

Board

Time Slot

yes

yes

yes

ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS

NULL

yes

yes

no

ALARM_CONFIGURE_BOARDS

NULL

yes

no

yes

configuration not supported

N/A

yes

no

no

none

NULL

no

yes

yes

ALARM_CONFIGURE_TIMESLOTS

Board linedev ID

no

yes

no

none

Board linedev ID

no

no

yes

none

Time slot linedev ID

no

no

no

configuration not supported

N/A

† Possible flag settings are ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS, ALARM_CONFIGURE_BOARDS, ALARM_CONFIGURE_TIMESLOTS. Attempts to configure unsupported configurations will return an error.

Termination Events

None

Cautions

When linedev is set to NULL, changing an alarm source object's configuration will change the default behavior for devices opened subsequent to the gc_SetAlarmNotifyAll( ) function call. That is, devices opened after the gc_SetAlarmNotifyAll( ) function call will get their default behavior from the alarm source object configuration information.
If a line device is specified and the given aso_id is not an alarm source object for the line device, an error will occur.

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
/* Example 1: change ASO, but not any open devices */
    int           rc;
    /* Enable alarm notification on all Springware E1 alarms */
    /* Note: this does not change any open devices */
    rc = gc_SetAlarmNotifyAll(0, ALARM_SOURCE_ID_SPRINGWARE_E1, ALARM_NOTIFY);
    if (rc < 0)
    {
         /* get and process the error */
    } 
/* Example 2: change ASO, and all open devices that use this ASO */
    int           rc;
    /* Enable alarm notification on all Springware E1 alarms */
    /* Note: this also changes all open devices associated that use this ASO */
    rc = gc_SetAlarmNotifyAll(0, ALARM_SOURCE_ID_SPRINGWARE_E1, ALARM_NOTIFY | 
                              ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS);
    if (rc < 0)
    {
         /* get and process the error */
    } 
See Also

gc_GetAlarmConfiguration( )
gc_SetAlarmConfiguration( )

Name:	int gc_SetAlarmNotifyAll(linedev, aso_id, value)
Inputs:	LINEDEV linedev	line device
	unsigned long aso_id	alarm source object ID
	int value	notification value to set
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	GCAMS
Mode:	synchronous
Platform and Technology:	Springware: T-1/E-1, ISDN DM3: T-1/E-1, ISDN IP (host-based stack)

Parameter	Description
linedev	line device. The linedev parameter must be set to NULL to set the notification attribute for alarm source objects. Setting linedev to NULL changes the default behavior for any device opened after the function call.
aso_id	alarm source object (ASO) ID. Use the gc_AlarmSourceObjectNameToID( ) function to obtain the ASO ID for the desired alarm source object. ALARM_SOURCE_ID_NETWORK_ID can be used if the network ASO ID is not known.
value	performs two roles. The first role is to set the alarm notification attribute. Possible values are: ALARM_NOTIFY notify the application of all alarms in alarm_list ALARM_NONOTIFY do not notify the application of alarms in alarm_list The second role is to define whether the notification attribute is to be set for all boards or time slots associated with the ASO or for a specific board associated with the ASO, allowing users to control the extent of the changes. The following flags, which may be ORed in, can be used to define whether which ASO IDs, boards, or time slots are to be configured: ALARM_CONFIGURE_BOARDS configure all the boards for the specified ASO ID ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS configure all the boards and time slots for the specified ASO ID ALARM_CONFIGURE_TIMESLOTS configure the time slots for the specified board See Table 13 for more information about setting these flags. Only one of the three flags may be set at a time.

**Table 13. Possible Flag Settings for value Parameter**
Object(s) to Configure:	alarm_config_type Flag Setting†	linedev Setting
ASO	Board	Time Slot
yes	yes	yes	ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS	NULL
yes	yes	no	ALARM_CONFIGURE_BOARDS	NULL
yes	no	yes	configuration not supported	N/A
yes	no	no	none	NULL
no	yes	yes	ALARM_CONFIGURE_TIMESLOTS	Board linedev ID
no	yes	no	none	Board linedev ID
no	no	yes	none	Time slot linedev ID
no	no	no	configuration not supported	N/A
† Possible flag settings are ALARM_CONFIGURE_BOARDS_AND_TIMESLOTS, ALARM_CONFIGURE_BOARDS, ALARM_CONFIGURE_TIMESLOTS. Attempts to configure unsupported configurations will return an error.

Click here to contact Telecom Support Resources