4.1 Messages

This chapter contains a list of the messages in the Telephony Service Provider Interface (TSPI). Messages are used to notify the TAPI DLL of the occurrence of asynchronous events that spontaneously occur within the Service Provider. The Service Provider passes these events to the TAPI DLL 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 the TAPI DLL in the sense that they are not a direct response to any request. These contrast with events reporting completion of requests made by the TAPI DLL. Such completion events are reported through the ASYNC_LINE_COMPLETION or ASYNC_PHONE_COMPLETION callback functions as described in the "Functions" chapter.

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 the TSPI. The TAPI DLL 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 what handles are included, along with what 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. The general rules of correspondence are as follows:

The set of messages is nearly identical. Where messages correspond, the same message name and value is used at the TSPI level.
Handles appearing at the TSPI level are the opaque types defined by the TSPI specification. These types (and their interpretation) differ from those at the TAPI level, although they refer to the same class of device. For example, where a TAPI message would include an HLINE handle, the corresponding TSPI message would typically include an HTAPILINE handle.
There is no dwCallbackInstance data passed to the callback.
dwParam1, dwParam2, and dwParam3 are usually identical to the corresponding parameters for the TAPI message.
line-oriented and call-oriented messages are passed to a different callback procedure than phone-oriented messages. For each message, this chapter lists the following items:
The purpose of the message
The callback procedure to which this message is passed
A description of the message parameters
Optional comments about using the message
Optional references to other functions, messages, and data structures
Optional comments comparing this message to the TAPI interface Certain messages are used to notify the TAPI DLL about a change in an object's status. These messages provide the TAPI DLL's opaque object handle and an indication of which status item has changed. The TAPI DLL 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 the TAPI DLL. For some event types, such as status changes, the TAPI DLL specifies a set of status changes in which it is interested. The Service Provider is advised to limit the status-change messages events it reports to those included in this set. The Service Provider is not required to adhere to this limit, i.e., it may report more changes than are strictly necessary. However, it should try to observe the limit for performance reasons.