Edit

File System Minifilter pre-operation callback _Flt_CompletionContext_Outptr_ annotation

  • Article

Use the _Flt_CompletionContext_Outptr_ annotation when you declare the file system minifilter pre-operation callback function PFLT_PRE_OPERATION_CALLBACK. Place this annotation on the CompletionContext parameter. This annotation directs the code analysis tool to check that the CompletionContext is correct for the FLT_PREOP_CALLBACK_STATUS return value.

If a pre-operation callback function (PFLT_PRE_OPERATION_CALLBACK) returns FLT_PREOP_SUCCESS_WITH_CALLBACK or FLT_PREOP_SYNCHRONIZE the CompletionContext might or might not be NULL. For any other FLT_PREOP_CALLBACK_STATUS return value the CompletionContext must be NULL. The CompletionContext is filter-defined state that is passed from the filter’s pre-operation callback to the corresponding post-operation callback function (PFLT_POST_OPERATION_CALLBACK). The post-operation callback is only called if the filter returned FLT_PREOP_SUCCESS_WITH_CALLBACK or FLT_PREOP_SYNCHRONIZE from its pre-operation callback function. If the filter doesn’t pass any state from its pre-operation callback function to its post-operation callback function the CompletionContext is NULL, and therefore CompletionContext in its post-operation callback function will be NULL. Each individual filter decides whether to return state in CompletionContext from a pre-operation callback function, so it is up to each individual filter to know whether or not it should look at CompletionContext in its post-operation callback function.

Example

The following example shows the function prototype for a PFLT_PRE_OPERATION_CALLBACK function called SwapPreReadBuffers. The CompletionContext parameter receives the context that will be passed to the post-operation callback function and it is declared with _Flt_CompletionContext_Outptr_ annotation.

FLT_PREOP_CALLBACK_STATUS
SwapPreReadBuffers(
    _Inout_ PFLT_CALLBACK_DATA Data,
    _In_ PCFLT_RELATED_OBJECTS FltObjects,
    _Flt_CompletionContext_Outptr_ PVOID *CompletionContext
    );

The _Flt_CompletionContext_Outptr_ annotation is defined in specstrings.h. Using the annotation can add valuable error checking without adding overhead or complexity to your code.

PFLT_PRE_OPERATION_CALLBACK

PFLT_POST_OPERATION_CALLBACK

SAL 2.0 Annotations for Windows Drivers