CM_Locate_DevNode_ExW function (cfgmgr32.h)

[Beginning with Windows 8 and Windows Server 2012, this function has been deprecated. Please use CM_Locate_DevNode instead.]

The CM_Locate_DevNode_Ex function obtains a device instance handle to the device node that is associated with a specified device instance ID, on a local machine or a remote machine.

Syntax

CMAPI CONFIGRET CM_Locate_DevNode_ExW(
  [out]          PDEVINST    pdnDevInst,
  [in, optional] DEVINSTID_W pDeviceID,
  [in]           ULONG       ulFlags,
  [in, optional] HMACHINE    hMachine
);

Parameters

[out] pdnDevInst

A pointer to the device instance handle that this function retrieves. The retrieved handle is bound to the machine handle specified by hMachine.

[in, optional] pDeviceID

A pointer to a NULL-terminated string representing a device instance ID. If this value is NULL, or if it points to a zero-length string, the function supplies a device instance handle to the device at the root of the device tree.

[in] ulFlags

A variable of ULONG type that supplies one of the following flag values that apply if the caller supplies a device instance identifier:

CM_LOCATE_DEVNODE_NORMAL

The function retrieves the device instance handle for the specified device only if the device is currently configured in the device tree.

CM_LOCATE_DEVNODE_PHANTOM

The function retrieves a device instance handle for the specified device if the device is currently configured in the device tree or the device is a nonpresent device that is not currently configured in the device tree.

CM_LOCATE_DEVNODE_CANCELREMOVE

The function retrieves a device instance handle for the specified device if the device is currently configured in the device tree or in the process of being removed for the device tree. If the device is in the process of being removed, the function cancels the removal of the device.

CM_LOCATE_DEVNODE_NOVALIDATION

Not used.

[in, optional] hMachine

A machine handle obtained from a call to CM_Connect_Machine, or a machine handle to which a device information set is bound. The machine handle for a device information set is obtained from the RemoteMachineHandle member of the SP_DEVINFO_LIST_DETAIL_DATA structure for the device information set. Call SetupDiGetDeviceInfoListDetail to obtain an SP_DEVINFO_LIST_DETAIL_DATA structure.

Return value

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

Remarks

For information about using device instance handles that are bound to a local or a remote machine, see CM_Get_Child_Ex.

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

See also

CM_Get_Child_Ex

CM_Locate_DevNode