5.1.1 Extensibility

Provisions are made for extending data types and structures both in a device independent way and in a device specific (i.e., vendor specific) way.

In data types that are scalar enumerations, a range of values is reserved for future common extensions. The remainder of values is identified as device specific. A vendor can define meanings for these values in any way desired. The interpretation of these values is keyed to the Extension ID provided via the LINEDEVCAPS data structure. For data types that are defined as bit flags, a range of low order bits are reserved, where the high order bits can be Extension specific. It is recommended that Extended values and bit arrays use bits from the highest value or high order bit down. This leaves the option to move the border between the common portion and Extension portion if there is need to do so in the future. Extensions to data structures are assigned a variable sized field with size/offset being part of the fixed part. The TSPI describes for each data structures what device specific extensions are allowed.

In addition to recognizing a specific Extension ID, the TAPI DLL (operating on behalf of an application) must negotiate the extension version number that the app and the service provider will operate under. This is done using the TSPI_lineNegotiateExtVersion and TSPI_phoneNegotiateExtVersion functions.

An Extension ID is a globally unique identifier. There is no central registry for Extension IDs. Instead, they are generated locally by the manufacturer by a utility that is available with the toolkit. The number is made up parts such as a (unique) LAN address, time of day, random number, to guarantee global uniqueness. Globally Unique Identifiers are designed to be distinguishable from HP/DEC universally unique identifiers and are thus fully compatible with them.

ASYNC_LINE_COMPLETION

The ASYNC_LINE_COMPLETION type represents a callback procedure supplied by the TAPI DLL at the time a Service Provider is initialized. The Service Provider calls this procedure to report completion of line and call device requests for which it returns an "asynchronous" notification. The full syntax and semantics of this procedure is described in the "Functions" chapter.

ASYNC_PHONE_COMPLETION

The ASYNC_PHONE_COMPLETION type represents a callback procedure supplied by the TAPI DLL at the time a Service Provider is initialized. The Service Provider calls this procedure to report completion of phone device requests for which it returns an "asynchronous" notification. The full syntax and semantics of this procedure is described in the "Functions" chapter.

DRV_REQUESTID

This type is used to supply a unique identifier for a request to the Service Provider. A value of this type is passed as a parameter to every function that allows for asynchronous operation. If the operation is asynchronous, the Service Provider returns this value as the return value of the function. Whenever the Service Provider flags a request as asynchronous in this way, it must eventually report the operation complete by calling either the ASYNC_LINE_COMPLETION or ASYNC_PHONE_COMPLETION callback.

The TAPI DLL guarantees that DRV_REQUESTID values it supplies are strictly positive, that is, between the values of 0x00000001 and 0x7FFFFFFF, inclusive. Furthermore, the values are "unique" in the sense that no value returned from a function to flag the request as asynchronous will be re-used before the operation is reported complete.

HDRVCALL

This type represents a Service Provider's opaque handle for a call data structure. It is the responsibility of the Service Provider to be able to resolve a value of this type into a reference to the appropriate data structure instance.

HDRVLINE

This type represents a Service Provider's opaque handle for a line data structure. It is the responsibility of the Service Provider to be able to resolve a value of this type into a reference to the appropriate data structure instance.

HDRVPHONE

This type represents a Service Provider's opaque handle for a phone data structure. It is the responsibility of the Service Provider to be able to resolve a value of this type into a reference to the appropriate data structure instance.

HTAPICALL

This type represents the TAPI DLL's opaque handle for a call data structure. It is the responsibility of the TAPI DLL to be able to resolve a value of this type into a reference to the appropriate data structure instance. The Service Provider should not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to the TAPI DLL at appropriate times.

HTAPILINE

This type represents the TAPI DLL's opaque handle for a line data structure. It is the responsibility of the TAPI DLL to be able to resolve a value of this type into a reference to the appropriate data structure instance. The Service Provider should not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to the TAPI DLL at appropriate times.

HTAPIPHONE

This type represents the TAPI DLL's opaque handle for a phone data structure. It is the responsibility of the TAPI DLL to be able to resolve a value of this type into a reference to the appropriate data structure instance. The Service Provider should not attempt to reference through this as if it were a pointer, make assumptions about its values, or interpret its representation in any way other than passing its value to the TAPI DLL at appropriate times.

INITIALIZE_NEGOTIATION

This is a special value of type DWORD. It may be passed as the dwDeviceID in the TSPI_lineNegotiateTSPIVersion and TSPI_phoneNegotiateTSPIVersion functions. Doing so indicates that the TAPI DLL wishes to negotiate a TSPI interface version number independent of any specific devices. This version number may be used as the interface version number for calling device-independent initialization functions such as TSPI_lineSetDeviceIDBase and TSPI_phoneSetDeviceIDBase.

LINEEVENT

The LINEEVENT type represents a callback procedure supplied by the TAPI DLL at the time a line is opened. The Service Provider calls this procedure to report spontaneous events that occur on the line or calls on the line. The full syntax and semantics of this procedure is described in the "Functions" chapter.

PHONEEVENT

The PHONEEVENT type represents a callback procedure supplied by the TAPI DLL at the time a phone is opened. The Service Provider calls this procedure to report spontaneous events that occur on the phone. The full syntax and semantics of this procedure is described in the "Functions" chapter.

TSPI_LINE_PROCS

The TSIP_LINE_PROCS type represents a table of procedure entry points for all of the line-related functions defined by the TSPI and implemented by the Service Provider. The TAPI DLL may retrieve this table using the TSPI_lineGetProcTable procedure. The full syntax and semantics of each of the procedure entry points included in this data structure is described in the "Functions" chapter. The fields of this data structure correspond exactly one-to-one with the set of procedures with a "TSPI_line" prefix, so they are not repeated here. Service Provider developers can refer to the TSPI header file for exact details.

TSPI_PHONE_PROCS

The TSIP_PHONE_PROCS type represents a table of procedure entry points for all of the phone-related functions defined by the TSPI and implemented by the Service Provider. The TAPI DLL may retrieve this table using the TSPI_phoneGetProcTable procedure. The full syntax and semantics of each of the procedure entry points included in this data structure is described in the "Functions" chapter. The fields of this data structure correspond exactly one-to-one with the set of procedures with a "TSPI_phone" prefix, so they are not repeated here. Service Provider developers can refer to the TSPI header file for exact details.

TSPIMessage

This is an enumeration type that defines the set of additional LINEEVENT and PHONEEVENT messages appearing in the TSPI that do not appear in the TAPI.

Values

The following TSPIMessage values are defined by the TSPI.
Specifies that a new, incoming call has arrived and introduces it to the TAPI DLL. This must be the first message sent to the TAPI DLL for a new incoming call. The TAPI DLL returns its opaque identifier for the call as part of its handling of this message.Specifies that a device-specific event has occurred on a call device.Specifies that a device-specific feature event has occurred on a call device.

Line-related Data Structures

The remaining data structures are identical to those defined at the TAPI level. The TSPI header file does not define them. It includes them from the TAPI header file. The following sections defining the line-related and phone-related data structures are identical to the corresponding descriptions in the TAPI interface.

In the case of most of the larger data structures, the responsibility for filling in fields is divided between the Service Provider and the TAPI DLL. The Service Provider must preserve the values present in fields "owned" by the TAPI DLL. The description of which fields must be set by the Service Provider and which fields must be preserved is provided in the "Functions" chapter in the functions that refer to that data structure.