2.4.1.13 Setting a Terminal for Phone Conversations
The user's PC may have access to multiple devices, selectable by the user, and used to conduct interactive voice conversations. First, there is the phone device itself, complete with lamps, buttons, display, ringer, and voice I/O device (handset, speakerphone, headset). The user's PC may also have a separate voice I/O device (e.g., headset, or mic/speaker combination attached to a sound card) for use with phone conversations. The Telephony SPI enables the user to select where he wants the information routed that the switch sends over the line, address, or call. The switch normally expects this to be one of its phone sets, and sends ring requests, lamp events (for stimulus phones), display data, and voice data as appropriate. The phone in turn sends hookswitch events, button press events (for stimulus phones), and voice data back to the switch. Note that the line portion of the Telephony SPI makes lamp events, display events, and ring events available, either as functional return codes to the various operations in the SPI, or as unsolicited functional call status messages sent to the application callback. The Telephony SPI implementation is responsible for mapping between the functional SPI level and the underlying stimulus or functional messages used by the telephony network. In functional telephony environments, the SPI functions are mapped to the functional protocol.
Via the TSPI_lineSetTerminal function, the TAPI DLL can control the routing of different low-level events exchanged between the switch and the station; it can also decide not to route some of these low-level events to a device. The routing of the different classes of events can be individually controlled. For example, the media stream of a call (e.g., voice) can be sent to any transducer device if the service provider/hardware is capable of doing so. Ring events from the switch to the phone can mapped into a visual alert on the PC's screen or they can be routed to a phone device. Lamp events and display events can be ignored or routed to a phone device (which will appear to behave as a normal phone set). Finally, button presses at a phone device may or may not be passed on to the line. In any case, this routing of low-level signals from the line does not affect the operation of the line SPI portion which always maps the low-level events to their functional equivalent. Consult a line's device capabilities to determine the terminals it has available.
TSPI_lineSetTerminal
Specifies the terminal device to which the specified line, address events or call media stream events are routed. Separate terminals can be specified for each event class. Event classes include: lamps, buttons, display, ringer, hookswitch, and media stream.
An example will help illustrate how to use this operation. Assume initially that the application suppresses the routing of all events, and the user selects a headset as his current I/O device. An incoming call will send a LINE_CALLSTATE message and a LINE_LINEDEVSTATE message with the ringing indication. Since routing of all events is suppressed, ring events are not routed to the phone, so ringing of the phone is suppressed. Instead the application notifies the user by means of a pop-up dialog box and a system beep in the headset. The user decides to answer the call. Since his current I/O device is the headset, the telephony application will invoke lineSetTerminal on the incoming call to route the call's media to the headset and answer the call. The application may also invoke lineSetTerminal to route lamp and display information events to the phone set to have the phone behave as usual.
As a second example, assume an incoming call is alerting at the user's PC. Instead of selecting the answer option with the mouse, the user decides to just pick up the phone's handset to answer the call. The offhook status at the phone (see further) sends a callback message to the application. The application can interpret this as a request by the user to select the phone handset to conduct the conversation. The application invokes lineSetTerminal to route the voice data on the call to the phone set.