ClfsReserveAndAppendLog function (wdm.h)

Article
02/25/2022

The ClfsReserveAndAppendLog routine reserves space in a marshalling area or appends a record to a marshalling area or does both atomically.

Syntax

CLFSUSER_API NTSTATUS ClfsReserveAndAppendLog(
  [in]            PVOID             pvMarshalContext,
  [in, optional]  PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]            ULONG             cWriteEntries,
  [in, optional]  PCLFS_LSN         plsnUndoNext,
  [in, optional]  PCLFS_LSN         plsnPrevious,
  [in]            ULONG             cReserveRecords,
  [in, out]       PLONGLONG         rgcbReservation,
  [in]            ULONG             fFlags,
  [out, optional] PCLFS_LSN         plsn
);

Parameters

[in] pvMarshalContext

A pointer to an opaque context that represents a marshalling area associated with a CLFS stream. The caller previously obtained this pointer by calling ClfsCreateMarshallingArea.

[in, optional] rgWriteEntries

A pointer to an array of CLFS_WRITE_ENTRY structures, each of which holds a pointer to a buffer of data that will become part of the record that is appended to the log. This parameter can be NULL if cWriteEntries is zero.

[in] cWriteEntries

The number of elements in the array pointed to by rgWriteEntries. This parameter must be zero if rgWriteEntries is NULL.

[in, optional] plsnUndoNext

A pointer to a CLFS_LSN structure that supplies the undo-next LSN of the record to be appended.

[in, optional] plsnPrevious

A pointer to a CLFS_LSN structure that supplies the previous LSN of the record to be appended.

[in] cReserveRecords

The number of elements in the array pointed to by rgcbReservation. This parameter must be zero if rgcbReservation is NULL or the CLFS_FLAG_USE_RESERVATION flag of fFlags is set.

[in, out] rgcbReservation

A pointer to an array of LONGLONG-typed variables. The caller sets each element of the array to the size, in bytes, of a record that must have space reserved for it. On return, each array element receives that actual size of the space reserved for the record. This includes the space required for headers and alignment. If the reservation value is negative, a reserved record that most nearly matches the absolute value of the provided negative value will be freed. This parameter can be NULL if cReserveRecords is zero and must be NULL if the CLFS_FLAG_USE_RESERVATION flag of fFlags is set.

[in] fFlags

This parameter can be zero or any combination of the following flags.

Flag	Meaning
CLFS_FLAG_FORCE_APPEND	After the current record is appended to a log I/O block, the block is queued, in LSN sequence, to stable storage. This flag provides no guarantee that the record is forced to stable storage (see CLFS_FLAG_FORCE_FLUSH).
CLFS_FLAG_FORCE_FLUSH	After the current record is appended to a log I/O block, the block is forced to stable storage.
CLFS_FLAG_USE_RESERVATION	The current record is placed in reserved space in a log I/O block within the marshalling area. The number of reserved records in the marshalling area is reduced by one. If this flag is set, cReserveRecords must be zero and rgcbReservation must be NULL.

[out, optional] plsn

A pointer to a CLFS_LSN structure that receives the LSN of the appended record. This parameter can be NULL if cWriteEntries is zero.

Return value

ClfsReserveAndAppendLog returns STATUS_SUCCESS if it succeeds; otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

The ClfsReserveAndAppendLog routine changes its fundamental behavior based on the presence of optional parameters and the state of the CLFS_USE_RESERVATION flag. The following table summarizes common scenarios.

Parameter and flag values	Actions performed
cWriteEntries = 0. rgWriteEntries = NULL. plsn = NULL.	Reserves space for a set of records, but does not append the records to the marshalling area. The rgcbReservation parameter gives the size of the data portion of each record that needs space reserved.
cWriteEntries > 0. rgWriteEntries is not NULL. plsn is not NULL. cReserveRecords = 0. rgcbReservation is NULL. CLFS_USE_RESERVATION is set.	Appends a record to the marshalling area by using space that has already been reserved. Reduces the number of reserved record spaces by one.
cWriteEntries > 0. rgWriteEntries is not NULL. plsn is not NULL. cReserveRecords = 0. rgcbReservation is NULL. CLFS_USE_RESERVATION is cleared.	Appends a record to the marshalling area by reserving new space. Leaves the number of reserved record spaces unchanged.
cWriteEntries > 0. rgWriteEntries is not NULL. plsn is not NULL. cReserveRecords > 0. rgcbReservation is not NULL. CLFS_USE_RESERVATION flag is cleared.	Appends a record to the marshalling area by reserving new space. Also reserves space for a set of records that are not appended at this time. The rgcbReservation parameter gives the size of each record that needs space reserved. Increases the number of reserved record spaces by the value of cReserveRecords.

Calling ClfsReserveAndAppendLog is equivalent to calling ClfsReserveAndAppendLogAligned with the cbEntryAlignment parameter set to one.

For an explanation of CLFS concepts and terminology, see Common Log File System.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Server 2003 R2, Windows Vista, and later versions of Windows.
Target Platform	Desktop
Header	wdm.h (include Wdm.h)
Library	Clfs.lib
DLL	Clfs.sys
IRQL	<= APC_LEVEL