2.5.3 Extended Phone Services
Extended Phone Services (or Device Specific Phone Services) include all service provider defined extensions to the SPI. The SPI defines a mechanism that enables service provider vendors to extend the Telephony SPI using device specific extensions. The SPI only defines the extension mechanism, and by doing so provides access to device specific extensions, but the SPI does not define their behavior. Behavior is completely defined by the service provider.
The Telephony SPI consists of scalar and bit flag data constant definitions, data structures, functions, and callback messages. Procedures are defined that enable a vendor to extend most of these as follows:
For extensible scalar data constants, a service provider vendor may define new values in a specified range. As most data constants are DWORDs, typically the range 0x00000000 through 0x7FFFFFFF is reserved for common future extensions, while 0x80000000 through 0xFFFFFFFF are available for vendor specific extensions. The assumption is that a vendor would define values that are natural extensions of the data types defined by the SPI.
For extensible bit flag data constants, a service provider vendor may define new values for specified bits. As most bit flag constants are DWORDs, typically a specific number of the lower bits are reserved for common extensions while the remaining upper bits are available for vendor specific extensions. Common bit flags are assigned from bit zero up; vendor specific extensions should be assigned from bit 31 down. This provides maximum flexibility in assigning bit positions to common extensions versus vendor specific extensions. A vendor is expected to define new values that are natural extensions of the bit flags defined by the SPI.
Extensible data structures have a variable sized field that is reserved for device specific use. Being variable sized, the service provider decides the amount of information and the interpretation. A vendor that defines a device specific field is expected to make these natural extensions of the original data structure defined by the SPI.
leftoff
The TSPI_phoneDevSpecific operation and associated PHONE_DEVSPECIFIC message enable the TAPI DLL's client application to access device-specific phone features that are unavailable via the common Telephony Services on phones. The parameter profile of the TSPI_phoneDevSpecific function is generic in that little interpretation of the parameters is made by the SPI. Device handle parameters have TSPI-defined meanings and are translated appropriately between the application and the Service Provider. Generic parameters are simply passed through unmodified. The interpretation of the generic parameters is defined by the service provider and must be understood by an application that uses them. An application that relies on device specific extensions will not generally work with other service providers, however, applications written to the common telephony phone services will work with the extended service provider.
There is an important consequence of the pass-through nature of the generic parts of the device-specific extensions when this handle-translation issue is considered. A Service Provider has no way to relate the handles used at the TSPI level to those appearing at the TAPI level except by passing them through the predefined handle parameters and fields. Any handle put into the generic extension area is untranslated by the TAPI DLL as it is passed between application and Service Provider. The designer of a Service Provider extension should generally not define extensions that pass handles in this way.
The appropriate approach when defining a device-specific extension that needs to refer to specific devices without using handles is to refer to them using their absolute device identification. The device ID used in opening a phone at the TAPI level, for example, is strictly the same value that is used at the TSPI level to open the phone. This is the motivation for the TSPI_phoneSetDeviceIDBase procedure. It adjusts the Service Provider's device ID numbering to be the same as the numbering used at the TAPI level. This gives the Service Provider designer the flexibility to use device IDs to identify devices in device-specific extensions.
TSPI_phoneDevSpecific
Device specific escape function to allow vendor dependent extensions.
PHONE_DEVSPECIFIC
Device specific messages sent to the application's callback.