Ruang Konteks Objek Kerangka Kerja

Ruang konteks objek adalah ruang memori tambahan, tidak dapat dialihkan ke halaman, yang dapat dialokasikan dan ditetapkan driver ke objek. Setiap driver berbasis kerangka kerja dapat membuat satu atau beberapa ruang konteks khusus objek untuk setiap objek kerangka kerja yang diterima atau dibuat driver.

Driver berbasis kerangka kerja harus menyimpan semua data khusus objek, baik berdasarkan nilai atau berdasarkan penunjuk, dalam ruang konteks objek tempat data berada.

Misalnya, driver untuk perangkat USB mungkin membuat ruang konteks untuk objek perangkat kerangka kerjanya. Dalam ruang konteks, driver mungkin menyimpan informasi spesifik perangkat seperti struktur USB_DEVICE_DESCRIPTOR dan USB_CONFIGURATION_DESCRIPTOR, ditambah handle ke objek koleksi yang mewakili pipa antarmuka perangkat.

Kerangka kerja tidak meneruskan objek kerangka kerja dari satu driver ke driver lain, sehingga Anda tidak dapat menggunakan ruang konteks objek untuk meneruskan data di antara dua driver.

Untuk menentukan ruang konteks objek, Anda harus membuat satu atau beberapa struktur. Setiap struktur mewakili ruang konteks terpisah. Driver Anda akan menggunakan setiap anggota struktur untuk menyimpan informasi khusus objek. Selain itu, driver Anda harus meminta kerangka kerja untuk menghasilkan metode aksesor untuk setiap struktur. Metode aksesori ini menerima handle objek sebagai input dan mengembalikan alamat ruang konteks objek.

Setiap kali driver Anda memanggil metode pembuatan objek, seperti WdfDeviceCreate, metode ini secara opsional mengalokasikan ruang konteks. Semua metode pembuatan objek menerima struktur WDF_OBJECT_ATTRIBUTES opsional sebagai input. Struktur ini menjelaskan ruang konteks yang Anda ingin kerangka kerja alokasikan untuk objek.

Untuk menambahkan ruang konteks tambahan ke objek setelah driver memanggil metode pembuatan objek, driver dapat memanggil metode WdfObjectAllocateContext--yang, seperti metode pembuatan objek, menerima struktur WDF_OBJECT_ATTRIBUTES sebagai input.

Saat kerangka kerja mengalokasikan ruang konteks untuk objek, kerangka kerja juga menginisialisasi ruang konteks secara nol.

Saat kerangka kerja atau driver menghapus objek kerangka kerja, kerangka kerja akan menghapus semua ruang konteks objek.

Jika driver Anda menggunakan ruang konteks untuk menyimpan pointer ke buffer yang dialokasikan driver saat membuat objek, driver harus menyediakan fungsi EvtCleanupCallback yang membatalkan alokasi buffer saat objek dihapus.

Untuk menentukan struktur ruang konteks objek dan metode aksesor untuk objek yang dibuat driver Anda, driver Anda harus menggunakan langkah-langkah berikut:

1. Tentukan struktur yang menjelaskan data yang ingin Anda simpan. Misalnya, jika Anda ingin membuat data konteks untuk objek perangkat driver Anda, driver Anda mungkin menentukan struktur yang disebut MY_DEVICE_CONTEXT.

2. Gunakan makro WDF_DECLARE_CONTEXT_TYPE atau makro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME. Kedua makro ini melakukan hal berikut:

   • Membuat dan menginisialisasi struktur WDF_OBJECT_CONTEXT_TYPE_INFO.
   • Tentukan metode aksesor yang nantinya akan digunakan driver Anda untuk mengakses ruang konteks objek. Nilai pengembalian metode aksesor adalah penunjuk ke ruang konteks objek.

   Makro WDF_DECLARE_CONTEXT_TYPE membuat nama metode aksesor dari nama struktur Anda. Misalnya, jika nama struktur konteks Anda MY_DEVICE_CONTEXT, makro membuat metode aksesor yang diberi nama WdfObjectGet_MY_DEVICE_CONTEXT.

   Makro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME memungkinkan Anda menentukan nama metode aksesor. Misalnya, Anda dapat menentukan GetMyDeviceContext sebagai nama untuk metode pengakses konteks untuk objek perangkat.

3. Panggil WDF_OBJECT_ATTRIBUTES_INIT untuk menginisialisasi struktur WDF_OBJECT_ATTRIBUTES objek.

4. Gunakan makro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE untuk mengatur ContextTypeInfo anggota struktur WDF_OBJECT_ATTRIBUTES ke alamat struktur WDF_OBJECT_CONTEXT_TYPE_INFO.

5. Panggil metode pembuatan objek, seperti WdfDeviceCreate.

Setelah driver Anda membuat objek, driver dapat memanggil WdfObjectAllocateContext kapan saja untuk menambahkan ruang konteks tambahan ke objek.

Karena langkah 1 dan 2 menentukan struktur data global dan membuat rutinitas yang dapat dipanggil driver, driver Anda harus menyelesaikan langkah-langkah ini di area driver yang mendeklarasikan data global--biasanya file header. Langkah-langkah ini tidak boleh diselesaikan dari dalam rutinitas pengemudi Anda.

Driver Anda harus menyelesaikan langkah 3, 4, dan 5 dari dalam rutinitas driver yang membuat objek, seperti fungsi panggilan balikEvtDriverDeviceAdd yang memanggil WdfDeviceCreate.

Kerangka kerja dapat membuat dua jenis objek -- objek permintaan kerangka kerja dan objek file kerangka kerja -- atas nama driver Anda. Driver Anda dapat mendaftarkan ruang konteks untuk objek ini dengan memanggil WdfDeviceInitSetRequestAttributes dan WdfDeviceInitSetFileObjectConfig, masing-masing. Driver Anda juga dapat memanggil WdfObjectAllocateContext untuk mengalokasikan ruang konteks untuk objek ini.

Setelah objek dibuat, driver dapat memperoleh penunjuk ke ruang konteks objek dengan menggunakan salah satu teknik berikut:

• Panggil metode pengakses konteks yang Anda buat di langkah 2 dalam prosedur sebelumnya dengan menggunakan WDF_DECLARE_CONTEXT_TYPE atau makro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME.

• Panggil WdfObjectGetTypedContext, memberikan nama struktur konteks yang ditentukan driver Anda.

Jika driver Anda memiliki penunjuk ruang konteks, driver dapat menemukan objek tempat ruang konteks berada dengan memanggil WdfObjectContextGetObject.