4.16 WFSLock

HRESULT WFSLock( hService, dwTimeOut , lppResult)

Establishes exclusive control by the calling application over the specified service. The synchronous version of WFSAsyncLock.

Parameters HSERVICE hService

Service provider handle as returned by WFSOpen or WFSAsyncOpen.

DWORD dwTimeOut

Number of milliseconds to wait for completion (WFS_INDEFINITE_WAIT to specify a request that will wait until completion).

LPWFSRESULT * lppResult

Pointer to the pointer to a WFSRESULT data structure (see Comments). The service provider allocates the memory for this structure.

Mode Synchronous

Comments A service provider can support a "shared" session, in which multiple applications' data are mixed in the service's I/O stream. More typically, a session is exclusive at any point in time; all I/O is for a single application. To define an exclusive use of the service provider, a lock function (synchronous or asynchronous) must be used. See Section 3.8 for more discussion of the lock concepts and policy.

The time to complete will depend on whether there is another application that has acquired exclusive access to the service. Note that trying to lock several services at the same time can lead to a deadlock. The timeout capability is provided in the API to allow applications to prevent this.

lppResult is a pointer to a pointer to a WFSRESULT data structure containing a null-terminated array of service handles (hService values), specifying any other services that are already locked by the application (i.e., under the same hApp) , only if those services are part of a compound device that includes the service being locked, and are interdependent with it. The returned pointer is NULL if there are no such "associated" services locked. See Section 3.8.2 for more discussion of this subject.

The application must call WFSFreeResult to deallocate the WFSRESULT data structure, if there is one. Note that a WFSRESULT structure may be returned even if the function completes with an error; see Section 3.13.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions.

WFS_ERR_CANCELED

The request was canceled by WFSCancelBlockingCall.

WFS_ERR_CONNECTION_LOST

The connection to the service is lost.

WFS_ERR_INTERNAL_ERROR

An internal inconsistency or other unexpected error occurred in the WOSA/XFS subsystem.

WFS_ERR_INVALID_HSERVICE

The hService parameter is not a valid service handle.

WFS_ERR_INVALID_POINTER

A pointer parameter does not point to accessible memory.

WFS_ERR_NOT_STARTED

The application has not previously performed a successful WFSStartUp.

WFS_ERR_OP_IN_PROGRESS

A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

WFS_ERR_TIMEOUT

The timeout interval expired.

See also WFSAsyncLock, WFSUnlock, WFSCancelBlockingCall