Функция ReadLogRecord (clfsw32.h)

Статья
03/14/2023

Инициирует последовательность операций чтения из указанного номера журнала (LSN) в одном из трех режимов и возвращает первую из указанных записей журнала и контекст чтения. Клиент может считывать последующие записи в указанном режиме, передав контекст чтения в ReadNextLogRecord.

Синтаксис

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
);

Параметры

[in] pvMarshal

Указатель на контекст маршалинга, выделенный с помощью функции CreateLogMarshallingArea .

[in] plsnFirst

Указатель на структуру CLFS_LSN , указывающую номер LSN записи, с которой должна начинаться операция чтения.

Это значение должно быть номером LSN допустимой записи в активном диапазоне журнала.

[in] eContextMode

Режим для контекста чтения, возвращаемого в *ppvReadContext.

В следующей таблице указаны три взаимоисключающих режима чтения.

Значение	Значение
ClfsContextPrevious	Считывает запись, связанную с plsnPrevious.
ClfsContextUndoNext	Считывает цепочку записей, связанную с plsnUndoNext.
ClfsContextForward	Считывает запись с номером LSN, который сразу же следует за текущим номером LSN в контексте чтения.

[out] ppvReadBuffer

Указатель на переменную, которая получает указатель на целевую запись в блоке ввода-вывода журнала.

[out] pcbReadBuffer

Указатель на переменную, которая получает размер данных, возвращаемых в *ppvReadBuffer, в байтах.

[out] peRecordType

Указатель на переменную, получающую тип считываемой записи.

Этот параметр является одной из констант CLFS_RECORD_TYPE.

[out] plsnUndoNext

Указатель на структуру CLFS_LSN , которая получает номер LSN следующей записи в цепочке отмены записей.

[out] plsnPrevious

Указатель на структуру CLFS_LSN , получающую номер LSN следующей записи в предыдущей цепочке записей.

[out] ppvReadContext

Указатель на переменную, которая получает указатель на выделенный системой контекст чтения при успешном чтении.

Если функция откладывает завершение операции, она возвращает допустимый указатель контекста чтения и состояние ошибки ERROR_IO_PENDING. Во всех остальных ошибках указатель контекста чтения имеет значение NULL. Дополнительные сведения об обработке отложенного завершения функции см. в разделе Примечания этой статьи.

После получения всех запрошенных записей журнала клиент должен передать контекст чтения в TerminateReadLog , чтобы освободить связанную память. Если это не сделать, это приведет к утечке памяти.

Примечание Общие контексты чтения файловой системы журналов (CLFS) не являются потокобезопасны. Они не должны использоваться несколькими потоками одновременно или передаваться в несколько асинхронных операций чтения за раз.

[in, out, optional] pOverlapped

Указатель на структуру OVERLAPPED , необходимую для асинхронной операции.

Если асинхронная операция не используется, этот параметр может иметь значение NULL .

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

В следующем списке указаны возможные коды ошибок.

Сообщение об ошибке ERROR_LOG_BLOCK_INCOMPLETE возвращается, если размер блока журнала, заданный параметром CreateLogMarshallingArea , недостаточно велик для хранения полного блока журнала.

Если метод ReadLogRecord вызывается с допустимой структурой pOverlapped и дескриптор журнала создается с перекрывающимся параметром, то если вызов этой функции завершается сбоем с кодом ошибки ERROR_IO_PENDING, указатель на допустимый контекст чтения помещается в переменную, на которую указывает параметр ppvReadContext .

При попытке открыть больше контекстов чтения, чем число буферов, указанных в предыдущем вызове CreateLogMarshallingArea, возвращается ERROR_LOG_BLOCK_EXHAUSTED.

Чтобы завершить копирование записи журнала, клиент должен сначала синхронизировать его выполнение с отложенным завершением перекрывающейся операции ввода-вывода с помощью GetOverlappedResult или одной из функций ожидания синхронизации. Дополнительные сведения см. в разделе Синхронизация и перекрытие входных и выходных данных.

После асинхронного завершения ReadLogRecord запрошенная запись считывается с диска, но не разрешается в указатель в *ppvReadBuffer.

Чтобы завершить запрошенное чтение и получить допустимый указатель на запись журнала, клиент должен вызвать ReadNextLogRecord, который передает указатель контекста чтения, возвращаемый ReadLogRecord .

Примечание Общие контексты чтения файловой системы журналов (CLFS) не являются потокобезопасны. Они не должны использоваться несколькими потоками одновременно.

Контексты чтения CLFS не должны передаваться в несколько асинхронных операций чтения за раз, иначе функция завершается сбоем с ERROR_BUSY.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 R2 [только классические приложения]
Целевая платформа	Windows
Header	clfsw32.h
Библиотека	Clfsw32.lib
DLL	Clfsw32.dll