gc_RetrieveCall( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_RetrieveCall(crn, mode)
Inputs:	CRN crn	call reference number
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	advanced call model
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1 (PDKRT only)†, ISDN BRI, ISDN PRI (DPNSS and Q.SIG only) SS7† †See the Global Call Technology User's Guides for additional information.

Description

The gc_RetrieveCall( ) function retrieves a call from the OnHold state. The call must be in the OnHold state before calling this function.

Parameter	Description
crn	call reference number
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

ISDN events:

GCEV_RETRIEVEACK

indicates that the function was successful, that is, the call was retrieved from the OnHold state

GCEV_RETRIEVEREJ

indicates that the function failed, that is, the call was not retrieved from hold

PDKRT events:

GCEV_RETRIEVECALL

indicates that the function was successful, that is, the call was retrieved from the OnHold state

GCEV_TASKFAIL

indicates that the function failed. For more information, see the "Error Handling" section in the Global Call API Programming Guide.

Cautions

The gc_RetrieveCall( ) function can only be used when the call is in the OnHold state or the function fails.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_RETRIEVEREJ or 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

/*
 * 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;
} 

See Also

• gc_HoldCall( )
• gc_RetrieveAck( )
• gc_RetrieveRej( )

Click here to contact Telecom Support Resources