WdfDeviceRetrieveDeviceInterfaceString 函数 (wdfdevice.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfDeviceRetrieveDeviceInterfaceString 方法检索操作系统分配给驱动程序为指定设备注册的设备接口的符号链接名称。

语法

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

参数

[in] Device

框架设备对象的句柄。

[in] InterfaceClassGUID

指向标识设备接口类的 GUID 的指针。

[in, optional] ReferenceString

指向描述设备接口的引用字符串 的 UNICODE_STRING 结构的指针。 此参数是可选的，如果驱动程序在调用 WdfDeviceCreateDeviceInterface 时未指定引用字符串，则该参数可为 NULL。

[in] String

框架字符串对象的句柄。 框架会将符号链接名称的 Unicode 字符串分配给字符串对象。

返回值

如果操作成功，WdfDeviceRetrieveDeviceInterfaceString 将返回STATUS_SUCCESS。 否则，该方法可能会返回以下值之一：

返回代码 说明
STATUS_INVALID_DEVICE_REQUEST

未在 IRQL = PASSIVE_LEVEL调用 WdfDeviceRetrieveDeviceInterfaceString。
STATUS_INVALID_PARAMETER
 指定的参数无效。
STATUS_INVALID_DEVICE_REQUEST
 指定的设备对象已由 WdfControlDeviceInitAllocate 初始化。
STATUS_OBJECT_NAME_NOT_FOUND
 找不到与指定的 GUID 和引用字符串匹配的设备接口。
STATUS_INVALID_DEVICE_STATE
 驱动程序名为 WdfDeviceCreateDeviceInterface ，但系统尚未向设备接口分配符号链接名称。
 

WdfDeviceRetrieveDeviceInterfaceString 也可能返回其他 NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

有关设备接口的详细信息，请参阅 使用设备接口。

示例

下面的代码示例创建一个字符串对象，然后检索指定设备接口的符号链接名称。

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;
    }
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfdevice.h (包括 Wdf.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另请参阅

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate