gc_RetrieveAck( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_RetrieveAck(crn)
Inputs:	CRN crn	call reference number
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_RetrieveAck( ) function accepts a retrieve request from remote equipment. The call must be in OnHold state and the GCEV_RETRIEVECALL event must be received before the function is called.

Parameter	Description
crn	call reference number

Termination Events

None

Cautions

• The ISDN Q.SIG protocol allows the retrieval of a call in the OnHold state to be accepted or rejected. If this function is used with a protocol that does not support the retrieval of a call in the OnHold state, the function fails.
• The gc_RetrieveAck( ) function is called only after the call is in the OnHold state and after the GCEV_RETRIEVECALL event is received, or the function fails.

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 != GC_SUCCESS) {
        /* 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_RetrieveAck(crn) != GC_SUCCESS) {
            /* Process error */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_RetrieveAck() 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_RetrieveCall( )
• gc_RetrieveRej( )

Click here to contact Telecom Support Resources