Fungsi WdfControlDeviceInitAllocate (wdfcontrol.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfControlDeviceInitAllocate mengalokasikan struktur WDFDEVICE_INIT yang digunakan driver saat membuat objek perangkat kontrol baru.

Sintaks

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

Parameter

[in] Driver

Handel ke objek driver kerangka kerja.

[in] SDDLString

Penunjuk ke struktur UNICODE_STRING yang menjelaskan string Unicode. String ini adalah representasi Security Descriptor Definition Language (SDDL) dari deskriptor keamanan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

WdfControlDeviceInitAllocate mengembalikan pointer ke struktur WDFDEVICE_INIT yang dialokasikan kerangka kerja, jika operasi berhasil. Jika tidak, metode mengembalikan NULL.

Keterangan

Jika Anda ingin driver Anda membuat objek perangkat kontrol, driver harus memanggil WdfControlDeviceInitAllocate untuk mendapatkan struktur WDFDEVICE_INIT yang dapat diteruskan ke WdfDeviceCreate.

Driver Anda dapat menentukan pengaturan keamanan dengan menggunakan subset SDDL. File Wdmsec.h menentukan sekumpulan konstanta berformat SDDL_DEVOBJ_Xxx yang dapat Anda gunakan. Untuk informasi selengkapnya tentang deskriptor keamanan dan SDDL, lihat Mengamankan Objek Perangkat.

Metode WdfDeviceInitAssignSDDLString menimpa pengaturan keamanan, jika ada, yang ditentukan WdfControlDeviceInitAllocate .

Untuk informasi selengkapnya tentang memanggil WdfControlDeviceInitAllocate, lihat Menggunakan Objek Perangkat Kontrol.

Contoh

Contoh kode berikut mengalokasikan struktur DEVICE_INIT, menetapkan nama objek perangkat, mendaftarkan fungsi panggilan balik pemberitahuan matikan, dan membuat objek perangkat kontrol. Untuk contoh yang lebih kompleks yang menggunakan WdfControlDeviceInitAllocate, lihat driver sampel NONPNP atau driver sampel 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);

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfcontrol.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan 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)