DXGKCB_ENUMHANDLECHILDREN callback function (d3dkmddi.h)

DXGKCB_ENUMHANDLECHILDREN enumerates the allocations associated with a given resource, one allocation at a time.

Syntax

DXGKCB_ENUMHANDLECHILDREN DxgkcbEnumhandlechildren;

D3DKMT_HANDLE DxgkcbEnumhandlechildren(
  [in] IN_CONST_PDXGKARGCB_ENUMHANDLECHILDREN unnamedParam1
)
{...}

Parameters

[in] unnamedParam1

Pointer to a DXGKARGCB_ENUMHANDLECHILDREN structure that describes the parent resource and the index of the child allocation to retrieve.

Return value

DXGKCB_ENUMHANDLECHILDREN returns the Dxgkrnl-specific handle to the child allocation that pData describes. To retrieve the device-specific data for the handle, the display miniport driver must call the DXGKCB_GETHANDLEDATA function.

DXGKCB_ENUMHANDLECHILDREN returns a NULL handle if the child-allocation index value supplied in the Index member of the DXGKARGCB_ENUMHANDLECHILDREN structure exceeds the number of allocations that are associated with the parent resource. If DXGKCB_ENUMHANDLECHILDREN unexpectedly returns a NULL handle, the DirectX graphics kernel subsystem was unable to resolve the handle to the parent resource, for a reason such as the following possibilities:

  • An invalid handle was received from the user-mode display driver because of a malicious attack or some other bug.
  • Allocations had lifetime issues.

If a NULL handle is returned unexpectedly, the display miniport driver should fail its currently running DDI function with STATUS_INVALID_HANDLE.

Remarks

A display miniport driver can call DXGKCB_ENUMHANDLECHILDREN in a loop to enumerate all of the allocations that are associated with a resource.

The allocation handle indices are zero-based. If the display miniport driver sets pData->Index to 0, DXGKCB_ENUMHANDLECHILDREN returns the first allocation handle; if Index is set to 1, DXGKCB_ENUMHANDLECHILDREN returns the second allocation handle; and so on. If Index is greater than the number of allocations that are associated with the resource, DXGKCB_ENUMHANDLECHILDREN returns NULL.

DXGKCB_XXX functions are implemented by Dxgkrnl. To use this callback function, set the appropriate members of DXGKARGCB_ENUMHANDLECHILDREN and then call DxgkCbEnumHandleChildren via the DXGKRNL_INTERFACE.

Requirements

Requirement Value
Minimum supported client Windows Vista (WDDM 1.0)
Target Platform Desktop
Header d3dkmddi.h (include D3dkmddi.h)
IRQL PASSIVE_LEVEL

See also

DXGKARGCB_ENUMHANDLECHILDREN

DXGKCB_GETHANDLEDATA

DXGKRNL_INTERFACE