5.1 Introduction

5.1.1 Making Parameter Changes Take Effect

5.2 Using lineDevSpecific

5.2.1 Setting Parameters

5.2.2 Starting a Protocol

5.2.3 Specifying lineOpen Behavior

5.2.4 Setting TSP-Specific Parameters

Setting the lineInitialize Timeout Period

Setting Consultation Call Parameters

5.3 Using lineSetMediaControl

5.1 Introduction

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

• lineDevSpecific

• lineSetMediaControl

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:

• Call progress

• Digit collection

• Call placement, transfer, and blocking

• Play and record

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.

5.1.1 Making Parameter Changes Take Effect

Parameter values entered through the Telephony Parameters tab in the NMS Configurator do not take effect until you restart tapisrv.exe.

To restart tapisrv.exe:

1. Close down any active TAPI applications.

2. From a command prompt, enter:
   net stop tapisrv

When a new TAPI application starts, tapisrv.exe restarts.

5.2 Using lineDevSpecific

Applications can use lineDevSpecific to modify Natural Access parameters. For information about default parameter settings for NMS hardware, refer to Appendix B.

The prototype for lineDevSpecific is as follows:

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

{

WORD dwCommand; /* Use CMD_SET_PARAM_BY_NAME */

PARAM_VALUE paramValue;

} NMSDEVSPECPARAM, FAR *PNMSDEVSPECPARAM;

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

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

At present, CMD_SET_PARAM_BY_NAME and CMD_START_PROTOCOL are the only supported commands.

5.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:

typedef struct _PARAM_VALUE

{

DWORD dwSize; /* Size of this structure */

CHAR szName[MAX_PARAM_NAME_LEN]; /* parameter name */

BYTE buffer[MAX_PARAM_BUFFER_LEN]; /* memory area for value */

UINT cValSize; /* size of buffer in bytes */

} PARAM_VALUE, FAR *PPARAM_VALUE;

The following code sample illustrates using lineDevSpecific to set the adi.placecall.connectmask numeric (DWORD) parameter.

NMSDEVSPECPARAM devSpecParms;
devSpecParms.dwCommand = CMD_SET_PARAM_BY_NAME;

devSpecParms.paramValue.dwSize = sizeof( PARAM_VALUE );
sprintf( devSpecParms.paramValue.szName, "adi.placecall.connectmask" );
*((DWORD*)(devSpecParms.paramValue.buffer)) = (DWORD)0x8000; /*Connect immediately*/
devSpecParms.paramValue.cValSize = sizeof( DWORD );

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

The following example shows using lineDevSpecific to set a String adi.lps.xferstring parameter:

NMSDEVSPECPARAM devSpecParms;
devSpecParms.dwCommand = CMD_SET_PARAM_BY_NAME;

devSpecParms.paramValue.dwSize = sizeof( PARAM_VALUE );
sprintf( devSpecParms.paramValue.szName, "adi.lps.xferstring" );
strncpy( (char *)devSpecParms.paramValue.buffer, "!!;!", 
 MAX_PARAM_BUFFER_LEN - 1 );
devSpecParms.paramValue.cValSize = 
strlen( (char *)devSpecParms.paramValue.buffer ) + 1;

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

5.2.2 Starting a Protocol

Applications can use lineDevSpecific to start a protocol (on a line) if one has not been started yet. When using lineDevSpecific, applications must specify the command CMD_START_PROTOCOL in the NMSDEVSPECPROTOCOL structure.

5.2.3 Specifying lineOpen Behavior

By default, the lineOpen function automatically starts a trunk control protocol. However, you can change this so that when the application calls lineOpen, it can set particular ADI.START parameters before NMS TAPI starts the protocol.

To change the way NMS TAPI behaves when it receives lineOpen calls:

1. Click the TAPI tab on the Advanced System-Level Configuration Dialog box and de-select Start Protocol.
   Note: The default is for Start Protocol to start automatically. By de-selecting the Start Protocol checkbox, you specify that when applications invoke lineOpen, they will be able to set ADI.START parameters before NMS TAPI starts a trunk control protocol.
2. Fill in a NMSDEVSPECPARAM structure as shown in the following table:

   Field	Set to...
   dwCommand	CMD_SET_PARAM_BY_NAME
   dwSize	sizeof(NMSDEVSPECPARAM)
   szName	The parameter name (for example, adi.start.eventmask)
   dwValue	The parameter's value (for example, 0xFFFF)
   cValSize	The value's size (for example, size of DWORD)

3. Invoke lineDevSpecific (as described in Section 5.2), and specify the following arguments:

   Argument	Value
   hLine	Line handle.
   lpParams	A pointer to the NMSDEVSPECPARAM structure (with the dwCommand value set to CMD_SET_PARAM_BY_NAME).
   dwSize	Size of the NMSDEVSPECPARAM structure.

4. Repeat Step 1 and 2 for each parameter to be set.

5. Start the desired protocol by using lineDevSpecific with the following arguments:

   Argument	Value
   lpParams	A pointer to the NMSDEVSPECPROTOCOL structure (with the dwCommand value set to CMD_START_PROTOCOL)
   dwSize	Size of the NMSDEVSPECPROTOCOL structure.

   Note: When you de-select the Start Protocol option in the Advanced System-Level Configuration dialog box, the protocol will not start when lineOpen is called. Therefore calls cannot be made or received until the application calls lineDevSpecific and specifies the NMSDEVSPECPROTOCOL structure.

5.2.4 Setting TSP-Specific Parameters

Use lineDevSpecific to change the following TSP-specific parameters:

• lineInitialize timeout period (for digital boards)

• Consultation call interruption procedures

Setting the lineInitialize Timeout Period

When lineInitialize is called, NMS TAPI waits until the specified digital trunk is in service before it resumes (by default, up to one minute). You can change this timeout period by changing the PRM.TSP.DigitalTrunk.WaitToBeInService parameter with lineDevSpecific (the period is measured in milliseconds).

Setting Consultation Call Parameters

The following three parameters determine what string is dialed when a consultation call is disconnected:

Parameter	Reason for Disconnect
PRM.TSP.xfer.recallstrings.ringnoanswer	There was no answer at the receiving end.
PRM.TSP.xfer.recallstrings.busy	The line was busy.
PRM.TSP.xfer.recallstrings.connected	The consultation call is disconnecting from the Connected state.

Note: These three strings are only used for the loop start and wink start protocols and only if the adi.lps.connstring or adi.wnk.connstring parameter is set to the null string ("").

Use the parameter PRM.TSP.xfer.recallstrings.confirmreturn to specify a string to dial if the TAPI application invokes lineDrop for a consultation call while the original call is on hold pending transfer. The application will receive a LINECALLSTATE_IDLE notification for the consultation call after the string is dialed.

For all four of these parameters, the specified string may be up to 15 characters long. The default setting is "!" (a hook flash).

Note: adiStartDial is the underlying Natural Access function used to dial these strings. The behavior of this function is controlled by the adi.dial.xxx parameters. For example, adi.dial.flashtime and adi.dial.shortpause determine the duration of the "!" and the "," respectively when they appear in one of the recall strings. For more information about adiStartDial, refer to the ADI Service Developer's Reference Manual.

5.3 Using lineSetMediaControl

lineSetMediaControl enables and disables the 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   */
            );