gc_HoldRej( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_HoldRej(crn, cause)
Inputs:	CRN crn	call reference number
	int cause	standard ISDN Network error code
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	interface specific
Mode:	synchronous
Platform and Technology:	Springware: ISDN BRI, ISDN PRI (DPNSS and Q.SIG only)

Description

The gc_HoldRej( ) function rejects a hold request from remote equipment. This function is called only after the call is in the Connected state and after the GCEV_HOLDCALL event is received.

Parameter	Description
crn	call reference number
cause	a standard ISDN Network cause/error code is returned indicating the reason the hold request was rejected. Possible causes include TEMPORARY_FAILURE (Cause 41), NETWORK_OUT_OF_ORDER (Cause 38), and NETWORK_CONGESTION (Cause 42). For a complete listing of ISDN Network cause/error codes, see the Global Call ISDN Technology User's Guide.

Termination Events

None

Cautions

• Call the gc_HoldRej( ) function only after the call is in the Connected state and after receiving the GCEV_HOLDCALL event or the function will fail.
• Not all ISDN Network cause/error codes are universally supported across switch types. Before you use a particular cause code, compare its validity with the appropriate switch vendor specifications.

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

/*
 * Assume the following has been done:
 * 1. device has been opened (e.g. :N_dtiB1T1:P_isdn, 
 *    :N_dtiB1T2:P_isdn, etc...)
 * 2. gc_WaitCall() has been issued to wait for a call.
 * 3. gc_GetMetaEvent() or gc_GetMetaEventEx() (Windows) has been 
 *    called to convert the event into metaevent.
 * 4. a GCEV_OFFERED event has been detected.
 */
GC_INFO  gc_error_info;  /* GlobalCall error information data */ 
    /*
     * Do the following:
     *    1. Get the CRN from the metaevent
     *    2. Proceed to place the call on hold
     */ 
    crn = metaevent.crn; 
    if(gc_HoldCall(crn, EV_ASYNC) != GC_SUCCESS) {
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_HoldCall() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                  CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                  metaevent.evtdev, 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);
    } 
    return 0;
}    
/* Retrieve events from SRL */
int evt_hdlr()
{
    LINEDEV  ldev;           /* Line device */
    CRN      crn;            /* Call Reference Number */
    GC_INFO  gc_error_info;  /* GlobalCall error information data */
    int      retcode;        /* Return Code */ 
    retcode = gc_GetMetaEvent(&metaevent);
    if (retcode != GC_SUCCESS ) {
            /* get and process the error */
    } else {
            /* Continue with normal processing */
    } 
    crn = metaevent.crn; 
    switch(metaevent.evttype) {
    case GCEV_HOLDCALL:
        /* retrieve signaling information from queue */
        if ( gc_HoldRej(crn, TEMPORARY_FAILURE) != GC_SUCCESS)
        {
             /* process error return as shown */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_HoldRej() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                  CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                  metaevent.evtdev, 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);
        }
        else {
            /* succeeded, process signaling information */
        } 
        break;
    }
    return 0;
} 

See Also

• gc_HoldCall( )
• gc_RetrieveCall( )

Click here to contact Telecom Support Resources