gc_WaitCall( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_WaitCall(linedev, crnp, waitcallp, timeout, mode)
Inputs:	LINEDEV linedev	Global Call line device handle
	CRN *crnp	pointer to CRN
	GC_WAITCALL_BLK *waitcallp	reserved for future use
	int timeout	time-out
	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_WaitCall( ) function indicates that the application is ready to receive inbound calls. The gc_WaitCall( ) function unblocks the time slot (if the technology and the line conditions permit unblocking the line) and enables notification of inbound calls.

In the asynchronous mode, after the gc_WaitCall( ) function was successfully called, the gc_ReleaseCallEx( ) function will not block the incoming notification. Therefore, it is only necessary to call a gc_WaitCall( ) function once. However, the gc_WaitCall( ) function must be called again after issuing a gc_Close( ) or a gc_ResetLineDev( ) function.

Also, the call reference parameter is not used in this function call. The application must retrieve the CRN from the METAEVENT structure returned when the call notification event (GCEV_OFFERED) arrives.

In the synchronous mode, notification of the next inbound call is blocked until the next gc_WaitCall( ) function is issued. If an inbound call arrives between the gc_ReleaseCallEx( ) and gc_WaitCall( ) functions, the call will be pending until the gc_WaitCall( ) function is reissued, at which point the application will be notified.

When called in the synchronous mode, the crnp parameter is assigned when the gc_WaitCall( ) function terminates. If the gc_WaitCall( ) function fails, the call (and thus the CRN) will be released automatically.

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 CRN. The crnp parameter must be of a global and non-temporary type. The crnp parameter is used only in the synchronous mode. For the asynchronous mode, this parameter must be set to NULL. When the GCEV_OFFERED event is received, the CRN can be retrieved.
waitcallp	not used. Set to zero.
timeout	(used only in synchronous mode; ignored in asynchronous mode) specifies the interval (in seconds) to wait for the call. In this case, when the time-out expires, the function will return -1 and the call will remain in the Null state. The error value is set to EGC_TIMEOUT. If the time-out is 0 and no inbound call is pending, the function returns -1 with an EGC_TIMEOUT error value.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

None

Note: In asynchronous mode, an unsolicited GCEV_OFFERED event will be received when a call is received and the call state transitions to the Offered state.

Cautions

• The application should always call a gc_ReleaseCallEx( ) function to release the CRN after the termination of a connection. Failure to do so may cause memory problems due to memory being allocated and not being released.
• In the asynchronous mode, the CRN will not be available until an inbound call has arrived (that is, until the GCEV_OFFERED event is received).
• For both the asynchronous and the synchronous modes, any active gc_WaitCall( ) function can be stopped by using the gc_ResetLineDev( ) function. When the gc_ResetLineDev( ) function completes, the application must reissue the gc_WaitCall( ) function to be able to receive incoming calls.
• If this function is called synchronously without waiting forever, calls may be lost unless the next gc_WaitCall( ) is called in less than a protocol-dependent time. It is highly recommended that either gc_WaitCall( ) be called asynchronously or if called synchronously, wait forever (that is, use a timeout value of INT_MAX).
• If the gc_WaitCall( ) function is already active and is called again, the resulting behavior depends on the call control library being used. For some call control libraries, an error will be returned, while other call control libraries will accept multiple gc_WaitCall( ) calls.

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> 
#define MAXCHAN   30            /* max. number of channels in system */
/*
 * Data structure which stores all information for each line
 */
struct linebag {
    LINEDEV  ldev;               /* 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. Open line devices for each time slot on dtiB1.
 *    2. Each Line Device ID is stored in linebag structure, 'port'.
 */
int wait_call(int port_num)
{
    GC_INFO        gc_error_info;    /* GlobalCall error information data */ 
    /* Find info for this time slot, specified by 'port_num' */
    pline = port + port_num; 
    /*
     * Wait for a call, with 0 timeout.
     */
    if (pline->state == GCST_NULL) {
        if (gc_WaitCall(pline->ldev, NULL, NULL, 0, EV_ASYNC) != GC_SUCCESS) {
            /* process error return as shown */
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_WaitCall() 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);
        } 
    }
    /*
     * GCEV_OFFERED event will indicate incoming call has arrived.
     */
    return (0);
} 

See Also

• gc_DropCall( )
• gc_MakeCall( )
• gc_ReleaseCallEx( )
• gc_ResetLineDev( )

Click here to contact Telecom Support Resources