FltAllocateCallbackData - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// fltkernel.h
NTSTATUS FLTAPI FltAllocateCallbackData(
[in] PFLT_INSTANCE Instance,
[in, optional] PFILE_OBJECT FileObject,
[out] PFLT_CALLBACK_DATA *RetNewCallbackData
);
View the official Windows Driver Kit DDI referenceNo description available.
FltAllocateCallbackData allocates a callback data structure that a minifilter driver can use to initiate an I/O request.
Instance [in]Opaque instance pointer for the minifilter driver instance that is initiating the I/O operation. This parameter is required and cannot be NULL.
FileObject [in, optional]File object pointer to be used in the I/O operation. This parameter is optional and can be NULL.
RetNewCallbackData [out]Pointer to a caller-allocated variable that receives the address of the newly allocated callback data (FLT_CALLBACK_DATA) structure.
FltAllocateCallbackData returns STATUS_SUCCESS or an appropriate NTSTATUS value such as the following:
| Return code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | FltAllocateCallbackData encountered a pool allocation failure when attempting to allocate the callback data structure. This is an error code. |
A minifilter driver can call FltAllocateCallbackData to allocate a callback data (FLT_CALLBACK_DATA) structure for an I/O operation initiated by the minifilter driver.
Note The FltAllocateCallbackData routine does not allocate all the memory that might be required by a subsequent I/O request. If an I/O request, such as FltPerformSynchronousIo or FltPerformAsynchronousIo, requires additional memory for some structure, the request could encounter a memory allocation. The FltAllocateCallbackDataEx routine can be used to avoid this potential problem by preallocating memory for additional structures to be used in an I/O request. If there is a memory allocation problem for either the RetNewCallbackData structure or additional required structures, it can be dealt with at the point of callback data allocation.
Callback data structures are allocated from nonpaged pool.
After initializing the parameters of the callback data structure returned by FltAllocateCallbackData, the caller initiates the I/O operation by passing the structure to FltPerformSynchronousIo or FltPerformAsynchronousIo. These routines send the I/O operation only to the minifilter driver instances attached below the initiating instance (specified in the Instance parameter) and to the file system. Minifilter drivers attached above the specified instance do not receive the I/O operation.
Minifilter drivers can only initiate IRP-based I/O operations. They cannot initiate fast I/O or file system filter (FSFilter) callback operations.
Minifilter drivers should use FltAllocateCallbackData, FltPerformAsynchronousIo, and FltPerformSynchronousIo only for I/O operations for which routines such as the following cannot be used:
When the callback data structure allocated by FltAllocateCallbackData is no longer needed, the caller is responsible for freeing it by calling FltFreeCallbackData.