 |
 |
 |
 |
 |
|
|
|
|
|
gc_GetConfigData( )
Termination Events | Cautions | Errors | Example | See Also
Description
The gc_GetConfigData( ) function supports the Real Time Configuration Management (RTCM) feature. The gc_GetConfigData( ) function retrieves parameter values for a given target object. The gc_GetConfigData( ) function also outputs a unique request ID, which is used by the application to trace the function call. All subsequent references to this request must be made using the request ID.
Configuration data for multiple parameters can be retrieved in a single call to the gc_GetConfigData( ) function. However, only one target object can be accessed in a single function call.
See Table 22, "GC Parameter Entry List Maintained in GCLIB" and Table 23, "Examples of Parameter Entry List Maintained in CCLIB". For more information about the RTCM feature, see the Global Call API Programming Guide.
target_type target object type target_id target object identifier. This identifier along with target_type, uniquely specifies the target object. target_datap specifies the pointer to the GC_PARM_BLK structure. The structure contains the parameter configuration data to be retrieved. time_out time interval (in seconds) during which the data of the target object must be retrieved; if the interval is exceeded, the request to retrieve is ignored. This parameter is ignored when set to 0. The time-out option is supported in synchronous mode only. If the data requested is not retrieved within the time specified, the gc_GetConfigData( ) function will return EGC_TIMEOUT. request_idp points to the retrieve request ID, which is generated by Global Call mode set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution The parameter target_datap points to the location of the GC_PARM_BLK that stores the configuration parameter data to be retrieved. Memory allocation and deallocation of the GC_PARM_BLK data block is done by the Global Call utility functions (gc_util_xxx). See Section 1.12, "GC_PARM_BLK Utility Functions" for more information.
It is the Global Call application's responsibility to use the Global Call utility functions to allocate an appropriately sized data block memory (GC_PARM_BLK) for the configuration parameters and to insert parameter information (such as the set ID, parm ID, value buffer size, and value buffer) into the GC_PARM_BLK data block. After calling the gc_GetConfigData( ) function, the successfully retrieved parameter value(s) will be passed back to the GC_PARM_BLK (value buffer fields). After the Global Call application finishes using the GC_PARM_BLK, the application should deallocate the GC_PARM_BLK data block using the gc_util_delete_parm_blk( ) function. See GC_PARM_BLK for more information.
The termination events, GCEV_GETCONFIGDATA and GCEV_GETCONFIGDATA_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, retrieved GC_PARM_BLK, etc. See GC_RTCM_EVTDATA for more information.
When the gc_GetConfigData( ) function is called to retrieve the configuration data of a group of parameters, the request will terminate if the retrieval of any single parameter fails. Use the gc_ErrorInfo( ) function (for function return values) or gc_ResultInfo( ) function (for termination events) to find out what kind of error occurred and which parameter data (set ID and parm ID) failed to be retrieved. See the "Error Handling" section in the Global Call API Programming Guide for more information about these error functions.
Termination Events
- GCEV_GETCONFIGDATA
- indicates that the gc_GetConfigData( ) function was successful, that is, the configuration data has been retrieved successfully.
- GCEV_GETCONFIGDATA_FAIL
- indicates that the gc_GetConfigData( ) function failed, that is, an error occurred during retrieval.
Cautions
Only synchronous mode is supported for the following target objects: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM, GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_NETIF. Otherwise, the function will return the async mode error.
Errors
If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_GETCONFIGDATA_FAIL event is received, use the gc_ResultInfo( ) function to retrieve information about the event. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).
Example
#include <stdio.h> #include <srllib.h> #include <gclib.h> #include <gcerr.h> #define MAXCHAN 30 #define T_MAX_NAMESTRING 50 /* Data structure which stores all information about each line device */ struct linebag { LINEDEV ldev; /* Lline device ID */ CRN crn; /* CRN */ int call_sate; } port[MAXCHAN]; struct linebag *pline; int get_parm_valuetype(GC_PARM_DATA * parmdatap); void print_parm_data(int valuetype, GC_PARM_DATAP parmdatap); /* get the configuration of a GC target object */ int get_configuration(int target_type, int port_num, GC_PARM_BLK * parm_blkp, long * request_idp) { int result; long target_id = 0; GC_INFO t_gcinfo; switch (target_type) { case GCTGT_GCLIB_SYSTEM: target_id = GC_LIB; break; case GCTGT_CCLIB_SYSTEM: /*get cclib ID */ break; case GCTGT_PROTOCOL_SYSTEM: /*get protocol ID by calling gc_QueryConfigData() with protocol name*/ break; case GCTGT_GCLIB_CRN: case GCTGT_CCLIB_CRN: /* If the target object is a CRN */ pline = port + port_num; target_id = pline->crn; break; case GCTGT_GCLIB_NETIF: case GCTGT_CCLIB_NETIF: case GCTGT_GCLIB_CHAN: case GCTGT_CCLIB_CHAN: case GCTGT_PROTOCOL_CHAN: case GCTGT_FIRMWARE_CHAN: /* If the target object is a line device (time slot or network interface) */ pline = port + port_num; target_id = pline->ldev; break; default: /* Otherwise: return -1 */ printf("Unsupported target type: 0x%lx\n", target_type); return -1; break; } /* Call gc_GetConfigData() function */ result = gc_GetConfigData(target_type, target_id, parm_blkp, 0, request_idp, EV_SYNC); if (result != GC_SUCCESS) { /* retrieve error values by calling gc_ErrorInfo */ if (gc_ErrorInfo(&t_gcinfo) == GC_SUCCESS) { printf("Error on target type: 0x%lx, target ID: 0x%lx\n", target_type, target_id); printf("with GC Error 0x%xh: %s\n", t_gcinfo.gcValue, t_gcinfo.gcMsg); printf("CCLib %d(%s) Error - 0x%xh: %s\n", t_gcinfo.ccLibId, t_gcinfo.ccLibName, t_gcinfo.ccValue, t_gcinfo.ccMsg); printf("Additional message: %s\n", t_gcinfo.additionalInfo); } else { printf("gc_ErrorInfo() failure"); } } return result; } /* retrieve the individual parameters from GC_PARM_BLK */ void retrieve_parm_data_blk(GC_PARM_BLK * parm_data_blkp) { /* get the first parm from the block */ GC_PARM_DATA * parmdatap = gc_util_next_parm(parm_data_blkp, NULL); int valuetype = 0; while (parmdatap != NULL) { /* get the type of parm value */ valuetype = get_parm_valuetype(parmdatap); if (valuetype != -1) { /* if the value type is valid, then print the parm data */ print_parm_data(valuetype, parmdatap); } /* get the next parm from the block */ parmdatap = gc_util_next_parm(parm_data_blkp, parmdatap); } } int main() { int port_num = 0; char t_StrValue[T_MAX_NAMESTRING] = ""; long request_id = 0; /* To call the GC PARM utility function to insert a parameter, the pointer to GC_PARM_BLK must be initialized to NULL */ GC_PARM_BLK * parm_data_blkp = NULL; /* First call GC PARM utility function to insert the parameters to be retrieved */ /* 1. insert device name parm */ gc_util_insert_parm_ref(&parm_data_blkp, GCSET_DEVICEINFO, GCPARM_DEVICENAME, T_MAX_NAMESTRING, t_StrValue); /* 2. insert network handle parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_DEVICEINFO, GCPARM_NETWORKH, sizeof(int), 0); /* 3. insert voice name parm */ gc_util_insert_parm_ref(&parm_data_blkp, GCSET_DEVICEINFO, GCPARM_VOICENAME, T_MAX_NAMESTRING, t_StrValue); /* 4. insert voice handle parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_DEVICEINFO, GCPARM_VOICEH, sizeof(int), 0); /* 5. insert board line device ID parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_DEVICEINFO, GCPARM_BOARD_LDID, sizeof(long), 0); /* 6. insert protocol ID parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_PROTOCOL, GCPARM_PROTOCOL_ID, sizeof(long), 0); /* 7. insert protocol name parm */ gc_util_insert_parm_ref(&parm_data_blkp, GCSET_PROTOCOL, GCPARM_PROTOCOL_NAME, T_MAX_NAMESTRING, t_StrValue); /* 8. insert call event parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_CALLEVENT_MSK, GCPARM_GET_MSK, sizeof(long), 0); /* 9. insert call state parm */ gc_util_insert_parm_val(&parm_data_blkp, GCSET_CALLSTATE_MSK, GCPARM_GET_MSK, sizeof(long), 0); /* after creating the GC_PARM_BLK, call get_configuration function to get the configuration data block */ get_configuration(GCTGT_GCLIB_CHAN, port_num, parm_data_blkp, &request_id); /* retrieve individual parameters from the GC_PARM_BLK */ retrieve_parm_data_blk(parm_data_blkp); /* delete the parm data block after using */ gc_util_delete_parm_blk(parm_data_blkp); return 0; } /* get the type of parm value for a given parm */ int get_parm_valuetype(GC_PARM_DATA * parmdatap) { switch (parmdatap->set_ID) { case GCSET_DEVICEINFO: { switch (parmdatap->parm_ID) { case GCPARM_DEVICENAME: case GCPARM_VOICENAME: /* a string value */ return GC_VALUE_STRING; break; case GCPARM_NETWORKH: case GCPARM_VOICEH: case GCPARM_CALLSTATE: /* an integer value */ return GC_VALUE_INT; break; case GCPARM_BOARD_LDID: /* a long value */ return GC_VALUE_LONG; break; default: return -1; break; } break; } case GCSET_PROTOCOL: { switch (parmdatap->parm_ID) { case GCPARM_PROTOCOL_ID: /* a long value */ return GC_VALUE_LONG; break; case GCPARM_PROTOCOL_NAME: /* a string value */ return GC_VALUE_STRING; break; } break; } case GCSET_CALLEVENT_MSK: case GCSET_CALLSTATE_MSK: case GCSET_CRN_INDEX: /* a long value */ return GC_VALUE_LONG; break; case GCSET_CCLIB_INFO: { switch (parmdatap->parm_ID) { case GCPARM_CCLIB_NAME: /* a string value */ return GC_VALUE_STRING; break; case GCPARM_CCLIB_ID: /* an integer value */ return GC_VALUE_INT; break; default: return -1; break; } break; } default: return -1; break; } return -1; } /* print the parm data */ void print_parm_data(int valuetype, GC_PARM_DATAP parmdatap) { int t_IntVal; char t_StrVal[T_MAX_NAMESTRING]; short t_ShortVal; long t_LongVal; char t_CharVal; switch (valuetype) { case GC_VALUE_INT: if (parmdatap->value_size == sizeof(int)) { memcpy(&t_IntVal, parmdatap->value_buf, sizeof(int)); printf("Retrieve Set ID = %d and Parm ID = %d with value = %d \n", parmdatap->set_ID, parmdatap->parm_ID, t_IntVal); } break; case GC_VALUE_LONG: if (parmdatap->value_size == sizeof(long)) { memcpy(&t_LongVal, parmdatap->value_buf, sizeof(long)); printf("Retrieve Set ID = %d and Parm ID = %d with value = %d \n", parmdatap->set_ID, parmdatap->parm_ID, t_LongVal); } break; case GC_VALUE_SHORT: if (parmdatap->value_size == sizeof(short)) { memcpy(&t_ShortVal, parmdatap->value_buf, sizeof(short)); printf("Retrieve Set ID = %d and Parm ID = %d with value = %d \n", parmdatap->set_ID, parmdatap->parm_ID, t_ShortVal); } break; case GC_VALUE_CHAR: if (parmdatap->value_size == sizeof(char)) { memcpy(&t_CharVal, parmdatap->value_buf, sizeof(char)); printf("Retrieve Set ID = %d and Parm ID = %d with value = %c \n", parmdatap->set_ID, parmdatap->parm_ID, t_CharVal); } break; case GC_VALUE_STRING: if (parmdatap->value_size == T_MAX_NAMESTRING) { strcpy(t_StrVal, (const char*)parmdatap->value_buf); printf("Retrieve Set ID = %d and Parm ID = %d with value = %s \n", parmdatap->set_ID, parmdatap->parm_ID, t_StrVal); } break; default: printf("Retrieve Unsupported parm Set ID = %d and Parm ID = %d\n", parmdatap->set_ID, parmdatap->parm_ID); break; } }See Also
|
|
|
|
|
Click here to contact Telecom Support Resources
Copyright 2003, Intel Corporation