cc_WaitCall( )

Description | Termination Events | Cautions | Example | Errors | See Also

Name:	int cc_WaitCall(linedev, crnptr, waitcall_blkp, timeout, mode)
Inputs:	LINEDEV linedev	device handle
	CRN *crnptr	pointer to call reference number
	WAITCALL_BLK *waitcall_blkp	for future use
	int timeout	amount of time to wait for calls
	unsigned long mode	synchronous or asynchronous
Returns:	0 on success < 0 on failure
Includes:	cclib.h
Category:	Call control
Mode:	synchronous or asynchronous
Technology:	BRI/2; BRI/SC; PRI (all protocols)

Description

The cc_WaitCall( ) function sets up conditions for processing an incoming call. This function also sets up the buffer location where the incoming call's information is stored and unblocks the time slot to allow for notification of other incoming calls

Parameter	Description
linedev:	The line device handle or, for the call waiting feature, the board device handle (BRI and Windows only). When a board device is specified, all subsequent CCEV_OFFERED events will be for that board device.
crnptr:	Pointer to where the call reference number will be stored. (The crnptr parameter is used in synchronous mode only.)
waitcall_blkp:	For future use. Set to NULL.
timeout:	The time, in seconds, that the application will wait for the call. If the timeout is 0, a value < 0 will return unless the incoming call is pending. The timeout parameter is used in synchronous mode only.
mode:	Specifies asynchronous (EV_ASYNC) or synchronous (EV_SYNC) mode.

When and how the cc_WaitCall( ) function is issued depends on whether the function is called in synchronous or asynchronous mode.

In synchronous mode, the cc_WaitCall( ) function cannot be stopped until timeout expires or until cc_Restart( ) is called from another process. The parameter crnptr will be assigned when cc_WaitCall( ) is terminated by the event CCEV_OFFERED. If the cc_WaitCall( ) function fails, the call (and the call reference number) will be released automatically.

When cc_WaitCall( ) is called in asynchronous mode, cc_ReleaseCall( ) will not block the incoming call notification. The application needs to issue cc_WaitCall( ) only once per line device. However, if cc_Restart( ) is called, the application must reissue cc_WaitCall( ).

The call reference parameter (crnptr) is not used in the cc_WaitCall( ) function in asynchronous mode. The application must retrieve the call reference number by using the cc_GetCRN( ) function when the call notification event, CCEV_OFFERED, is received.

Termination Events

• CCEV_OFFERED - indicates that the setup message has been received by the application.
• CCEV_TASKFAIL - indicates that a request/message was rejected by the firmware. The application can use cc_Restart( ) after the event is received to reset the channel.

Cautions

• Call Waiting Feature (BRI and Windows only):
  • The cc_WaitCall( ) function must be used in asynchronous mode to support the call waiting feature.
  • A board device must be specified in linedev to allow the application to receive incoming waiting calls.
  • To receive incoming waiting calls, applications using the NTT protocol must use the cc_SetInfoElem( ) function to override the default Channel ID IE content. This ensures that the application complies with the NTT protocol specification requiring the first reply to the SETUP message to specify the B channel on which the call will proceed.
• The application should always release the call reference number after the termination of a connection by calling cc_ReleaseCall( ). Failure to do so may cause memory allocation errors.
• In asynchronous mode, the CRN will not be available until an incoming call has arrived. In synchronous mode, the CRN will not be available until the cc_WaitCall( ) function completes successfully.
• The structures crnptr and waitcall_blkp should be globally allocated.

Example

#include <windows.h>   /* For Windows applications only */  
#include <stdio.h>  
#include <errno.h>  
#include "srllib.h"  
#include "dtilib.h"  
#include "cclib.h"  
void main()  
{  
   LINEDEV   devhdl    = 0;  
   CRN       crn = 0;  
   char     *devname = "dtiB1T1";  
   if ( cc_Open( &devhdl, devname, 0 ) < 0 )   
   {  
      printf("Error opening device: errno = %d\n", errno);  
      exit(1);  
   }  
   printf("Waiting for call\n");  
   if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 )  
        procdevfail(devhdl);  
   if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 )  
        callfail(crn);  
        .  
        .  
        .  
        .  
        .  
   /* Drop the call */  
   if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 )  
        callfail(crn);  
   if ( cc_ReleaseCall(crn) < 0 )  
        callfail(crn);  
   if ( cc_Close( devhdl ) < 0 )   
      printf("Error closing device, errno = %d\n", errno);  
}  
int callfail(CRN crn)  
{                 
        LINEDEV ld;  
         cc_CRN2LineDev(crn,&ld);  
         procdevfail(ld);  
}  
int procdevfail(LINEDEV handle)  
{  
        int reason;  
        char *msg;  
        reason = cc_CauseValue(handle);  
        cc_ResultMsg(handle,reason,&msg);  
        printf("reason = %x - %s\n",reason,msg);  
}

Errors

If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.

Error codes from the cc_WaitCall( ) function include the following:

Error Code	Description
ERR_ISDN_LIB | E_ISBADPAR	Bad input parameter
ERR_ISDN_LIB | E_ISBADTS	Bad time slot
ERR_ISDN_LIB | E_ISBADIF	Bad interface number
ERR_ISDN_LIB | E_ISBADCRN	Bad call reference number
ERR_ISDN_LIB | E_ISNULLPTR	Null pointer error

See Also

• cc_DropCall( )
• cc_MakeCall( )
• cc_ReleaseCall( )

Click here to contact Dialogic Customer Engineering