CreateLogFile-Funktion (clfsw32.h)

Artikel
11/20/2024

Erstellt oder öffnet ein Protokoll. Das Protokoll kann dediziert oder multiplexed sein, und das hängt vom Protokollnamen ab. Verwenden Sie die CloseHandle--Funktion, um das Protokoll zu schließen.

Syntax

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

Parameter

[in] pszLogFileName

Der Name des Protokolls.

Dieser Name wird beim Erstellen des Protokolls mithilfe CreateLogFile-angegeben. Im folgenden Beispiel wird das zu verwendende Format identifiziert.

Protokoll:<LogName>[::<LogStreamName>]

Beispiel: Der Pfad "LOG:c:\MyDirectory\MyLog" erstellt die Datei "c:\MyDirectory\MyLog.blf". Der Pfad "?? \LOG:\HarddiskVolume1\MyDirectory\MyLog" erstellt die Datei "\.\HarddiskVolume1\MyDirectory\MyLog.blf", wie der Pfad "\clfs\Device\HarddiskVolume1\MyDirectory\MyLog".

< LogName-> entspricht einem gültigen Dateipfad im Dateisystem, und <LogStreamName-> ist der eindeutige Name eines Protokolldatenstroms im Protokoll. Weitere Informationen finden Sie unter Protokolltypen.

[in] fDesiredAccess

Der Typ des Zugriffs, den das zurückgegebene Handle für das Protokollobjekt hat.

Wert	Bedeutung
GENERIC_READ	Gibt den Lesezugriff auf das Objekt an.
GENERIC_WRITE	Gibt schreibzugriff auf das Objekt an.
DELETE-	Protokolllöschzugriff angeben

Ein bitweiser ODER von zwei oder mehr dieser Flags ermöglicht Kombinationen aus Lese-, Schreib- und Löschzugriff auf das Objekt.

Hinweis Sie müssen DELETE- Zugriff angeben, um das Protokoll löschen zu können.

Windows Server 2003 R2: Dieser Parameter muss auf GENERIC_WRITEfestgelegt werden.

[in] dwShareMode

Der Freigabemodus einer Datei.

Ein Client kann keinen Freigabemodus anfordern, der mit einem Modus in Konflikt steht, der in einer vorherigen offenen Anforderung mit einem offenen Handle angegeben ist.

Wenn dieser Parameter null ist und die Funktion erfolgreich ausgeführt wird, kann das Objekt nicht freigegeben und erst wieder geöffnet werden, nachdem das Handle geschlossen wurde.

Dieser Parameter kann einen oder mehrere der folgenden Werte sein.

Wert	Bedeutung
FILE_SHARE_DELETE	Aktiviert geöffnete Vorgänge für das Objekt, um den Löschzugriff anzufordern. Ohne diesen Wert können andere Prozesse das Objekt nicht öffnen, wenn der Löschzugriff angefordert wird.
FILE_SHARE_READ	Aktiviert geöffnete Vorgänge für das Objekt, um Lesezugriff anzufordern. Ohne diesen Wert können andere Prozesse das Objekt nicht öffnen, wenn lesezugriff angefordert wird.
FILE_SHARE_WRITE	Ermöglicht geöffneten Vorgängen für das Objekt das Anfordern des Schreibzugriffs. Ohne diesen Wert können andere Prozesse das Objekt nicht öffnen, wenn Schreibzugriff angefordert wird.

[in, optional] psaLogFile

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur, die die Sicherheitsattribute eines Protokolls angibt.

Es bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Wenn dieser Parameter NULL-ist, kann das Handle nicht geerbt werden.

Der lpSecurityDescriptor Mitglied von SECURITY_ATTRIBUTES gibt einen Sicherheitsdeskriptor an, der für das neue Protokollhandle. Wenn psaLogFile-NULL-ist, erhält das Objekt einen Standardsicherheitsdeskriptor. Die Zugriffssteuerungslisten (Access Control Lists, ACL) im Standardsicherheitsdeskriptor für ein Protokoll stammen aus dem primären oder Identitätswechseltoken des Erstellers.

[in] fCreateDisposition

Eine zu ergreifende Aktion.

Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
CREATE_NEW	Erstellt eine neue Datei und schlägt fehl, wenn die Datei bereits vorhanden ist.
OPEN_EXISTING	Öffnet eine vorhandene Datei und schlägt fehl, wenn die Datei nicht vorhanden ist.
OPEN_ALWAYS	Öffnet eine vorhandene Datei oder erstellt die Datei, wenn sie nicht vorhanden ist.

[in] fFlagsAndAttributes

Die Dateiattribute und Flags für die Datei.

Dieser Parameter kann die folgenden Werte annehmen.

Wert	Bedeutung
FILE_ATTRIBUTE_ARCHIVE	Dieses nicht ephemerale Protokoll sollte archiviert werden. Wenn diese Kennzeichnung nicht angegeben wird, muss das Protokoll nicht archiviert werden, und ein Archivschwanz wird für Recyclingprotokollcontainer nicht verwaltet.
FILE_FLAG_OVERLAPPED	Wenn das FILE_FLAG_OVERLAPPED Flag festgelegt ist, werden alle anderen Flagwerte ignoriert. Wenn Sie FILE_FLAG_OVERLAPPED angeben, bedeutet dies, dass eine Datei für überlappende E/A geöffnet wird, wodurch mehrere E/A-Vorgänge für das Protokollhandle ausgeführt werden können. Wenn dieses Flag beim Erstellen eines Protokolls festgelegt ist, müssen alle asynchronen E/A-Aufrufe für dieses Protokoll eine überlappende Struktur angeben und mit dem verzögerten Abschluss des Aufrufs synchronisiert werden.

Wert

Bedeutung

FILE_ATTRIBUTE_ARCHIVE

Dieses nicht ephemerale Protokoll sollte archiviert werden.

Wenn diese Kennzeichnung nicht angegeben wird, muss das Protokoll nicht archiviert werden, und ein Archivschwanz wird für Recyclingprotokollcontainer nicht verwaltet.

FILE_FLAG_OVERLAPPED

Wenn das FILE_FLAG_OVERLAPPED Flag festgelegt ist, werden alle anderen Flagwerte ignoriert.

Wenn Sie FILE_FLAG_OVERLAPPED angeben, bedeutet dies, dass eine Datei für überlappende E/A geöffnet wird, wodurch mehrere E/A-Vorgänge für das Protokollhandle ausgeführt werden können. Wenn dieses Flag beim Erstellen eines Protokolls festgelegt ist, müssen alle asynchronen E/A-Aufrufe für dieses Protokoll eine überlappende Struktur angeben und mit dem verzögerten Abschluss des Aufrufs synchronisiert werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Protokoll.

Wenn die Funktion fehlschlägt, wird der Rückgabewert INVALID_HANDLE_VALUE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Die folgende Liste identifiziert die möglichen Fehlercodes:

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 R2 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	clfsw32.h
Library	Clfsw32.lib
DLL-	Clfsw32.dll