gc_GetUserInfo( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_GetUserInfo (target_type, target_id, infoparmblkp)
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
Outputs:	GC_PARM_BLKP* infoparmblkp	pointer to location of user information GC_PARM_BLK as defined by call control library
Returns:	0 if successful <0 if failure
Includes:	gclib.h
Category:	interface specific, FTE
Mode:	synchronous
Platform and Technology:	Springware: ISDN† †See the Global Call Technology User's Guides for additional information.

Description

The gc_GetUserInfo( ) function retrieves technology-specific user information. An example of user information is information elements (IEs) in the case of ISDN. The actual definition and use of the user information is totally technology dependent. See the associated Global Call Technology User's Guide for definition and usage of the user information parameter.

For the gc_GetUserInfo( ) function, the target type identifies whether the basic entity is a line device (GCTGT_GCLIB_CHAN) or a call (GCTGT_GCLIB_CRN). See Section 6.2, "Target Objects" for more information.

Parameter	Description
target_type	target object type. Valid values are: GCTGT_GCLIB_CHAN GCTGT_GCLIB_CRN See Table  22, "GC Parameter Entry List Maintained in GCLIB" for details.
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
infoparmblkp	address of pointer to the location of GC_PARM_BLK, which contains user information parameters. See the appropriate Global Call Technology User's Guide for definitions of the user information parameters contained in the GC_PARM_BLK.

Termination Events

None

Cautions

The user information parameters in the GC_PARM_BLK buffer that are returned via the infoparmblkp parameter must be processed or copied prior to the next Global Call function call. This is because the GC_PARM_BLK buffer will be deallocated in a subsequent Global Call function call.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. 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 <gclib.h>
#include <gcerr.h>
#include <gcisdn.h> 
/* ISDN: Retrieves and copies unprocessed information elements in CCITT format. */
/* Refer to "ISDN Technology User's Guide" for details.    */
int GetUserInfo (LINEDEV linedev, IE_BLK **ie_blkp)
{
    GC_PARM_BLKP  infoparmblkp = NULL; /* input parameter block pointer */
    int           retval   = GC_SUCCESS;
    GC_INFO       gc_error_info;       /* GlobalCall error information data */
    GC_PARM_DATAP t_parm_datap = NULL; 
    /* retrieve the information element for the specified line device */
    retval = gc_GetUserInfo(GCTGT_GCLIB_NETIF, linedev, &infoparmblkp); 
    if (retval != GC_SUCCESS)
    {
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_GetUserInfo() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                 CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                 linedev, 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); 
    } 
    /* retrieve and copy the IE block from the parameter block */
    t_parm_datap = gc_util_find_parm(infoparmblkp, GCIS_SET_IE, GCIS_PARM_UIEDATA);
    memcpy((*ie_blkp), t_parm_datap, sizeof(IE_BLK)); 
    return (retval);
} 

See Also

• gc_SetUserInfo( )

Click here to contact Telecom Support Resources