TagParser::BackupHelper Namespace Reference

Helps to create and restore backup files when rewriting files to apply changed tag information. More...

Functions
TAG_PARSER_EXPORT void	restoreOriginalFileFromBackupFile (const std::string &originalPath, const std::string &backupPath, CppUtilities::NativeFileStream &originalStream, CppUtilities::NativeFileStream &backupStream)
TAG_PARSER_EXPORT void	createBackupFile (const std::string &backupDir, const std::string &originalPath, std::string &backupPath, CppUtilities::NativeFileStream &originalStream, CppUtilities::NativeFileStream &backupStream)
TAG_PARSER_EXPORT void	createBackupFileCanonical (const std::string &backupDir, std::string &originalPath, std::string &backupPath, CppUtilities::NativeFileStream &originalStream, CppUtilities::NativeFileStream &backupStream)
	Creates a backup file like createBackupFile() but canonicalizes originalPath before doing the backup.
TAG_PARSER_EXPORT void	handleFailureAfterFileModified (MediaFileInfo &fileInfo, const std::string &backupPath, CppUtilities::NativeFileStream &outputStream, CppUtilities::NativeFileStream &backupStream, Diagnostics &diag, const std::string &context="making file")
TAG_PARSER_EXPORT void	handleFailureAfterFileModifiedCanonical (MediaFileInfo &fileInfo, const std::string &originalPath, const std::string &backupPath, CppUtilities::NativeFileStream &outputStream, CppUtilities::NativeFileStream &backupStream, Diagnostics &diag, const std::string &context)
	Handles a failure/abort which occurred after the file has been modified.
void	restoreOriginalFileFromBackupFile (const std::string &originalPath, const std::string &backupPath, NativeFileStream &originalStream, NativeFileStream &backupStream)
	Restores the original file from the specified backup file.
void	createBackupFile (const std::string &backupDir, const std::string &originalPath, std::string &backupPath, NativeFileStream &originalStream, NativeFileStream &backupStream)
	Creates a backup file for the specified file.
void	handleFailureAfterFileModified (MediaFileInfo &fileInfo, const std::string &backupPath, NativeFileStream &outputStream, NativeFileStream &backupStream, Diagnostics &diag, const std::string &context)
	Handles a failure/abort which occurred after the file has been modified.

Detailed Description

Helps to create and restore backup files when rewriting files to apply changed tag information.

Methods in this namespace are internally used eg. in implementations of AbstractContainer::internalMakeFile().

Function Documentation

createBackupFile() [1/2]

TAG_PARSER_EXPORT void TagParser::BackupHelper::createBackupFile	(	const std::string &	backupDir,
		const std::string &	originalPath,
		std::string &	backupPath,
		CppUtilities::NativeFileStream &	originalStream,
		CppUtilities::NativeFileStream &	backupStream
	)

createBackupFile() [2/2]

void TagParser::BackupHelper::createBackupFile	(	const std::string &	backupDir,
		const std::string &	originalPath,
		std::string &	backupPath,
		NativeFileStream &	originalStream,
		NativeFileStream &	backupStream
	)

Creates a backup file for the specified file.

Parameters

backupDir	Specifies the directory to store backup files. If empty, the directory of the file to be backuped is used.
originalPath	Specifies the path of the file to be backuped.
backupPath	Contains the path of the created backup file when this function returns.
originalStream	Specifies a std::fstream for the original file.
backupStream	Specifies a std::fstream for creating the backup file.

This helper function is used by MediaFileInfo and container implementations to create a backup file when applying changes. The specified backupPath is set to the path of the created backup file. The specified backupStream will be closed if currently open. Then it is used to open the backup file using the flags ios_base::in and ios_base::binary.

The specified originalStream is closed before performing the move operation.

If moving isn't possible (eg. originalPath and backupPath refer to different partitions) the backup file will be created by copying.

The original file can now be rewritten to apply changes. When this operation fails the created backup file can be restored using restoreOriginalFileFromBackupFile().

Exceptions

Throws

std::ios_base::failure on failure.

Todo:

Implement callback for progress updates (copy).

Definition at line 111 of file backuphelper.cpp.

createBackupFileCanonical()

