FilterAttachAtAltitude function (fltuser.h)

The FilterAttachAtAltitude function is a debugging support function that attaches a new minifilter instance to a volume at a specified altitude, overriding any settings in the minifilter's setup information (INF) file.

Syntax

HRESULT FilterAttachAtAltitude(
  [in]            LPCWSTR lpFilterName,
  [in]            LPCWSTR lpVolumeName,
  [in]            LPCWSTR lpAltitude,
  [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\"

[in] lpAltitude

Pointer to a null-terminated wide-character string that contains a numeric value specifying the target position that the minifilter instance should occupy in the stack for the volume. The higher the number, the higher the relative position in the stack. An altitude string consists of one or more digits in the range from 0 through 9, and it can include a single decimal point. The decimal point is optional. For example, "100.123456" is a valid altitude string. This 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

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

Remarks

An application should only use FilterAttachAtAltitude for debugging. It should not call this function in a retail version of the application.

FilterAttachAtAltitude is the Win32 equivalent of FltAttachVolumeAtAltitude.

The term "altitude" refers to the position that an instance occupies (or should occupy) in the minifilter instance stack for a volume. The higher the altitude, the farther the instance is from the base file system in the stack. Only one instance can be attached at a given altitude on a given volume.

Altitude is specified by an altitude string, which is a wide-character array containing one or more decimal digits in the range from 0 through 9, and it can include a single decimal point. The decimal point is optional. For example, "100.123456" and "03333" are valid altitude strings.

The string "03333" represents a higher altitude than "100.123456". (Leading and trailing zeros are ignored.) In other words, an instance whose altitude is "03333" is farther from the base file system than an instance whose altitude is "100.123456". However, this comparison is only meaningful if both instances are attached to the same volume.

The instance name returned in lpCreatedInstanceName is unique across the system.

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

Requirements

See also

FilterAttach

FilterDetach

FltAttachVolumeAtAltitude