Expandir Minimizar

WdfDeviceRetrieveDeviceInterfaceString method

[Applies to KMDF and UMDF]

The WdfDeviceRetrieveDeviceInterfaceString method retrieves the symbolic link name that the operating system assigned to a device interface that the driver registered for a specified device.

Syntax


NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]            WDFDEVICE Device,
  [in]            const GUID *InterfaceClassGUID,
  [in, optional]  PCUNICODE_STRING ReferenceString,
  [in]            WDFSTRING String
);

Parameters

Device [in]

A handle to a framework device object.

InterfaceClassGUID [in]

A pointer to a GUID that identifies the device interface class.

ReferenceString [in, optional]

A pointer to a UNICODE_STRING structure that describes a reference string for the device interface. This parameter is optional and can be NULL if the driver did not specify a reference string when it called WdfDeviceCreateDeviceInterface.

String [in]

A handle to a framework string object. The framework will assign the symbolic link name's Unicode string to the string object.

Return value

WdfDeviceRetrieveDeviceInterfaceString returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:

Return codeDescription
STATUS_INVALID_DEVICE_REQUEST

WdfDeviceRetrieveDeviceInterfaceString was not called at IRQL = PASSIVE_LEVEL.

STATUS_INVALID_PARAMETER

An invalid parameter was specified.

STATUS_INVALID_DEVICE_REQUEST

The specified device object was initialized by WdfControlDeviceInitAllocate.

STATUS_OBJECT_NAME_NOT_FOUND

A device interface that matches the specified GUID and reference string could not be found.

STATUS_INVALID_DEVICE_STATE

The driver called WdfDeviceCreateDeviceInterface but the system has not yet assigned a symbolic link name to the device interface.

 

WdfDeviceRetrieveDeviceInterfaceString might also return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

For more information about device interfaces, see Using Device Interfaces.

Examples

The following code example creates a string object and then retrieves a specified device interface's symbolic link name.


NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfdevice.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

PASSIVE_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

UNICODE_STRING
WdfStringCreate
WdfControlDeviceInitAllocate
WdfDeviceCreateDeviceInterface

 

 

Send comments about this topic to Microsoft

Mostrar:
© 2014 Microsoft