HRESULT WFPOpen( hService, lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, hWnd, ReqID, hProvider, dwSPIVersionsRequired, lpSPIVersion, dwSrvcVersionsRequired, lpSrvcVersion )
Establishes a connection between the XFS Manager and the service provider that supports the specified service, and initiates a session (a series of service requests terminated with the WFPClose function).
Parameters HSERVICE hService
The service handle to be associated with the session being opened..
LPSTR lpszLogicalName
Points to a null-terminated string containing the pre-defined logical name of a service. It is a high level name such as "SYSJOURNAL1," "PASSBOOKPTR3" or "ATM02," that is used by the XFS Manager and the service provider as a key to obtain the specific configuration information they need.
HAPP hApp
The application handle to be associated with the session being opened.
See WFSCreateAppHandle and Sections 3.5 and 3.8.2 for details.
LPSTR lpszAppID
Pointer to a null terminated string containing the application ID; the pointer may be NULL if the ID is not used.
DWORD dwTraceLevel
See WFPSetTraceLevel.
DWORD dwTimeOut
Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
HWND hWnd
The window handle which is to receive the completion message for this request.
REQUESTID ReqID
Request identification number.
HPROVIDER hProvider
Service provider handle supplied by the XFS Manager – used by the service provider to identify itself when calling the WFMReleaseDLL function.
DWORD dwSPIVersionsRequired
Specifies the range of WOSA/XFS SPI versions that the XFS Manager can support. (See Comments.) The low-order word indicates the highest version the XFS Manager can support; the high-order word indicates the lowest version the XFS Manager 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 lpSPIVersion
Pointer to the data structure that is to receive SPI version support information and (optionally) other details about the SPI implementation (returned parameter).
DWORD dwSrvcVersionsRequired
Service-specific interface versions required; see dwSPIVersionsRequired above, and WFSOpen.
LPWFSVERSION lpSrvcVersion
Pointer to the service-specific interface implementation information; see lpSPIVersion above, and WFSOpen (returned parameter).
Mode Asynchronous
Comments This function establishes the connection between the XFS Manager and the service provider, including version negotiation and passing of implementation information, and initiates a session between the application and the service. This call is made by the XFS Manager each time any application issues a WFSOpen or WFSAsyncOpen call to the specified service (immediately after loading the service provider DLL, if it is not already loaded).
In order to support future WOSA/XFS implementations with maximum flexibility, two version negotiations take place in WFPOpen. In the first, the XFS Manager specifies in the dwSPIVersionsRequired parameter the range of versions of the WOSA/XFS SPI specification which it can support. If the range of versions specified by the XFS Manager overlaps the range of versions that the service provider can support, the call succeeds. Otherwise the call fails.
The WFSVERSION data structure (described in Section 8.2) is used by the service provider to return the version of SPI support it expects the XFS Manager to use (the highest common version), as well as the lowest and highest versions it is capable of. In addition, this structure is used optionally by the XFS Manager to specify other information about the service provider implementation. If the call fails, WFSVERSION is still returned, to help with analysis of the failure.
The version numbers refer to the SPI 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 the XFS Manager and a service provider to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFPOpen works in conjunction with different XFS Manager and service provider versions:
| XFS Manager versions | Service Provider versions | Return status from WFPOpen | 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_SPI_VER_TOO_LOW | fails |
| 1.11 - 3.00 | 1.00 | WFS_ERR_SPI_VER_TOO_HIGH | fails |
The second negotiation is is in relation to the service-specific interface, between the application program and the service provider. See WFSOpen, Section 4.19, for details.
Note that a version negotiation error also generates a system event (see Section 9.7).
Also, see WFSStartUp, Section 4.24.
Messages WFS_OPEN_COMPLETE
Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions, indicating that the asynchronous operation was not initiated. Any service-specific errors that can be returned are defined in the specifications for each service class.
The following error conditions are returned via the asynchronous command completion message, as the hResult from the WFSRESULT structure. The service-specific errors that can be returned are defined in the specifications for each service class.