FltAttachVolumeAtAltitude function (fltkernel.h)

Article
10/21/2021

FltAttachVolumeAtAltitude is a debugging support routine that attaches a minifilter driver instance to a volume at a specified altitude, overriding any settings in the minifilter driver's INF file.

Syntax

NTSTATUS FLTAPI FltAttachVolumeAtAltitude(
  [in, out]       PFLT_FILTER      Filter,
  [in, out]       PFLT_VOLUME      Volume,
  [in]            PCUNICODE_STRING Altitude,
  [in, optional]  PCUNICODE_STRING InstanceName,
  [out, optional] 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] Altitude

Pointer to a UNICODE_STRING structure containing the altitude string for the instance. This parameter is required and cannot be NULL. (For more information about this parameter, see the following Remarks section.)

[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, FltAttachVolumeAtAltitude generates an instance name from the minifilter driver name and the altitude string that Altitude points to. The generated name is truncated, if necessary, to INSTANCE_NAME_MAX_CHARS characters.

[out, optional] 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

FltAttachVolumeAtAltitude returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_FLT_DELETING_OBJECT	The specified Filter or Volume is being torn down. This is an error code.
STATUS_FLT_FILTER_NOT_READY	The minifilter driver has not started filtering. For more information, see FltStartFiltering. This is an error code.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	An instance already exists at this altitude on the volume specified. This is an error code.
STATUS_FLT_INSTANCE_NAME_COLLISION	An instance already exists with this name on the volume specified. This is an error code.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude encountered a pool allocation failure. This is an error code.
STATUS_INVALID_PARAMETER	The UNICODE_STRING structure that Altitude points to did not contain a valid altitude string. This is an error code.

Remarks

A minifilter driver should only use FltAttachVolumeAtAltitude for debugging. It should not call this routine in a retail version of the minifilter driver.

FltAttachVolumeAtAltitude is the kernel equivalent of the Win32 FilterAttachAtAltitude function.

The term "altitude" refers to the position that an instance occupies (or should occupy) in the minifilter driver 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 from 0 through 9; the array can include a single decimal point. 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 specified in the InstanceName parameter is required to be unique across the system.

FltAttachVolumeAtAltitude 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.

FltAttachVolumeAtAltitude 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 FltAttachVolumeAtAltitude must be matched by a subsequent call to FltObjectDereference.

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