WdfControlDeviceInitAllocate 函式 (wdfcontrol.h)

發行項
02/27/2024

[僅適用於 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);

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfcontrol.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	ControlDeviceInitAPI (kmdf) ， CtlDeviceFinishInitDeviceAdd (kmdf) ， CtlDeviceFinishInitDrEntry (kmdf ) ， DoubleDeviceInitFree (kmdf) ， DriverCreate (kmdf) ， InitFreeDeviceCCallback (kmdf) 、 InitFreeDeviceCreate (kmdf) 、 InitFreeDeviceCreateType2 (kmdf) 、 InitFreeDeviceCreateType4 (kmdf ) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、KmdfIrqlExplicit (kmdf)