Global Call API for HMP on Windows Programming Guide — August 2006 115
Real Time Configuration Management
•the update condition; that is, whether the update should occur either at the Null call state or
immediately when updating the parameters of a target object with an active call. (This
parameter does not apply to the gc_GetConfigData( ) function.)
9.4.2.1 Programming Mode The customer application can specify whether to access configurations in the asynchronous mode
or synchronous mode. The following describe how the gc_GetConfigData() and
gc_SetConfigData( ) functions operate in the asynchronous and synchronous programming
modes:
gc_GetConfigData( ) (E1, T1 and ISDN technologies only)
Synchronous Mode: Upon completion of the function call, the retrieved parameter data is still
in the original GC_PARM_BLK data block after the gc_GetConfigData() function returns.
The function’s return value, GC_SUCCESS, indicates that all requested parameters in a given
target object have been successfully retrieved. Other return values indicate that at least one
requested parameter in the target object failed to be retrieved due to an error. The
gc_ErrorInfo() functio n is called immediately to obtain the last error and the additional
message, which describes the parameter and the error (pointer to the additional message field).
During the gc_GetConfigData( ) function call, once an error occurs, Global Call stops
retrieving the remaining parameters and returns an error value to the application. If this
function call is retrieving multiple parameters, the parameters before the error may have been
retrieved while other parameters will not have had a chance to be retrieved.
gc_GetConfigData( ) (E1, T1 and ISDN technologies only)
Asynchronous Mode: Upon completion of the function call, the Global Call application
receives the GCEV_GETCONFIGDATA event if all requested parameters have been
successfully retrieved. Otherwise, the Global Call application receives the
GCEV_GETCONFIGDATA_FAIL event, which means at least one requested parameter of
this request failed to retrieve due to an error. The METAEVENT data structure associated with
both events has a field evtdatap that points to a GC_RTCM_EVTDATA data structure. In the
GC_RTCM_EVTDATA event, the retrieved _parmblkp field points to the retrieved parameter
data. The error value and additional message describing the parameter and the error are also
provided in GC_RTCM_EVTDATA data structure.
Note: The gc_GetConfigData() function cannot be called in asynchronous m ode for the following target
types: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM,
GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_SYSTEM. The function returns
invalid target type. The gc_GetConfigData() function must be called in synchronous mode for
these target types.
gc_SetConfigData() (al l technologies)
Synchronous Mode: Upon completion of the function call, the gc_SetConfigData( ) function
returns a value of GC_SUCCESS to indicate that all requested parameters in a given target
object have been successfully updated. Any other return value indicates that at least one
requested parameter in a target object failed to be updated due to an error. The
gc_ErrorInfo() function is called immediately to obtain the last error and additional message
describing the parameter and the error (pointer to the additional message field). During the
gc_SetConfigData() function call, once an error occurs, Global Call stops updating the
remaining parameters and returns an error value to the application. If this function call requires
updating multiple parameters in a target object, the parameters before the error may have been
updated while other parameters will not have a chance to be updated.