Filter
Top Products
444 Voice API for Windows Operating Systems Library Reference — November 2003
dx_wtring( ) — wait for a specified number of rings
!
!!
! Cautions
• 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 (such as 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( ).
• 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.
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.
• Do not use the sigset( ) system call with SIGALRM while waiting for rings.
!
!!
! Errors
If the function returns -1, use the Standard Runtime Library (SRL) Standard Attribute function
ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive
error message. One of the following error codes may be returned:
EDX_BADPARM
Invalid parameter
EDX_SYSTEM
Error from operating system; use dx_fileerrno( ) to obtain error value
EDX_TIMEOUT
Timeout limit is reached
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was
opened using dx_open( ) function
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. Valid values:
• DX_OFFHOOK – channel goes off-hook when nrings number of
rings are detected
• DX_ONHOOK – channel remains on-hook when nrings number of
rings are detected
timeout specifies the maximum length of time in tenths of seconds to wait for a
ring. Valid values:
• number 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