FltAttachVolumeAtAltitude function (fltkernel.h)
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 |
|---|---|
|
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 at this altitude on the volume specified. This is an error code. |
|
An instance already exists with this name on the volume specified. This is an error code. |
|
FltAttachVolumeAtAltitude encountered a pool allocation failure. This is an error code. |
|
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 |