Programming Guide

74 Global Call API for HMP on Windows Programming Guide — August 2006
Event Handling
4.5 Events Indicating Errors
Events that explicitly provide error indications are as follows:
GCEV_TASKFAIL
Received when an API function call fails
When this events is received, the application should call gc_ResultInfo( ) immediately after the
event arrives to determine the reason for the event. The data structure associated with
gc_ResultInfo( ) can contain reason information provided by Global Call and additional reason
information provided by the underlying call control library. See the Global Call API Library
Reference for more information.
4.6 Masking Events
Some events are maskable. See the gc_SetConfigData( ) function description in the Global Call
API Library Reference for specific information regarding enabling and disabling events.
4.7 Event Handlers
An event handler is a user-defined function called by the SRL to handle a specific event that occurs
on a specified device.
Typically, in a Windows environment, processing events within a thread or using a separate thread
to process events tends to be more efficient than using event handlers. However, if event handlers
are used, such as when an application is being ported from Linux, then you must use the
asynchronous with SRL callback model.
The following guidelines apply to using event handlers:
• more than one handler can be enabled for an event. The SRL calls all specified handlers when
the event is detected
• handlers can be enabled or disabled from any thread
• general handlers can be enabled to handle all events on a specific device
• a handler can be enabled to handle any event on any device
• synchronous functions cannot be called from a handler
By default, when the sr_enbhdlr( ) function is first called, a thread internal to the SRL is created to
service the application-enabled event handlers. This SRL handler thread exists as long as one
handler is still enabled. The creation of this internal SRL event handler thread is controlled by the
SR_MODELTYPE value of the SRL sr_setparm( ) function. The SRL handler thread should be:
• enabled when using the asynchronous with SRL callback model. Enable the SRL event
handler thread by not specifying the SR_MODELTYPE value (default is to enable) or by
setting this value to SR_MTASYNC (do not specify SR_STASYNC).