FltSetVolumeContext function (fltkernel.h)
FltSetVolumeContext sets a context for a volume.
Syntax
NTSTATUS FLTAPI FltSetVolumeContext(
[in] PFLT_VOLUME Volume,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out, optional] PFLT_CONTEXT *OldContext
);
Parameters
[in] Volume
Opaque volume pointer for the volume.
[in] Operation
Flag specifying details of the operation to be performed. This parameter must be one of the following:
Flag | Meaning |
---|---|
FLT_SET_CONTEXT_REPLACE_IF_EXISTS | If a context is already set for Volume, FltSetVolumeContext will replace it with NewContext>. Otherwise, it will insert NewContext into the list of contexts for the volume. |
FLT_SET_CONTEXT_KEEP_IF_EXISTS | If a context is already set for this volume, FltSetVolumeContext will return STATUS_FLT_CONTEXT_ALREADY_DEFINED, and will not replace the existing context or increment the reference count. If a context has not already been set, the routine will insert NewContext into the list of contexts for the volume and increment the reference count. |
[in] NewContext
Pointer to the new context to be set for the volume. This parameter is required and cannot be NULL.
[out, optional] OldContext
Pointer to a caller-allocated variable that receives the address of the existing volume context for Volume. This parameter is optional and can be NULL. For more information about this parameter, see the following Remarks section.
Return value
FltSetVolumeContext returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:
Return code | Description |
---|---|
STATUS_FLT_CONTEXT_ALREADY_DEFINED | IF FLT_SET_CONTEXT_KEEP_IF_EXISTS was specified for Operation, this error code indicates that a context is already attached to the volume. |
STATUS_FLT_CONTEXT_ALREADY_LINKED | The context pointed to by the NewContext parameter is already linked to an object. In other words, this error code indicates that NewContext is already in use due to a successful prior call of a FltSetXxxContext routine. |
STATUS_FLT_DELETING_OBJECT | The specified Volume is being torn down. This is an error code. |
STATUS_INVALID_PARAMETER | An invalid parameter was passed. For example, the NewContext parameter does not point to a valid volume context, or an invalid value was specified for Operation. This is an error code. |
Remarks
For more information about contexts, see About minifilter contexts.
A minifilter driver calls FltSetVolumeContext to attach a context to a volume, or to remove or replace an existing volume context. A minifilter driver can attach only one context to a volume.
Reference Counting
If FltSetVolumeContext succeeds:
- The reference count on NewContext is incremented. When NewContext is no longer needed, the minifilter must call FltReleaseContext to decrement its reference count.
Else if FltSetVolumeContext fails:
- The reference count on NewContext remains unchanged.
- If OldContext is not NULL and does not point to NULL_CONTEXT then OldContext is a referenced pointer to the context currently associated with the volume. The filter calling FltSetVolumeContext must call FltReleaseContext for OldContext as well when the context pointer is no longer needed.
Regardless of success:
- The filter calling FltSetVolumeContext must call FltReleaseContext to decrement the reference count on the NewContext object that was incremented by FltAllocateContext.
For more information, see Referencing Contexts.
Other context operations
For more information, see Setting Contexts, and Releasing Contexts:
To allocate a new context, call FltAllocateContext.
To get a volume context, call FltGetVolumeContext.
To delete a volume context, call FltDeleteVolumeContext or FltDeleteContext.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Available and supported in Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later operating systems. |
Target Platform | Universal |
Header | fltkernel.h (include Fltkernel.h) |
Library | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | <= APC_LEVEL |