4.23 WFSStartUp

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:

WFS_ERR_ALREADY_STARTED
A WFSStartUp has already been issued by the application, without an intervening WFSCleanUp.
WFS_ERR_API_VER_TOO_HIGH
The range of versions of WOSA/XFS API support requested by the application is higher than any supported by this particular WOSA/XFS implementation.
WFS_ERR_API_VER_TOO_LOW
The range of versions of WOSA/XFS API support requested by the application is lower than any supported by this particular WOSA/XFS implementation.
WFS_ERR_INTERNAL_ERROR
An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.
WFS_ERR_INVALID_POINTER
A pointer parameter does not point to accessible memory.

See also WFSCleanUp