CreateLogContainerScanContext

CreateLogContainerScanContext function

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


BOOL WINAPI CreateLogContainerScanContext(
  _In_        HANDLE             hLog,
  _In_        ULONG              cFromContainer,
  _In_        ULONG              cContainers,
  _In_        CLFS_SCAN_MODE     eScanMode = CLFS_SCAN_FORWARD,
  _Inout_     PCLFS_SCAN_CONTEXT pcxScan,
  _Inout_opt_ LPOVERLAPPED       pOverlapped
);

Parameters

hLog [in]

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.

cFromContainer [in]

The container where the scan is to be started.

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

cContainers [in]

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.

eScanMode [in]

The mode to scan containers.

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

ValueMeaning
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.

 

pcxScan [in, out]

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.

pOverlapped [in, out, optional]

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:

ERROR_ACCESS_DENIED
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_OUT_OF_MEMORY

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

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

See also

CLFS_CONTAINER_INFORMATION
CLFS_SCAN_CONTEXT
CLFS_SCAN_MODE
Common Log File System Functions
ScanLogContainers

 

 

Community Additions

ADD
Show:
© 2016 Microsoft