Global Call API Library Reference: gc

gc_MakeCall( )

Termination Events | Cautions | Errors | Example | See Also

Name: int gc_MakeCall(linedev, crnp, numberstr, makecallp, timeout, mode)

Inputs:
LINEDEV linedev

line device

CRN *crnp

pointer to returned call reference number

char *numberstr

destination phone number

GC_MAKECALL_BLK *makecallp

pointer to outbound call info

int timeout

time-out value

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_MakeCall( ) function makes an outgoing call on the specified line device. When this function is issued asynchronously, a call reference number (CRN) will be assigned and returned immediately if the function is successful. All subsequent communications between the application and the Global Call library regarding that call will use the CRN as a reference. If this function is issued synchronously, the CRN will be available at the successful completion of the function.

The gc_MakeCall( ) function changes the call state from the Null state or, when performing a supervised transfer, the Dialtone state to the Dialing state. If the call is answered, the call state changes from the Dialing state to the Connected state. If the other end is not ready to receive the call, the call state changes from Dialing to Alerting. If the gc_MakeCall( ) function fails, the resulting call state depends on the point in the calling process where the failure occurred and the call control library being used.

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

Parameter

Description

linedev Global Call line device handle

crnp points to the memory location where the call reference number is to be stored

numberstr called party's telephone number (must be terminated with "\0"). Maximum length is 32 digits.

makecallp points to the GC_MAKECALL_BLK structure; see GC_MAKECALL_BLK for details. The GC_MAKECALL_BLK structure lists the parameters used to make an outbound call. Assigning a NULL to the makecallp parameter indicates that the default values should be used for the call.

timeout time interval (in seconds) during which the call must be established, or the function will return with a time-out error. This parameter is ignored when set to 0. Not all call control libraries support this argument in asynchronous mode. (For DM3 boards, timeout is supported in both the synchronous and asynchronous modes.) See the appropriate Global Call Technology User's Guide for technology-specific information.

mode set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

In the asynchronous mode, if the function is successfully initiated but connection is not achieved (no GCEV_CONNECTED event returned), then the application must issue gc_DropCall( ) and gc_ReleaseCallEx( ) functions to terminate the call completely.

In the synchronous mode, if the *crnp is zero, the call state is Null. A Null state indicates that the call was fully terminated and that another gc_MakeCall( ) function can be issued. For non-zero *crnp values, the application must issue gc_DropCall( ) and gc_ReleaseCallEx( ) functions to terminate the call completely before issuing another gc_MakeCall( ) function.

The GCEV_ALERTING event (enabled by default) notifies the application that the call has reached its destination but is not yet connected to the called party. When this event is received, the call state changes to Alerting. In the Alerting state, the reception of a GCEV_CONNECTED event (or, if in synchronous mode, the successful completion of the function) causes a transition to the Connected state thus indicating a complete call connection.

The GCEV_CALLSTATUS event informs the application that a time-out or a no answer (call control library dependent) condition occurred. This event does not cause any state change. Not all call control libraries generate this event (for example, the ISDN library).

If glare handling is not specified in the protocol, the inbound call prevails when glare occurs.

Table 9 lists error conditions, associated event/return values, and the result/error value returned. For all errors, the following apply:

Asynchronous: When an error condition is encountered, an event value such as GCEV_TASKFAIL, GCEV_CALLSTATUS, or GCEV_DISCONNECTED is returned. Issue a gc_ResultValue( ) function to retrieve the reason or result code for the event and then issue a gc_ResultMsg( ) function to retrieve the ASCII message describing the error condition. When an error condition occurs in asynchronous mode, you must issue the gc_DropCall( ) and gc_ReleaseCallEx( ) functions before you can initiate your next call.
Synchronous: When an error condition is encountered, a value that is <0 is returned. Issue a gc_ErrorValue( ) function to retrieve the error code and then issue a gc_ResultMsg( ) function to retrieve the ASCII message describing the error condition.

When an error condition occurs in synchronous mode, if the crn returned is:

0, then the call state is Null; you may initiate your next call or call related operation.
non-0, then you must issue the gc_DropCall( ) and gc_ReleaseCallEx( ) functions before you can initiate your next call or call related operation.

In asynchronous mode, when the function fails to start, <0 is returned. In this case, no CRN was assigned to the call and you should not do a drop and release call.

Table 9. Call Conditions and Results

Condition

Event/Return Value

Result/Error Value

Call answered at remote end

Async: GCEV_CONNECTED

Sync: 0

None - normal completion of function; line is connected and called party answered

Glare detected

Async: GCEV_TASKFAIL or GCEV_DISCONNECTED

Async: GCRV_GLARE or GCRV_PROTOCOL result value

Sync: <0

Sync: EGC_GLARE, EGC_INVSTATE, or EGC_PROTOCOL error depending on the call control library used

Error, other than glare, occurs prior to dialing

Async: GCEV_TASKFAIL

Sync: <0

Varies depending on the reason for the failure

Error occurs during dialing

Async: a call control library related error or GCEV_DISCONNECTED

Async: GCRV_TIMEOUT or GCRV_PROTOCOL result value

Sync: <0

Sync: EGC_TIMEOUT or EGC_PROTOCOL error depending on the call control library used

Busy line

