This topic has not yet been rated - Rate this topic

CreateLogMarshallingArea function

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

C++


BOOL WINAPI CreateLogMarshallingArea(
  _In_      HANDLE hLog,
  _In_opt_  CLFS_BLOCK_ALLOCATION pfnAllocBuffer,
  _In_opt_  CLFS_BLOCK_DEALLOCATION pfnFreeBuffer,
  _In_opt_  PVOID   pvBlockAllocContext,
  _In_      ULONG cbMarshallingBuffer,
  _In_      ULONG  cMaxWriteBuffers,
  _In_      ULONG cMaxReadBuffers,
  _Out_     PVOID *ppvMarshal
);

Parameters

hLog [in]

A handle to the log that is obtained from CreateLogFile.

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

pfnAllocBuffer [in, optional]

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

pfnFreeBuffer [in, optional]

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.

pvBlockAllocContext [in, optional]

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.

cbMarshallingBuffer [in]

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.

cMaxWriteBuffers [in]

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.

cMaxReadBuffers [in]

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

Read contexts use at least one read block.

ppvMarshal [out]

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:

ERROR_ACCESS_DENIED
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_NO_SYSTEM_RESOURCES
ERROR_OUT_OF_MEMORY

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

Community Additions