Dialogic® Global Call API Library Reference

Table 14. Parameter Configuration Data Conditions and Results
update the configuration data — gc_SetConfigData( )
Parameter Update Condition Result when gc_SetConfigData( ) is Called
Read-only An error is returned immediately.
Update immediately Configuration data is updated immediately.
Update only at Null call state Configuration data is updated when the target object does not have an
active call (Null call state). A request for an immediate update may fail.
To immediately update parameters that can be updated only at the Null
call state, call gc_SetConfigData( ) with GCUPDATE_ATNULL and then
call gc_ResetLineDev( ).
The gc_SetConfigData( ) function supports both the synchronous and asynchronous modes. In the
asynchronous mode, the termination events, GCEV_SETCONFIGDATA and
GCEV_SETCONFIGDATA_FAIL, both have an associated GC_RTCM_EVTDATA data structure
(to which the evtdatap field in METAEVENT points) that includes the request ID, additional
message, etc., but without the retrieved GC_PARM_BLK field. The request ID is used by the
application to trace the function call. See GC_RTCM_EVTDATA, on page 450 for more
information.
When the gc_SetConfigData( ) function is called to update the configuration data of a group of
parameters, the request will terminate on any single parameter updating failure. Some parameters
may be updated while others may not be updated. To find out what kind of error occurred and
which parameter data pair (set ID, parm ID) were being updated when it occurred, use the
gc_ErrorInfo( ) function to retrieve information about function return values or the
gc_ResultInfo( ) function to retrieve information about termination events. (See the “Error
Handling” section in the Dialogic ® Global Call API Programming Guide for more information
about these error functions.) To determine which parameters were updated, use the
gc_GetConfigData( ) function to retrieve the current configuration. After the error is fixed, call the
gc_SetConfigData( ) function again to update the remaining parameters.
Termination Events
GCEV_SETCONFIGDATA
indicates that the gc_SetConfigData( ) function was successful, that is, the configuration data
has been successfully updated
GCEV_SETCONFIGDATA_FAIL
indicates that the gc_SetConfigData( ) function failed
Cautions
Parameters should be set with caution. Improper setting of parameters may result in
unpredictable behavior. Consult the Dialogic ® Global Call API Programming Guide and the
appropriate Global Call Technology Guide for the impact of changing any settings.
In the synchronous mode, the function does not return until the request is completed. If the
parameter is allowed to update only at the Null call state (no active call) but the current call
state for the related target object is not at the Null call state, the system may be blocked. This
occurs because the function waits for the Null call state while the system waits for the function
to finish. To avoid this blocking, use the asynchronous mode.
Dialogic ® Global Call API Library Reference — January 2008 321
Dialogic Corporation