3.1 TAPI Functions

3.1.1 Supported Microsoft TAPI Functions

3.1.2 NMS Specific TAPI Functions

3.1.3 Supported TAPI Messages

3.2 Media Modes

3.3 TAPI Call States

3.3.1 Inbound Call States

3.3.2 Outgoing Call States

3.1 TAPI Functions

This chapter describes TAPI line device functions supported by the NMS TSP. Line devices are physical devices such as fax boards, modems, or ISDN cards that are physically connected to an actual telephone line. These devices do not need to be physically connected to the computer on which the telephony application is running. Line devices support telephony applications by allowing them to send or receive information over telephone networks.

Note: NMS TAPI was not designed to work in a client/server environment.

3.1.1 Supported Microsoft TAPI Functions

NMS TAPI fully supports the following Microsoft TAPI functions:

lineClose	lineConfigDialogEdit
lineConfigDialog	lineDeallocateCall
lineConfigProvider	lineGetMessage
lineGetIcon	lineNegotiateAPIVersion
lineInitialize	lineConfigDialogEdit
lineNegotiateExtVersion	lineSetCallData
lineSetAppSpecific	lineUnhold
lineShutdown

For more information about other Microsoft TAPI functions, refer to the Microsoft Platform SDK documentation. For a list of partially supported functions, see Section 3.1.2, NMS Specific TAPI Functions.

3.1.2 NMS Specific TAPI Functions

The following table describes the partially supported TAPI functions. These functions work differently under NMS TAPI than they might work in other environments.

Function	NMS TAPI Details
lineAccept	lineAccept ignores lpsUserUserInfo and dwSize arguments.
lineAnswer	lineAnswer does not support sending user information data and it ignores lpsUserUserInfo and dwSize arguments.
lineDevSpecific	lineDevSpecific supports two commands: CMD_SET_PARAM_BY_NAME and CMD_START_PROTOCOL.
lineBlindTransfer	lineBlindTransfer is not supported for ISDN or No Call Control (NOCC).
lineCompleteTransfer	lineCompleteTransfer is not supported for ISDN or No Call Control (NOCC).
lineDial	lineDial is only supported as part of a supervised transfer operation.
lineDrop	lineDrop does not support lpszDestAddress and dwCountryCode.
lineGatherDigits	dwDigitModes supports only LINEDIGITMODE_DTMF. The valid digits for lpszTerminationDigits are: 0...9, A, B, C, D, #, and *. dwFirstDigitTimeout is supported if the value is less than the MAX_DIGIT_TIMEOUT. dwInterDigitTimeout is supported if the value is less than the MAX_DIGIT_TIMEOUT.
lineGenerateDigits	dwDigitMode supports only LINEDIGITMODE_DTMF. Not greater than MAX_DIGIT_DURATION 0x0000FFFE.
lineGenerateTone	lineGenerateTone does not support LINETONE_BILLING. It does support: · LINEMODE_CUSTOM (one tone, two frequencies) · LINETONEMODE_RINGBACK · LINETONEMODE_BUSY · LINETONEMODE_BEEP
lineGetAddressCaps	AddressID must be set to 0. You can have only one address per line.
lineGetAddressID	Supports one address per line. A 0 is always returned because dwAddressMode and lpsAddress are ignored.
lineGetAddressStatus	Not all fields are set in lpAddressStaus.
lineGetCallInfo	Not all fields will be set in lpCallInfo.
lineGetCallStatus	Not all fields will be set in lpCallStatus.
lineGetDevCaps	Not all fields will be set in lpLineDevCaps.
lineGetDevConfig	Does not use configuration data.
lineGetID	Supports: tapi/line, wave/in, wave/out, and nms/fax.
lineGetLineDevStatus	See LINEDEVSTATUS structure.
lineMakeCall	lineMakeCall does not support partial lineDial. Refer to the structure support list for information about LINECALLPARAMS.
lineMonitorDigits	Supports LINEDIGITMODE_DTMF | LINEDIGITMODE_DTMFEND. Does not support LINEDIGITMODE_PULSE.
lineMonitorMedia	The only media that can be monitored using lineMonitorMedia is Group 3 Fax (LINEMEDIAMODE_G3FAX), which can be used to detect fax tones for the purposes of handing the call off to a fax application. Monitoring for fax tones uses one of the two available tone detectors. See lineMonitorTones.
lineMonitorTones	Specifies the unique ID for a tone list. Several tone lists can be outstanding at once. The service provider replaces any old list that has the same dwToneListID with the new tone list. If lpToneList is NULL, the tone list with dwToneListID is dropped. Other tone lists with different dwToneListIDs are unchanged.
lineOpen	dwMediaModes supports: INTERACTIVEVOICE, AUTOMATEDVOICE, and LINEMEDIAMODE_G3FAX. A call is automatically connected when the board is configured as No Call Control (NOCC).
lineSetMediaControl	Only LINESELECT_CALL is supported. Others are ignored. LINEDIGITMODE_DTMF is the only digit mode that is supported. DTMF_END is not supported at all. Supports LINEMEDIACONTROL_STOPPLAYDTMF and LINEMEDICONROL_STOPRECORDDTMF. dwMediaControl supports: LINEMEDIACONTROL_CONTINUERECORDIGNNOVOICE and LINEMEDIACONTROL_CONTINUERECORDSILENCE.
lineSetupTransfer	Not all fields are used from lpCallParms. lineSetupTransfer is not supported for ISDN or No Call Control (NOCC).

