dx_wtcallid( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_wtcallid (chdev, nrings, timeout, bufferp)
Inputs:	int chdev	Channel device handle
	int nrings	Number of rings to wait
	short timeout	Time to wait for rings (in seconds)
	unsigned char *bufferp	Pointer to where to return the Caller ID information
Returns:	0 success
	-1 error return code
Includes:	srllib.h
	dxxxlib.h
Category:	Caller ID
Mode:	synchronous

Description

The dx_wtcallid( ) function waits for rings and reports Caller ID, if available. Using this function is equivalent to using the voice functions dx_setevtmsk( ) and dx_getevt( ), and the Caller ID function dx_gtcallid( ) to return the caller's Directory Number (DN).

This function has the following parameters:

Parameter	Description
chdev:	Channel device handle.
Nrings:	Number of rings to wait before answering. Valid values: -_ 1-(Note: Minimum 2 for CLASS and ACLIP)
timeout:	Maximum length of time to wait for a ring: Valid values (0.1-second units): -_ 0 --1-waits forever; never times out If timeout is set to zero and a ring event does not already exist, the function returns immediately.
bufferp:	Pointer to where to return calling line Directory Number (DN).

On successful completion, a NULL terminated string containing the caller's phone number (DN) is placed in the buffer.

NOTE:

Non-numeric characters (punctuation, space, dash) may be included in the number string. The string may not be suitable for dialing without modification.

The dx_wtcallid( ) function is a Caller ID Convenience function provided to allow applications to wait for a specified number of rings (as set for the ring event) and returns the calling station's Directory Number (DN). The dx_wtcallid( ) function combines the functionality of the following:

• dx_setevtmsk( ) voice function
• dx_getevt( ) voice function
• dx_gtcallid( ) Caller ID function

Non-numeric characters (punctuation, space, dash) may be included in the number string. The string may not be suitable for dialing without modification.

Caller ID information is available for the call from the moment the ring event is generated (if the ring event is set to occur on or after the second ring (CLASS, ACLIP), or set to occur on or after the first ring (CLIP, JCLIP) until either of the following occurs:

• If the call is answered (the application channel goes off-hook), the Caller ID information is available to the application until the call is disconnected (the application channel goes on-hook).
• If the call is not answered (the application channel remains on-hook), the Caller ID information is available to the application until rings are no longer received from the Central Office (signaled by ring off event, if enabled).

Cautions

dx_wtcallid( ) changes the event enabled on the channel to DM_RINGS.

Example

/*$ dx_wtcallid( ) example $*/



#include <srllib.h>

#include <dxxxlib.h>



unsigned char buffer[21];      /* char buffer */

int rc;                        /* value returned by function */

int chdev;                     /* channel descriptor */

unsigned short parmval;        /* Parameter value */



/* open channel */

if ((chdev = dx_open("dxxxB1C1", NULL) == -1) {

   /* process error *.

}



/* Enable Caller ID */

parmval = DX_CALLIDENABLE;

if (dx_setparm(chdev, DXCH_CALLID, (void *)&parmval) == -1) {

   /* process error */

}



/* sit and wait for two rings on this channel - no timeout */

if (dx_wtcallid(chdev,2,-1,buffer) == -1) {

   printf("Error waiting for ring (with Caller ID): 0x%x\n", 

   ATDV_LASTERR(chdev));

   /* process error */

}

printf("Caller ID = %s\n", buffer);

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons:

EDX_BADPARM	Invalid parameter
EDX_BUSY	Channel is busy
EDX_CLIDBLK	Caller ID is blocked or private or withheld (other information may be available using dx_gtextcallid( ))
EDX_CLIDINFO	Caller ID information not sent, sub-message(s) requested not available or Caller ID information invalid
EDX_CLIDOOA	Caller ID is out of area (other information may be available using dx_gtextcallid( ))
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value
EDX_TIMEOUT	Time out limit is reached

See Also

• dx_gtcallid( )
• dx_setevtmsk( )
• dx_getevt( )

Click here to contact Dialogic Customer Engineering