Async: GCEV_DISCONNECTED

Async: GCRV_BUSY result value

Sync: <0

Sync: EGC_BUSY error

Ring, no answer

Async: GCEV_CALLSTATUS or GCEV_DISCONNECTED.
Not all call control libraries generate the GCEV_CALLSTATUS event (for example, the ISDN library).

Async: GCRV_NOANSWER or GCRV_TIMEOUT result value

Sync: <0

Sync: EGC_NOANSWER or EGC_TIMEOUT error depending on the call control library used

Other errors

Async: reflects the error encountered and the call control library used

Sync: <0

Varies depending on the reason for the failure and the call control library used

Termination Events

GCEV_CALLSTATUS

indicates that a time-out or no answer condition was returned while the gc_MakeCall( ) function was active.

GCEV_CONNECTED

indicates that the gc_MakeCall( ) function was successful, that is, the call resulted in a connection.

GCEV_DISCONNECTED

indicates that a request or message was rejected or that it timed out, halting further processing of the call.

GCEV_TASKFAIL

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

Note: See Table 9 for other events that may be received by the application.

Cautions

In both asynchronous and synchronous modes, after a time-out or a no answer condition is reported and before the gc_DropCall( ) function has successfully completed, a GCEV_CONNECTED event may arrive. Ignore this event since the call cannot be salvaged.
If the timeout parameter is set to a value larger than a protocol time-out value, a protocol time-out may occur first, which will cause the gc_MakeCall( ) function to fail. For ANAPI and ICAPI protocols, the protocol time-out is configured in the CDP file.

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
#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h>
#include <gcisdn.h> 
#define MAXCHAN   30                 /* max. number of channels in system */ 
/*
 * Data structure which stores all information for each line
 */
struct linebag {
    LINEDEV  ldev;                    /* GlobalCall line device handle */
    CRN      crn;                     /* GlobalCall API call handle */
    int      state;                   /* state of first layer state machine */
} port[MAXCHAN+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"
 */
int make_call(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; 
    /*
     * Make a call to the number 993-3000.
     */
    if (gc_MakeCall(pline->ldev, &pline->crn, "9933000", NULL, 0, EV_SYNC) == GC_SUCCESS) {
        /* Call successfully connected; continue processing */
    }
    else {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_MakeCall() on linedev: 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);
    } 
    /*
     * Application may now wait for an event to indicate call
     * completion.
     */
    return (0);
} 
See Also

gc_DropCall( )
gc_GetCallInfo( )
gc_LoadDxParm( )
gc_ReleaseCallEx( )

Name:	int gc_MakeCall(linedev, crnp, numberstr, makecallp, timeout, mode)
Inputs:	LINEDEV linedev	line device
	CRN *crnp	pointer to returned call reference number
	char *numberstr	destination phone number
	GC_MAKECALL_BLK *makecallp	pointer to outbound call info
	int timeout	time-out value
	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.

Parameter	Description
linedev	Global Call line device handle
crnp	points to the memory location where the call reference number is to be stored
numberstr	called party's telephone number (must be terminated with "\0"). Maximum length is 32 digits.
makecallp	points to the GC_MAKECALL_BLK structure; see GC_MAKECALL_BLK for details. The GC_MAKECALL_BLK structure lists the parameters used to make an outbound call. Assigning a NULL to the makecallp parameter indicates that the default values should be used for the call.
timeout	time interval (in seconds) during which the call must be established, or the function will return with a time-out error. This parameter is ignored when set to 0. Not all call control libraries support this argument in asynchronous mode. (For DM3 boards, timeout is supported in both the synchronous and asynchronous modes.) See the appropriate Global Call Technology User's Guide for technology-specific information.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

**Table 9. Call Conditions and Results**
Condition	Event/Return Value	Result/Error Value
Call answered at remote end	Async: GCEV_CONNECTED Sync: 0	None - normal completion of function; line is connected and called party answered
Glare detected	Async: GCEV_TASKFAIL or GCEV_DISCONNECTED	Async: GCRV_GLARE or GCRV_PROTOCOL result value
Sync: <0	Sync: EGC_GLARE, EGC_INVSTATE, or EGC_PROTOCOL error depending on the call control library used
Error, other than glare, occurs prior to dialing	Async: GCEV_TASKFAIL Sync: <0	Varies depending on the reason for the failure
Error occurs during dialing	Async: a call control library related error or GCEV_DISCONNECTED	Async: GCRV_TIMEOUT or GCRV_PROTOCOL result value
Sync: <0	Sync: EGC_TIMEOUT or EGC_PROTOCOL error depending on the call control library used
Busy line	Async: GCEV_DISCONNECTED	Async: GCRV_BUSY result value
Sync: <0	Sync: EGC_BUSY error
Ring, no answer	Async: GCEV_CALLSTATUS or GCEV_DISCONNECTED. Not all call control libraries generate the GCEV_CALLSTATUS event (for example, the ISDN library).	Async: GCRV_NOANSWER or GCRV_TIMEOUT result value
Sync: <0	Sync: EGC_NOANSWER or EGC_TIMEOUT error depending on the call control library used
Other errors	Async: reflects the error encountered and the call control library used Sync: <0	Varies depending on the reason for the failure and the call control library used

Click here to contact Telecom Support Resources