When a WOSA/XFS API or SPI function call completes, it returns a value that either defines the completion status, or in the case of asynchronous functions, the status of the initial processing of the request. When an asynchronous function completes, the completion message includes the final status of the request. The return value of most functions is a “result handle,” hResult, of type HRESULT. hResult values are defined to be WFS_SUCCESS (zero) for success; other values indicate the specific error that occurred, as defined in each function specification.
The XFS Manager and the service providers return status from a function call, in the form of an hResult result handle, in two manners:
By returning an hResult value as the function return.
By posting a completion message to the window specified in the request. The message contains a pointer to a structure that includes the hResult.
The mechanism depends on the category of function being processed, as follows:
Immediate API
The XFS Manager processes the request, and immediately returns a result handle. In some cases, the XFS Manager calls the service provider to process the request, then returns the result handle from the service provider to the application.
Asynchronous API
Since the processing is performed in a number of steps, as described earlier, return status is generated at a number of levels:
The service provider performs any validations which can be processed immediately.
If an error is detected, the service provider returns the hResult to the XFS Manager, which immediately returns it to the application.
Otherwise, the request is scheduled and an hResult of WFS_SUCCESS is immediately returned to the XFS Manager, which immediately returns it to the application. This informs the application that the request has been accepted and is being processed.
Upon completion of the deferred request, a completion message is posted to the application's window. This message points to the structure that includes the hResult indicating the completion status of the request.
Synchronous API
Since a synchronous API call is translated by the XFS Manager to an asynchronous SPI, the service provider behaves the same as in asynchronous API processing. Specifically, the service provider performs any validations which can be processed immediately.
If an error is detected, the service provider returns the hResult to the XFS Manager, which immediately returns it to the application.
Otherwise, the request is scheduled and an hResult of WFS_SUCCESS is immediately returned to the XFS Manager, indicating that the request has been accepted and is being processed.
Upon completion of the deferred request, a completion message is posted to the XFS Manager window. The XFS Manager retrieves the hResult from the structure pointed to by the message and returns it to the application.