ClfsCreateLogFile-Funktion (wdm.h)
Die ClfsCreateLogFile Routine erstellt oder öffnet einen CLFS-Stream. Bei Bedarf erstellt ClfsCreateLogFile auch das zugrunde liegende physische Protokoll, das die Datensätze des Datenstroms enthält.
Syntax
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
Parameter
[out] pplfoLog
Ein Zeiger auf eine Variable, die einen Zeiger auf eine LOG_FILE_OBJECT Struktur empfängt, die eine geöffnete Instanz des Datenstroms darstellt.
[in] puszLogFileName
Ein Zeiger auf eine UNICODE_STRING-Struktur, die den Namen des Datenstroms oder des zugrunde liegenden physischen Protokolls bereitstellt.
Wenn der Datenstrom bereits vorhanden ist und der einzige Datenstrom eines dedizierten Protokolls ist, weist der Name das Formularprotokoll auf:physischen Protokollnamen, wobei physischen Protokollnamen der Pfadname im zugrunde liegenden Dateisystem des vorhandenen physischen Protokolls ist, das die Datensätze des Datenstroms enthält.
Wenn der Datenstrom noch nicht vorhanden ist und der einzige Datenstrom eines dedizierten Protokolls werden soll (das noch nicht vorhanden ist), weist der Name das Formularprotokoll auf:physischen Protokollnamen, wobei physischen Protokollnamen der Pfadname des zugrunde liegenden Dateisystems des physischen Protokolls ist, das erstellt wird, um die Datensätze des Datenstroms zu speichern.
Wenn der Datenstrom zu einem der Datenströme eines Multiplexed-Protokolls wird (oder werden soll), der Name hat das Formularprotokoll:physischen Protokollnamen::Datenstromname, wobei physischen Protokollnamen der Pfadname im zugrunde liegenden Dateisystem des physischen Protokolls ist, das die Datensätze des Datenstroms enthält, und Datenstromname ist der Name eines Datenstroms, der das physische Protokoll teilt (oder teilt).
Wenn Sie ein Multiplexed-Protokoll erstellen möchten, das momentan keine Datenströme enthält, verwenden Sie einen Namen des Formularprotokolls:physischen Protokollnamen::, wobei physischen Protokollnamen der Pfadname des zugrunde liegenden Dateisystems des zu erstellenden physischen Protokolls ist.
Die folgende Liste enthält einige Beispiele für gültige Namen.
- "Log:c:\myLog" erstellt oder öffnet ein dediziertes Protokoll und seinen zugehörigen Datenstrom.
- "Log:c:\myCommonLog::" erstellt ein Multiplexed-Protokoll, das noch keine Datenströme enthält.
- "Log:c:\myCommonLog::Stream1" erstellt oder öffnet einen der Streams (Stream1) eines Multiplexed-Protokolls.
[in] fDesiredAccess
Eine ACCESS_MASK, die den Typ des Zugriffs bereitstellt, über den der Client verfügt (mithilfe des in pplfoLog) zurückgegebenen Zeigers auf den Datenstrom. Wenn dieser Parameter null ist, können Clients den Datenstrom nach seinen Attributen abfragen, aber nicht aus dem Datenstrom lesen oder in den Datenstrom schreiben. Dieser Parameter kann null oder eine beliebige Kombination der folgenden Flags sein:
| Flagge | Bedeutung |
|---|---|
| GENERIC_READ | Der Client hat Lesezugriff auf den Datenstrom. |
| GENERIC_WRITE | Der Client hat Schreibzugriff auf den Datenstrom. |
| LÖSCHEN | Der Client kann den Datenstrom zum Löschen markieren. |
[in] dwShareMode
Der Freigabemodus des Datenstroms, der null (nicht freigegeben) oder eine beliebige Kombination der folgenden Flags sein kann:
| Flagge | Bedeutung |
|---|---|
| FILE_SHARE_DELETE | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Löschzugriff werden erfolgreich ausgeführt. |
| FILE_SHARE_READ | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Lesezugriff werden erfolgreich ausgeführt. |
| FILE_SHARE_WRITE | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Schreibzugriff werden erfolgreich ausgeführt. |
[in, optional] psdLogFile
Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur, die Sicherheitsattribute für den Datenstrom bereitstellt. Dieser Parameter kann NULL-sein.
[in] fCreateDisposition
Die auszuführende Aktion hängt davon ab, ob der Datenstrom bereits vorhanden ist. Dieser Parameter muss auf einen der folgenden Werte festgelegt werden:
| Wert | Bedeutung |
|---|---|
| CREATE_NEW | Erstellen Sie einen neuen Datenstrom, wenn der Datenstrom noch nicht beendet wird. Schlägt fehl, wenn der Datenstrom bereits vorhanden ist. |
| OPEN_EXISTING | Öffnen Sie einen vorhandenen Datenstrom. Schlägt fehl, wenn der Datenstrom noch nicht vorhanden ist. |
| OPEN_ALWAYS | Öffnen Sie einen vorhandenen Datenstrom. Erstellen Sie den Datenstrom, wenn er noch nicht vorhanden ist. |
[in] fCreateOptions
Eine Reihe von Flags, die Optionen angeben, die beim Erstellen oder Öffnen des Datenstroms angewendet werden sollen. Dieser Parameter kann null oder eine kompatible Kombination der folgenden Flags sein:
| Flagge | Bedeutung |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | Die Datensätze des Datenstroms können nicht in den internen Puffern eines Treibers zwischengespeichert werden. |
| FILE_SYNCHRONOUS_IO_ALERT | Alle Vorgänge im Datenstrom werden synchron ausgeführt. Jede Wartezeit im Auftrag des Anrufers unterliegt einer vorzeitigen Kündigung durch Warnungen. Wenn dieses Kennzeichen festgelegt ist, muss das FILE_SYNCHRONOUS_IO_NONALERT Flag gelöscht werden. |
| FILE_SYNCHRONOUS_IO_NONALERT | Alle Vorgänge im Datenstrom werden synchron ausgeführt. Waits in the system that synchronize I/O queuing and completion are not subject to alerts. Wenn dieses Kennzeichen festgelegt ist, muss das FILE_SYNCHRONOUS_IO_ALERT Flag gelöscht werden. |
[in] fFlagsAndAttributes
Ein Wert, der angibt, ob der Datenstrom für normalen oder schreibgeschützten Zugriff geöffnet wird. Dieser Parameter muss auf eine der beiden Parameter festgelegt werden.
FILE_ATTRIBUTE_NORMAL oder FILE_ATTRIBUTE_READONLY.
[in] fLogOptionFlag
Ein Hinweis auf die Beziehung zwischen CLFS und der Komponente, die den Datenstrom erstellt oder öffnet. Dieser Parameter muss auf einen der folgenden Werte festgelegt werden:
| Wert | Bedeutung |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS und die erstellungskomponente weisen die standardnormale Beziehung auf. Kernelmoduskomponenten verwenden diesen Wert, es sei denn, sie fallen in eine der drei anderen Kategorien, die in dieser Tabelle aufgeführt sind. Wenn pvContext- nicht NULL-ist, überprüft CLFS, dass cbContext- größer als Null ist. Andernfalls werden pvContext und cbContext- ignoriert. |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | Die Erstellungskomponente ist das Dateisystem, das den zugrunde liegenden Speicher für CLFS bereitstellt. CLFS verwendet das Dateisystem zum Zuordnen von Containern, und das Dateisystem verwendet CLFS-Datenströme. In diesem Fall ist es möglich, dass das Dateisystem CLFS aufruft und CLFS Aufrufe an das Dateisystem im selben Thread oder in verschiedenen Threads zurückgibt. Wenn pvContext- nicht NULL-ist, überprüft CLFS, dass cbContext- größer als Null ist. Andernfalls werden pvContext und cbContext- ignoriert. |
| CLFS_FLAG_NON_REENTRANT_FILTER | Die Erstellungskomponente ist ein Dateisystemfiltertreiber, der alle zugehörigen CLFS-E/A-Dateien an eine bestimmte Ebene unterhalb des Filterstapels sendet. Mit dieser Option kann ein Filtertreiber ein CLFS-Protokoll erstellen, ohne die eigene Protokollierungs-E/A anzuzeigen. Der Aufrufer übergibt das nicht-NULL- Zielgeräteobjekt im pvContext Parameter, wobei cbContext auf die entsprechende Größe festgelegt ist. CLFS verwendet die IoCreateFileSpecifyDeviceObjectHint Routine, um Container auf einer zielbezogenen Ebene im vom Geräteobjekt angegebenen E/A-Filterstapel zu erstellen. |
| CLFS_FLAG_REENTRANT_FILTER | Die Erstellungskomponente ist ein Dateisystemfiltertreiber, der alle CLFS-E/A-Dateien an den Anfang des Filterstapels sendet. Der Filter verfügt über eine rekursive Beziehung mit CLFS, da er seine eigene Protokollierungs-E/A filtert, wenn CLFS einen Dateisystemvorgang in seinen Containern ausführt. Der pvContext Parameter bietet eine Möglichkeit für Filter, einen erkennbaren Kontext mit seinen CLFS-Containern zuzuordnen, da log I/O den Filterstapel herunterkommt. Der cbContext Parameter gibt die Größe des undurchsichtigen Kontexts in Bytes an. |
| CLFS_FLAG_MINIFILTER_LEVEL | Die Erstellungskomponente ist ein Dateisystem-Minifiltertreiber, der alle CLFS-E/A-Dateien an eine bestimmte Ebene unterhalb des Filterstapels sendet. Mit dieser Option kann ein Minifilter ein CLFS-Protokoll erstellen, ohne die eigene Protokollierungs-E/A anzuzeigen. Der Aufrufer übergibt das nicht-NULL- Minifilterkontextobjekt im pvContext Parameter, wobei cbContext- auf die entsprechende Größe festgelegt ist. CLFS verwendet die IoCreateFileSpecifyDeviceObjectHint Routine, um Container in einer Höhe (angegeben im Minifilterkontext) im Minifilterstapel des Filter-Managers zu erstellen. |
[in, optional] pvContext
Ein Zeiger auf einen Kontext. Die Art und Weise, wie der Kontext interpretiert wird, hängt vom Wert ab, der an fLogOptionsFlagübergeben wird.
[in] cbContext
Die Größe des Kontexts in Bytes, auf den pvContextverweist. Wenn pvContext- nicht NULL-ist, muss dieser Parameter größer als Null sein.
Rückgabewert
ClfsCreateLogFile- gibt STATUS_SUCCESS zurück, wenn sie erfolgreich ist; andernfalls wird eine der fehlercodes zurückgegeben, die in Ntstatus.h definiert sind.
Bemerkungen
Wenn Sie einen CLFS-Datenstrom erstellen, wird er durch ein zugrunde liegendes physisches CLFS-Protokoll gesichert. Das zugrunde liegende Protokoll kann entweder dediziert (nur ein Datenstrom) oder multiplexed (unterstützt mehrere Datenströme). Ein dediziertes Protokoll kann nicht in ein Multiplexed-Protokoll konvertiert werden, und ein Multiplexed-Protokoll kann nicht in ein dediziertes Protokoll konvertiert werden.
Ein physischer CLFS-Protokollname enthält nicht die BLF-Erweiterung.
Eine Erläuterung der CLFS-Konzepte und -Terminologie finden Sie unter Common Log File System.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Windows Server 2003 R2, Windows Vista und höheren Versionen von Windows. |
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h) |
| Library | Clfs.lib |
| DLL- | Clfs.sys |
| IRQL- | <= APC_LEVEL |