Fungsi KsAllocateObjectHeader (ks.h)
Fungsi KsAllocateObjectHeader menginisialisasi header konteks file yang diperlukan.
Sintaks
KSDDKAPI NTSTATUS KsAllocateObjectHeader(
[out] KSOBJECT_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList,
[in] PIRP Irp,
[in] const KSDISPATCH_TABLE *Table
);
Parameter
[out] Header
Arahkan ke lokasi yang dialokasikan penelepon untuk mengembalikan penunjuk ke KSOBJECT_HEADER yang diinisialisasi jika berhasil.
[in] ItemsCount
Menentukan jumlah item buat objek di Daftar Item yang akan ditambahkan ke header objek setelah header dialokasikan. Nilai ini harus nol jika ItemsList adalah NULL.
[in, optional] ItemsList
Secara opsional menentukan penunjuk ke buffer yang dialokasikan pemanggil yang berisi serangkaian struktur KSOBJECT_CREATE_ITEM untuk ditambahkan ke header objek. Harus diatur ke NULL jika tidak ada item pembuatan objek.
[in] Irp
Menunjuk ke IRP, dari fungsi utama IRP_MJ_CREATE, yang berisi informasi yang diperlukan untuk menyelesaikan pembuatan header objek.
[in] Table
Menunjuk ke tabel pengiriman yang diinisialisasi untuk objek file ini.
Nilai kembali
Fungsi KsAllocateObjectHeader mengembalikan STATUS_SUCCESS jika berhasil atau STATUS_INSUFFICIENT_RESOURCES jika tidak ada cukup sumber daya yang tersedia untuk memenuhi permintaan.
Keterangan
Sebelum memanggil rutinitas ini, driver harus mengalokasikan penyimpanan residen sistem untuk KSDISPATCH_TABLE dan menginisialisasi tabel pengiriman. Memori untuk tabel pengiriman ini tidak dapat dilepaskan sampai KsFreeObjectHeader dipanggil.
KsAllocateObjectHeader mengalokasikan memori untuk struktur KSOBJECT_HEADER dan mengembalikan penunjuk ke header di Header. Driver tidak boleh mencoba membebaskan memori itu sendiri, melainkan memanggil KsFreeObjectHeader ketika semua operasi yang memerlukan header objek ini telah selesai.
Jika subobjek ada untuk perangkat tertentu, driver harus, sebelum memanggil KsAllocateObjectHeader, alokasikan buffer memori berhalaman atau tidak berhalaman dengan ukuran yang cukup untuk menyimpan struktur KSOBJECT_CREATE_ITEM untuk setiap subobjek. Contohnya:
/* Allocate a buffer for 4 subobjects for a given streaming device */
PKSOBJECT_CREATE_ITEM createBuffer ;
ULONG bufferSize = (sizeof (KSOBJECT_CREATE_ITEM)) * 4 ;
createBuffer = (PKSOBJECT_CREATE_ITEM)
ExAllocatePoolWithTag (PagedPool, bufferSize) ;
Driver tidak boleh membebaskan memori yang dialokasikan untuk daftar KSOBJECT_CREATE_ITEM subobject sampai setelah memanggil KsFreeDeviceHeader. Kegagalan untuk melakukannya dapat mengakibatkan kondisi pemeriksaan bug.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | ks.h (termasuk Ks.h) |
| Pustaka | Ks.lib |
| IRQL | < DISPATCH_LEVEL |