Metode IWDFDriver::CreatePreallocatedWdfMemory (wudfddi.h)

Artikel
08/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode CreatePreallocatedWdfMemory membuat objek memori kerangka kerja untuk buffer yang ditentukan.

Sintaks

HRESULT CreatePreallocatedWdfMemory(
  [in]           BYTE       *pBuff,
  [in]           SIZE_T     BufferSize,
  [in, optional] IUnknown   *pCallbackInterface,
  [in, optional] IWDFObject *pParentObject,
  [out]          IWDFMemory **ppWdfMemory
);

Parameter

[in] pBuff

Penunjuk ke buffer data yang disediakan driver untuk objek memori.

[in] BufferSize

Ukuran, dalam byte, dari data yang menunjuk pBuff .

[in, optional] pCallbackInterface

Penunjuk ke antarmuka IUnknown yang digunakan kerangka kerja untuk menentukan fungsi panggilan balik peristiwa terkait objek yang berlangganan driver pada objek memori yang baru dibuat. Parameter ini bersifat opsional. Driver dapat melewati NULL jika driver tidak memerlukan pemberitahuan. Antarmuka IUnknown digunakan untuk pembersihan dan pembuangan objek. Jika driver melewati pointer yang valid, kerangka kerja akan memanggil QueryInterface pada antarmuka IUnknown untuk antarmuka IObjectCleanup . Jika kerangka kerja mendapatkan antarmuka IObjectCleanup driver, kerangka kerja kemudian dapat memanggil metode IObjectCleanup::OnCleanup driver untuk memberi tahu driver bahwa objek memori dibersihkan.

[in, optional] pParentObject

Penunjuk ke antarmuka IWDFObject untuk objek induk objek memori yang dibuat. Jika NULL, objek driver menjadi induk default.

[out] ppWdfMemory

Penunjuk ke buffer yang menerima penunjuk ke antarmuka IWDFMemory untuk objek memori WDF yang baru dibuat.

Mengembalikan nilai

CreatePreallocatedWdfMemory mengembalikan S_OK jika operasi berhasil. Jika tidak, metode ini mengembalikan salah satu kode kesalahan yang ditentukan dalam Winerror.h.

Keterangan

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

Driver UMDF dapat memanggil CreatePreallocatedWdfMemory jika harus 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 CreatePreallocatedWdfMemory untuk membuat objek memori sehingga driver dapat meneruskan struktur ke target I/O.

Setelah driver UMDF memanggil CreatePreallocatedWdfMemory, driver dapat memanggil IWDFMemory::SetBuffer untuk menetapkan buffer yang berbeda ke objek memori yang dibuat CreatePreallocatedWdfMemory .

Ketika objek memori kerangka kerja yang dibuat CreatePreallocatedWdfMemory dihapus, kerangka kerja tidak membatalkan alokasi buffer yang sudah ada sebelumnya. Demikian juga, panggilan ke IWDFMemory::SetBuffer tidak membatalkan alokasi buffer yang ditetapkan sebelumnya.

Contoh

Contoh kode berikut menunjukkan cara membuat objek memori untuk buffer.

    //
    // Allocate a request.
    hr = wdfDevice->CreateRequest(NULL, NULL, &request);

    // Allocate a buffer and wrap it in a memory object. 
    // Make the memory object a child of the request. 
    // When the request object is deleted, the memory object 
    // is also deleted. 

    if (SUCCEEDED(hr))
    {
       buffer = new BYTE[m_HidDescriptor->wReportLength];

       if (buffer == NULL)
       {
          hr = E_OUTOFMEMORY;
       }
    }

    if (SUCCEEDED(hr))
    {
       CComPtr<IWDFDriver> driver;
       wdfDevice->GetDriver(&driver);

       hr = driver->CreatePreallocatedWdfMemory(
                       buffer,
                       m_HidDescriptor->wReportLength,
                       NULL,
                       request,
                       &memory
                       );
    }

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1,5
Header	wudfddi.h (termasuk Wudfddi.h)
DLL	WUDFx.dll