2.3.12 General Interface characteristics

The functions in the TSPI interface can be broken down into three major categories. These are described briefly here and in more detail in later chapters:

Requests with asynchronous execution option. This category generally consists of operations that directly manipulate or query telephony hardware. Such operations may have to interact with carrier networks, server PBXs, etc. Since this may take a long time in some telephony environments, the operations have to option of completing asynchronously. The TAPI DLL chooses a unique request ID before calling the TSPI function to request the operation. The Service Provider decides whether to perform the request synchronously or not. If it performs it synchronously, it simply returns the final result. If it performs asynchronously, it returns an indication that the operation was started successfully. At a later time, it calls a callback function to indicate that the operation was completed. It passes the unique request ID to identify the outstanding request, along with a result code indicating the final outcome. Service Provider designers should choose carefully between synchronous and asynchronous execution of functions. The asynchronous model is designed to allow applications to continue operating and giving appropriate visual feedback during long-running operations. A Service Provider should avoid synchronous implementations that may tie up the caller for a time long enough for a user to notice.
Synchronous requests. Some TSPI functions are defined such that they always operate synchronously, on the grounds that it is not feasible for the caller to proceed until it has the results of the function. The set of such functions has been carefully limited to ones that the great majority of Service Providers will be able to execute very quickly. Most of these functions are bookkeeping functions related to starting up or shutting down the "life cycle" of certain sequences of operations. The rest of these functions have to do with retrieving fundamental device-specific capabilities of the Service Provider itself.
Asynchronous events. Some events detected in the Service Provider are "spontaneous" in the sense that they are not direct side-effects of requests made by the TAPI DLL. For example, a spontaneous event occurs when an incoming call arrives. The Service Provider calls a callback procedure in the TAPI DLL to report such events. The TAPI DLL supplies the pointer to the callback procedure early in the initialization sequence.