PrepareLogArchive function (clfsw32.h)
Prepares a physical log for archival. The function takes a snapshot of the current active log, builds an ordered set of log archive descriptors for the active log extents, and returns a log archive context.
By passing this log archive context to GetNextLogArchiveExtent, a client can iterate through the set of log archive extents to archive the log. You can also specify a range of records to archive.
Syntax
CLFSUSER_API BOOL PrepareLogArchive(
[in] HANDLE hLog,
[in, out] PWSTR pszBaseLogFileName,
[in] ULONG cLen,
[in, optional] const PCLFS_LSN plsnLow,
[in, optional] const PCLFS_LSN plsnHigh,
[out, optional] PULONG pcActualLength,
[out] PULONGLONG poffBaseLogFileData,
[out] PULONGLONG pcbBaseLogFileLength,
[out] PCLFS_LSN plsnBase,
[out] PCLFS_LSN plsnLast,
[out] PCLFS_LSN plsnCurrentArchiveTail,
[out] PCLFS_LOG_ARCHIVE_CONTEXT ppvArchiveContext
);
Parameters
[in] hLog
A handle to the log that is obtained by a successful call to CreateLogFile.
This handle can be the handle to a dedicated or multiplexed log.
[in, out] pszBaseLogFileName
A pointer to a user-allocated buffer to receive the fully qualified path of the base log.
If the buffer is not large enough, it contains a truncated file path on exit, and the function fails with an ERROR_BUFFER_OVERFLOW status code.
The length of the file path is returned in the variable pointed to by pcActualLength. The client can re-attempt a failed call with a name buffer that is large enough.
[in] cLen
The size of the pszBaseLogFileName buffer, in wide characters.
[in, optional] plsnLow
A pointer to a CLFS_LSN structure that specifies the log sequence number (LSN) of the low end of the range of the active log where the log client needs log archival information.
If this parameter is omitted, the low end of the range defaults to the LSN of the log archive tail.
[in, optional] plsnHigh
A pointer to a CLFS_LSN structure that specifies the LSN of the high end of the range of the active log where the log client needs log archival information.
If this parameter is omitted, the high end of the range defaults to the next LSN to be written to the log.
[out, optional] pcActualLength
A pointer to a variable that receives the actual length of the name of the base log path, in characters.
If this value is greater than cLen, the function returns an ERROR_BUFFER_OVERFLOW status with a truncated path that is stored in the pszBaseLogFileName buffer and all other out parameters that are not set to meaningful values.
[out] poffBaseLogFileData
A pointer to a variable that receives the offset where the metadata begins in the base log.
The contiguous extent in the base log pszBaseLogFileName represents the full contents of the log metadata—that is, from poffBaseLogFileData to pcbBaseLogFileLength.
[out] pcbBaseLogFileLength
A pointer to a variable that specifies the exact length of the base log, in bytes.
[out] plsnBase
A pointer to a CLFS_LSN structure to receive the base log sequence number (LSN) of the active log.
[out] plsnLast
A pointer to a CLFS_LSN structure to receive the highest valid LSN in the active log.
[out] plsnCurrentArchiveTail
A pointer to a CLFS_LSN structure to receive the current LSN of the archive tail of the log.
[out] ppvArchiveContext
A pointer to the variable that receives a pointer to an archive context that the system allocates.
The archive context maintains the cursor state of the archival iterator and the log handle context. The archival client is responsible for releasing the context by calling TerminateLogArchive.
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
You must call TerminateLogArchive to free the archive context, or memory leaks can occur.
Until you call TerminateLogArchive, containers that are being archived cannot be recycled.
You can only perform one archive operation at a time per handle that CreateLogFile returns.
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 |