2.11.  Run Time Configuration of PDK Protocol Parameters

NOTE:

The information in this section is applicable to Springware boards only. DM3 boards do not use PDKRT analog protocols. On DM3, the analog protocol is embedded in the firmware.

Configurable PDK protocol parameters are grouped in two sets:

• Protocol state information (PSI) variable parameters
• Protocol service layer (PSL) variable parameters

NOTE:

To avoid errors, both PSI and PSL parameters of a GCTGT_PROTOCOL_CHAN channel are allowed to be changed only when the channel object does not have an active call.

PSI variable parameters are interpreted by the PDK run-time component (PDKRT). The names of the PSI variable parameters (beginning with CDP_) are found in the .cdp file. The PSI parameters that can be accessed via gc_GetConfigData( ), gc_SetConfigData( ), and gc_QueryConfigData( ) are shown in Table 6.

Table 6.  CDP Parameters

Parameter Name	Data Type
CDP_ConnectOnNoRingBack	boolean
CDP_Working_Under_PBX_Env	boolean
CDP_Time_Before_Blind_Dialing_Under_PBX_Env	integer
CDP_Dgts_For_Outside_Line_In_PBX_Env	string
CDP_PBX_DialToneTimeout	integer
CDP_DialTone_As_Disconnect_In_Connected	boolean

The PSL variable parameters are not available to the protocol state machine, but rather are used by the protocol services layer to control the behavior of various network and voice functions. The names of the PSL variable parameters begin with PSL_ and SYS_. No variation in the names is allowed. These parameters are required to control protocol parameters (e.g., timing) or they may control the behavior of the underlying implementation. In the latter case, the parameters will most likely have a platform tag. All of these parameter names must begin with PSL. The PSL parameters that can be accessed via gc_GetConfigData( ), gc_SetConfigData( ), and gc_QueryConfigData( ) are shown in Table 7.

Table 7.  PSL and SYS Parameters

PSL Variable Name	Data Type
PSL_MakeCall_CallProgress	integer
PSL_MakeCall_MediaDetect	integer
PSL_DefaultMakeCallTimeout	integer
PSL_ANALOG_NUM_RINGS_BEFORE_RINGON	integer
SYS_PSINAME	string

Table 8 shows the Set ID and Parm ID for these parameter types.

Table 8.  Configurable PDK Protocol Parameters

Set ID	Parm ID	Target Object Type	Explanation	Update Flag **
PDKSET_ PSI_VAR *	Dynamically assigned	GCTGT_ PROTOCOL_ SYSTEM, GCTGT_PROTOCOL_CHAN	Protocol state information (PSI) variable parameters	GC_W_N
PDKSET_ SERVICE_ VAR	Dynamically assigned	GCTGT_ PROTOCOL_ SYSTEM, GCTGT_PROTOCOL_CHAN	Protocol service layer (PSL) variable parameter and system parameters	GC_W_N
*Indicates that CAS pattern signals and tones cannot be accessed. ** GC_W_N - update only at null state

The PDK GCTGT_PROTOCOL_SYSTEM target object is not available until the first gc_OpenEx( ) function is called to run this protocol.

The Global Call application can call gc_GetConfigData( ) to retrieve protocol configuration information or gc_SetConfigData( ) to set protocol configuration information. Since these parameters are protocol dependent, their parameters are dynamically assigned when a protocol is loaded into the PDKRT. Therefore, a Global Call application must call gc_QueryConfigData( ) to find the parameter information (set ID, parm ID, and value data type, etc.) first. For more information about these functions, refer to the Global Call API Programming Guide.

The pair (target object type, target object ID) supporting gc_QueryConfigData( ) to find PDKRT protocol parameter information can be one of the following:

• (GCTGT_PROTOCOL_SYSTEM, Global Call protocol ID)
• (GCTGT_PROTOCOL_CHAN, Global Call line device ID)

For a given protocol, although the GCTGT_PROTOCOL_SYSTEM target object and GCTGT_PROTOCOL_CHAN target object share the same set ID and parm ID for PSI variables, they can have different values. When a new GCTGT_PROTOCOL_CHAN target object is opened, it gets a copy of the current PSI variable configuration of GCTGT_PROTOCOL_SYSTEM target object. Under this situation, changes to the GCTGT_PROTOCOL_SYSTEM target object configuration will not affect the configuration of the GCTGT_PROTOCOL_CHAN target object. But the GCTGT_PROTOCOL_SYSTEM target object shares the same PSL variable configuration with other GCTGT_PROTOCOL_CHAN target objects.

The following example shows how to set the CDP_ConnectOnNoRingBack parameter for channel ldev running a PDK protocol at the NULL state in asynchronous mode.

NOTE:

Error handling is not shown.

   GC_PARM t_SourceParm, t_DestParm;  
   GC_PARM_ID t_ParmIDSt;  
   char t_name[25] = "CDP_ConnectOnNoRingBack";  
   long request_id;  
   LINEDEV ldev;  
   GC_PARM_BLK * t_pParmBlk = NULL;  
/* first find the parameter info by calling gc_QueryConfigData() function */  
   t_SourceParm.padress = t_name;             /* Pass the PSI variable name */  
   memset(&t_ParmIDSt, 0, sizeof(GC_PARM_ID));  
   t_DestParm.pstruct = &t_ParmIDStruct;      /* Pass desired the parm info */  
   gc_QueryConfigData(GCTGT_PROTOCOL_CHAN, ldev, &t_SourceParm,  
                      GCQUERY_PARM_NAME_TO_ID, &t_DestParm);  
/* Call GC utility function to insert a parameter data to GC_PARM_BLK */  
   gc_util_insert_parm_val(&t_pParmBlk, t_ParmIDStruct.set_ID,   
                           t_ParmIDStruct.parm_ID, sizeof(int), 10);  
/* Call gc_SetConfigData() function to set the "CDP_ConnectOnNoRingBack" */   
   gc_SetConfigData(GCTGT_PROTOCOL_CHAN, ldev, t_pParmBlk, 0,   
                    GCUPDATE_ATNULL, &request_id, EV_ASYNC);  
   ...  
/* Call GC utility function to release the memory after using the GC_PARM_BLK */  
   gc_util_delete_parm_blk(t_pParmBlk);

Click here to contact Telecom Support Resources