FltAllocateCallbackData function (fltkernel.h)

  • Article

FltAllocateCallbackData allocates a callback data structure that a minifilter driver can use to initiate an I/O request.

Syntax

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parameters

[in] Instance

Opaque instance pointer for the minifilter driver instance that is initiating the I/O operation. This parameter is required and cannot be NULL.

[in, optional] FileObject

File object pointer to be used in the I/O operation. This parameter is optional and can be NULL.

[out] RetNewCallbackData

Pointer to a caller-allocated variable that receives the address of the newly allocated callback data (FLT_CALLBACK_DATA) structure.

Return value

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.

Remarks

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:

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

When the callback data structure allocated by FltAllocateCallbackData is no longer needed, the caller is responsible for freeing it by calling FltFreeCallbackData.

Requirements

Requirement Value
Target Platform Universal
Header fltkernel.h (include Fltkernel.h)
Library FltMgr.lib
IRQL <= APC_LEVEL

See also

FLT_CALLBACK_DATA

FltClose

FltCreateFile

FltFreeCallbackData

FltPerformAsynchronousIo

FltPerformSynchronousIo

FltQueryVolumeInformation

FltReadFile

FltReissueSynchronousIo

FltReuseCallbackData

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile