Platform SDK: TAPI

TSPI Messages

This section contains a list of the messages in the Telephony Service Provider Interface (TSPI). These messages are used to notify TAPI of the occurrence of asynchronous events that spontaneously occur within the service provider. The service provider passes these events to TAPI by calling a LINEEVENT or PHONEEVENT callback function, depending on whether the service provider is reporting an event on a line, call, or phone device. The LINEEVENT procedure for reporting events occurring on a line or call is supplied to the service provider at the time the line is opened with the TSPI_lineOpen function. The PHONEEVENT procedure for reporting events occurring on a phone is supplied with the TSPI_phoneOpen function.

These spontaneous events are unsolicited by TAPI in the sense that they are not a direct response to any request. These events contrast with those reporting completion of requests made by TAPI. Such completion events are reported through the ASYNC_COMPLETION callback function.

The parameter profiles for the spontaneous event procedures include parameters that identify the relevant object for which the event is being reported (phone, line, or call). The identification is in the form of an opaque handle whose exact interpretation is not published by TSPI. TAPI internally determines the relationship between these opaque handles and whatever data structures it used to represent the devices.

The parameter profile for spontaneous event procedures also includes a message parameter identifying the type of the message. Each message type has a corresponding definition that determines the handles that are included, along with other parameters and their meanings. There is a very strong correspondence between the messages appearing at the TSPI level and those that appear at the TAPI level. These are the general rules of correspondence:

For each message, this section lists the following items:

Certain messages are used to notify TAPI about a change in an object's status. These messages provide the TAPI opaque object handle and an indication of which status item has changed. TAPI can subsequently call an appropriate "get status" function of the object to obtain the object's full status.

When an event occurs, a message may or may not be sent to TAPI. For some event types, such as status changes, TAPI specifies a set of status changes in which it is interested. The service provider is advised to limit the status-change message events it reports to those included in this set. The service provider is not required to adhere to this limit. In other words, it may report more changes than are strictly necessary. However, it should try to observe the limit for performance reasons.

The LINE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.

The PHONE_REPLY message is not used at the TSPI level. Completion of an asynchronous request is reported using the ASYNC_COMPLETION callback.

For more information see the following topics: