FilterAttachAtAltitude-Funktion (fltuser.h)

  • Artikel

Die FilterAttachAtAltitude-Funktion ist eine Debugunterstützungsfunktion, die einen neuen Minifilter-instance an ein Volume in einer angegebenen Höhe anfügt und alle Einstellungen in der Setupinformationsdatei (INF) des Minifilters überschreibt.

Syntax

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

Parameter

[in] lpFilterName

Zeiger auf eine mit NULL beendete Breitzeichenzeichenfolge, die den Namen des Minifilters enthält, für den ein instance erstellt werden soll. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] lpVolumeName

Zeiger auf eine mit NULL beendete Breitzeichenzeichenfolge, die den Namen des Volumes enthält, an das die neu erstellte instance angefügt werden soll.

Die LpVolumeName-Eingabezeichenfolge kann eine der folgenden Sein: Der nachfolgende umgekehrte Schrägstrich (\) ist optional.

  • Ein Laufwerkbuchstabe, z. B. "D:\"
  • Ein Pfad zu einem Volumeeinbindungspunkt, z. B. "c:\mnt\edrive\"
  • Ein eindeutiger Volumebezeichner (auch als Volume-GUID-Name bezeichnet), z. B. "\?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\"
  • Ein nichtpersistent-Gerätename (auch als Zielname oder NT-Gerätename bezeichnet), z. B. "\Device\HarddiskVolume1\"
Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] lpAltitude

Zeiger auf eine mit NULL beendete Breitzeichenzeichenfolge, die einen numerischen Wert enthält, der die Zielposition angibt, die der Minifilter instance im Stapel für das Volume einnehmen soll. Je höher die Zahl, desto höher ist die relative Position im Stapel. Eine Höhenzeichenfolge besteht aus einer oder mehreren Ziffern im Bereich von 0 bis 9 und kann einen einzelnen Dezimalpunkt enthalten. Der Dezimalpunkt ist optional. Beispielsweise ist "100.123456" eine gültige Höhenzeichenfolge. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in, optional] lpInstanceName

Zeiger auf eine mit NULL beendete Breitzeichenzeichenfolge, die den instance Namen für die neue instance enthält. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, erhält der neue instance den Standardnamen instance Minifilters, wie im Abschnitt Hinweise für FltAttachVolume beschrieben.

[in, optional] dwCreatedInstanceNameLength

Länge des Puffers, auf den lpCreatedInstanceName verweist, in Bytes. Dieser Parameter ist optional und kann null sein.

[out, optional] lpCreatedInstanceName

Zeiger auf eine vom Aufrufer zugewiesene Variable, die den instance Namen für die neue instance empfängt, wenn die instance erfolgreich an das Volume angefügt wurde. Dieser Parameter ist optional und kann NULL sein. Wenn er nicht NULL ist, muss der Puffer groß genug sein, um INSTANCE_NAME_MAX_CHARS Zeichen und einen NULL-Abschlussator zu enthalten.

Rückgabewert

FilterAttachAtAltitude gibt bei erfolgreicher Ausführung S_OK zurück. Andernfalls wird ein Fehlerwert zurückgegeben, z. B. einer der folgenden.

Rückgabecode Beschreibung
ERROR_FLT_INSTANCE_ALTITUDE_COLLISION
 In dieser Höhe des angegebenen Volumens ist bereits ein instance vorhanden.
ERROR_FLT_INSTANCE_NAME_COLLISION
 Auf dem angegebenen Volume ist bereits ein instance mit diesem Namen vorhanden.

Hinweise

Eine Anwendung sollte nur FilterAttachAtAltitude zum Debuggen verwenden. Diese Funktion sollte nicht in einer Einzelhandelsversion der Anwendung aufgerufen werden.

FilterAttachAtAltitude ist das Win32-Äquivalent von FltAttachVolumeAtAltitude.

Der Begriff "Höhe" bezieht sich auf die Position, die ein instance im Minifilter instance Stapels für ein Volume einnimmt (oder belegen sollte). Je höher die Höhe, desto weiter ist die instance aus dem Basisdateisystem im Stapel. Nur eine instance kann in einer bestimmten Höhe auf einem bestimmten Volumen angebracht werden.

Die Höhe wird durch eine Höhenzeichenfolge angegeben, bei der es sich um ein Breitzeichenarray handelt, das eine oder mehrere Dezimalstellen im Bereich von 0 bis 9 enthält und einen einzelnen Dezimalpunkt enthalten kann. Der Dezimalpunkt ist optional. Beispielsweise sind "100.123456" und "03333" gültige Höhenzeichenfolgen.

Die Zeichenfolge "03333" stellt eine höhere Höhe als "100,123456" dar. (Führende und nachfolgende Nullen werden ignoriert.) Mit anderen Worten, ein instance dessen Höhe "0333" ist, ist weiter vom Basisdateisystem entfernt als ein instance dessen Höhe "100,123456" ist. Dieser Vergleich ist jedoch nur sinnvoll, wenn beide Instanzen an dasselbe Volume angefügt sind.

Der in lpCreatedInstanceName zurückgegebene instance Name ist systemweit eindeutig.

Um einen Minifilter instance von einem Volume zu trennen, rufen Sie FilterDetach auf.

Anforderungen

   
Zielplattform Universell
Header fltuser.h (einschließlich Fltuser.h)
Bibliothek FltLib.lib
DLL FltLib.dll

Weitere Informationen

FilterAttach

FilterDetach

FltAttachVolumeAtAltitude