Edit

CreateLogMarshallingArea function (clfsw32.h)

  • Article

Creates a marshaling area for a log, and when successful it returns a marshaling context. Before creating a marshaling area, the log must have at least one container.

The marshaling context is used to append records to or read records from a log. Because records are always stored in log blocks, they must pass through the marshaling context.

Log records are written by calling ReserveAndAppendLog.

Syntax

CLFSUSER_API BOOL CreateLogMarshallingArea(
  [in]           HANDLE                  hLog,
  [in, optional] CLFS_BLOCK_ALLOCATION   pfnAllocBuffer,
  [in, optional] CLFS_BLOCK_DEALLOCATION pfnFreeBuffer,
  [in, optional] PVOID                   pvBlockAllocContext,
  [in]           ULONG                   cbMarshallingBuffer,
  [in]           ULONG                   cMaxWriteBuffers,
  [in]           ULONG                   cMaxReadBuffers,
  [out]          PVOID                   *ppvMarshal
);

Parameters

[in] hLog

A handle to the log that is obtained from CreateLogFile.

The log handle can refer to a dedicated or multiplexed log.

[in, optional] pfnAllocBuffer

The callback function that allocates memory for log blocks.

If this parameter is NULL, the Common Log File System (CLFS) provides a default block allocation function. This parameter cannot be NULL if a block-freeing callback is specified by using the pfnFreeBuffer parameter.

The following example identifies the syntax of the block allocation callback function:

typedef PVOID (* CLFS_BLOCK_ALLOCATION) (ULONG cbBufferSize, PVOID pvUserContext);

[in, optional] pfnFreeBuffer

The callback function that frees log blocks allocated by pfnAllocBuffer.

If this parameter is NULL, CLFS provides a default block deallocation function. This parameter cannot be NULL if a block allocation callback is specified by using the pfnAllocBuffer parameter.

The following example identifies the syntax of the block-freeing callback function:

typedef void (* CLFS_BLOCK_DEALLOCATION) (PVOID pvBuffer, PVOID pvUserContext);

The buffer parameter of "ClfsBlockDeallocProc" must point to a block that is allocated by using the callback pointed to by pfnAllocBuffer.

[in, optional] pvBlockAllocContext

A pointer to a buffer that is passed back as a user context to the block allocation and deallocation routines, if a buffer is specified.

If pfnAllocBuffer is NULL, this parameter is ignored.

[in] cbMarshallingBuffer

The size, in bytes, of the individual log I/O blocks that will be used by the new marshaling area. This must be a multiple of the sector size on the stable storage medium. The sector size is the value returned in the lpBytesPerSector parameter of the GetDiskFreeSpace function.

Records cannot be appended or read if they are longer than this value.

[in] cMaxWriteBuffers

The maximum number of blocks that can be allocated at any time for write operations.

This value can affect the frequency of data flushes. If you do not need to specify a limit to control the frequency of the data flush cycle, specify INFINITE.

[in] cMaxReadBuffers

The maximum number of blocks that can be allocated at any time for read operations.

Read contexts use at least one read block.

[out] ppvMarshal

A pointer to the marshaling context that CLFS allocates when CreateLogMarshallingArea completes successfully.

This context must be used with all read, append, write, and flush operations to log marshaling areas. All operations that access marshaling areas by using a marshaling context are thread-safe. This parameter is NULL if the operation is not successful.

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:

Requirements

Requirement Value
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

Common Log File System Functions

CreateLogFile

DeleteLogMarshallingArea