(Page 1 of 1 in this chapter)

Chapter 3

Using TAPI Functions

3.1 TAPI Functions
3.1.1 Supported TAPI Functions
3.1.2 Using TAPI Functions With NMS TAPI
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 to and from telephone networks.

3.1.1 Supported TAPI Functions

The NMS TSP supports the following TAPI functions:

TAPI Functions

lineAddProvider

 lineGetAddressCaps

 lineMonitorMedia*

lineAnswer

 lineGetAddressID

 lineMonitorMediaModes*

lineBlindTransfer*

 lineGetAddressStatus

 lineMonitorTones

lineClose

 lineGetCallInfo

 lineNegotiateAPIVersion

lineCompleteTransfer

 lineGetCallStatus

 lineNegotiateExtVersion

lineConfigDialog

 lineGetDevCaps

lineNegotiateAPIVersion

lineConfigDialogEdit

 lineGetDevConfig

 lineOpen

lineConfigProvider

 lineGetIcon

 lineSetCallData

lineDeallocateCall

 lineGetID

 lineSetDevConfig

lineDevSpecific**

 lineGetLineDevStatus

 lineSetMediaControl**

lineDial*

 lineGetProviderList

 lineSetStatusMessages*

lineDrop

 lineHandoff

 lineSetupTransfer*

lineGatherDigits

 lineInitialize

 lineShutdown

lineGenerateDigits

 lineMakeCall*

lineGenerateTone

 lineMonitorDigits

Note: Refer to Section 3.1.2 for additional details about these functions. For more information about lineSetMediaMode and lineDevSpecific refer to Chapter 6. For more information about other Microsoft TAPI functions, refer to the Microsoft Platform SDK documentation.

3.1.2 Using TAPI Functions With NMS TAPI

The following table provides information about how specific TAPI functions work under NMS TAPI:
Function

 NMS TAPI Details

lineBlindTransfer

 When applications call lineBlindTransfer, the transfer completes only if the new call is connected. If there is no answer or the destination is busy, this function returns an error and the original call remains in a Connected state. See also lineSetupTransfer.

lineDial

 lineDial is only supported on consultation calls that have been created with lineSetupTransfer.

lineMakeCall

 Applications should not pass partial dial strings to lineMakeCall.

lineMonitorMediaModes

 The only media that can be monitored for using lineMonitorMediaModes is Group 3 Fax. This 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

 A maximum of two tones can be monitored on a given line at a given time. If an application is monitoring for Fax tones using lineMonitorMediaModes, that operation takes the place of one of the two tones.

If an application requests monitoring for a tone with two frequencies, both tones must have the same cadence on and cadence off patterns. The TSP looks only at the cadence of the first tone and uses it for both.

lineMonitorTones does not provide a means for applications to specify what bandwidth to use for monitoring tones. The TSP uses the following assumptions: if monitoring for Group 3 Fax, bandwidth is 100, otherwise bandwidth is 50. (This is not applicable for silence detection.)

lineSetupTransfer

 If any activity is ongoing, such as tone/digit monitoring or generation, or playing or recording of wave files, the transfer functions fail. It is up to the application to cancel any activity before transferring a call.

lineSetStatusMessages

 LINEDEVSTATE_RINGING is the only message currently supported.

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:
TAPI Line Messages

LINE_ADDRESSSTATE

 LINE_LINEDEVSTATE

LINE_CALLINFO

 LINE_MONITORDIGITS

LINE_CALLSTATE

 LINE_MONITORMEDIA

LINE_CLOSE

 LINE_MONITORTONE

LINE_GATHERDIGITS

 LINE_APPNEWCALL

LINE_GENERATE

 LINE_REPLY

For more information about any of these TAPI line messages, refer to the Microsoft Platform SDK documentation.

3.2 Media Modes

When a call is in the connected state, information can be transmitted through the call. The call's media mode indicates the type of information (for example, its datatype, or higher-level protocol) provided in the call.

The NMS TSP supports the following TAPI media modes:

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

3.3 TAPI Call States

This section provides two state diagrams of call control functions. Figure 2 shows state transitions that occur when NMS TAPI applications accept, reject, and connect inbound calls. Figure 3 shows state transitions that occur when NMS TAPI applications place and connect 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's state is now changed to Offering.
    

    

  3. The application can respond in several ways:
    

      

    • 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's state has 
changed to Idle.

      

      

    • 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's state has changed to Disconnected. The application must 
explicitly call lineDrop to change the call state to Idle.

      

      

    • 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 
call's state has changed to Connected.

      

      

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

        

      • 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's state has changed to Idle.

        

        

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

        

        

      • Once the call is in the Idle state, the application invokes lineDeallocate to terminate the call and free call resources.
        

        



        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 indicates the status of the call as it changes to any of the following states:
        

          

        • Dial tone

          

          

        • Dialing

          

          

        • Proceeding

          

          

        • Ringback

          

          

        • Connected

          

          

        • Disconnected (by the network)

          

          

        • 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 the call is Idle.
          

          

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

            

          • 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's state has changed to Idle.

            

            

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

            

            

          • Once the call is in the Idle state, the application invokes lineDeallocate to terminate the call and frees call resources.
            

            



            Figure 3.	 TAPI Outbound Call States
            

          


          

          

          


          
 
    (Page 1 of 1 in this chapter)
          


          
 



          
tech_support@nmss.com

          

Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.