struktur WDF_OBJECT_ATTRIBUTES (wdfobject.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Struktur WDF_OBJECT_ATTRIBUTES menjelaskan atribut yang dapat dikaitkan dengan objek kerangka kerja apa pun.

Sintaks

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

Anggota

Size

Ukuran, dalam byte, dari struktur ini.

EvtCleanupCallback

Penunjuk ke fungsi panggilan balik EvtCleanupCallback driver, atau NULL.

EvtDestroyCallback

Penunjuk ke fungsi panggilan balik EvtDestroyCallback driver, atau NULL.

ExecutionLevel

Nilai yang diketik WDF_EXECUTION_LEVEL yang menentukan IRQL maksimum tempat kerangka kerja akan memanggil fungsi panggilan balik peristiwa objek. Untuk daftar objek kerangka kerja yang drivernya dapat menentukan nilai ExecutionLevel , lihat WDF_EXECUTION_LEVEL.

SynchronizationScope

Nilai yang diketik WDF_SYNCHRONIZATION_SCOPE yang menentukan bagaimana kerangka kerja akan menyinkronkan eksekusi fungsi panggilan balik peristiwa objek. Untuk daftar objek kerangka kerja yang drivernya dapat menentukan nilai SynchronizationScope , lihat WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Handel ke objek induk objek, atau NULL jika objek tidak memiliki induk yang ditentukan driver.

Lihat Ringkasan Objek Kerangka Kerja untuk tabel yang memperlihatkan objek yang mengizinkan induk yang ditentukan driver. Tabel juga memperlihatkan induk default dari setiap objek.

ContextSizeOverride

Jika bukan nol, nilai ini mengambil alih anggota ContextSize dari struktur WDF_OBJECT_CONTEXT_TYPE_INFO yang dirujuk anggota ContextTypeInfo . Nilai ini bersifat opsional dan bisa nol. Jika nilainya bukan nol, nilai harus menentukan ukuran, dalam byte, yang lebih besar dari nilai yang ditentukan untuk anggota ContextSize dari struktur WDF_OBJECT_CONTEXT_TYPE_INFO. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

ContextTypeInfo

Penunjuk ke struktur WDF_OBJECT_CONTEXT_TYPE_INFO . Makro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE mengatur penunjuk ini.

Keterangan

Struktur WDF_OBJECT_ATTRIBUTES digunakan sebagai argumen input ke beberapa metode yang membuat objek kerangka kerja.

Untuk menginisialisasi struktur WDF_OBJECT_ATTRIBUTES, driver harus memanggil WDF_OBJECT_ATTRIBUTES_INIT.

Selain itu, jika Anda menentukan informasi konteks khusus objek untuk objek, Anda harus menggunakan makro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE .

Atau, Anda dapat menggunakan makro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE alih-alih makro WDF_OBJECT_ATTRIBUTES_INIT dan WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE.

Untuk informasi selengkapnya tentang menggunakan makro ini, lihat Ruang Konteks Objek Kerangka Kerja.

Gunakan anggota ContextSizeOverride dari WDF_OBJECT_ATTRIBUTES jika Anda ingin membuat ruang konteks objek yang memiliki panjang variabel. Misalnya, Anda dapat menentukan struktur ruang konteks yang berisi array, sebagai berikut:

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Saat driver Anda membuat objek yang menggunakan struktur ruang konteks, driver dapat menggunakan anggota ContextSizeOverride untuk menentukan ukuran konteks yang diperlukan untuk setiap objek individual. Misalnya, driver Anda mungkin menghitung jumlah byte yang diperlukan dalam array dari contoh sebelumnya lalu menggunakan ContextSizeOverride untuk menentukan byte tambahan, sebagai berikut:

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

Driver kemudian dapat membuat objek dengan ukuran konteks yang disesuaikan.

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

Untuk informasi selengkapnya tentang aturan pembersihan untuk hierarki objek kerangka kerja, lihat Siklus Hidup Objek Kerangka Kerja.