5.1 Data Types

This chapter describes error codes, constants, data types, and structures used by the Telephony SPI. The TSPI defines only a few of the data structures it uses. The great majority of data structures used in the Telephony SPI are defined by the Telephony API. As a consequence, the organization of this chapter is as follows:

The error codes, constants, data types, and data structures specific to, and defined by, the TSPI are presented in alphabetical order.
The error codes, constants, data types, and data structures used in the TSPI but defined by the TAPI are presented in alphabetical order. This part of the description is identical to the data structure description given in the TAPI specification. Readers familiar with that specification can skip this section.

For each data type or structure, whether it is defined by the TSPI or by the TAPI, this chapter lists the following items:

The purpose of the data type or structure
A description of the values or fields
A description of the type or structure's extensibility
Optional comments about using the data type or structure
Optional references to other functions, messages, and data types or structures.

Memory for all data structures whose representation is published and shared by both the TAPI DLL and the Service Provider is allocated by the TAPI DLL or an application using the TAPI DLL. The TAPI DLL passes a far pointer to the TSPI function that returns the information. The TSPI fills the data structure with the requested information. If the operation is asynchronous, then the information is not available until the asynchronous reply callback indicates success.

A few types defined by the TSPI are "opaque handles". These are used in the TSPI as public references to private data structures. This allows type-checking of parameters supplied to the interface procedures while still giving a measure of type protection. Only the "owner" of the private data structure knows how to interpret the opaque type as a reference to its data structure representation. As an example of how opaque handles are used, consider a phone device. Both the TAPI DLL and the Service Provider typically maintain data structures representing their respective views of the device as shown in the following illustration:

Typical phone data structures (boxes) maintained by the TAPI DLL and a Service Provider are shown. Each contains an opaque handle for the other data structure (small solid circles). These were exchanged at an early initialization step. When the TAPI DLL calls a function in the TSPI interface (dashed line) it passes the opaque handle to refer to the device. The Service Provider knows how to resolve this as a reference (arrow) to its data structure. A similar process occurs when the Service Provider calls a callback function in the TAPI DLL.