IWiaErrorHandler::GetStatusDescription method

The system UI calls the GetStatusDescription method to provide the user with extra information about an error, if the user requests this information. This method is implemented by a driver's UI extension.

Syntax

HRESULT GetStatusDescription(
  LONG      lFlags,
  IWiaItem2 *pWiaItem2,
  HRESULT   hrStatus,
  BSTR      *pbstrDescription
);

Parameters

lFlags

Currently unused. Should be set to zero.

pWiaItem2

Pointer to the IWiaItem2 item being transferred. IWiaItem2 is described in the Microsoft Windows SDK documentation.

hrStatus

HRESULT variable that contains the status code received by the WIA transfer method, for example the IWiaDataCallback::BandedDataCallback method (described in the Windows SDK documentation).

pbstrDescription

Pointer to a BSTR that receives a description of the status or error encountered during the transfer. This parameter cannot be NULL. The driver must allocate the string using the SysAllocString function and the caller must free the string using the SysFreeString function. The SysFreeString and SysAllocString functions are described in the Windows SDK documentation.

Return value

Returns a standard COM error code if an error occurs, or one of the following:

Return code Description
S_OK
The pbstrDescription parameter contains a valid BSTR pointer.
WIA_STATUS_NOT_HANDLED
The value in the hrStatus parameter is unknown to the extension and no description is available.

Remarks

In order for an application to call IWiaErrorHandler::GetStatusDescription, the application must call IWiaItem2::GetExtension first to receive an interface pointer to the error handling extension. An application must pass "ErrorHandler" as bstrName and IID_IWiaErrorHandler as riidExtensionInterface. An application should pass 0 as lFlags to ensure upward compatibility.

The implementation of IWiaErrorHandler::GetStatusDescription should return S_OK for all the device status codes (hrStatus) that the implementation of IWiaErrorHandler::ReportStatus handles, and WIA_STATUS_NOT_HANDLED for those that IWiaErrorHandler::ReportStatus does not handle.

Requirements

   
Minimum supported client Available in Windows Vista and later versions of the Windows operating systems.
Target Platform Desktop
Header wia_lh.h (include Wia.h)

See also

IWiaErrorHandler

IWiaErrorHandler::ReportStatus