ReadLogRecord-Funktion (clfsw32.h)

Artikel
08/22/2023

Initiiert eine Sequenz von Lesevorgängen aus einer angegebenen Protokollsequenznummer (LSN) in einem von drei Modi und gibt den ersten der angegebenen Protokolldatensätze und einen Lesekontext zurück. Ein Client kann nachfolgende Datensätze im festgelegten Modus lesen, indem er den Lesekontext an ReadNextLogRecord übergibt.

Syntax

CLFSUSER_API BOOL ReadLogRecord(
  [in]                PVOID             pvMarshal,
  [in]                PCLFS_LSN         plsnFirst,
  [in]                CLFS_CONTEXT_MODE eContextMode,
  [out]               PVOID             *ppvReadBuffer,
  [out]               PULONG            pcbReadBuffer,
  [out]               PCLFS_RECORD_TYPE peRecordType,
  [out]               PCLFS_LSN         plsnUndoNext,
  [out]               PCLFS_LSN         plsnPrevious,
  [out]               PVOID             *ppvReadContext,
  [in, out, optional] LPOVERLAPPED      pOverlapped
);

Parameter

[in] pvMarshal

Ein Zeiger auf einen Marshallkontext, der mithilfe der CreateLogMarshallingArea-Funktion zugeordnet wird.

[in] plsnFirst

Ein Zeiger auf eine CLFS_LSN-Struktur , die die Protokollsequenznummer (LSN) des Datensatzes angibt, in dem der Lesevorgang gestartet werden soll.

Dieser Wert muss ein LSN eines gültigen Datensatzes im aktiven Bereich des Protokolls sein.

[in] eContextMode

Der Modus für den Lesekontext, der in *ppvReadContext zurückgegeben wird.

In der folgenden Tabelle sind die drei sich gegenseitig ausschließenden Lesemodi aufgeführt.

Wert	Bedeutung
ClfsContextPrevious	Liest den Datensatz, mit dem durch plsnPrevious verknüpft ist.
ClfsContextUndoWeiter	Liest die Datensatzkette, mit der plsnUndoNext verknüpft ist.
ClfsContextForward	Liest den Datensatz mit dem LSN, der unmittelbar dem aktuellen LSN im Lesekontext folgt.

[out] ppvReadBuffer

Ein Zeiger auf eine Variable, die einen Zeiger auf den Zieldatensatz im Protokoll-E/A-Block empfängt.

[out] pcbReadBuffer

Ein Zeiger auf eine Variable, die die Größe der in *ppvReadBuffer zurückgegebenen Daten in Bytes empfängt.

[out] peRecordType

Ein Zeiger auf eine Variable, die den Typ des Gelesenen Datensatzes empfängt.

Dieser Parameter ist eine der CLFS_RECORD_TYPE Konstanten.

[out] plsnUndoNext

Ein Zeiger auf eine CLFS_LSN-Struktur , die den LSN des nächsten Datensatzes in der Undo-Datensatzkette empfängt.

[out] plsnPrevious

Ein Zeiger auf eine CLFS_LSN-Struktur , die den LSN des nächsten Datensatzes in der vorherigen Datensatzkette empfängt.

[out] ppvReadContext

Ein Zeiger auf eine Variable, die einen Zeiger auf einen systemseitig zugewiesenen Lesekontext empfängt, wenn ein Lesevorgang erfolgreich ist.

Wenn die Funktion den Abschluss eines Vorgangs zurücksetzt, gibt sie einen gültigen Lesekontextzeiger und einen Fehler status von ERROR_IO_PENDING zurück. Bei allen anderen Fehlern ist der Lesekontextzeiger NULL. Weitere Informationen zum Behandeln der verzögerten Vervollständigung der Funktion finden Sie im Abschnitt Hinweise zu diesem Thema.

Nach dem Abrufen aller angeforderten Protokolldatensätze muss der Client den Lesekontext an TerminateReadLog übergeben, um den zugeordneten Arbeitsspeicher freizugeben. Wenn dies nicht geschieht, führt dies zu Speicherverlusten.

Hinweis CLFS-Lesekontexte (Common Log File System) sind nicht threadsicher. Sie sollten nicht von mehr als einem Thread gleichzeitig verwendet oder an mehrere asynchrone Lesevorgänge gleichzeitig übergeben werden.

[in, out, optional] pOverlapped

Ein Zeiger auf eine ÜBERLAPPENDE Struktur, die für asynchrone Vorgänge erforderlich ist.

Dieser Parameter kann NULL sein, wenn kein asynchroner Vorgang verwendet wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

In der folgenden Liste werden die möglichen Fehlercodes identifiziert.

Hinweise

Die Fehlermeldung ERROR_LOG_BLOCK_INCOMPLETE wird zurückgegeben, wenn die von CreateLogMarshallingArea angegebene Protokollblockgröße nicht groß genug ist, um einen vollständigen Protokollblock aufzunehmen.

Wenn ReadLogRecord mit einer gültigen pOverlapped-Struktur aufgerufen wird und das Protokollhandle mit der Option überlappend erstellt wird, wird ein Zeiger auf einen gültigen Lesekontext in der Variablen platziert, auf die der ppvReadContext-Parameter verweist, wenn ein Aufruf dieser Funktion mit einem Fehlercode von ERROR_IO_PENDING fehlschlägt.

Wenn Sie versuchen, mehr Lesekontexte als die in einem vorherigen Aufruf von CreateLogMarshallingArea angegebenen Zahlenpuffer zu öffnen, wird ERROR_LOG_BLOCK_EXHAUSTED zurückgegeben.

Um eine Protokolldatensatzkopie abzuschließen, sollte der Client zunächst seine Ausführung mit verzögertem Abschluss des überlappenden E/A-Vorgangs mithilfe von GetOverlappedResult oder einer der Synchronisierungswartefunktionen synchronisieren. Weitere Informationen finden Sie unter Synchronisierung und überlappende Eingabe und Ausgabe.

Nachdem ReadLogRecord asynchron abgeschlossen wurde, wird der angeforderte Datensatz vom Datenträger gelesen, aber nicht in einen Zeiger in *ppvReadBuffer aufgelöst.

Um den angeforderten Lesevorgang abzuschließen und einen gültigen Zeiger auf den Protokolldatensatz abzurufen, muss der Client ReadNextLogRecord aufrufen, der den von ReadLogRecord zurückgegebenen Lesekontextzeiger übergibt.

Hinweis CLFS-Lesekontexte (Common Log File System) sind nicht threadsicher. Sie sollten nicht von mehr als einem Thread gleichzeitig verwendet werden.

CLFS-Lesekontexte sollten nicht gleichzeitig an mehrere asynchrone Lesevorgänge übergeben werden, oder die Funktion schlägt mit ERROR_BUSY fehl.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	clfsw32.h
Bibliothek	Clfsw32.lib
DLL	Clfsw32.dll