FltGetUpperInstance function (fltkernel.h)

The FltGetUpperInstance routine returns an opaque instance pointer for the next higher minifilter driver instance, if there is one, that is attached above a given minifilter driver instance on the same volume.

Syntax

NTSTATUS FLTAPI FltGetUpperInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *UpperInstance
);

Parameters

[in] CurrentInstance

Opaque instance pointer for the instance for which the next higher instance is requested.

[out] UpperInstance

Pointer to a caller-allocated variable that receives an opaque instance pointer for the next higher instance. This parameter is required and cannot be NULL.

Return value

FltGetUpperInstance returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as the following:

Remarks

One instance is said to be above another if it is attached at a higher altitude on the same volume. 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 counted Unicode string consisting of one or more decimal digits in the range of 0 through 9, and it 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.

FltGetUpperInstance adds a rundown reference to the opaque instance pointer returned in the UpperInstance parameter. When this pointer is no longer needed, the caller must release it by calling FltObjectDereference. Thus every successful call to FltGetUpperInstance must be matched by a subsequent call to FltObjectDereference.

Requirements

See also

FltAttachVolume

FltAttachVolumeAtAltitude

FltCompareInstanceAltitudes

FltGetBottomInstance

FltGetLowerInstance

FltGetTopInstance

FltObjectDereference