FltAttachVolume function (fltkernel.h)
FltAttachVolume creates a new minifilter driver instance and attaches it to the given volume.
Syntax
NTSTATUS FLTAPI FltAttachVolume(
[in, out] PFLT_FILTER Filter,
[in, out] PFLT_VOLUME Volume,
[in, optional] PCUNICODE_STRING InstanceName,
[out] PFLT_INSTANCE *RetInstance
);
Parameters
[in, out] Filter
Opaque filter pointer for the caller. This parameter is required and cannot be NULL.
[in, out] Volume
Opaque volume pointer for the volume that the minifilter driver instance is to be attached to. This parameter is required and cannot be NULL.
[in, optional] InstanceName
Pointer to a UNICODE_STRING structure containing the instance name for the new instance. This parameter is optional and can be NULL. If it is NULL, FltAttachVolume attempts to read the minifilter driver's default instance name from the registry. (For more information about this parameter, see the following Remarks section.)
[out] RetInstance
Pointer to a caller-allocated variable that receives an opaque instance pointer for the newly created instance. This parameter is optional and can be NULL.
Return value
FltAttachVolume returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:
| Return code | Description |
|---|---|
|
The specified Filter or Volume is being torn down. This is an error code. |
|
The minifilter driver has not started filtering. For more information, see FltStartFiltering. This is an error code. |
|
An instance already exists with this name on the volume specified. |
|
FltAttachVolume encountered a pool allocation failure. This is an error code. |
|
Another instance was already attached at the altitude specified in the instance attributes that were read from the registry. This is an error code. |
Remarks
If the caller specifies a non-NULL value for InstanceName, FltAttachVolume reads any instance attributes specified by the minifilter driver that are stored in the registry under HKLM\CurrentControlSet\Services\ServiceName\Instances\InstanceName, where ServiceName is the minifilter driver's service name. This service name is specified in the AddService directive in the DefaultInstall.Services section of the minifilter driver's INF file. (For more information about filter driver INF files, see Installing a File System Filter Driver.)
If the caller does not specify a value for InstanceName, FltAttachVolume uses the name stored in the registry under HKLM\CurrentControlSet\Services\ServiceName\Instances\DefaultInstance for the InstanceName portion of the registry path.
The instance name specified in the InstanceName parameter is required to be unique across the system.
FltAttachVolume returns an opaque instance pointer for the new instance in *RetInstance. This pointer value uniquely identifies the minifilter driver instance and remains constant as long as the instance is attached to the volume.
FltAttachVolume adds a rundown reference to the opaque instance pointer returned in *RetInstance. When this pointer is no longer needed, the caller must release it by calling FltObjectDereference. Thus every successful call to FltAttachVolume must be matched by a subsequent call to FltObjectDereference.
To attach a minifilter driver instance to a volume at a given altitude, call FltAttachVolumeAtAltitude.
To compare the altitudes of two minifilter driver instances attached to the same volume, call FltCompareInstanceAltitudes.
To detach a minifilter driver instance from a volume, call FltDetachVolume.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | fltkernel.h (include Fltkernel.h) |
| Library | FltMgr.lib |
| IRQL | PASSIVE_LEVEL |