FilterAttach function (fltuser.h)

Article
10/13/2021

The FilterAttach function attaches a new minifilter instance to the given volume.

Syntax

HRESULT FilterAttach(
  [in]            LPCWSTR lpFilterName,
  [in]            LPCWSTR lpVolumeName,
  [in, optional]  LPCWSTR lpInstanceName,
  [in, optional]  DWORD   dwCreatedInstanceNameLength,
  [out, optional] LPWSTR  lpCreatedInstanceName
);

Parameters

[in] lpFilterName

Pointer to a null-terminated wide-character string containing the name of the minifilter for which an instance is to be created. This parameter is required and cannot be NULL.

[in] lpVolumeName

Pointer to a null-terminated wide-character string containing the name of the volume to which the newly created instance is to be attached.

The lpVolumeName input string can be any of the following. The trailing backslash (\) is optional.

A drive letter, such as "D:\"
A path to a volume mount point, such as "c:\mnt\edrive\"
A unique volume identifier (also called a volume GUID name), such as "\??\Volume{7603f260-142a-11d4-ac67-806d6172696f}\"
A nonpersistent device name (also called a target name or an NT device name), such as "\Device\HarddiskVolume1\"

The lpVolumeName parameter is required and cannot be NULL.

[in, optional] lpInstanceName

Pointer to a null-terminated wide-character string containing the instance name for the new instance. This parameter is optional and can be NULL. If this parameter is NULL, the new instance receives the minifilter's default instance name as described in the Remarks section for FltAttachVolume.

[in, optional] dwCreatedInstanceNameLength

Length, in bytes, of the buffer that lpCreatedInstanceName points to. This parameter is optional and can be zero.

[out, optional] lpCreatedInstanceName

Pointer to a caller-allocated variable that receives the instance name for the new instance if the instance is successfully attached to the volume. This parameter is optional and can be NULL. If it is not NULL, the buffer must be large enough to hold INSTANCE_NAME_MAX_CHARS characters plus a NULL terminator.

Return value

FilterAttach returns S_OK if successful. Otherwise, it returns an error value such as one of the following.

Return code	Description
ERROR_FLT_INSTANCE_ALTITUDE_COLLISION	An instance already exists at this altitude on the volume specified.
ERROR_FLT_INSTANCE_NAME_COLLISION	An instance already exists with this name on the volume specified.
ERROR_FILE_NOT_FOUND	If lpInstanceName is non-NULL, lpInstanceName does not match a registered filter instance name in the registry.

Remarks

FilterAttach is the Win32 equivalent of FltAttachVolume.

The instance name specified in lpInstanceName is required to be unique across the system.

To attach a minifilter instance to a volume at a given altitude, call FilterAttachAtAltitude.

To detach a minifilter instance from a volume, call FilterDetach.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltuser.h (include Fltuser.h)
Library	FltLib.lib
DLL	FltLib.dll