Windows Dev Center

ReadLogRecord function

Initiates a sequence of reads from a specified log sequence number (LSN) in one of three modes, and returns the first of the specified log records and a read context. A client can read subsequent records in the designated mode by passing the read context to ReadNextLogRecord.

Syntax


BOOL WINAPI 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,
  _Inout_opt_ LPOVERLAPPED      pOverlapped
);

Parameters

pvMarshal [in]

A pointer to a marshaling context that is allocated by using the CreateLogMarshallingArea function.

plsnFirst [in]

A pointer to a CLFS_LSN structure that specifies the log sequence number (LSN) of the record where the read operation should start.

This value must be an LSN of a valid record in the active range of the log.

eContextMode [in]

The mode for the read context that is returned in *ppvReadContext.

The following table identifies the three mutually exclusive read modes.

ValueMeaning
ClfsContextPrevious

Reads the record linked to by plsnPrevious.

ClfsContextUndoNext

Reads the record chain linked to by plsnUndoNext.

ClfsContextForward

Reads the record with the LSN that immediately follows the current LSN in the read context.

 

ppvReadBuffer [out]

A pointer to a variable that receives a pointer to the target record in the log I/O block.

pcbReadBuffer [out]

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

peRecordType [out]

A pointer to a variable that receives the type of record read.

This parameter is one of the CLFS_RECORD_TYPE Constants.

plsnUndoNext [out]

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

plsnPrevious [out]

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

ppvReadContext [out]

A pointer to a variable that receives a pointer to a system-allocated read context when a read is successful.

If the function defers completion of an operation, it returns a valid read-context pointer and an error status of ERROR_IO_PENDING. On all other errors, the read-context pointer is NULL. For more information about handling deferred completion of the function, see the Remarks section of this topic.

After obtaining all requested log records, the client must pass the read context to TerminateReadLog to free the associated memory. Failure to do so results in memory leakage.

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, or passed into more than one asynchronous read at a time.
pOverlapped [in, out, optional]

A pointer to an OVERLAPPED structure, which 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.

ERROR_ACCESS_DENIED
ERROR_HANDLE_EOF
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_IO_DEVICE
ERROR_IO_PENDING
ERROR_LOG_BLOCKS_EXHAUSTED
ERROR_LOG_BLOCK_INCOMPLETE
ERROR_LOG_START_OF_LOG

Remarks

The error message ERROR_LOG_BLOCK_INCOMPLETE is returned if the log block size specified by CreateLogMarshallingArea is not large enough to hold a complete log block.

If ReadLogRecord is called with a valid pOverlapped structure and the log handle is created with the overlapped option, then if a call to this function fails with an error code of ERROR_IO_PENDING, a pointer to a valid read context is placed in the variable that is pointed to by the ppvReadContext parameter.

If you attempt to open more read contexts than the number buffers specified in a previous call to CreateLogMarshallingArea, ERROR_LOG_BLOCK_EXHAUSTED is returned.

To complete a log-record copy, the client should first 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 ReadLogRecord completes asynchronously, the requested record is read from the disk, but is not resolved to a pointer in *ppvReadBuffer.

To complete the requested read and obtain a valid pointer to the log record, the client must call ReadNextLogRecord, which passes in the read-context pointer that ReadLogRecord returns.

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_BUSY.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 R2 [desktop apps only]

Header

Clfsw32.h

Library

Clfsw32.lib

DLL

Clfsw32.dll

See also

CLFS_CONTEXT_MODE
CLFS_LSN
CLFS_RECORD_TYPE
Common Log File System Functions
CreateLogMarshallingArea
OVERLAPPED
ReadNextLogRecord
TerminateReadLog

 

 

Community Additions

ADD
Show:
© 2015 Microsoft