4.13 WFSGetInfo

HRESULT WFSGetInfo( hService, dwCategory, lpQueryDetails, dwTimeOut, lppResult )

Retrieves information from the specified service provider. The synchronous version of WFSAsyncGetInfo.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwCategory

Specifies the category of the query (e.g., for a printer, WFS_INF_PTR_STATUS to request status or WFS_INF_PTR_CAPABILITIES to request capabilities). The available categories depend on the service class, the service provider and the service. The information requested can be either static or dynamic, e.g., basic service capabilities (static) or current service status (dynamic).

LPVOID lpQueryDetails

Pointer to the data structure to be passed to the service provider, containing further details to make the query more precise, e.g., a form name. (Many queries have no input parameters, in which case this pointer is NULL.)

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 the data structure to be filled with the result of the execution. The service provider allocates the memory for the structure.

Mode Synchronous

Comments The XFS Manager passes the request to the service provider, and since the information may be stored remotely, the function cannot be immediate. Note that many requests can be satisfied by the service provider and will therefore complete immediately.

The definitions of the dwCategory and lpQueryDetails parameters are provided in the service-specific command sections of this specification. Note that these information retrieval functions are separate from the other service-specific commands, since those commands can be executed only via WFSExecute or WFSAsyncExecute, which require that the service be either locked by the application issuing the command, or unlocked. The GetInfo functions, however, can be used even when a service is locked by another application.

The application must call WFSFreeResult to deallocate the WFSRESULT data structure which is returned by this function. 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. Any service-specific errors that can be returned are defined in the specifications for each service class.

WFS_ERR_CANCELED

The request was canceled by WFSCancelBlockingCall.

WFS_ERR_CONNECTION_LOST

The connection to the service is lost.

WFS_ERR_DEV_NOT_READY

The function required device access, and the device was not ready or timed out.

WFS_ERR_HARDWARE_ERROR

The function required device access, and an error occured on the device.

WFS_ERR_INTERNAL_ERROR

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

WFS_ERR_INVALID_CATEGORY

The dwCategory issued is not supported by this service class.

WFS_ERR_INVALID_DATA

The data structure passed as input parameter contains invalid data.

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_SOFTWARE_ERROR

The function required access to configuration information, and an error occured on the software.

WFS_ERR_TIMEOUT

The timeout interval expired.

WFS_ERR_UNSUPP_CATEGORY

The dwCategory issued, although valid for this service class, is not supported by this service provider.

See Also WFSAsyncGetInfo