Global Call API for HMP on Windows Programming Guide — August 2006 73
Event Handling
critical events. In addition, if the GCEV_BLOCKED event is disabled, some functions will fail
with a reason of EGC_INVALIDSTATE, which may cause confusion. For more information on
blocking alarms and the GCEV_BLOCKED and GCEV_UNBLOCKED events, see Section8.2.1,
“Generation of Events for Blocking Alarms”, on page99.
Note: A GCEV_UNBLOCKED event will be generated when opening a virtual board device. A
GCEV_BLOCKED event will also be generated if there are blocking alarms on the virtual board
and the corresponding GCEV_UNBLOCKED event will be generated when the blocking alarms
clear. The application must be prepared to handle these events.
4.4 Event Retrieval
All events are retrieved using the current Standard Runtime Library (SRL) event retrieval
mechanisms (see the Standard Runtime Library API Programming Guide for details), including
event handlers. The gc_GetMetaEvent() function or, for Windows extended asynchronous
models, the gc_GetMetaEventEx( ) function, maps the current SRL event into a metaevent. A
metaevent is a data structure that explicitly contains the information describing the event. This data
structure provides uniform information retrieval among all call control libraries.
For Global Call events, the structure contains Global Call related information (CRN and line
device) used by the application. For events that are not Global Call events, the device descriptor,
the event type, a pointer to variable length event data, and the length of the event data are available
through the METAEVENT structure. Since all the data associated with an event is accessible via
the METAEVENT structure, no additional SRL calls are required to access the event data.
The LDID associated with an event is available from the linedev field of the METAEVENT. If the
event is related to a CRN, that CRN is available from the crn field of the METAEVENT; if the crn
field of the METAEVENT is 0, then the event is not a call-related event.
The METAEVENT structure also includes an extevtdatap field which contains a pointer to more
information about the event. The memory pointed to by the extevtdatap field should be treated as
read-only and should not be altered and/or freed.
The application should issue a gc_DropCall() function before issuing the gc_ReleaseCallEx( )
function. Failure to issue this function could result in one or more of the following problems:
•memory problems due to memory being allocated and not being released
•a blocking condition
•events sent to the previous user of a CRN that could be processed by a later user of the CRN
with unexpected results
The reason for an event can be retrieved using the gc_ResultInfo() function. The information
returned uniquely identifies the cause of the event.