gc_SetUserInfo( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetUserInfo (target_type, target_id, infoparmblkp, duration)
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
	GC_PARM_BLKP infoparmblkp	pointer to user information GC_PARM_BLK as specified by the technology
	int duration	duration of the user information setting
Returns:	0 if successful <0 if failure
Includes:	gclib.h
Category:	FTE
Mode:	synchronous
Platform and Technology:	Springware: ISDN† DM3: ISDN† IP (host-based stack† and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Description

The gc_SetUserInfo( ) function permits the setting of technology-specific user information. The 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_SetUserInfo( ) function, the target type identifies whether the basic entity is either 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.
infoparmblkp	points to GC_PARM_BLK which contains parameters defining user information. See the appropriate Global Call Technology User's Guide for GC_PARM_BLK pointer referenced structure definitions.
duration	duration of the user information block setting: GC_SINGLECALL effective for the next call if in the Idle or Null call state, otherwise effective for the current call. The user information returns to its default when the call is cleared, and the line returns to Idle state. GC_ALLCALLS effective for the current or next call, and all subsequent calls.

Termination Events

None

Cautions

If the duration is specified as GC_ALLCALLS, the specified user information block is maintained for either the duration of the line device (that is, until gc_Close( ) is invoked on the device) or until gc_SetUserInfo( ) is invoked again. In the case where gc_SetUserInfo( ) is invoked subsequent times on a single line device, each prior data setting is overwritten with the data specified in each subsequent 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 Example:  Include specified information element in the next outbound message. */
/* Refer to "ISDN Technology User's Guide" for details.    */
int SetInfoElemt(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; 
    /* allocate GC_PARM_BLK for call progress message parameter */
    gc_util_insert_parm_ref(&infoparmblkp, GCIS_SET_IE, GCIS_PARM_UIEDATA, 
                            sizeof(IE_BLK), ie_blkp); 
    if (infoparmblkp == NULL)
    {
        /* memory allocation error */
        return(-1);
    } 
    /* configure user specified info element for transmitting in next outbound message
       to network */
    retval = gc_SetUserInfo(GCTGT_GCLIB_NETIF, linedev, infoparmblkp, GC_SINGLECALL); 
    if (retval != GC_SUCCESS)
    {
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetUsrInfo() on device handle: 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);
    } 
    /* free the parameter block */
    gc_util_delete_parm_blk(infoparmblkp); 
    return (retval);
} 

See Also

• gc_GetUserInfo( )

Click here to contact Telecom Support Resources