3.1.3 Supported TAPI Messages

The TAPI specification defines a set of messages for line devices. The following table lists the supported TAPI line device messages that can be sent from the NMS TSP to applications:

• LINE_CALLINFO

• LINE_CALLSTATE

• LINE_GATHERDIGITS

• LINE_GENERATE

• LINE_MONITORDIGITS

• LINE_MONITORMEDIA

• LINE_MONITORTONE

For more information about any of these TAPI line messages, refer to the Microsoft Platform SDK documentation. For more information on TAPI call states, refer to Section 3.3, TAPI Call States.

3.2 Media Modes

When a call is in the Connected state, media can be transmitted over the established connection.

NMS TAPI supports the following TAPI media modes:

• Interactive voice: Voice energy is detected on the call, the call is handled as an interactive voice call, and there is a person at the application end.

• Automated voice: Voice energy is detected on the call, and the call is handled as a voice call, but there is no person at the application's end (for example, an answering machine application).

• Unknown: The media mode is unknown before the incoming call is answered (on analog loop start lines).

For more information about TAPI media modes, refer to the Microsoft Platform SDK documentation.

3.3 TAPI Call States

This section provides state diagrams of the functions used to connect inbound and outbound calls.

3.3.1 Inbound Call States

The following state transitions take place as NMS TAPI applications respond to inbound calls (as shown in Figure 2):

1. The application receives a LINE_APPNEWCALL event indicating that a new call appeared.

2. The application receives a LINE_CALLSTATE(OFFERING) event indicating that a new call is being offered. The call state is now changed to Offering.

3. The application can respond in several ways:

4. It can reject the call by invoking lineDrop. The application receives an asynchronous LINE_REPLY event indicating the results of lineDrop. If the command executed successfully, the application receives a LINE_CALLSTATE(IDLE) event indicating that the call state has changed to Idle.

5. The call may be disconnected before the application can respond (for instance, if the calling party hangs up). In this case, the application receives a LINE_CALLSTATE(DISCONNECTED) event indicating that the call state has changed to Disconnected. The application must explicitly call lineDrop to change the call state to Idle.

6. It can answer the call by invoking lineAnswer. The application receives an asynchronous LINE_REPLY event that indicates the results of lineAnswer. If the command executed successfully, the application receives a LINE_CALLSTATE(CONNECTED) event indicating that the Connected.

7. Once a call is in the Connected state, the following may occur:

8. The application can eventually terminate the call by invoking lineDrop. The application receives an asynchronous LINE_REPLY event indicating the results of lineDrop. If the command executed successfully, the application receives a LINE_CALLSTATE(IDLE) event indicating that the call state has changed to Idle.
   Note: The transition to Idle state can only occur after the remote party has dropped the connection.

9. The call may eventually be terminated by the remote party. The application then receives a LINE_CALLSTATE(DISCONNECTED) event indicating that the call state has changed to Disconnected. The application must explicitly call lineDrop to change the call state to Idle.

10. Once the call is in the Idle state, the application invokes lineDeallocateCall to terminate the call and free call resources. This function can also be called from any other call state.
    
    
    Figure 2. TAPI Inbound Call States

3.3.2 Outgoing Call States

The following state transitions take place as NMS TAPI applications place outbound calls (as shown in Figure 3):

1. The application invokes lineMakeCall to initiate an outbound call. The application receives an asynchronous LINE_REPLY event that indicates the results of lineMakeCall. If the command executed successfully, the application also receives LINE_CALLSTATE events that indicate the status of the call as it changes to any of the following states:

2. Dialtone

3. Dialing

4. Proceeding

5. Ringback

6. Connected

7. Disconnected (by the network)

8. If the call is disconnected, the application must explicitly call lineDrop to return the call to the Idle state. It will receive a synchronous LINE_REPLY event, and a LINE_CALLSTATE(IDLE) event indicating that the call state has changed to Idle.

9. Once a call is in the Connected state, the following can occur:

10. The application can terminate the call by invoking lineDrop. The application receives an asynchronous LINE_REPLY event indicating the results of lineDrop. If the command executed successfully, the application receives a LINE_CALLSTATE(IDLE) event indicating that the call state has changed to Idle.
    Note: The transition to Idle state can only occur after the remote party has dropped the connection.

11. The call can be terminated by the remote party. The application then receives a LINE_CALLSTATE(DISCONNECTED) event indicating that the call state has changed to Disconnected. The application must explicitly call lineDrop to change the call state to Idle.

12. Once the call is in the Idle state, the application invokes lineDeallocateCall to terminate the call and to free call resources. This function can also be called from any other call state.

Figure 3 illustrates the TAPI outbound call states. If a lineDrop occurs during any of these states, the state will return to Idle.

Figure 3. TAPI Outbound Call States