gc_RetrieveRej( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_RetrieveRej(crn, cause)
Inputs:	CRN crn	call reference number
	int cause	standard ISDN Network cause/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_RetrieveRej( ) function rejects a retrieve request from remote equipment. The call must be in the OnHold state and the GCEV_RETRIEVECALL event must be received before calling this function.

Parameter	Description
crn	call reference number
cause	a standard ISDN Network cause/error code is returned indicating the reason the Retrieve 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

• ISDN Q.SIG is the only protocol that allows the retrieval of a call in the OnHold state to be rejected. If this function is used with any other protocol, the gc_RetrieveRej( ) function call will complete without generating an error, that is, the Retrieve Reject request will be ignored by the protocol and the call will be retrieved (call will no longer be in the OnHold state).
• Call the gc_RetrieveRej( ) function only after the call is in the OnHold state and after the GCEV_RETRIEVECALL event is received, 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.
 */ 
#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h>
#include <gcisdn.h> 
METAEVENT metaevent;  
int retrieve_call() 
{
    LINEDEV  ldev;           /* Line device */
    CRN      crn;            /* call reference number */
    GC_INFO  gc_error_info;  /* GlobalCall error information data */ 
    /*
     * Do the following:
     *    1. Get the CRN from the metaevent
     *    2. Proceed to retrieve the call on hold
     */ 
    crn = metaevent.crn; 
    if(gc_RetrieveCall(crn, EV_ASYNC) != GC_SUCCESS) {
         /* Process error */
         gc_ErrorInfo( &gc_error_info );
         printf ("Error: gc_RetrieveCall() on device handle: 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 <0 ) {
            /* get and process the error */
    } else {
            /* Continue with normal processing */
    } 
    crn = metaevent.crn; 
    switch(metaevent.evttype) { 
    case GCEV_RETRIEVECALL:
        /* retrieve signaling information from queue */
        if (gc_RetrieveRej(crn, TEMPORARY_FAILURE) != GC_SUCCESS) {
            /* Process error */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_RetrieveRej() on device handle: 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_RetrieveAck( )
• gc_RetrieveCall( )

Click here to contact Telecom Support Resources