Expand Minimize

CM_Get_Child_Ex function

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

Syntax


CMAPI
CONFIGRET
WINAPI CM_Get_Child_Ex(
  _Out_     PDEVINST pdnDevInst,
  _In_      DEVINST dnDevInst ,
  _In_      ULONG ulFlags,
  _In_opt_  HMACHINE hMachine
);

Parameters

pdnDevInst [out]

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

dnDevInst [in]

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

ulFlags [in]

Not used, must be zero.

hMachine [in, optional]

Caller-supplied machine handle to which the caller-supplied device instance handle is bound.

Note  Using this function to access remote machines is not supported beginning with Windows 8 and Windows Server 2012, as this functionality has been removed.

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 a local or a remote machine's device tree, first call CM_Get_Child_Ex to obtain a handle to the first child node, then call CM_Get_Sibling_Ex 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.

Use CM_Connect_Machine to obtain a remote machine handle for use with remote device instance handles.

To obtain a local or a remote device instance handle, do one of the following.

You can also use the device installation functions to obtain device instance handles. Do the following steps:

  1. Obtain a device information set.

  2. Obtain an SP_DEVINFO_DATA structure for a device instance in the device information set.

  3. Obtain the device instance handle for the device instance from the DevInst member of the SP_DEVINFO_DATA structure.

  4. Obtain the machine handle to which the device instance handle is bound. 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. (Call SetupDiGetDeviceInfoListDetail to obtain an SP_DEVINFO_LIST_DETAIL_DATA structure.)

Functionality to access remote machines has been removed in Windows 8 and Windows Server 2012 and later operating systems thus you cannot access remote machines when running on these versions of Windows.

Requirements

Version

Available in Microsoft Windows 2000 and later versions of Windows.

Header

Cfgmgr32.h (include Cfgmgr32.h)

Library

Cfgmgr32.lib

See also

CM_Get_Child
CM_Get_Parent
CM_Get_Parent_Ex
CM_Get_Sibling
CM_Get_Sibling_Ex
CM_Locate_DevNode
CM_Locate_DevNode_Ex
SetupDiGetDeviceInfoListDetail
SP_DEVINFO_DATA
SP_DEVINFO_LIST_DETAIL_DATA

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft