gc_HoldCall( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_HoldCall(crn, mode)
Inputs:	CRN crn	call reference number for the active call
	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_HoldCall( ) function places an active call on hold. The call must be in the Connected state to be put on hold.

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_HOLDACK

indicates that the gc_HoldCall( ) function was successful, that is, the call was placed on hold.

GCEV_HOLDREJ

indicates that the function failed and the request to place the call on hold was rejected.

PDKRT events:

GCEV_HOLDCALL

indicates that the gc_HoldCall( ) function was successful, that is, the call was placed on hold.

GCEV_TASKFAIL

indicates that the function failed. See the "Error Handling" section in the Global Call API Programming Guide.

Cautions

The gc_HoldCall( ) function should only be used when the call is in the Connected state or the function will fail.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_HOLDREJ 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 hold_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 place the call on hold
     */ 
    crn = metaevent.crn; 
    if(gc_HoldCall(crn, EV_ASYNC) != GC_SUCCESS) {
        /* process error return as shown */
        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;
}    

See Also

• gc_HoldACK( )
• gc_HoldRej( )
• gc_RetrieveCall( )

Click here to contact Telecom Support Resources