WdfControlDeviceInitAllocate 函数 (wdfcontrol.h)

项目
08/08/2023

[仅适用于 KMDF]

WdfControlDeviceInitAllocate 方法分配驱动程序在创建新的控制设备对象时使用的WDFDEVICE_INIT结构。

语法

PWDFDEVICE_INIT WdfControlDeviceInitAllocate(
  [in] WDFDRIVER            Driver,
  [in] const UNICODE_STRING *SDDLString
);

参数

[in] Driver

框架驱动程序对象的句柄。

[in] SDDLString

指向描述 Unicode 字符串的UNICODE_STRING 结构的指针。此字符串是安全描述符定义语言 (SDDL) 安全描述符的表示形式。有关更多信息，请参见下面的“备注”部分。

返回值

如果操作成功，WdfControlDeviceInitAllocate 返回指向框架分配的WDFDEVICE_INIT结构的指针。否则，方法返回 NULL。

注解

如果希望驱动程序创建控制设备对象，驱动程序必须调用 WdfControlDeviceInitAllocate 以获取可传递给 WdfDeviceCreate 的WDFDEVICE_INIT结构。

驱动程序可以使用 SDDL 的子集指定安全设置。 Wdmsec.h 文件定义一组可以使用的SDDL_DEVOBJ_Xxx 格式常量。有关安全描述符和 SDDL 的详细信息，请参阅保护设备对象。

WdfDeviceInitAssignSDDLString 方法将覆盖 WdfControlDeviceInitAllocate 指定的安全设置（如果有）。

有关调用 WdfControlDeviceInitAllocate 的详细信息，请参阅使用控制设备对象。

示例

下面的代码示例分配DEVICE_INIT结构，分配设备对象名称，注册关闭通知回调函数，并创建控制设备对象。有关使用 WdfControlDeviceInitAllocate 的更复杂的示例，请参阅 NONPNP 示例驱动程序或 NDISProt 示例驱动程序。

PWDFDEVICE_INIT  deviceInit = NULL;
NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  objectAttribs;

deviceInit = WdfControlDeviceInitAllocate(
                                          hDriver,
                                          &SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R
                                          );
if (deviceInit == NULL) {
    status = STATUS_INSUFFICIENT_RESOURCES;
    goto Error;
}
status = WdfDeviceInitAssignName(
                                 deviceInit,
                                 &ntDeviceName
                                 );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlDeviceInitSetShutdownNotification(
                                            deviceInit,
                                            EvtShutdownNotification,
                                            WdfDeviceShutdown
                                            );
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);

status = WdfDeviceCreate(
                         &deviceInit,
                         &objectAttribs,
                         &controlDevice
                         );
if (!NT_SUCCESS(status)) {
    WdfDeviceInitFree(deviceInit);
    deviceInit = NULL;
    goto Error;
}
WdfControlFinishInitializing(controlDevice);

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
标头	wdfcontrol.h (包括 Wdf.h)
Library	Wdf01000.sys (请参阅框架库版本控制.)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	ControlDeviceInitAPI (kmdf) ， CtlDeviceFinishInitDeviceAdd (kmdf) ， CtlDeviceFinishInitDrEntry (kmdf) ， DoubleDeviceInitFree (kmdf) ， DriverCreate (kmdf) ， InitFreeDeviceCallback (kmdf) 、 InitFreeDeviceCreate (kmdf) 、 InitFreeDeviceCreateType2 (kmdf) 、 InitFreeDeviceCreateType4 (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf)