ReadNextLogRecord function (clfsw32.h)

Article
10/13/2021

Reads the next record in a sequence that is initiated by a call to ReadLogRecord or ReadLogRestartArea. By using ReadNextLogRecord iteratively, a client can read all records of a specified type in a log. The direction of enumeration is determined by specifying the context mode when beginning the read sequence.

Syntax

CLFSUSER_API BOOL ReadNextLogRecord(
  [in, out]           PVOID             pvReadContext,
  [out]               PVOID             *ppvBuffer,
  [out]               PULONG            pcbBuffer,
  [in, out]           PCLFS_RECORD_TYPE peRecordType,
  [in, optional]      PCLFS_LSN         plsnUser,
  [out]               PCLFS_LSN         plsnUndoNext,
  [out]               PCLFS_LSN         plsnPrevious,
  [out]               PCLFS_LSN         plsnRecord,
  [in, out, optional] LPOVERLAPPED      pOverlapped
);

Parameters

[in, out] pvReadContext

A pointer to a read context that the system allocates and creates during a successful call to ReadLogRecord or ReadLogRestartArea.

If the function defers completion of an operation, it returns a pointer to a valid read context and an error status of ERROR_IO_PENDING. For information about handling asynchronous completion, see the Remarks section of this topic.

[out] ppvBuffer

A pointer to a variable that receives a pointer to the read data.

[out] pcbBuffer

A pointer to a variable that receives the size of the read data that is returned in ppvReadBuffer, in bytes.

[in, out] peRecordType

A pointer that, on input, specifies the record type filter of the next record read, and on output specifies the record type that is returned.

Clients can specify any of the following record types.

Value	Meaning
ClfsDataRecord	Only user-data records are read.
ClfsRestartRecord	Only restart records are read.
ClfsClientRecord	All restart and data records are read.

[in, optional] plsnUser

A pointer to a CLFS_LSN structure that specifies the log client to read this log sequence number (LSN) as the next LSN instead of reading forward to the next record, reading the previous LSN, or reading the next undo LSN.

This parameter gives log clients the ability to cursor through user-defined LSN chains in client buffers. The relationship of this parameter to the current LSN held by the read context must be consistent with the context mode, ecxMode, that is specified in the ReadLogRecord entry points; otherwise, an error code of ERROR_INVALID_PARAMETER is returned.

[out] plsnUndoNext

A pointer to a CLFS_LSN structure that receives the LSN of the next record in an undo record chain.

[out] plsnPrevious

A pointer to a CLFS_LSN structure that receives the LSN of the next record in the previous record chain.

[out] plsnRecord

A pointer to a CLFS_LSN structure that receives the LSN of the current record read into the read context.

[in, out, optional] pOverlapped

A pointer to an OVERLAPPED structure that is required for asynchronous operation.

This parameter can be NULL if asynchronous operation is not used.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

The following list identifies the possible error codes:

Remarks

If ReadNextLogRecord returns with a status code of ERROR_IO_PENDING, the client should synchronize its execution with deferred completion of the overlapped I/O operation by using GetOverlappedResult, or one of the synchronization Wait Functions. For more information, see Synchronization and Overlapped Input and Output.

After ReadNextLogRecord completes asynchronously, the requested record is read from the disk, but is not resolved to a pointer in *ppvReadBuffer. To obtain a valid pointer to the record, the client must call ReadNextLogRecord a second time.

Note Common Log File System (CLFS) read contexts are not thread-safe. They should not be used by more than one thread at a time.

CLFS read contexts should not be passed into more than one asynchronous read at a time, or the function fails with ERROR_READ.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 R2 [desktop apps only]
Target Platform	Windows
Header	clfsw32.h
Library	Clfsw32.lib
DLL	Clfsw32.dll