gc_DropCall( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_DropCall(crn, cause, mode)
Inputs:	CRN crn	call reference number
	int cause	reason to drop call
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	basic
Mode:	asynchronous or synchronous
Platform and Technology:	All† †See the Global Call Technology User's Guides for additional information.

Description

The gc_DropCall( ) function disconnects a call specified by the call reference number (CRN) and enables inbound calls to be detected internally to Global Call on the line device.

The application will not be notified of any pending call until after the gc_ReleaseCallEx( ) function is issued. However, for some technologies, a GCEV_OFFERED event may be generated after gc_DropCall( ) is issued and before the call is released. The application must allow for this possibility and be able to handle the event.

The gc_DropCall( ) function changes the current active call state (Accepted, Answered, Alerting, Connected, Detected, or Offered) to the Idle state.

See also the appropriate Global Call Technology User's Guide for technology-specific information.

Parameter	Description
crn	call reference number
cause	indicates reason for disconnecting or rejecting a call. See Table 4 for a list of possible causes, and see the appropriate Global Call Technology User's Guide for valid and/or additional causes for your specific technology.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Table 4. gc_DropCall( ) Causes

Cause†	Description
GC_CALL_REJECTED	Call was rejected
GC_CHANNEL_UNACCEPTABLE	Channel is not acceptable
GC_DEST_OUT_OF_ORDER	Destination is out of order
GC_NETWORK_CONGESTION	Call dropped due to traffic volume on network
GC_NORMAL_CLEARING	Call dropped under normal conditions
GC_REQ_CHANNEL_NOT_AVAIL	Requested channel is not available
GC_SEND_SIT	Special Information Tone
GC_UNASSIGNED_NUMBER	Requested number is unknown
GC_USER_BUSY	End user is busy
† See the appropriate Global Call Technology User's Guide for valid and/or additional causes for your specific technology.

Termination Events

GCEV_DROPCALL

indicates that the gc_DropCall( ) function was successful, that is, the call was dropped.

GCEV_TASKFAIL

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

Note: A GCEV_DISCONNECTED event may be reported to the application as an unsolicited event after the gc_DropCall( ) function is issued.

Cautions

• The gc_DropCall( ) function does not release a CRN. Therefore, the gc_ReleaseCallEx( ) function must always be used after a gc_DropCall( ) function. Failure to do so will cause a blocking condition and may cause memory problems due to memory being allocated and not being released.
• You must use the dx_stopch( ) function to terminate any application-initiated voice functions, such as dx_play( ) or dx_record( ), before calling gc_DropCall( ).
• Not all E-1 CAS protocols support a forced release of the line, that is, issuing a gc_DropCall( ) function after a gc_AcceptCall( ) function, from the Accepted state. If a forced release is attempted, the function will fail and an error will be returned. To recover, the application should issue a gc_AnswerCall( ) function followed by gc_DropCall( ) and gc_ReleaseCallEx( ) functions. When using the ICAPI call control library, see the Global Call Country Dependent Parameters (CDP) Reference for protocol specific limitations. However, any time a GCEV_DISCONNECTED event is received in the Accepted state, the gc_DropCall( ) function can be issued.
• Different technologies and protocols support some or all of the cause values defined above; see the appropriate Global Call Technology User's Guide for valid causes for your specific technology.

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> 
/*
 * Assume the following has been done:
 *    1. Opened line devices for each time slot on DTIB1.
 *    2. Wait for a call using gc_WaitCall()
 *    3. The application has chosen to terminate the call
 *                   OR
 *       the unsolicited event GCEV_DISCONNECTED has arrived
 * Note: A call may be dropped from any state other than Idle or Null
 */ 
int drop_call(CRN crn)
{
    GC_INFO        gc_error_info;    /* GlobalCall error information data */ 
    if (gc_DropCall(crn, GC_NORMAL_CLEARING, EV_ASYNC) != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_DropCall() 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);
    } 
    /*
     * gc_DropCall() is terminated by the GCEV_DROPCALL event.
     * Application must then release the call using gc_ReleaseCallEx().
     */
    return (0);
} 

See Also

• gc_MakeCall( )
• gc_ReleaseCallEx( )
• gc_WaitCall( )

Click here to contact Telecom Support Resources