Global Call API for HMP on Windows Programming Guide — August 2006 85
6
6.Error Handling
The chapter describes the error handling capabilities provided by Global Call. Topics include the
following:
•Error Handling Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.1 Error Handling OverviewWhen an error occurs during execution of a function, one of the following occurs:
•The function returns with a value < 0
•The unsolicited error event, GCEV_TASKFAIL, is sent to the application
Call control libraries supported by the Global Call API may have a larger set of error codes than
those defined in the gcerr.h header file. The call control library error values are available using the
gc_ErrorInfo() functio n, which retrieves Global Call and call control library information. To
retrieve the information, this function must be called immediately after the Global Call function
failed. This function returns a result value associated directly with the Global Call and call control
library.
The gc_ResultInfo( ) function retrieves information about solicited and unsolicited events when a
Global Call application gets an expected or unexpected event. To retrieve the information, the
gc_ResultInfo( ) function must be called immediately after a Global Call event arrives and before
the next event returns Global Call and call control library information related to the last Global Call
function call. To process an error, this function must be called immediately after an event is
returned to the application. For example, if an alarm occurs while making an outbound call, a
GCEV_DISCONNECTED event is sent to the application with a result value indicating an alarm
on the line. The GCEV_BLOCKED event is also generated with a result value that also indicates
an alarm on the line. See the appropriate Global Call Technology Guide for information on specific
protocol errors.
If an error occurs during execution of an asynchronous function, a termination event, such as the
GCEV_GETCONFIGDATA_FAIL (E1, T1 and ISDN technologies only), or
GCEV_SETCONFIGDATA_FAIL (all technologies) event is sent to the application. No change of
state is triggered by this event. If events on the line require a state change, this state change occurs
as described in Section 3.4.3, “Call Termination in Asynchronous Mode”, on page60. When an
error occurs during a protocol operation, the error event is placed in the event queue with the error
value that identifies the error. Upon receiving a GCEV_TASKFAIL event, the application can
retrieve the reason for the failure using the gc_ResultInfo() function.
An unsolicited GCEV_ERROR event can be received if an internal component fails. The
gc_ResultInfo( ) function can be used to determine the reason for the event. Valid reasons are any
of the Global Call reasons (error code or result values) or a call control library-specific reason (see
the appropriate Global Call Technology Guide).