2.4.1.5 Version Compatibility
Over time, different versions may exist for the Telephony DLL, applications, and service providers for a line or phone. New versions may define new features, new fields to data structures and bit fields, etc. Version numbers therefore indicate how to interpret various data structures.
To allow optimal mixing and matching of different versions of applications, versions of the Telephony DLL itself, and versions of service providers by different vendors, the SPI provides a simple version negotiation mechanism for applications. There are two different versions that need to be agreed on by the TAPI DLL and the service provider for each line device. One is the version number for the basic and supplementary Telephony SPI and is referred to as the TSPI Interface Version, the other is the version for the provider-specific extensions, if any, and is referred to as the Extension version. The format of the data structures and data types used by the SPI's basic and supplementary features is defined by the SPI version, while the Extension version determines the format of data structures defined by the vendor-specific extensions.
These two different types of version negotiation are handled by two different procedures. TSPI_lineNegotiateTSPIVersion is used to negotiate the TSPI Interface version and TSPI_lineNegotiateExtVersion is used to negotiate the Extension version. Extension version negotiation can always be skipped if extensions are not desired. An Extension version of zero is a special value indicating that no extensions are to be used.
In either case of negotiation, the TAPI DLL passes the Service Provider the highest and lowest version numbers it is compatible with. The Service Provider compares this with its own supported range of version numbers. If these ranges overlap, the Service Provider returns a value within the overlapping portion of the range as the result of the negotiation. Usually, this should be the highest possible value. If the ranges do not overlap, the two parties are incompatible and the function returns an error.
Results of a negotiation simply indicate that the Service Provider is "willing" to operate at a particular version number, but do not commit the Service Provider to doing so. For example, the TAPI DLL may re-negotiate to determine an "ideal" version after having negotiated a "possible" version. TSPI Interface version is only committed when a line is opened through TSPI_lineOpen and survives until the device is closed. Extension version is committed when the TSPI_lineSelectExtVersion function is called, and survives until the selection is canceled by selecting Extension version zero.
Extension version selection can happen many times, including while an extension version is in effect. Since the Service Provider is committed to the extension version, its range of supported versions narrows to exactly that extension version. For example, consider a Service Provider that is normally compatible with Extension versions 1.0 through 5.5. If version 3.0 is in effect while a caller attempts to negotiate a version within the range 1.0 to 5.5, the negotiation returns 3.0.
TSPI_lineNegotiateTSPIVersion
Negotiates a TSPI Interface version for a particular device
TSPI_lineNegotiateExtVersion
Negotiates an Extension version for a particular device
TSPI_lineSelectExtVersion
Selects or cancels an Extension version for a particular device