CreateLogContainerScanContext function (clfsw32.h)

Article
10/13/2021

Creates a scan context to use with ScanLogContainers to enumerate all log containers that are associated with a log, and performs the first scan.

Syntax

CLFSUSER_API BOOL CreateLogContainerScanContext(
  [in]                HANDLE             hLog,
  [in]                ULONG              cFromContainer,
  [in]                ULONG              cContainers,
  [in]                CLFS_SCAN_MODE     eScanMode,
  [in, out]           PCLFS_SCAN_CONTEXT pcxScan,
  [in, out, optional] LPOVERLAPPED       pOverlapped
);

Parameters

[in] hLog

A handle to the log that is obtained from CreateLogFile with permissions to scan the log containers.

The file can be a dedicated or multiplexed log.

[in] cFromContainer

The container where the scan is to be started.

This parameter is an ordinal number relative to the number of containers in the log.

[in] cContainers

The number of CLFS_CONTAINER_INFORMATION structures for CreateLogContainerScanContext to allocate.

This number is the number of containers scanned with each scan call so the caller knows the scan is complete when the number of containers returned is less than this value.

On exit, a pointer to the system-allocated array of CLFS_CONTAINER_INFORMATION structures is placed in the pinfoContainer member of the client-allocated CLFS_SCAN_CONTEXT structure. This member is pointed to by the pcxScan parameter (that is, "pcxScan->pinfoContainer[]"), and the actual number of structures in the array is placed in "pcxScan->cContainersReturned".

The client must call ScanLogContainers with the eScanMode parameter set to CLFS_SCAN_CLOSE so that it can free this array; otherwise, memory leaks result.

[in] eScanMode

The mode to scan containers.

Containers can be scanned in any one of the following modes.

Value	Meaning
CLFS_SCAN_INIT	Initializes or reinitializes a scan from the first container in the container list. This mode initializes the container context and returns the first set of container descriptors that cContainers specifies.
CLFS_SCAN_FORWARD	Returns the first set of containers that cContainers specifies.
CLFS_SCAN_BACKWARD	Returns the last set of containers that cContainers specifies.

[in, out] pcxScan

A pointer to a client-allocated CLFS_SCAN_CONTEXT structure that receives a scan context that can be passed to the ScanLogContainers function when a client scans the log containers of a dedicated log.

[in, out, optional] pOverlapped

A pointer to an OVERLAPPED structure that is required for asynchronous operation.

This parameter can be NULL if an asynchronous operation is not used.

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:

Remarks

After completing a scan, the client must call ScanLogContainers again with the eScanMode parameter set to CLFS_SCAN_CLOSE so that it can free the system-allocated array of CLFS_CONTAINER_INFORMATION structures; otherwise, memory leaks result.

Examples

For an example that uses this function, see Enumerating Log Containers.

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

Share via