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。 否则,该方法可能会返回以下值之一:
返回代码 | 说明 |
---|---|
|
未在 IRQL = PASSIVE_LEVEL调用 WdfDeviceRetrieveDeviceInterfaceString。 |
|
指定的参数无效。 |
|
指定的设备对象已由 WdfControlDeviceInitAllocate 初始化。 |
|
找不到与指定的 GUID 和引用字符串匹配的设备接口。 |
|
驱动程序名为 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) |