ReadNextLogRecord function

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 PCLFS_LSN             plsnUser,
  OUT PCLFS_LSN            plsnUndoNext,
  OUT PCLFS_LSN            plsnPrevious,
  OUT PCLFS_LSN            plsnRecord,
  IN OUT LPOVERLAPPED      pOverlapped
);

Parameters

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.

ppvBuffer

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

pcbBuffer

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

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.

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.

plsnUndoNext

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

plsnPrevious

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

plsnRecord

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

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

   
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

See Also

CLFS_LSN

CLFS_RECORD_TYPE

Common Log File System Functions

OVERLAPPED

ReadLogRecord

ReadLogRestartArea

Synchronization and Overlapped Input and Output