dx_wtring( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_wtring(chdev,nrings,hstate,timeout)
Inputs:	int chdev	valid Dialogic channel device handle
	int nrings	number of rings to wait for
	int hstate	hook state to set after rings are detected
	int timeout	in seconds
Returns:	0 if successful
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
Category:	Configuration

Description

The dx_wtring( ) function waits for a specified number of rings and sets the channel to on-hook or off-hook after the rings are detected. Using dx_wtring( ) is equivalent to using dx_setevtmsk( ), dx_getevt( ), and dx_sethook( ) to wait for a ring. When dx_wtring( ) is called, the specified channel's event is set to DM_RINGS.

NOTE:

Do not call this function for a digital T-1 SCbus configuration that includes a D/240SC, D/240SC-T1, or DTI/241SC board. Transparent signaling for SCbus digital interface devices is not supported.

The function parameters are defined as follows:

Parameter	Description
chdev	specifies the valid channel device handle obtained when the channel was opened using dx_open( ).
nrings	specifies the number of rings to wait for before setting the hook state.
hstate	sets the hookstate of the channel after the number of rings specified in nrings are detected. hstate can have either of the following values:
	DX_ONHOOK:	channel remains on-hook when nrings number of rings are detected
	DX_OFFHOOK:	channel goes off-hook when nrings number of rings are detected
timeout	specifies the maximum length of time in tenths of seconds to wait for a ring. timeout can have one of the following values:
	# of seconds:	maximum length of time to wait for a ring.
	-1:	dx_wtring( ) waits forever and never times out.
	0:	dx_wtring( ) returns -1 immediately if a ring event does not already exist.

Cautions

1. dx_wtring( ) changes the event enabled on the channel to DM_RINGS. For example, "process A" issues dx_setevtmsk( ) to enable detection of another type of event, e.g., DM_SILON, on channel one. If "process B" issues dx_wtring( ) on channel one, then process A will now be waiting for a DM_RINGS event since process B has reset the channel event to DM_RINGS with dx_wtring( ).
2. A channel can detect rings immediately after going on hook. Rings may be detected during the time interval between dx_sethook( ) and dx_wtring( ). Rings are counted as soon as they are detected.

   NOTE:

   If the number of rings detected before dx_wtring( ) returns is equal to or greater than nrings, dx_wtring( ) will not terminate. This may cause the application to miss calls that are already coming in when the application is first started.

3. Do not use the Windows sigset( ) system call with SIGALRM while waiting for rings.

Example

#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int chdev;   /* channel descriptor */  
   .  
   .  
   /* Open Channel */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
      /* process error */  
   }  
   
   /* Wait for two rings on this channel - no timeout */  
   if (dx_wtring(chdev,2,DX_OFFHOOK,-1) == -1) {  
      /* process error */  
   }  
   .  
   .  
}

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_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value
EDX_TIMEOUT	Timeout limit is reached

See Also

• dx_setevtmsk( )
• dx_getevt( )
• dx_sethook( )
• DX_EBLK

Click here to contact Dialogic Customer Engineering