116 Global Call API for HMP on Windows Programming Guide — August 2006
Real Time Configuration Management
gc_SetConfigData() (all technologies)
Asynchronous Mode: The Global Call application receives the GCEV_SETCONFIGDATA
event if all the requested parameters in a given target object are successfully updated.
Otherwise, the Global Call application receives the GCEV_SETCONFIGDATA_FAIL event,
which indicates that at least one requested parameter in the target object failed to update due to
an error. The METAEVENT data structure, which is associated with both events, has a field,
evtdatap, that points to a GC_RTCM_EVTDATA data structure. The GC_RTCM_EVTDATA
data structure provides the error value and additional message describing the parameter and the
error.
Note: When using E1, T1 and ISDN technologies, the gc_SetConfigData( ) function cannot be called in
asynchronous mode 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_SetConfigData( ) function must be called in synchronous mode for these target types.
The original GC_PARM_BLK data block is not changed after the gc_SetConfigData() function
returns.
9.4.2.2 Timeout Option When using IP technology, the timeout option provided by the timeout parameter in the
gc_SetConfigData( ) function is not supported and should be set to 0.
When using E1, T1 and ISDN technology, the following apply:
•The customer application can specify the timeout for completing the parameter retrieval or
update. The gc_GetConfigData( ) and gc_SetConfigData( ) functions support the timeout
option only in synchronous mode. When a timeout occurs in the synchronous mode, the
function returns an EGC_TIMEOUT error to the application. The timeout option is ignored if
the function is executed in asynchronous mode.
•The function call is stopped immediately when a timeout occurs. When accessing multiple
parameters in a single function call, some, but not all, parameters may have been retrieved or
updated before the timeout.
•A timeout value selected to be less than or equal to zero indicates an infinite timeout. When the
gc_SetConfigData( ) function has an infinite timeout set and is updated at the Null call state,
this thread is blocked if the target object still has any active call. The customer application can
avoid this situation by using the asynchronous mode or multi-threading technology.
9.4.2.3 Update Condition When using the gc_SetConfigData() function to update the parameters of a target object with an
active call, the application can specify whether the update should occur either at the Null call state
or immediately. If parameters are to be updated at the Null state, but the function requests to
immediately update them while the target object has any active calls, the function returns an error
to the application. If parameters are to be updated immediately, the function can update them
immediately or at the Null state.
Table13 describes the possible settings and resulting actions for the update condition as used by
the gc_SetConfigData() function.