When an application invokes an API function, the outcome can be one of three things:
When the function returns, the request or service corresponding to the function has been carried out successfully. The function returns zero indicating success. The request has completed synchronously.
The function detects an error and the request is not carried out. The function returns a negative error number that identifies the error. The request has failed synchronously.
The function does not detect any errors, but instead of completing the request synchronously, it vectors the request to another active entity in the system (LAN server, add-in hardware, switch, network, ...) and returns to the application. The function returns a positive Request ID number. The request is handled asynchronously, and a reply callback is later made to the application to report the success or failure of the asynchronous portion of the request. The app should remember the Request IDs of its requests in progress.
The reply callback made to the application carries the Request ID and an error indication. Valid error indications for this reply are identical to those that can be returned synchronously for the associated request, or zero for success. Only the application that issued the request will receive the reply callback.
The API guarantees that a reply message will be sent for every request that operates asynchronously. Note that for API requests that require involvement of the service provider, the service provider has the option to operate synchronously or asynchronously. A service provider may even decide on an invocation-by-invocation basis which model makes more sense. For example, in client/server configurations, information may be cached at times in the client PCs. A provider may decide to complete a request synchronously if the requested information is currently cached or asynchronously otherwise. The application must be prepared to deal with both models.
API requests that are to return information to the application may do so either synchronously or asynchronously. The returned information is not valid until the request has returned a success indication.
Note that certain telephone networks do not provide any (positive or negative) acknowledgment about the completion of certain requests. A service provider must decide between success or failure of a request even in such situations.