dx_sethook( )

Description | Cautions | Example 1: | Example 2: | Errors | See Also

Description

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( ).
hookstate	forces the hookstate of the specified channel to on-hook or off-hook. The following values can be specified:
	DX_ONHOOK:		set to on-hook state
	DX_OFFHOOK:		set to off-hook state
mode	specifies whether to run dx_sethook( ) asynchronously or synchronously. Specify one of the following:
	EV_ASYNC:	Run dx_sethook( ) asynchronously.
	EV_SYNC:	Run dx_sethook( ) synchronously (default).

The dx_sethook( ) function provides control of the hookswitch status of the specified channel. A hookswitch state may be either on-hook or off-hook.

NOTES:

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

2. Calling dx_sethook( ) with no parameters clears the loop current and silence history from the channel's buffers.

Asynchronous Operation

To run dx_sethook( ) asynchronously, set the mode field to EV_ASYNC. The function will return 0 to indicate it has initiated successfully, and will generate a termination event to indicate completion. Use the SRL Event Management functions to handle the termination event.

If running asynchronously, termination is indicated by a TDX_SETHOOK event. The cst_event field in the data structure will specify one of the following:

• DX_ONHOOK if the hookstate has been set to on-hook
• DX_OFFHOOK if the hookstate has been set to off-hook

Use the Event Management function sr_getevtdatap( ) to return a pointer to the DX_CST structure.

ATDX_HOOKST( ) will also return the type of hookstate event.

Synchronous Operation

By default, this function runs synchronously.

If running synchronously (default) dx_sethook( ) will return 0 when complete.

Cautions

None.

Example 1: Using dx_sethook( ) in synchronous mode

#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
main()  
{  
   int chdev;  
   /* open a channel with chdev as descriptor */  
   if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {  
     /* process error */  
   }  
   
   /* put the channel on-hook */  
   if (dx_sethook(chdev,DX_ONHOOK,EV_SYNC) == -1) {  
     /* error setting hook state */  
   }  
   .  
   .  
   /* take the channel off-hook */  
   if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {  
     /* error setting hook state */  
   }  
   .  
   .  
}

Example 2: Using dx_sethook( ) in asynchronous mode

#include <stdio.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <windows.h>  
   
#define MAXCHAN 24  
   
int sethook_hdlr();  
   
main()  
{  
   int i, chdev[MAXCHAN];  
   char *chnamep;  
   int srlmode;  
   
   /* Set SRL to run in polled mode. */  
   srlmode = SR_POLLMODE;  
   if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) {  
      /* process error */  
   }  
   
   for (i=0; i<MAXCHAN; i++) {  
   
      /* Set chnamep to the channel name - e.g, dxxxB1C1, dxxxB1C2,... */  
   
      /* open a channel with chdev[i] as descriptor */  
      if ((chdev[i] = dx_open(chnamep,NULL)) == -1) {  
         /* process error */  
      }  
   
      /* Using sr_enbhdlr(), set up handler function to handle sethook  
       * events on this channel.  
       */  
      if (sr_enbhdlr(chdev[i], TDX_SETHOOK, sethook_hdlr) == -1) {  
         /* process error */  
      }  
   
      /* put the channel on-hook */  
      if (dx_sethook(chdev[i],DX_ONHOOK,EV_ASYNC) == -1) {  
         /* error setting hook state */  
      }  
   }  
   
   /* Use sr_waitevt() to wait for the completion of dx_sethook().  
    * On receiving the completion event, TDX_SETHOOK, control is transferred  
    * to the handler function previously established using sr_enbhdlr().  
    */  
   .  
   .  
}  
   
int sethook_hdlr()  
{  
   DX_CST *cstp;  
   
   /* sr_getevtdatap() points to the call status transition  
    * event structure, which contains the hook state of the  
    * device.  
    */  
   cstp = (DX_CST *)sr_getevtdatap();  
   
   switch (cstp->cst_event) {  
   case DX_ONHOOK:  
      printf("Channel %s is ON hook\n", ATDX_NAMEP(sr_getevtdev()));  
      break;  
   case DX_OFFHOOK:  
      printf("Channel %s is OFF hook\n", ATDX_NAMEP(sr_getevtdev()));  
      break;  
   default:  
      /* process error */  
      break;  
   }  
   
   /* Kick off next function in the state machine model. */  
   .  
   .  
   
   return 0;  
}

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

• DX_CST structure
• sr_getevtdatap( )
• ATDX_HOOKST( )
• DV_TPT

Click here to contact Dialogic Customer Engineering