dx_stopch( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_stopch(chdev,mode)
Inputs:	int chdev	valid Dialogic channel device handle
	unsigned short mode	Reserved for future use
Returns:	0 if success
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
Category:	I/O
Mode:	asynchronous/synchronous

Description

The dx_stopch( ) function forces termination of currently active I/O functions on a channel. It forces a channel in the busy state to become idle. If the channel specified in chdev already is idle, dx_stopch( ) has no effect and will return a success.

Running this function asynchronously will initiate the dx_stopch( ) without affecting processes on other channels.

Running this function synchronously within a process does not block other processing. Other processes continue to be serviced.

When an I/O function terminates due to a dx_stopch( ) being issued on the channel, the termination reason returned by ATDX_TERMMSK( ) will be TM_USRSTOP. (If running the dx_dial( ) function with Call Analysis, you can call ATDX_CPTERM( ) to determine the reason for Call Analysis termination. This will return CR_STOPD if Call Analysis stopped due to a dx_stopch( ).)

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( ).
mode	Set to EV_ASYNC. The stop will be issued, but the driver does not "sleep" and wait for the channel to become idle before dx_stopch( ) returns.

Cautions

1. dx_stopch( ) will have no effect on a channel that has either of the following functions issued:
   • dx_dial( ) without Call Analysis enabled
   • dx_wink( )

The functions will continue to run normally, dx_stopch( ) will return a success. For dx_dial( ), the digits specified in the dialstrp parameter will still be dialed.

2. If dx_stopch( ) is called on a channel dialing with Call Analysis enabled, the Call Analysis process will stop but dialing will be completed. Any Call Analysis information collected prior to the stop will be returned by Extended Attribute functions.
3. If an I/O function terminates (due to another reason) before dx_stopch( ) is issued, the reason for termination will not indicate dx_stopch( ) was called.
4. When calling dx_stopch( ) from a signal handler, mode must be set to EV_ASYNC.

Example

#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int chdev, srlmode;  
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
   
   /* Open the channel using dx_open( ). Get channel device descriptor in  
    * chdev.  
    */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
      /* process error */  
   }  
   
   /* continue processing */  
               .  
               .  
   /* Force the channel idle.  The I/O function that the channel is  
    * executing will be terminated, and control passed to the handler  
    * function previously enabled, using sr_enbhdlr(), for the  
    * termination event corresponding to that I/O function.  
    * In the asynchronous mode, dx_stopch() returns immediately,  
    * without waiting for the channel to go idle.  
    */  
   if ( dx_stopch(chdev, EV_ASYNC) == -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

See Also

Related I/O functions:

• dx_dial( )
• dx_getdig( )
• dx_play( )
• dx_playf( )
• dx_playtone( )
• dx_rec( )
• dx_recf( )
• dx_wink( )

Retrieving I/O termination reason due to dx_stopch( ):

• ATDX_TERMMSK( )
• ATDX_CPTERM( ) - dx_dial( ) with Call Analysis

Click here to contact Dialogic Customer Engineering