HRESULT WFSOpen( lpszLogicalName, hApp, lpszAppID, dwTraceLevel, dwTimeOut, dwSrvcVersionsRequired, lpSrvcVersion, lpSPIVersion, lphService )
Initiates a session (a series of service requests terminated with the WFSClose function) between the application and the specified service. The synchronous version of WFSAsyncOpen.
Parameters 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 "CASHDISP02," that is used by the XFS Manager and the service provider solely as a key to obtain the specific configuration information they need.
HAPP hApp
The application handle to be associated with the session being opened. If this parameter is equal to WFS_DEFAULT_HAPP, the session is associated with the calling process as a whole (i.e., the calling process, not some subset of its threads, is the owner of the session and its hService). See WFSCreateAppHandle and Sections 3.5 and 3.8.2 for details.
LPSTR lpszAppID
Points to a null-terminated string containing the application ID; the pointer may be NULL if the ID is not used. This ID may be used by services in a variety of ways; e.g., it is included in the SYSTEM_EVENT message for undeliverable events, to aid in finding system problems
DWORD dwTraceLevel
See WFMSetTraceLevel. NULL turns off all tracing.
DWORD dwTimeOut
Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).
DWORD dwSrvcVersionsRequired
Specifies the range of versions of the service-specific interface that the application can support. (See Comments.) The low-order word indicates the highest version of the interface the application can support; the high-order word indicates the lowest version of the interface 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 lpSrvcVersion
Pointer to the data structure that is to receive version support information and other details about the service-specific interface implementation (returned parameter).
LPWFSVERSION lpSPIVersion
Pointer to the data structure that is to receive version support information and (optionally) other details about the SPI implementation of the service provider being opened (returned parameter). This pointer may be NULL if the application is not interested in receiving this information. See WFPOpen.
LPHSERVICE lphService
Pointer to the service handle that the XFS Manager assigns to the service on a successful open; the application uses this handle for communication with the service provider for the remainder of the session (returned parameter). If a process opens the same service twice, the XFS Manager generates and returns different hService values.
Mode Synchronous
Comments This function is used by an application to initiate a session with a service; the session is terminated by WFSClose. After WFSStartUp, an application must use this function (or the asynchronous version) to access a service. The request is made in terms of a logical service name (lpLogicalName) which is mapped by the XFS Manager to a service provider. The XFS Manager loads the service provider, if necessary, and returns a logical service handle to the application which is used during the session to refer to the service.
In order to support future WOSA/XFS implementations with maximum flexibility, two version negotiations take place in WFSOpen processing. An application specifies in the dwSrvcVersionsRequired parameter the range of versions of the service-specific interface (as defined in the separate XFS specifications for specific classes of devices, such as banking printers and cash dispensers) that it can support. If the range of versions specified by the application overlaps the range of versions that the service provider’s implementation can support, the call succeeds. Otherwise the call fails. (The other negotiation that takes place during the open process is between the XFS Manager and the service provider regarding the SPI level. See WFPOpen for details.)
Information describing the actual service provider implementation is returned in the WFSVERSION data structure (defined in Section 8.2). In particular, it returns the version the service provider 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 complete interface specification: the service-specific WFSExecute and WFSGetInfo commands, 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 a service provider to operate successfully if there is any overlap in their versions. The following chart gives examples of how WFSOpen works in conjunction with different application and service provider versions:
| Application version(s) | Service Provider version(s) | Return status from WFSOpen | 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_SRVC_VERS_TOO_LOW | fails |
| 1.11 - 3.00 | 1.00 | WFS_ERR_SRVC_VERS_TOO_HIGH | fails |
Note that a version negotiation error also generates a system event (see Section 9.7).
Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.
See also WFSAsyncOpen, WFSClose, WFSCreateAppHandle