CM_Get_Child function (cfgmgr32.h)

Article
05/24/2022

The CM_Get_Child function is used to retrieve a device instance handle to the first child node of a specified device node (devnode) in the local machine's device tree.

Note

In Windows Vista and later versions of Windows, the unified device property model uses the DEVPKEY_Device_Children property key to represent device children. See Retrieving Device Relations for details.

Syntax

CMAPI CONFIGRET CM_Get_Child(
  [out] PDEVINST pdnDevInst,
  [in]  DEVINST  dnDevInst,
  [in]  ULONG    ulFlags
);

Parameters

[out] pdnDevInst

Caller-supplied pointer to the device instance handle to the child node that this function retrieves. The retrieved handle is bound to the local machine. See the Remarks section.

[in] dnDevInst

Caller-supplied device instance handle that is bound to the local machine.

[in] ulFlags

Not used, must be zero.

Return value

If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the CR_-prefixed error codes defined in Cfgmgr32.h.

Remarks

To enumerate all children of a devnode in the local machine's device tree, first call CM_Get_Child to obtain a device instance handle to the first child node, then call CM_Get_Sibling to obtain handles for the rest of the children.

Using Device Instance Handles

Device instance handle that you use with PnP configuration manager functions are bound to machine handles, as follows:

All local device instance handles are bound to a NULL-valued local machine handle.
If you use a remote machine handle to obtain a device instance handle, the resulting remote device instance handle is bound to the remote machine handle.
A device instance handle can be used only with the machine handle to which it is bound.
A device instance handle can be used with another device instance handle only if both device instance handles are bound to the same machine handle.

To obtain a device instance handle that is bound to the local machine, do one of the following.

Use one of the following functions that retrieve only local device instance handles: CM_Locate_DevNode, CM_Get_Child, CM_Get_Parent, or CM_Get_Sibling.
Use one of the following functions, which retrieves local and remote device instance handles, to retrieve a local device instance handle: CM_Locate_DevNode_Ex, CM_Get_Child_Ex, CM_Get_Parent_Ex, or CM_Get_Sibling_Ex.

You can also use the device installation functions to obtain local device instance handles from a device information set that is bound to the local machine. Do the following steps:

Obtain a device information set that is bound to the local machine. (A device instance handle obtained from a device information set is bound to the machine handle to which the device information set is bound. You obtain the machine handle for a device information set from the RemoteMachineHandle member of its SP_DEVINFO_LIST_DETAIL_DATA structure. For a local device information set that is bound to the local machine, the value of RemoteMachineHandle is NULL. Call SetupDiGetDeviceInfoListDetail to obtain an SP_DEVINFO_LIST_DETAIL_DATA structure.)
Obtain an SP_DEVINFO_DATA structure for a device instance in the device information set.
Obtain the device instance handle for the device instance from the DevInst member of the SP_DEVINFO_DATA structure.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	cfgmgr32.h (include Cfgmgr32.h)
Library	Cfgmgr32.lib; OneCoreUAP.lib on Windows 10
DLL	CfgMgr32.dll