Tag Parser: TagParser::BackupHelper Namespace Reference

Tag Parser 12.5.2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Functions
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.