PFLT_PRE_OPERATION_CALLBACK Rückruffunktion (fltkernel.h)
Die PFLT_PRE_OPERATION_CALLBACK Routine eines Minifiltertreibers führt die Verarbeitung vor dem Betrieb für E/A-Vorgänge durch.
Syntax
PFLT_PRE_OPERATION_CALLBACK PfltPreOperationCallback;
FLT_PREOP_CALLBACK_STATUS PfltPreOperationCallback(
[in, out] PFLT_CALLBACK_DATA Data,
[in] PCFLT_RELATED_OBJECTS FltObjects,
[out] PVOID *CompletionContext
)
{...}
Parameter
[in, out] Data
Ein Zeiger auf die Rückrufdatenstruktur (FLT_CALLBACK_DATA) für den E/A-Vorgang.
[in] FltObjects
Ein Zeiger auf eine FLT_RELATED_OBJECTS Struktur, die undurchsichtige Zeiger für die Objekte enthält, die mit der aktuellen E/A-Anforderung zusammenhängen.
[out] CompletionContext
Wenn diese Rückrufroutine FLT_PREOP_SUCCESS_WITH_CALLBACK oder FLT_PREOP_SYNCHRONIZE zurückgibt, ist dieser Parameter ein optionaler Kontextzeiger, der an die entsprechende Rückrufroutine nach dem Vorgang übergeben werden soll. Andernfalls muss es NULL sein.
Rückgabewert
Diese Rückrufroutine gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS Werte zurück.
| Rückgabecode | Beschreibung |
|---|---|
| FLT_PREOP_COMPLETE | Der Minifilter schließt den E/A-Vorgang ab. Ausführliche Informationen finden Sie in den Hinweisen. |
| FLT_PREOP_DISALLOW_FASTIO | Der Vorgang ist ein schneller E/A-Vorgang, und der Minifilter lässt nicht zu, dass der schnelle E/A-Pfad für diesen Vorgang verwendet werden kann. Ausführliche Informationen finden Sie in den Hinweisen. |
| FLT_PREOP_PENDING | Der Minifilter hat den E/A-Vorgang eingestiftet, und der Vorgang steht noch aus. Ausführliche Informationen finden Sie in den Hinweisen. |
| FLT_PREOP_SUCCESS_NO_CALLBACK | Der Minifilter gibt den E/A-Vorgang zur weiteren Verarbeitung an FltMgr zurück. In diesem Fall ruft FltMgr den Post-Operation-Rückruf des Minifiltertreibers, sofern vorhanden, während der E/A-Fertigstellung nicht auf. |
| FLT_PREOP_SUCCESS_WITH_CALLBACK | Der Minifilter gibt den E/A-Vorgang zur weiteren Verarbeitung an FltMgr zurück. In diesem Fall ruft FltMgr den Post-Operation-Rückruf des Minifilters während der E/A-Fertigstellung auf. |
| FLT_PREOP_SYNCHRONIZE | Der Minifilter gibt den E/A-Vorgang zur weiteren Verarbeitung an FltMgr zurück, der Vorgang wird jedoch nicht abgeschlossen. Ausführliche Informationen finden Sie in den Hinweisen. |
| FLT_PREOP_DISALLOW_FSFILTER_IO | Der Minifilter weist einen schnellen QueryOpen-Vorgang auf und erzwingt den Vorgang auf dem langsamen Pfad. Dies bewirkt, dass der E/A-Manager die Anforderung bedient, indem eine Open/Query/Close der Datei ausgeführt wird. Minifiltertreiber sollten diesen Status nur für QueryOpen zurückgeben. |
Bemerkungen
Weitere Informationen finden Sie unter Schreiben von Rückrufroutinen.
Die Voroperationsrückrufroutine eines Minifilters verarbeitet einen oder mehrere Arten von E/A-Vorgängen. (Diese Rückrufroutine ähnelt einer Dispatchroutine im älteren Filtermodell.)
Ein Minifilter registriert eine Voroperationsrückrufroutine für einen bestimmten Typ von E/A-Vorgängen, indem der Einstiegspunkt der Rückrufroutine im OperationRegistration Array der FLT_REGISTRATION-Struktur gespeichert wird. Der Minifilter übergibt diese Struktur als Parameter an FltRegisterFilter in der DriverEntry Routine. Ein Minifilter kann eine Voroperationsrückrufroutine für einen bestimmten Typ von E/A-Vorgängen registrieren, ohne einen Rückruf nach dem Vorgang (PFLT_POST_OPERATION_CALLBACK) zu registrieren und umgekehrt.
Die Vor- oder Nachoperationsrückrufroutine eines Minifiltertreibers kann den Inhalt der Rückrufdatenstruktur für den Vorgang ändern. Wenn dies der Fall ist, muss sie FltSetCallbackDataDirtyaufrufen, es sei denn, sie hat den Inhalt der IoStatus Feld der Rückrufdatenstruktur geändert.
Die IRQL für diese generische Rückrufroutine hängt von den spezifischen E/A-Pfaden ab. Sie können KeGetCurrentIRQL schnell und billig aufrufen, wenn Sie die aktuelle IRQL kennen müssen. Weitere Informationen zu IRQL finden Sie unter Schreiben von Rückrufroutinen.
Dateisysteme runden Schreib- und Lesevorgänge am Ende der Datei auf ein Vielfaches der Sektorgröße des zugrunde liegenden Dateispeichergeräts auf. Beim Verarbeiten von Vorlese- oder Vorschreibvorgängen müssen Filter, die Puffer zuordnen und austauschen, die Größe eines zugeordneten Puffers auf ein Vielfaches der Sektorgröße des zugeordneten Geräts runden. Ist dies nicht der Grund, überschreitet die Länge der vom zugrunde liegenden Dateisystem übertragenen Daten die zugewiesene Länge des Puffers. Weitere Informationen zum Austauschen von Puffern finden Sie im SwapBuffers Minifilter-Beispiel.
Ab Windows 8 verwendet CompletionContext die Flt_CompletionContext_Outptr Anmerkung, die gültige Kontextwerte basierend auf dem Vorgangsergebnis definiert. Nachfolgend sehen Sie ein Verwendungsbeispiel für den Rückruf mit der Anmerkung für CompletionContext.
FLT_PREOP_CALLBACK_STATUS
SwapPreReadBuffers(
_Inout_ PFLT_CALLBACK_DATA Data,
_In_ PCFLT_RELATED_OBJECTS FltObjects,
_Flt_CompletionContext_Outptr_ PVOID *CompletionContext
);
Zurückgeben von FLT_PREOP_COMPLETE
Wenn diese Routine FLT_PREOP_COMPLETE zurückgibt, muss die IoStatus.Status- Feld der Rückrufdatenstruktur auf den endgültigen NTSTATUS-Wert für den E/A-Vorgang festgelegt werden. Dieser NTSTATUS-Wert kann nicht STATUS_PENDING werden. Bei einem Bereinigungs- oder Abschlussvorgang muss es sich um einen anderen NTSTATUS-Erfolgswert als STATUS_PENDING sein, da Bereinigungs- und Schließenvorgänge nicht fehlschlagen können.
Wenn diese Routine FLT_PREOP_COMPLETE zurückgibt, sendet FltMgr den E/A-Vorgang nicht an minifiltertreiber unter dem Aufrufer im Treiberstapel oder an das Dateisystem. In diesem Fall ruft FltMgr nur die Rückrufroutinen nach dem Vorgang über dem Aufrufer im Treiberstapel auf.
Zurückgeben von FLT_PREOP_DISALLOW_FASTIO
Wenn diese Routine FLT_PREOP_DISALLOW_FASTIO zurückgibt, sollte die IoStatus.Status- Feld der Rückrufdatenstruktur nicht festgelegt werden, da FltMgr dieses Feld automatisch auf STATUS_FLT_DISALLOW_FAST_IO festlegt.
FLT_PREOP_DISALLOW_FASTIO kann nur für einen schnellen E/A-Vorgang zurückgegeben werden. Um zu ermitteln, ob eine bestimmte Rückrufdatenstruktur einen schnellen E/A-Vorgang darstellt, verwenden Sie das FLT_IS_FASTIO_OPERATION Makro.
Wenn diese Routine FLT_PREOP_DISALLOW_FASTIO zurückgibt, sendet FltMgr den schnellen E/A-Vorgang nicht an Minifiltertreiber unter dem Aufrufer im Treiberstapel oder an das Dateisystem. In diesem Fall ruft FltMgr nur die Rückrufroutinen nach dem Vorgang über dem Aufrufer im Treiberstapel auf.
Zurückgeben von FLT_PREOP_PENDING
FLT_PREOP_PENDING können nur für IRP-basierte E/A-Vorgänge zurückgegeben werden, da nur IRP-basierte E/A-Vorgänge pendiert werden können. Um zu bestimmen, ob eine bestimmte Rückrufdatenstruktur einen IRP-basierten E/A-Vorgang darstellt, verwenden Sie das FLT_IS_IRP_OPERATION Makro.
Wenn diese Routine FLT_PREOP_PENDING zurückgibt, verarbeitet FltMgr den E/A-Vorgang erst weiter, wenn der Minifiltertreiber FltCompletePendedPreOperationaufruft.
Zurückgeben von FLT_PREOP_SYNCHRONIZE
Wenn die Voroperationsrückrufroutine eines Minifilters FLT_PREOP_SYNCHRONIZE zurückgibt, muss der Minifilter einen entsprechenden Rückruf nach dem Vorgang registriert haben. Wenn diese Routine FLT_PREOP_SYNCHRONIZE zurückgibt, ruft FltMgr den Post-Operation-Rückruf des Minifilters im Kontext des aktuellen Threads bei IRQL <= APC_LEVEL auf.
FLT_PREOP_SYNCHRONIZE sollte nur für IRP-basierte E/A-Vorgänge zurückgegeben werden. Wenn sie für einen E/A-Vorgang zurückgegeben wird, der keine IRP-basierte Operation ist, behandelt FltMgr diesen Rückgabewert so, als wäre er FLT_PREOP_SUCCESS_WITH_CALLBACK.
Minifiltertreiber sollten nicht FLT_PREOP_SYNCHRONIZE für Erstellungsvorgänge zurückgeben, da diese Vorgänge bereits von FltMgrsynchronisiert werden.
Minifilter dürfen niemals FLT_PREOP_SYNCHRONIZE für asynchrone Lese- und Schreibvorgänge zurückgeben. Dies kann sowohl den Minifiltertreiber als auch die Systemleistung erheblich beeinträchtigen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Microsoft Windows 2000 UpdateRollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1 und höher Windows-Betriebssysteme. |
| Zielplattform- | Desktop |
| Header- | fltkernel.h (include FltKernel.h) |
| IRQL- | Siehe Abschnitt "Hinweise" |