HRESULT WFSStartUp( dwVersionsRequired, lpWFSVersion )
Establishes a connection between an application and the XFS Manager.
Parameters DWORD dwVersionsRequired
Specifies the range of versions of the XFS Manager that the application can support. The low-order word indicates the highest version of the XFS Manager the application can support; the high-order word indicates the lowest version of the XFS Manager the application can support. In each word, the low-order byte specifies the major version number and the high-order byte specifies the minor version number (i.e., the numbers before and after the decimal).
Note: in order to allow intermediate minor revisions (e.g., between 1.10 and 1.20), the minor version number should always be expressed as two decimal digits, i.e., 1.10, 1.11, 1.20, etc.
LPWFSVERSION lpWFSVersion
Pointer to the data structure that is to receive version support information and other details about the current WOSA/XFS implementation (returned parameter).
Mode Immediate
Comments This function is used by an application to register itself with the XFS Manager and specify the version(s) of the WOSA/XFS API specification it can use, and returns information on the specific WOSA/XFS implementation. It must be the first WOSA/XFS API function called by an application. An application may only issue further WOSA/XFS functions after a successful WFSStartUp has completed.
In order to support future WOSA/XFS implementations with maximum flexibility, a version negotiation process takes place in WFSStartUp. An application specifies in the dwVersionsRequired parameter the range of versions of the WOSA/XFS API specification which it can support. If the range of versions specified by the application overlaps the range of versions that the current implementation of XFS Manager can support, the call succeeds. Otherwise the call fails.
Information describing the actual WOSA/XFS implementation is returned by the XFS Manager in the WFSVERSION data structure (defined in Section 8.2). In particular, it returns the version it expects the application to use (the highest common version), as well as the lowest and highest versions it is capable of. If the call fails, WFSVERSION is still returned, to help with analysis of the failure.
The version numbers refer to the API specification, specifically functions, parameters, data structures, error codes, and messages. If there are any changes to these, the version number should be changed.
This version negotiation allows a WOSA/XFS application and the XFS Manager to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFSStartUp works in conjunction with different application and XFS Manager versions:
Application versions | XFS Manager versions | Return status from WFSStartUp | Result |
1.00 | 1.00 | WFS_SUCCESS | use 1.00 |
1.00 - 2.10 | 1.00 | WFS_SUCCESS | use 1.00 |
1.11 | 1.00 - 2.00 | WFS_SUCCESS | use 1.11 |
2.11 - 3.00 | 1.00 - 2.20 | WFS_SUCCESS | use 2.20 |
1.00 | 2.20 - 3.00 | WFS_ERR_API_VERS_TOO_LOW | fails |
1.11 - 3.00 | 1.00 | WFS_ERR_API_VERS_TOO_HIGH | fails |
Note that a version negotiation error also generates a system event (see Section 9.7).
After making its last WOSA/XFS call, an application must call WFSCleanUp to allow the XFS Manager to release any resources allocated for the application.
Error Codes The return value indicates whether the application was registered successfully (i.e., the XFS Manager can support requests from the application). If the function was successful, the returned value is WFS_SUCCESS; if not, it is one of the following error conditions:
See also WFSCleanUp