Debugging Tools for Windows

ReadHandleData

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

HRESULT
  IDebugDataSpaces2::ReadHandleData(
    IN ULONG64  Handle,
    IN ULONG  DataType,
    OUT OPTIONAL PVOID  Buffer,
    IN ULONG  BufferSize,
    OUT OPTIONAL PULONG  DataSize
    );

Parameters

Handle
Specifies the system handle of the object whose data is requested. See Handles for information about system handles.
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.

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.

BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be returned.
DataSize
Receives the size of the data in bytes. If DataSize is NULL, this information is not returned.

Return Value

S_OK
The method was successful.

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

Interface Version

ReadHandleData is available in IDebugDataSpaces2 and later versions.

Comments

This method is only available in user-mode debugging.

Requirements

Headers: Defined in Dbgeng.h. Include Dbgeng.h.

See Also

Handles

Build machine: CAPEBUILD