KsAllocateDeviceHeader function (ks.h)
The KsAllocateDeviceHeader function allocates and initializes the required device extension header.
Syntax
KSDDKAPI NTSTATUS KsAllocateDeviceHeader(
[out] KSDEVICE_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList
);
Parameters
[out] Header
Points to the location in which to return a pointer to the initialized header.
[in] ItemsCount
Specifies the number of subitems in the ItemsList. This should be zero if an ItemsList is not passed.
[in, optional] ItemsList
Optional. Points to a KSOBJECT_CREATE_ITEM structure for each subitem. If there are no subitems, this value should be NULL and ItemsCount should be zero.
Return value
The KsAllocateDeviceHeader function returns STATUS_SUCCESS if successful or STATUS_INSUFFICIENT_RESOURCES if unable to allocate the necessary resources.
Remarks
The KsAllocateDeviceHeader function allocates memory for the KSDEVICE_HEADER structure for a device. When the header is no longer needed, the driver should call the KsFreeDeviceHeader function to free the memory allocated.
If subobjects exist for a given device, the driver must, before calling KsAllocateDeviceHeader, 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) ;
Drivers must not free the memory allocated for the subobject KSOBJECT_CREATE_ITEM list until after calling KsFreeDeviceHeader. Failure to do so can result in a bug check condition.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | ks.h (include Ks.h) |
| Library | Ks.lib |
| IRQL | < DISPATCH_LEVEL |