void TagParser::BackupHelper::createBackupFileCanonical	(	const std::string &	backupDir,
		std::string &	originalPath,
		std::string &	backupPath,
		CppUtilities::NativeFileStream &	originalStream,
		CppUtilities::NativeFileStream &	backupStream
	)

Creates a backup file like createBackupFile() but canonicalizes originalPath before doing the backup.

Remarks

• This function sets originalPath to be a canonical path.
• Using this function (instead of createBackupFile()) is recommended so the actual file is being altered.

Definition at line 199 of file backuphelper.cpp.

handleFailureAfterFileModified() [1/2]

TAG_PARSER_EXPORT void TagParser::BackupHelper::handleFailureAfterFileModified	(	MediaFileInfo &	fileInfo,
		const std::string &	backupPath,
		CppUtilities::NativeFileStream &	outputStream,
		CppUtilities::NativeFileStream &	backupStream,
		Diagnostics &	diag,
		const std::string &	context = "making file"
	)

handleFailureAfterFileModified() [2/2]

void TagParser::BackupHelper::handleFailureAfterFileModified	(	MediaFileInfo &	fileInfo,
		const std::string &	backupPath,
		NativeFileStream &	outputStream,
		NativeFileStream &	backupStream,
		Diagnostics &	diag,
		const std::string &	context
	)

Handles a failure/abort which occurred after the file has been modified.

• Restores the backup file using restoreOriginalFileFromBackupFile() if one has been created.
• Adds appropriate notifications to the specified fileInfo.
• Re-throws the exception.

Remarks

Must only be called when an exception derived from Failure or ios_base::failure has been caught; this method uses the "exception dispatcher" idiom.

Parameters

fileInfo	Specifies the MediaFileInfo instance which has been modified.
backupPath	Specifies the path of the backup file; might be empty if none has been created.
outputStream	Specifies the stream used to write the output file. This is usually just the stream of fileInfo, but is specified here explicitly for higher flexibility.
backupStream	Specifies the stream assembled using createBackupFile(); might be a default fstream if no backup file has been created.
diag	Specifies the container to add diagnostic messages to.
context	Specifies the context used to add notifications.

Definition at line 230 of file backuphelper.cpp.

handleFailureAfterFileModifiedCanonical()

void TagParser::BackupHelper::handleFailureAfterFileModifiedCanonical	(	MediaFileInfo &	fileInfo,
		const std::string &	originalPath,
		const std::string &	backupPath,
		CppUtilities::NativeFileStream &	outputStream,
		CppUtilities::NativeFileStream &	backupStream,
		Diagnostics &	diag,
		const std::string &	context
	)

Handles a failure/abort which occurred after the file has been modified.

Remarks

Same as handleFailureAfterFileModified() but allows specifying the original path instead of just using the path from mediaFileInfo.

Definition at line 241 of file backuphelper.cpp.

restoreOriginalFileFromBackupFile() [1/2]

TAG_PARSER_EXPORT void TagParser::BackupHelper::restoreOriginalFileFromBackupFile	(	const std::string &	originalPath,
		const std::string &	backupPath,
		CppUtilities::NativeFileStream &	originalStream,
		CppUtilities::NativeFileStream &	backupStream
	)

restoreOriginalFileFromBackupFile() [2/2]

void TagParser::BackupHelper::restoreOriginalFileFromBackupFile	(	const std::string &	originalPath,
		const std::string &	backupPath,
		NativeFileStream &	originalStream,
		NativeFileStream &	backupStream
	)

Restores the original file from the specified backup file.

Parameters

originalPath	Specifies the path to the original file.
backupPath	Specifies the path to the backup file.
originalStream	Specifies a std::fstream instance for the original file.
backupStream	Specifies a std::fstream instance for the backup file.

This helper function is used by MediaFileInfo and container implementations to restore the original file from the specified backup file in the case a Failure or an IO error occurs. The specified streams will be closed if currently open.

If moving isn't possible (eg. originalPath and backupPath refer to different partitions) the backup file will be restored by copying.

Exceptions

Throws

std::ios_base::failure on failure.

Todo:

Implement callback for progress updates (copy).

Definition at line 48 of file backuphelper.cpp.