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 offene instance des Datenstroms darstellt.
[in] puszLogFileName
Ein Zeiger auf eine UNICODE_STRING-Struktur , die den Namen des Datenstroms oder des zugrunde liegenden physischen Protokolls angibt.
Wenn der Stream bereits vorhanden ist und der einzige Stream eines dedizierten Protokolls ist, hat der Name das Format log:physical log name. Dabei ist der Name des physischen Protokolls der Pfadname des vorhandenen physischen Protokolls, das die Datensätze des Datenstroms enthält, im zugrunde liegenden Dateisystem.
Wenn der Stream noch nicht vorhanden ist und der einzige Stream eines dedizierten Protokolls werden soll (das noch nicht vorhanden ist), hat der Name das Format log:Physischer Protokollname, wobei der Name des physischen Protokolls im zugrunde liegenden Dateisystem der Pfadname des physischen Protokolls ist, das für die Datensätze des Datenstroms erstellt wird.
Wenn der Stream einer der Datenströme eines Multiplexprotokolls ist (oder werden soll), hat der Name das Format log:physical log name::stream name, wobei der name des physischen Protokolls im zugrunde liegenden Dateisystem der Pfadname des physischen Protokolls ist, das die Datensätze des Datenstroms enthält, und der Streamname ist der Name eines Datenstroms, der dieses physische Protokoll teilt (oder freigeben wird).
Wenn Sie ein Multiplexprotokoll erstellen möchten, das derzeit keine Streams enthält, verwenden Sie einen Namen des Formulars log:physical log name::, wobei der Name des physischen Protokolls der Pfadname des zu erstellenden physischen Protokolls im zugrunde liegenden Dateisystem ist.
Die folgende Liste enthält einige Beispiele für gültige Namen.
- "Log:c:\myLog" erstellt oder öffnet ein dediziertes Protokoll und seinen einen Stream.
- "Log:c:\myCommonLog::" erstellt ein Multiplexprotokoll, das noch keine Streams enthält.
- "Log:c:\myCommonLog::Stream1" erstellt oder öffnet einen der Streams (Stream1) eines Multiplexprotokolls.
[in] fDesiredAccess
Eine ACCESS_MASK , die den Typ des Zugriffs angibt, den der Client (mithilfe des in pplfoLog zurückgegebenen Zeigers) auf den Stream hat. Wenn dieser Parameter 0 ist, können Clients den Stream nach seinen Attributen abfragen, aber nicht aus dem Stream lesen oder in diesen schreiben. Dieser Parameter kann null oder eine beliebige Kombination der folgenden Flags sein:
| Flag | Bedeutung |
|---|---|
| GENERIC_READ | Der Client hat Lesezugriff auf den Stream. |
| GENERIC_WRITE | Der Client hat Schreibzugriff auf den Stream. |
| Delete | Der Client kann den Stream zum Löschen markieren. |
[in] dwShareMode
Der Freigabemodus des Streams, der null (nicht freigegeben) oder eine beliebige Kombination der folgenden Flags sein kann:
| Flag | Bedeutung |
|---|---|
| FILE_SHARE_DELETE | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Löschzugriff sind erfolgreich. |
| FILE_SHARE_READ | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Lesezugriff sind erfolgreich. |
| FILE_SHARE_WRITE | Nachfolgende Anforderungen zum Öffnen des Datenstroms mit Schreibzugriff sind erfolgreich. |
[in, optional] psdLogFile
Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur , die Sicherheitsattribute für den Stream bereitstellt. Dieser Parameter kann NULL sein.
[in] fCreateDisposition
Die auszuführende Aktion hängt davon ab, ob der Stream bereits vorhanden ist. Dieser Parameter muss auf einen der folgenden Werte festgelegt werden:
| Wert | Bedeutung |
|---|---|
| CREATE_NEW | Erstellen Sie einen neuen Stream, wenn der Stream nicht bereits beendet wird. Schlägt fehl, wenn der Stream bereits vorhanden ist. |
| OPEN_EXISTING | Öffnen Sie einen vorhandenen Stream. Schlägt fehl, wenn der Stream noch nicht vorhanden ist. |
| OPEN_ALWAYS | Öffnen Sie einen vorhandenen Stream. Erstellen Sie den Stream, falls 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:
| Flag | Bedeutung |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | Die Datensätze des Streams können nicht in den internen Puffern eines Treibers zwischengespeichert werden. |
| FILE_SYNCHRONOUS_IO_ALERT | Alle Vorgänge für den Stream werden synchron ausgeführt. Jede Wartezeit im Namen des Anrufers unterliegt der vorzeitigen Beendigung von Warnungen. Wenn dieses Flag festgelegt ist, muss das FILE_SYNCHRONOUS_IO_NONALERT Flag gelöscht werden. |
| FILE_SYNCHRONOUS_IO_NONALERT | Alle Vorgänge für den Stream werden synchron ausgeführt. Wartezeiten im System, die E/A-Warteschlangen und Vervollständigung synchronisieren, unterliegen keinen Warnungen. Wenn dieses Flag festgelegt ist, muss das FILE_SYNCHRONOUS_IO_ALERT-Flag gelöscht werden. |
[in] fFlagsAndAttributes
Ein Wert, der angibt, ob der Stream für normalen oder schreibgeschützten Zugriff geöffnet wird. Dieser Parameter muss auf einen 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 Stream erstellt oder öffnet. Dieser Parameter muss auf einen der folgenden Werte festgelegt werden:
| Wert | Bedeutung |
|---|---|
| CLFS_FLAG_NO_FLAGS | CLFS und die erstellender Komponente verfügen über die Standard-Normalbeziehung. 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, ob cbContext größer als 0 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 für die Zuweisung von Containern, und das Dateisystem verwendet CLFS-Streams. In diesem Fall ist es möglich, dass das Dateisystem CLFS aufruft, und CLFS kann für denselben Thread oder andere Threads Wiederaufrufe an das Dateisystem vornehmen. Wenn pvContext nicht NULL ist, überprüft CLFS, ob cbContext größer als 0 ist. Andernfalls werden pvContext und cbContext ignoriert. |
| CLFS_FLAG_NON_REENTRANT_FILTER | Die erstellende Komponente ist ein Dateisystemfiltertreiber, der alle CLFS-E/A-Vorgänge an eine angegebene Ebene unterhalb des Filterstapels sendet. Mit dieser Option kann ein Filtertreiber ein CLFS-Protokoll erstellen, ohne eigene Protokollierungs-E/A zu sehen. Der Aufrufer übergibt das Nicht-NULL-Zielgerätobjekt im pvContext-Parameter, wobei cbContext auf die entsprechende Größe festgelegt ist. CLFS verwendet die IoCreateFileSpecifyDeviceObjectHint-Routine , um Container auf einer zielorientierten Ebene im vom Geräteobjekt angegebenen E/A-Filterstapel zu erstellen. |
| CLFS_FLAG_REENTRANT_FILTER | Die erstellende Komponente ist ein Dateisystemfiltertreiber, der alle CLFS-E/A-Vorgänge an den Anfang des Filterstapels sendet. Der Filter verfügt über eine rekursive Beziehung mit CLFS, da er seine eigenen Protokollierungs-E/A filtert, wenn CLFS einen Dateisystemvorgang für seine Container ausführt. Der pvContext-Parameter bietet eine Möglichkeit für Filter, seinen CLFS-Containern einen erkennbaren Kontext zuzuordnen, da Protokoll-E/A 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-Vorgänge an eine angegebene Ebene unterhalb des Filterstapels sendet. Mit dieser Option kann ein Minifilter ein CLFS-Protokoll erstellen, ohne eigene Protokollierungs-E/A-Vorgänge 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 pvContext verweist. Wenn pvContext nicht NULL ist, muss dieser Parameter größer als 0 sein.
Rückgabewert
ClfsCreateLogFile gibt bei Erfolg STATUS_SUCCESS zurück. Andernfalls wird einer der in "Ntstatus.h" definierten Fehlercodes zurückgegeben.
Hinweise
Wenn Sie einen CLFS-Stream erstellen, wird er von einem zugrunde liegenden physischen CLFS-Protokoll unterstützt. Das zugrunde liegende Protokoll kann entweder dediziert (nur einen Stream) oder multiplexed (mehrere Streams) sein. Ein dediziertes Protokoll kann nicht in ein Multiplexprotokoll konvertiert werden, und ein multiplexiertes 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( Common Log File System).
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows Server 2003 R2, Windows Vista und höheren Versionen von Windows. |
| Zielplattform | Desktop |
| Kopfzeile | wdm.h (wdm.h einschließen) |
| Bibliothek | Clfs.lib |
| DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |