PrepareLogArchive-Funktion (clfsw32.h)
Bereitet ein physisches Protokoll für die Archivierung vor. Die Funktion übernimmt eine Momentaufnahme des aktuellen aktiven Protokolls, erstellt einen geordneten Satz von Protokollarchivdeskriptoren für die aktiven Protokollausweitungen und gibt einen Protokollarchivkontext zurück.
Durch Übergeben dieses Protokollarchivkontexts an GetNextLogArchiveExtent kann ein Client den Satz von Protokollarchiverweiterungen durchlaufen, um das Protokoll zu archivieren. Sie können auch einen Bereich von Datensätzen angeben, die archiviert werden sollen.
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
);
Parameter
[in] hLog
Ein Handle für das Protokoll, das durch einen erfolgreichen Aufruf von CreateLogFile abgerufen wird.
Bei diesem Handle kann es sich um das Handle für ein dediziertes Protokoll oder ein Multiplexprotokoll handelt.
[in, out] pszBaseLogFileName
Ein Zeiger auf einen vom Benutzer zugewiesenen Puffer, um den vollqualifizierten Pfad des Basisprotokolls zu empfangen.
Wenn der Puffer nicht groß genug ist, enthält er beim Beenden einen abgeschnittenen Dateipfad, und die Funktion schlägt mit einem ERROR_BUFFER_OVERFLOW status Code fehl.
Die Länge des Dateipfads wird in der Variablen zurückgegeben, auf die von pcActualLength verwiesen wird. Der Client kann einen fehlgeschlagenen Aufruf mit einem ausreichend großen Namenspuffer erneut versuchen.
[in] cLen
Die Größe des Puffers pszBaseLogFileName in breiten Zeichen.
[in, optional] plsnLow
Ein Zeiger auf eine CLFS_LSN-Struktur , die die Protokollsequenznummer (LSN) des unteren Endes des Bereichs des aktiven Protokolls angibt, in dem der Protokollclient Protokollarchivinformationen benötigt.
Wenn dieser Parameter ausgelassen wird, wird das untere Ende des Bereichs standardmäßig auf den LSN des Protokollarchiv-Tails festgelegt.
[in, optional] plsnHigh
Ein Zeiger auf eine CLFS_LSN-Struktur , die den LSN des hohen Bereichs des aktiven Protokolls angibt, in dem der Protokollclient Protokollarchivinformationen benötigt.
Wenn dieser Parameter ausgelassen wird, wird das high end des Bereichs standardmäßig auf den nächsten LSN festgelegt, der in das Protokoll geschrieben werden soll.
[out, optional] pcActualLength
Ein Zeiger auf eine Variable, die die tatsächliche Länge des Namens des Basisprotokollpfads in Zeichen empfängt.
Wenn dieser Wert größer als cLen ist, gibt die Funktion einen ERROR_BUFFER_OVERFLOW status mit einem abgeschnittenen Pfad zurück, der im Puffer pszBaseLogFileName und allen anderen out-Parametern gespeichert ist, die nicht auf aussagekräftige Werte festgelegt sind.
[out] poffBaseLogFileData
Ein Zeiger auf eine Variable, die den Offset empfängt, an dem die Metadaten im Basisprotokoll beginnen.
Die zusammenhängende Ausdehnung im Basisprotokoll pszBaseLogFileName stellt den vollständigen Inhalt der Protokollmetadaten dar, d. h. von poffBaseLogFileData bis pcbBaseLogFileLength.
[out] pcbBaseLogFileLength
Ein Zeiger auf eine Variable, die die genaue Länge des Basisprotokolls in Bytes angibt.
[out] plsnBase
Ein Zeiger auf eine CLFS_LSN Struktur zum Empfangen der Basisprotokollsequenznummer (Base Log Sequence Number, LSN) des aktiven Protokolls.
[out] plsnLast
Ein Zeiger auf eine CLFS_LSN-Struktur , um den höchsten gültigen LSN im aktiven Protokoll zu empfangen.
[out] plsnCurrentArchiveTail
Ein Zeiger auf eine CLFS_LSN-Struktur , um den aktuellen LSN des Archivendes des Protokolls zu empfangen.
[out] ppvArchiveContext
Ein Zeiger auf die Variable, die einen Zeiger auf einen Archivkontext empfängt, den das System zuordnet.
Der Archivkontext behält den Cursorzustand des Archiv-Iterators und des Protokollhandlekontexts bei. Der Archivclient ist für die Freigabe des Kontexts durch Aufrufen von TerminateLogArchive verantwortlich.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. In der folgenden Liste werden die möglichen Fehlercodes identifiziert:
Hinweise
Sie müssen TerminateLogArchive aufrufen, um den Archivkontext freizugeben, da es zu Speicherverlusten kommen kann.
Bis Sie TerminateLogArchive aufrufen, können container, die archiviert werden, nicht wiederverwendet werden.
Sie können jeweils nur einen Archivvorgang pro Handle ausführen, das CreateLogFile zurückgibt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 R2 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | clfsw32.h |
| Bibliothek | Clfsw32.lib |
| DLL | Clfsw32.dll |