Share via

3.2.4.4.1.53 IVolumeClient::HrGetErrorData (Opnum 70)

  • Article

The HrGetErrorData method retrieves user-readable error information associated with an HRESULT error code.<177>

 HRESULT HrGetErrorData(
   [in] HRESULT hr,
   [in] DWORD dwFlags,
   [out] DWORD* pdwStoredFlags,
   [out] int* pcszw,
   [out, string, size_is(,*pcszw,)] 
     wchar_t*** prgszw
 );

hr: The HRESULT error code from which error information is retrieved.

dwFlags: Bitmap of retrieval flags. The value of this field is generated by combining zero or more of the applicable flags, defined as follows, with a logical OR operation.

Value

Meaning

ERRFLAG_NOREMOVE

0x00020000

Do not delete the error information.

ERRFLAG_IGNORETAG

0x00040000

Retrieve the error information even if it was not produced for this client.

pdwStoredFlags: Pointer to a bitmap of error flags. There are no flags defined.<178>

pcszw: Pointer to the number of strings returned in prgszw.

prgszw: Pointer to an array of strings that contain error information for the HRESULT. For example, for error LDM_E_CRASHDUMP_PAGEFILE_BOOT_SYSTEM_VOLUME, the string is: "The request cannot be completed because the volume is open or in use. It MAY be configured as a system, boot, or page file volume, or to hold a crashdump file." Memory for the array is allocated by the server and freed by the client.

Return Values: The method MUST return 0 or a nonerror HRESULT on success, or an implementation-specific nonzero error code on failure (as specified in [MS-ERREF]; see also section 2.2.1 for HRESULT values predefined by the Disk Management Remote Protocol).

Upon receiving this message, the server MUST validate parameters:

  1. Verify that pdwStoredFlags is not NULL.

  2. Verify that pcszw and prgszw are not NULL.

If parameter validation fails, the server MUST fail the operation immediately, returning an appropriate error as its response to the client.

Otherwise, the server MUST compose a response to the client as follows:

  1. Enumerate user-readable error messages that can be used to better explain the error code specified by hr to the end user:

    • Such error messages are produced by the server during failed client requests. Because the server is not allowed to return error messages in the response to the protocol message that failed, it MAY save such information in a store in preparation for returning it to the client in a subsequent call to IVolumeClient::HrGetErrorData.

      Note Servers are not mandated to support producing error messages. Servers that choose to support producing error messages are free to decide which protocol messages produce error messages and which do not.<179>

  2. Unless the flag ERRFLAG_IGNORETAG is set in the input parameter dwFlags, the server MUST filter out error messages produced as a result of failed requests initiated by other clients.

  3. For each one of the enumerated error messages, allocate a buffer large enough to contain the entire error message, including the terminating null character. Populate each buffer with the corresponding error message.

  4. Allocate an array large enough to contain pointers to each one of the error message buffers.

  5. Populate the array with pointers to the error message buffers.

  6. The array MUST be returned to the client in the output parameter prgszw.

  7. The number of pointers to error messages in the array MUST be returned to the client in the output parameter pcszw.

  8. The output parameter pdwStoredFlags MUST be set to 0.

  9. Unless the flag ERRFLAG_NOREMOVE is set in the input parameter dwFlags, the server MUST delete the error messages for the error code specified by hr from its store.

  10. Return a response that contains the output parameters mentioned previously and the status of the operation.