ClfsReserveAndAppendLog function (wdm.h)
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 |