gc_ReqService( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_ReqService(target_type, target_ID, pserviceID, reqdatap, respdatapp, mode)
Inputs:	int target_type	type of target object
	long target_ID	ID of target object
	unsigned long *pserviceID	pointer to service ID
	GC_PARM_BLKP reqdatap	pointer to data associated with the request
	GC_PARM_BLKP *respdatapp	pointer to location that stores the pointer to the response buffer generated by the call control library
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	Global Call Service Request (GCSR)
Mode:	asynchronous or synchronous
Platform and Technology:	IP (host-based stack)† †See the Global Call Technology User's Guides for additional information.

Description

The gc_ReqService( ) function requests a service from a remote device. Some examples of requests are device registration, channel setup, call setup, and information request. See the appropriate Global Call Technology User's Guide for the service requests supported under each technology.

For more information about the gc_ReqService( ) function, see the discussion of the Global Call Service Request (GCSR) feature in the Global Call API Programming Guide.

Parameter	Description
target_type	target object type. Valid values are: GCTGT_GCLIB_CHAN GCTGT_GCLIB_CRN
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
pserviceID	points to the service ID of this request. Assigned by the call control library when this function returns.
reqdatap	points to the user-specified data associated with the request
respdatapp	points to the address of the response buffer (GC_PARM_BLK) generated by the call control library. See the appropriate Global Call Technology User's Guide on how to set up the data structure for a particular technology. Set to NULL in asynchronous mode. 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_SERVICERESP

indicates a response to a request for a service from a remote device.

GCEV_TASKFAIL

indicates that the function failed.

Note: The extevtdatap field of these events contains a pointer to a GC_PARM_BLK that contains an unsigned long value that is the Service ID associated with the event. This pointer is only valid until the next gc_GetMetaEvent( ) or gc_GetMetaEventEx( ) is called. See the appropriate Global Call Technology User's Guide for technology-specific information.

Cautions

• In synchronous mode, if the user specifies that no response is necessary, no data will be stored in the respdatapp structure.
• Only synchronous mode is supported for the following target objects: GCTGT_GCLIB_SYSTEM, GCTGT_CCLIB_SYSTEM, GCTGT_PROTOCOL_SYSTEM, and GCTGT_FIRMWARE_NETIF. Otherwise, the function will return the async mode error.
• The GC_PARM_BLK buffer, if one is returned via the respdatapp pointer, 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.
• When using the gc_ReqService( ) function, PARM_REQTYPE and PARM_ACK are mandatory parameters of the GC_PARM_BLK pointed to by the reqdatap function parameter.

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 "gclib.h" 
void main( ) 
{
    LINEDEV         devh;
    unsigned long   serviceID;
    GC_PARM_BLKP    reqdatap = NULL;
    GC_INFO         gc_error_info;   /* GlobalCall error information data */ 
    /* Following code assumes that gc_OpenEx has been done with handle = devh */ 
    /* Set up GC_PARM_BLK */
    if ( gc_util_insert_parm_val( &reqdatap, GCSET_SERVREQ, PARM_REQTYPE,
            sizeof( int ), 0 ) != GC_SUCCESS )
    {
        /* Process error */
    }
    if ( gc_util_insert_parm_val( &reqdatap, GCSET_SERVREQ, PARM_ACK,
            sizeof( short ), GC_NACK) != GC_SUCCESS )
    {
        /* Process error */
    } 
    /* Insert any other technology-dependent parameters */ 
    if ( gc_ReqService( GCTGT_GCLIB_CHAN, devh, &serviceID, reqdatap, NULL, 
            EV_ASYNC ) != GC_SUCCESS )
    {
         /* Process error */
         gc_ErrorInfo( &gc_error_info );
         printf ("Error: gc_ReqService() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s,
                 CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
         devh, gc_error_info.gcValue, gc_error_info.gcMsg, 
                 gc_error_info.ccLibId, gc_error_info.ccLibName,
                 gc_error_info.ccValue, gc_error_info.ccMsg);
    } 
    /* Wait for GCEV_SERVRESP and process */ 
    /* Delete GC_PARM_BLK */
    gc_util_delete_parm_blk( reqdatap );
} 

See Also

• gc_RespService( )

Click here to contact Telecom Support Resources