gc_SetUpTransfer( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetUpTransfer(calltohold, consultationcall, mode)
Inputs:	CRN calltohold	call reference number for call to be transferred
	CRN *consultationcall	pointer to call reference number returned for the consultation 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)† †See the Global Call Technology User's Guide for additional information.

Description

The gc_SetUpTransfer( ) function initiates a supervised call transfer and allocates a call reference number (CRN) for the consultation call. A supervised transfer means that the party transferring the call consults with the party receiving the transferred call, before the transfer is completed.

The CRN allocated by the gc_SetUpTransfer( ) function is known as the consultation CRN. The consultation CRN is the same as the CRN returned by the gc_MakeCall( ) function when the consultation call is established. The consultation CRN is used by the gc_CompleteTransfer( ) function to complete the transfer request. The gc_SwapHold( ) function also uses the consultation CRN when switching between the call on hold (the call pending transfer) and the active call.

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

Parameter	Description
calltohold	call reference number for the existing call to be transferred
consultationcall	points to the memory location where the call reference number for the consultation call is to be stored
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_SETUPTRANSFER

indicates that the function was successful, that is, the supervised call transfer was initiated.

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_SetUpTransfer( ) function can be used only when an active call is in the Connected call 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.
 */
int call_setuptransfer(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 original call on hold and allocate a CRN for the consultation call */ 
    if (gc_SetupTransfer(pline->original_crn, &pline->consultation_crn, EV_ASYNC) == -1)
    {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetupTransfer() 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); 
    }
    /* The gc_MakeCall() function can be called here to establish the consultation call. */
    /* The consultation_crn can be re-used/over-written here since the CRN will be the same. */
    return (0);
} 

See Also

• gc_CompleteTransfer( )
• gc_BlindTransfer( )
• gc_SwapHold( )

Click here to contact Telecom Support Resources