KsAllocateObjectHeader 函式 (ks.h)
KsAllocateObjectHeader 函式會初始化必要的檔案內容標頭。
語法
KSDDKAPI NTSTATUS KsAllocateObjectHeader(
[out] KSOBJECT_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList,
[in] PIRP Irp,
[in] const KSDISPATCH_TABLE *Table
);
參數
[out] Header
指向呼叫端配置的位置，如果成功，則會將指標傳回初始化 KSOBJECT_HEADER 。
[in] ItemsCount
指定在配置標頭之後，要加入至對象標頭之 ItemsList 中的物件建立項目數目。 如果 ItemsList 為 NULL，此值應該為零。
[in, optional] ItemsList
選擇性地指定呼叫端配置的緩衝區指標，其中包含要新增至對象標頭的一系列 KSOBJECT_CREATE_ITEM 結構。 如果沒有物件建立專案，則必須設定為 NULL 。
[in] Irp
指向主要函式 IRP_MJ_CREATE的 IRP，其中包含完成對象標頭建立所需的資訊。
[in] Table
指向這個檔案物件的初始化分派數據表。
傳回值
如果成功，則 KsAllocateObjectHeader 函式會傳回 STATUS_SUCCESS ，如果沒有足夠的資源可供滿足要求， 則傳回STATUS_INSUFFICIENT_RESOURCES 。
備註
呼叫此例程之前，驅動程式必須為 KSDISPATCH_TABLE 配置系統駐留記憶體，並初始化分派數據表。 呼叫 KsFreeObjectHeader 之前，無法釋放此分派數據表的記憶體。
KsAllocateObjectHeader 會為 KSOBJECT_HEADER 結構配置記憶體，並傳回 標頭的指標。 驅動程式不得嘗試釋放記憶體本身，而是在完成需要此對象標頭的所有作業時呼叫 KsFreeObjectHeader 。
如果給定裝置有子物件存在，驅動程式必須先呼叫 KsAllocateObjectHeader，再配置已分頁或未分頁記憶體的緩衝區，以保留每個子物件的 KSOBJECT_CREATE_ITEM 結構。 例如：
/* 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) ;
驅動程式在呼叫 KsFreeDeviceHeader 之前，不得釋放配置給子物件KSOBJECT_CREATE_ITEM清單的記憶體。 無法這麼做可能會導致錯誤檢查條件。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 標頭 | ks.h (包含 Ks.h) |
| 程式庫 | Ks.lib |
| IRQL | < DISPATCH_LEVEL |