gc_SwapHold( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SwapHold(activecall, callonhold, mode)
Inputs:	CRN activecall	call reference number for active call
	CRN *callonhold	pointer to call reference number for call on hold (pending transfer)
	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)† †See the Global Call Technology User's Guides for additional information.

Description

The gc_SwapHold( ) function is used to switch between an active call and a call on hold. The gc_SwapHold( ) function can also be used in a supervised transfer to switch between the consultation call and the call pending transfer. This function can be called only when a consultation call has been established (see the gc_CompleteTransfer( ) function description).

For more information about supervised transfers, see the information about the advanced call model in the Global Call API Programming Guide.

Parameter	Description
activecall	call reference number for the original (active) call
callonhold	points to call reference number for the call on hold/pending transfer
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_SWAPHOLD

indicates the successful completion of the gc_SwapHold( ) function, that is, the active call and the call on hold (pending transfer) were switched.

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_SwapHold( ) function can be called only when one call is the Connected state and the other call is in the OnHoldPendingTransfer state or the OnHold state.

Errors

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

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
#define MAX_CHAN 30              /* max. number of channels in system */ 
/*
* Data structure which stores all information for each line
*/
static struct linebag {
      LINEDEV    ldev;              /* GlobalCall API line device handle */
      CRN        original_crn;      /* GlobalCall API call handle */
      CRN        consultation_crn;  /* GlobalCall API call handle */
      int        blocked;           /* channel blocked/unblocked */
      int        networkh;          /* network handle */
} port[MAX_CHAN+1];
struct linebag *pline;              /* pointer to access line device */ 
/*
 * Assume the following has been done:
 *    1. Opened line devices for each time slot on DTIB1.
 *    2. Each line device is stored in linebag structure "port".
 *    3. A call has been established (original_crn) and 
 *       is in connected state.
 *    4. The gc_SetUpTransfer() has been called successfully 
 *       to initiate the transfer.
 *    5. A consultation call has also been established.
 */
int call_swaphold(int port_num)
{
    GC_INFO  gc_error_info;   /* GlobalCall error information data */ 
    /* Find info for this time slot, specified by 'port_num' */
    /* (assumes port_num is valid) */
    pline = port + port_num; 
    /* Put the consultation call on hold, and make the original call active */
    if (gc_SwapHold(pline->original_crn, pline->consultation_crn, EV_ASYNC) == -1) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SwapHold() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                pline->ldev, 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_CompleteTransfer( )
• gc_BlindTransfer( )
• gc_SetUpTransfer( )

Click here to contact Telecom Support Resources