Initiates the enumeration of a software device.
HRESULT SwDeviceCreate( PCWSTR pszEnumeratorName, PCWSTR pszParentDeviceInstance, const SW_DEVICE_CREATE_INFO *pCreateInfo, ULONG cPropertyCount, const DEVPROPERTY *pProperties, SW_DEVICE_CREATE_CALLBACK pCallback, PVOID pContext, PHSWDEVICE phSwDevice );
A string that names the enumerator of the software device. Choose a name that represents the component that enumerates the devices.
A string that specifies the device instance ID of the device that is the parent of the software device.
This can be HTREE\ROOT\0, but we recommend to keep children of the root device to a minimum. We also recommend that the preferred parent of a software device be a real device that the software device is extending the functionality for. In situations where a software device doesn't have such a natural parent, create a device as a child of the root that can collect all the software devices that a component will enumerate; then, enumerate the actual software devices as children of this device grouping node. This keeps the children of the root device to a manageable number.
A pointer to a SW_DEVICE_CREATE_INFO structure that describes info that PnP uses to create the device.
The number of DEVPROPERTY structures in the pProperties array.
An optional array of DEVPROPERTY structures. These properties are set on the device after it is created but before a notification that the device has been created are sent. For more info, see Remarks. This pointer can be NULL.
The SW_DEVICE_CREATE_CALLBACK callback function that the operating system calls after PnP enumerates the device.
An optional client context that the operating system passes to the callback function. This pointer can be NULL.
A pointer to a variable that receives the HSWDEVICE handle that represents the device. Call SwDeviceClose to close this handle after the client app wants PnP to remove the device.
DECLARE_HANDLE(HSWDEVICE); typedef HSWDEVICE *PHSWDEVICE;
S_OK is returned if device enumeration was successfully initiated. This does not mean that the device has been successfully enumerated. Check the CreateResult parameter of the SW_DEVICE_CREATE_CALLBACK callback function to determine if the device was successfully enumerated.
SwDeviceCreate returns a handle that represents the device. After this handle is closed, PnP will remove the device.
The calling process must have Administrator access in order to initiate the enumeration of a software device.
PnP forms the device instance ID of a software device as "SWD<pszEnumeratorName><pszInstanceId>," but this string might change or PnP might decorate the name. Always get the device instance ID from the callback function.
There is a subtle difference between properties that are set as part of a SwDeviceCreate call and properties that are later set by calling SwDevicePropertySet. Properties that are set as part of SwDeviceCreate are stored in memory; if the device is uninstalled or a null driver wipes out the property stores, these properties are written out again by the Software Device API feature when PnP re-enumerates the devices. This is all transparent to the client. Properties that are set using SwDevicePropertySet after the enumeration don't persist in memory. But, if you set a property by using SwDeviceCreate, you can update the value with SwDevicePropertySet, and this update is applied to the in-memory value as well as the persisted store.
We recommend that all properties be specified as part of the call to SwDeviceCreate when possible and that these properties be specified for every call to SwDeviceCreate.
|Minimum supported client||Windows 8|
|Minimum supported server||Windows Server 2012|
|Library||Swdevice.lib; OneCoreUAP.lib on Windows 10|