IDebugDataSpaces3::ReadHandleData method (dbgeng.h)

Article
10/21/2021

The ReadHandleData method retrieves information about a system object specified by a system handle.

Syntax

HRESULT ReadHandleData(
  [in]            ULONG64 Handle,
  [in]            ULONG   DataType,
  [out, optional] PVOID   Buffer,
  [in]            ULONG   BufferSize,
  [out, optional] PULONG  DataSize
);

Parameters

[in] Handle

Specifies the system handle of the object whose data is requested. See Handles for information about system handles.

[in] DataType

Specifies the data type to return for the system handle. The following table contains the valid values, along with the corresponding return type:

Value	Description
DEBUG_HANDLE_DATA_TYPE_BASIC	Returns basic information about the system object. In this case, the argument Buffer can be considered to have type PDEBUG_HANDLE_DATA_BASIC.
DEBUG_HANDLE_DATA_TYPE_TYPE_NAME	Returns the name of the object type. For example, "Process" or "Thread". In this case, the argument Buffer can be considered to have type PSTR.
DEBUG_HANDLE_DATA_TYPE_OBJECT_NAME	Returns the name of the object. This includes its location in the object directory. In this case, the argument Buffer can be considered to have type PSTR.
DEBUG_HANDLE_DATA_TYPE_HANDLE_COUNT	Returns the number of handles held by the object. This is similar to the field DEBUG_HANDLE_DATA_BASIC.HandleCount. In this case, the argument Buffer can be considered to have type PULONG.
DEBUG_HANDLE_DATA_TYPE_TYPE_NAME_WIDE	Returns the name of the object type. In this case, the argument Buffer can be considered to have type PWSTR
DEBUG_HANDLE_DATA_TYPE_OBJECT_NAME_WIDE	Returns the name of the object. In this case, the argument Buffer can be considered to have type PWSTR.

[out, optional] Buffer

Receives the object data. Upon successful completion of the method, the contents of this buffer may be accessed by casting Buffer to the type specified in the above table.

If Buffer is NULL, this information is not returned.

[in] BufferSize

Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be returned.

[out, optional] DataSize

Receives the size of the data in bytes. If DataSize is NULL, this information is not returned.

Return value

Return code	Description
S_OK	The method was successful.

This method can also return error values. See Return Values for more details.

Remarks

This method is only available in user-mode debugging.

Requirements

Requirement	Value
Target Platform	Desktop
Header	dbgeng.h (include Dbgeng.h)