Export (0) Print
Expand All
Expand Minimize

FltAllocateCallbackData routine

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

Syntax


NTSTATUS FltAllocateCallbackData(
  _In_      PFLT_INSTANCE Instance,
  _In_opt_  PFILE_OBJECT FileObject,
  _Out_     PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parameters

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.

Return value

FltAllocateCallbackData returns STATUS_SUCCESS or an appropriate NTSTATUS value such as the following:

Return codeDescription
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

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

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft