Global Call API Library Reference: gc

gc_Extension( )

Termination Events | Cautions | Errors | Example | See Also

Name: int gc_Extension(target_type, target_id, ext_id, parmblkp, retblkp, mode)

Inputs:
int target_type

type of target object (line device or call reference number)

long target_id

ID of target: either line device handle or call reference number

unsigned char ext_id

extension function identifier as specified by the technology

GC_PARM_BLK* parmblkp

pointer to GC_PARM_BLK as specified by the technology

GC_PARM_BLKP* retblkp

pointer to address of GC_PARM_BLK union where parameter values are to be returned. Optional depending on technology.

unsigned long mode

async or sync

Returns:
0 if successful

<0 if failure

Includes:
gclib.h

Category:
FTE

Mode:
asynchronous or synchronous

Platform and Technology:
Springware: T-1/E-1 (PDKRT only)†, ISDN†, Analog (PDKRT only)

DM3: ISDN†

SS7†

IP (host-based stack† and embedded stack†)

†See the Global Call Technology User's Guides for additional information.

Description

The gc_Extension( ) function provides a generic interface for technology-specific features, which otherwise require the support of the lower-level call control library APIs.

A target object is a configurable basic entity and is represented by its target type and target ID. For the gc_Extension( ) function, the target type identifies whether the basic entity is either a line device (GCTGT_GCLIB_CHAN) or a call (GCTGT_GCLIB_CRN). The target ID identifies the specific target object (for example, line device handle or CRN), which is generated by Global Call at runtime. See Section 6.2, "Target Objects" for more information.

The Global Call Technology User's Guides provide the details on how to map the Global Call extension function to the intended corresponding technology-specific function provided via the call control library. This mapping is done via the function identifier, which is used by the call control library as an index for the requested extension function, should more than one extension function be provided by the library.

The EXTENSIONEVTBLK extension block structure contains technology-specific information and is referenced via the extevtdatap pointer in the METAEVENT structure associated with the GCEV_EXTENSION and GCEV_EXTENSIONCMPLT events.

If the gc_Extension( ) function is used to transmit information to the remote end point, the application at the remote end point receives a GCEV_EXTENSION event.

Parameter

Description

target_type target object type. Valid types are:

GCTGT_GCLIB_CHAN
GCTGT_GCLIB_CRN
See Table 22, "GC Parameter Entry List Maintained in GCLIB" for details about these two types.

target_id target object identifier. This identifier, along with target_type, uniquely specifies the target object. Valid identifiers are:

line device handle
call reference number

ext_id extension function identifier, if multiple extension functions are provided by the technology. If multiple extension functions are not provided, this parameter is not used. See the appropriate Global Call Technology User's Guide for actual definitions.

parmblkp points to GC_PARM_BLK as defined by the technology. This parameter is not used in cases where extension functions do not have any parameters.

retblkp points to the GC_PARM_BLK used for potential return of parameter values, as defined by the technology. This pointer is not used in cases where extension functions do not return one or more parameter values to the caller. See the appropriate Global Call Technology User's Guide for definitions of parameters contained within the GC_PARM_BLK. If a GC_PARM_BLK buffer is returned, the parameters in this buffer must be processed or copied prior to the next Global Call function call. The reason for this is that the GC_PARM_BLK buffer will be deallocated in a subsequent Global Call function call.

mode set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_EXTENSIONCMPLT

indicates the successful completion of the extension function.

GCEV_TASKFAIL

indicates that the function failed. See the "Error Handling" section in the Global Call API Programming Guide.

Cautions

The EXTENSIONEVTBLK extension block structure has a persistence only until the next call of gc_GetMetaEvent( ) or gc_GetMetaEventEx( ). In other words, any information contained or referenced in a GCEV_EXTENSION or GCEV_EXTENSIONCMPLT event must be either processed or cached within the application, or risk being lost upon the next call of gc_GetMetaEvent( ) or gc_GetMetaEventEx( ).
The GC_PARM_BLK buffer, if one is returned via the retblkp pointer, also has a guaranteed persistence only until the next Global Call function call. Any parameters within this buffer must be processed or copied within the application, or risk being lost when the next Global Call function call is invoked.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_TASKFAIL 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 "gclib.h"
#include "gcerr.h"
#include "gcisdn.h" 
/* ISDN Example:  Send an PROGRESS message to the network. */
/* Refer to "ISDN Technology User's Guide" for details.    */
int ExtSendCallProgressMsg(CRN crn)
{
    GC_PARM_BLKP  parmblkp = NULL; /* input parameter block pointer */
    GC_PARM_BLKP  retblkp  = NULL; /* pointer for output parameter block (unused) */
    int           progval  = 0;    /* call progress indicator value */
    int           retval   = GC_SUCCESS;
    GC_INFO     gc_error_info;    /* GlobalCall error information data */ 
    printf("\n Enter call progress indicator value : ");
    progval = getchar(); 
    /* allocate GC_PARM_BLK for call progress message parameter */
    gc_util_insert_parm_ref(&parmblkp,GCIS_SET_CALLPROGRESS,
                            GCIS_PARM_CALLPROGRESS_INDICATOR, sizeof(int), &progval); 
    if (parmblkp == NULL)
    {
       /* memory allocation error */
       return(-1);
    } 
    /* transmit PROGRESS message to network */
    retval = gc_Extension(GCTGT_GCLIB_CRN, crn, GCIS_EXID_CALLPROGRESS, parmblkp,
                          &retblkp, EV_SYNC); 
    if (retval != GC_SUCCESS)
    {
        gc_ErrorInfo( &gc_error_info );
        printf ("Error : gc_Extension() on CRN: 0x%lx, GC ErrorValue: 0x%hx - %s, 
               CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               crn, gc_error_info.gcValue, gc_error_info.gcMsg, 
               gc_error_info.ccLibId, gc_error_info.ccLibName,
               gc_error_info.ccValue, gc_error_info.ccMsg);
        return (gc_error_info.gcValue);
    } 
    /* free the parameter block */
    gc_util_delete_parm_blk(parmblkp); 
    return (retval);
} 
See Also

None

Name:	int gc_Extension(target_type, target_id, ext_id, parmblkp, retblkp, mode)
Inputs:	int target_type	type of target object (line device or call reference number)
	long target_id	ID of target: either line device handle or call reference number
	unsigned char ext_id	extension function identifier as specified by the technology
	GC_PARM_BLK* parmblkp	pointer to GC_PARM_BLK as specified by the technology
	GC_PARM_BLKP* retblkp	pointer to address of GC_PARM_BLK union where parameter values are to be returned. Optional depending on technology.
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h
Category:	FTE
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only)†, ISDN†, Analog (PDKRT only) DM3: ISDN† SS7† IP (host-based stack† and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Parameter	Description
target_type	target object type. Valid types are: GCTGT_GCLIB_CHAN GCTGT_GCLIB_CRN See Table 22, "GC Parameter Entry List Maintained in GCLIB" for details about these two types.
target_id	target object identifier. This identifier, along with target_type, uniquely specifies the target object. Valid identifiers are: line device handle call reference number
ext_id	extension function identifier, if multiple extension functions are provided by the technology. If multiple extension functions are not provided, this parameter is not used. See the appropriate Global Call Technology User's Guide for actual definitions.
parmblkp	points to GC_PARM_BLK as defined by the technology. This parameter is not used in cases where extension functions do not have any parameters.
retblkp	points to the GC_PARM_BLK used for potential return of parameter values, as defined by the technology. This pointer is not used in cases where extension functions do not return one or more parameter values to the caller. See the appropriate Global Call Technology User's Guide for definitions of parameters contained within the GC_PARM_BLK. If a GC_PARM_BLK buffer is returned, the parameters in this buffer must be processed or copied prior to the next Global Call function call. The reason for this is that the GC_PARM_BLK buffer will be deallocated in a subsequent Global Call function call.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Click here to contact Telecom Support Resources