(Page 1 of 1 in this chapter)

Chapter 6

Using Hardware-Specific Functions

6.1 Introduction
6.2 Using lineDevSpecific
6.2.1 Setting Parameters
6.3 Using lineSetMediaControl

6.1 Introduction

NMS TSP implements the following TAPI functions for performing extended operations on NMS telephony boards:

lineDevSpecific allows applications to modify telephony parameters used by the NMS TSP (Microsoft refers to this as hardware specific functionality). These parameters determine the behavior of such NMS board operations as:

These parameters can also be set with the NMS Configurator. However, changes made with lineDevSpecific affect specific TAPI lines. Changes set with the NMS Configurator affect all TAPI lines on the system.

lineSetMediaControl enables applications to control conditions under which play and record operations are terminated. There is no way to control this behavior with the NMS Configurator.

6.2 Using lineDevSpecific

Applications can use lineDevSpecific to modify telephony parameters specific to NMS hardware (these parameters are generally controlled by the CT Access Runtime environment). For information about default parameter settings for NMS hardware, refer to Appendix D.

The prototype for lineDevSpecific is as follows:

Prototype

LONG lineDevSpecific ( HLINE hLine,
DWORD dwAddressID,
HCALL hCall,
LPVOID *lpParams,
DWORD dwSize)

hLine A handle to a line device returned by lineOpen.

dwAddressID An address identifier on the given line device (this argument is ignored by the NMS TSP).

hCall Handle to a call (not used by the NMS TSP).

lpParams Pointer to a memory area used to hold the
NMSDEVSPECPARAM parameter block (defined in the header file nmstapi.h):

        typedef struct _NMSDEVSPECPARAM
          {
      /* Command to perform.           */ 
         DWORD         dwCommand;
      /* Arguments for dwcommand.              */
         PARAM_VALUE     paramValue; 
      } NMSDEVSPECPARAM;

dwSize The size, in bytes, of the parameter block area. For the NMS TSP, this is the size of the NMSDEVSPECPARAM structure.

Details

Parameters set with lineDevSpecific apply to only to the line associated with the specified line handle (hLine).

At present CMD_SET_PARAM_BY_NAME is the only command supported.

Note: lineDevSpecific can be used to change parameters only on systems using CT Access.

6.2.1 Setting Parameters

Applications can use lineDevSpecific to set specific NMS board environment parameters. When using lineDevSpecific, applications must specify the command CMD_SET_PARAM_BY_NAME in the NMSDEVSPECPARAM structure. Applications use CMD_SET_PARAM_BY_NAME to specify parameter values by name.

In addition, applications must fill in the PARAM_VALUE structure shown below: 

typedef struct _PARAM_VALUE
{
    DWORD     dwSize;    /* Size of this structure            */
    CHAR     szName[MAX_PARAM_NAME_LEN]; /* Parameter name                */
    DWORD     dwValue;    /* Memory area for value            */
    UINT     cValSize;    /* Size of value(<= sizeof(DWORD))            */

} PARAM_VALUE;
The following code fragment illustrates using lineDevSpecific to change the connectmask field in the ADI_PLACECALL_PARMS. This structure is used to define when a line is considered Connected in the call setup process.


/* Change the connectmask so that a call made on this line will */
/* transition to the connected state once the call is placed.   */
NMSDEVSPECPARAM devSpecParms;
devSpecParms.dwCommand = CMD_SET_PARAM_BY_NAME;
devSpecParms.paramValue.dwSize = sizeof( PARAM_VALUE );
sprintf( devSpecParms.paramValue.szName,"adi.placecall.connectmask" );
devSpecParms.paramValue.dwValue=(DWORD)0x8000; /*Connect Immediately*/
devSpecParms.paramValue.cValSize = sizeof( DWORD );

lineDevSpecific( 
  mhLine,     /* Line handle        */
  (DWORD)0,   /* Address ID        */
  (HCALL)0,   /* Call handle        */
  &devSpecParms,
  sizeof( NMSDEVSPECPARAM )
);

6.3 Using lineSetMediaControl

lineSetMediaControl enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states. The NMS TSP implements a subset of this functionality. Use it to control conditions under which play and record operations are terminated.

Playing and recording can be terminated with waveOutReset, waveInReset or waveInStop. However, an NMS telephony board can also terminate play and record functions when DTMF digits are detected. With lineSetMediaControl, applications can specify which digits terminate play or record operations.

Note: LINEMEDIACONTROL_xxx constants defined by Microsoft in tapi.h are currently unsupported.

Two device specific constants, defined in the header file nmstapi.h, are used by lineSetMediaControl as shown in the table below.
Constant

Description

LINEMEDIACONTROL_STOPPLAY

 Abort play if a DTMF is detected. Used in the LINEMEDIACONTROLDIGIT structure.

LINEMEDIACONTROL_STOPRECORD

 Abort record if a DTMF is detected. Used in the LINEMEDIACONTROLDIGIT structure.

The following code sample illustrates using lineSetMediaControl to set conditions for terminating a call:

   #define NUM_DIGITS 3
        LINEMEDIACONTROLDIGIT digitList[NUM_DIGITS];
         // Stop play on the DTMF digit `1' or `3'
        digitList[0].dwDigit = '1';
        digitList[0].dwDigitModes = LINEDIGITMODE_DTMF;
        digitList[0].dwMediaControl = LINEMEDIACONTROL_STOPPLAY;

        digitList[1].dwDigit = '3';
        digitList[1].dwDigitModes = LINEDIGITMODE_DTMF;
        digitList[1].dwMediaControl = LINEMEDIACONTROL_STOPPLAY;

        /* Stop record on the DTMF digit `*'                  */
        digitList[2].dwDigit = '*';
        digitList[2].dwDigitModes = LINEDIGITMODE_DTMF;
        digitList[2].dwMediaControl = LINEMEDIACONTROL_STOPRECORD;

       lineSetMediaControl( 
             mhLine,                 /* Line handle              */
            (DWORD)0,                /* Address ID               */
            (HCALL)0,                /* Call handle              */
             LINECALLSELECT_LINE,
             digitList, NUM_DIGITS, /* Digit list                */
             NULL, 0,               /* Media control list        */
             NULL, 0,               /* Tone control list         */
             NULL, 0                /* Call state control list   */
            );


(Page 1 of 1 in this chapter)

tech_support@nmss.com
Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.