The KsAllocateObjectHeader function initializes the required file context header.
NTSTATUS KsAllocateObjectHeader( _Out_ KSOBJECT_HEADER *Header, _In_ ULONG ItemsCount, _In_opt_ PKSOBJECT_CREATE_ITEM ItemsList, _In_ PIRP Irp, _In_ const KSDISPATCH_TABLE *Table );
Points to the caller-allocated location in which to return a pointer to the initialized KSOBJECT_HEADER if successful.
Specifies the number of object create items in the ItemsList to be added to the object header once the header is allocated. This value should be zero if ItemsList is NULL.
Optionally specifies a pointer to a caller-allocated buffer containing a series of KSOBJECT_CREATE_ITEM structures to be added to the object header. Must be set to NULL if there are no object create items.
Points to the IRP, of major function IRP_MJ_CREATE, that contains the necessary information to complete the creation of the object header.
Points to an initialized dispatch table for this file object.
The KsAllocateObjectHeader function returns STATUS_SUCCESS if successful or STATUS_INSUFFICIENT_RESOURCES if not enough resources are available to fulfill the request.
Before calling this routine the driver must allocate system-resident storage for a KSDISPATCH_TABLE and initialize the dispatch table. The memory for this dispatch table cannot be released until KsFreeObjectHeader is called.
KsAllocateObjectHeader allocates the memory for the KSOBJECT_HEADER structure and returns a pointer to the header at Header. Drivers must not attempt to free the memory themselves, but rather call KsFreeObjectHeader when all operations requiring this object header have been completed.
If subobjects exist for a given device, the driver must, before calling KsAllocateObjectHeader, allocate a buffer of either paged or nonpaged memory of sufficient size to hold a KSOBJECT_CREATE_ITEM structure for each subobject. For example:
/* 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) ;
|Header||ks.h (include Ks.h)|