Fungsi WdfMemoryCreatePreallocated (wdfmemory.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfMemoryCreatePreallocated membuat objek memori kerangka kerja untuk buffer memori yang disediakan driver.

Sintaks

NTSTATUS WdfMemoryCreatePreallocated(
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           __drv_aliasesMem PVOID Buffer,
  [in]           size_t                 BufferSize,
  [out]          WDFMEMORY              *Memory
);

Parameter

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang berisi atribut objek untuk objek memori baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Penunjuk ke buffer yang disediakan driver.

[in] BufferSize

Ukuran bukan nol, dalam byte, dari buffer yang ditinjuk Buffer .

[out] Memory

Penunjuk ke lokasi yang menerima handel ke objek memori baru.

Nilai kembali

WdfMemoryCreatePreallocated mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfMemoryCreatePreallocated , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Keterangan

Metode WdfMemoryCreatePreallocated membuat objek memori kerangka kerja untuk buffer yang sebelumnya telah dialokasikan atau diperoleh driver.

Driver Anda dapat memanggil WdfMemoryCreatePreallocated jika Anda perlu membuat objek memori yang mewakili buffer memori yang sudah ada sebelumnya. Misalnya, driver mungkin menerima struktur yang ditentukan driver dalam buffer untuk permintaan I/O yang berisi kode kontrol I/O internal. Driver dapat memanggil WdfMemoryCreatePreallocated untuk membuat objek memori sehingga driver dapat meneruskan struktur ke target I/O.

Setelah driver memanggil WdfMemoryCreatePreallocated, driver dapat memanggil WdfMemoryAssignBuffer untuk menetapkan buffer yang berbeda ke objek memori yang dibuat WdfMemoryCreatePreallocated .

Objek induk default untuk setiap objek memori adalah objek driver kerangka kerja yang mewakili driver yang disebut WdfMemoryCreatePreallocated. Jika driver Anda membuat objek memori yang digunakannya dengan objek perangkat tertentu, objek permintaan, atau objek kerangka kerja lainnya, itu harus mengatur induk objek memori dengan tepat. Objek memori akan dihapus ketika objek induk dihapus. Jika Anda tidak mengubah objek induk default, objek memori akan tetap berada dalam memori hingga manajer I/O membongkar driver Anda.

Driver juga dapat menghapus objek memori dengan memanggil WdfObjectDelete.

Ketika objek memori kerangka kerja yang dibuat WdfMemoryCreatePreallocated dihapus, kerangka kerja tidak membatalkan alokasi buffer yang sudah ada sebelumnya. Demikian juga, panggilan ke WdfMemoryAssignBuffer tidak membatalkan alokasi buffer yang ditetapkan sebelumnya.

Untuk informasi selengkapnya tentang objek memori kerangka kerja, lihat Menggunakan Buffer Memori.

Contoh

Contoh kode berikut mengalokasikan buffer lalu membuat objek memori kerangka kerja untuk buffer.

PVOID  pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  memHandle;

pBuffer = ExAllocatePoolWithTag(
                                NonPagedPool,
                                MY_BUFFER_SIZE,
                                MY_DRIVER_TAG
                                );
if (pBuffer == NULL){
    goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;

status = WdfMemoryCreatePreallocated(
                                     &attributes,
                                     pBuffer,
                                     MY_BUFFER_SIZE,
                                     &memHandle
                                     );

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfmemory.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)