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.


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



Currently unused. Should be set to zero.


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


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).


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
The pbstrDescription parameter contains a valid BSTR pointer.
The value in the hrStatus parameter is unknown to the extension and no description is available.


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.


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