Dialogic 05-2239-009 User Manual

437

Dialogic Corporation

The gc_util_next_parm_ex( ) function updates the data structure referenced by the parm pointer 
and returns GC_SUCCESS if there is another parameter element in the GC_PARM_BLK 
following the element that was identified in the function call. If the current parameter data structure 
referenced by parm identifies the last parameter element in the GC_PARM_BLK, the next 
function call returns EGC_NO_MORE_PARMS. 

„ Cautions

Unlike the similar gc_util_next_parm( ) function, the parm pointer used in this function cannot 
be used to update the parameter itself because it references a data structure that is in the 
application’s memory rather than pointing to a location within the GC_PARM_BLK itself. 

„ Errors

If this function returns GC_ERROR to indicate failure, use the gc_ErrorInfo( ) function to 
retrieve the reason for the error. See the “Error Handling” section in the Dialogic

API Programming Guide. All Global Call error codes are defined in the gcerr.h file.

The parm parameter must point to a valid GC_PARM_DATA_EXT structure. If it is desired to 
search from the beginning of the parameter block, the application must initialize the structure 
via INIT_GC_PARM_DATA_EXT(parm) before calling gc_util_next_parm_ex( ). 

„ Example

#include "gclib.h"

 

#include "gcip.h"

void process_parm_block(GC_PARM_BLKP pparm_blk) 

 

{

 

   GC_PARM_DATA_EXT parm_data_ext;

 

   int ret = 0;

   /* Initialize this structure for two reasons:

 

    * 1. To retrieve the first parameter in the parm block

 

    * 2. The first time this structure is used it must be initialized

 

    */

 

   INIT_GC_PARM_DATA_EXT(&parm_data_ext);

   /* Loop to retrieve all of the parameters and associated data from the GC_PARM_BLK

 

    */

 

   while ( GC_SUCCESS == (ret = gc_util_next_parm_ex( pparm_blk, &parm_dat_ext)) )

 

   {

 

      /* Process set_ID/parm_ID pairs */

 

      switch(parm_data_ext.set_ID);

 

parm_blk 

points to the valid GC_PARM_BLK structure where data is stored

parm 

pointer to a valid GC_PARM_DATA_EXT structure provided by the 
application. If the pointer that is passed in the function call refers to a structure 
that was just initialized with INIT_GC_PARM_DATA_EXT(parm), the 
function retrieves the first parameter element in the GC_PARM_BLK. If the 
passed pointer references a structure that contains data from a previously 
found parameter element, the function retrieves the next parameter element in 
the block (if any). When the function completes successfully, the 
GC_PARM_DATA_EXT structure is updated to contain the retrieved 
information for the parameter element.