WdfPdoInitAssignInstanceID function (wdfpdo.h)

[Applies to KMDF only]

The WdfPdoInitAssignInstanceID method updates the instance ID for a child device.

Syntax

NTSTATUS WdfPdoInitAssignInstanceID(
  [in] PWDFDEVICE_INIT  DeviceInit,
  [in] PCUNICODE_STRING InstanceID
);

Parameters

[in] DeviceInit

A pointer to a WDFDEVICE_INIT structure.

[in] InstanceID

A pointer to a UNICODE_STRING structure that contains an instance ID string. The driver can allocate the string's buffer from paged pool.

Return value

If the operation succeeds, the method returns STATUS_SUCCESS. Additional return values include:

Return code Description
STATUS_INVALID_DEVICE_REQUEST
The driver is initializing an FDO instead of a PDO.
STATUS_INSUFFICIENT_RESOURCES
The driver could not allocate space to store the instance ID string.
 

The method might also return other NTSTATUS values.

Remarks

For more information about instance IDs, see Device Identification Strings.

The driver must call WdfPdoInitAssignInstanceID before calling WdfDeviceCreate. For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

Examples

The following code example converts a device's serial number to a Unicode string and then registers the Unicode string as the device's instance ID.

DECLARE_UNICODE_STRING_SIZE(instanceID, INSTANCEID_LENGTH);

status =  RtlIntegerToUnicodeString(
                                    SerialNo,
                                    BASE_DEC,
                                    &instanceID
                                    );
status = WdfPdoInitAssignInstanceID(
                                    pDeviceInit,
                                    &instanceID
                                    );

Requirements

Requirement Value
Target Platform Universal
Minimum KMDF version 1.0
Header wdfpdo.h (include Wdf.h)
Library Wdf01000.sys (see Framework Library Versioning.)
IRQL PASSIVE_LEVEL
DDI compliance rules ChildDeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)

See also

RtlIntegerToUnicodeString

WdfPdoInitAddCompatibleID

WdfPdoInitAddHardwareID

WdfPdoInitAssignDeviceID