|
Home |
The QtFileCopier class allows you to copy and move files in a background process. More...
#include <QtFileCopier>
Inherits QObject.
The QtFileCopier class allows you to copy and move files in a background process.
QtFileCopier provides a collection of functions performing the copy and move operations:
If you want to present visual feedback of an operation's progress in an console application or in a GUI application, you can either create an instance of the QtCopyDialog class, and connect it to your instance of the QtFileCopier class using the QtCopyDialog::setFileCopier() function, or you can let the application provide the visual feedback itself.
The QtFileCopier class also provides a series of other functions, signals and slots.
Operations are queued and performed one by one. You are notified about the beginning and end of each operation by the started() and finished() signals, respectively. In particular, when an operation concerns a directory, you are notified about the beginning and end of each sub-directory operation recursively.
While performing the operations you are notified about the progress with the dataTransferProgress() signal. If an error occurs, the error() signal is emitted.
You can retrieve information about current and pending operations using the pendingRequests() and currentId() functions. To retrieve information about a specific operation you can use the sourceFilePath(), destinationFilePath(), entryList() and isDir() functions, passing the operation's identifier as argument.
All pending operations can be canceled with the cancelAll() slot, you can cancel any given operation by specifying its identifier as argument.
By default, a file copier works in an interactive mode which means that when an error occurs, the operation is halted, the error() signal is emitted, and the file copier waits for the user's respons. The user can choose to resume by skipping the operation, overwrite the destination or repeat the operation using the skip(), skipAll(), overwrite(), overwriteAll() or retry() slots.
You can manipulate the behavior, and the result, of each operation with the QtFileCopier::CopyFlags passed with the copy() and move() functions. Note that when the QtFileCopier::NonInteractive flag is passed as argument, the operation will not halt if an error occurs.
An instance of the QtFileCopier class is always in one of the states specified by the QtFileCopier::State enum. You are notified about transitions from one state to another by the stateChanged() signal. The new state is passed as argument.
When all pending operations are completed, the done() signal is emitted.
If you want to provide feedback and error handling, you can use your class constructor to create the file copier, and an associated copy dialog, and to connect the various QtFileCopier signals to your own custum slots. For example:
QtFileCopier *copier;
QtCopyDialog *copyDialog;
MyClass::MyClass(QObject *parent)
{
copier = new QtFileCopier(parent);
copyDialog = new QtCopyDialog(parent);
copyDialog->setFileCopier(copier);
QObject::connect(copier, SIGNAL(stateChanged(QtFileCopier::State)),
this, SLOT(stateChanged(QtFileCopier::State)));
QObject::connect(copier, SIGNAL(done(bool)), this, SLOT(done(bool)));
QObject::connect(copier, SIGNAL(error(int, QtFileCopier::Error, bool)),
this, SLOT(error(int, QtFileCopier::Error, bool)));
}
The copy dialog provides visual feedback, and the option of aborting the operation. The error handling can be implemented in a custom slot. In addition, you can implement any other respons to the file copier's signals:
QMainWindow *mainWindow;
MyClass::error(int identifier, QtFileCopier::Error error, bool stopped)
{
if (stopped == true) {
... // make interactive query
}
}
MyClass::stateChanged(QtFileCopier::State state)
{
if (state != Idle) {
mainWindow->setCursor(Qt::WaitCursor);
... // copying started
} else {
mainWindow->unsetCursor();
...
}
}
MyClass::done(bool error)
{
mainWindow->statusBar()->showMessage(tr("Done"));
}
In the end, you can let your copy() function perform the required operations:
QString sourceFile;
QStringList sourceFiles;
QString destinationPath;
QString destinationDir;
CopyFlags flags;
MyClass::copy()
{
copier->copy(sourceFile, destinationPath, flags);
copier->copyFiles(sourceFiles, destinationDir, flags);
copier->move(sourceFile, destinationPath, flags);
}
If you choose to use the QtFileCopier class to perform the operations in a background process without error handling and visual feedback, you can implement the QtFileCopier construction in your copy() function:
MyClass::copy()
{
QtFileCopier copier(this);
QtFileCopier::QtCopyFlags flags = QtFileCopier::NonInteractive;
copier.copy(sourceFile, destinationPath, flags);
copier.copyFiles(sourceFiles, destinationDir, flags);
copier.move(sourceFile, destinationPath, flags);
}
Note that when reaching the end of the MyClass::copy() function in the example above, the QtFileCopier destructor will not abort the operations currently performed, nor will it wait for the operations to be completed; the destructor will destroy the file copier while the operations will still be running in their own threads. When all tasks in a thread are done, the thread will automatically destroy itself.
See also QtCopyDialog.
This enum type is used to specify how QtFileCopier performs a copy or move operation.
| Constant | Value | Description |
|---|---|---|
| QtFileCopier::NonInteractive | 0x01 | QtFileCopier ignores any errors that occur while performing the operation (i.e. an error in the operation will not block the QtFileCopier's thread). |
| QtFileCopier::Force | 0x02 | When the destination file cannot be opened for writing, the QtFileCopier tries to remove it and open it again. |
| QtFileCopier::MakeLinks | 0x04 | The QtFileCopier makes symbolic links (or shortcuts on Windows) instead of copying. |
| QtFileCopier::FollowLinks | 0x08 | The QtFileCopier recursively follows symbolic links (or shortcuts on Windows) and copies the target instead of copying link itself. |
The CopyFlags type is a typedef for QFlags<CopyFlag>. It stores an OR combination of CopyFlag values.
This enum type is used to specify the various errors that can occur during a copy or move operation.
| Constant | Value | Description |
|---|---|---|
| QtFileCopier::NoError | 0 | No error occured. |
| QtFileCopier::SourceNotExists | 1 | The source file doesn't exist. |
| QtFileCopier::DestinationExists | 2 | The destination file exists. |
| QtFileCopier::SourceDirectoryOmitted | 3 | The source was supposed to be a file, but the specified source is a directory (e.g. calling the copy() function). |
| QtFileCopier::SourceFileOmitted | 4 | The source was supposed to be a directory, but the specified source is a file (e.g. calling the copyDirectory() function). |
| QtFileCopier::PathToDestinationNotExists | 5 | The path to the destination file doesn't exist. |
| QtFileCopier::CannotCreateDestinationDirectory | 6 | The destination directory cannot be created. |
| QtFileCopier::CannotOpenSourceFile | 7 | The source file cannot be opened. |
| QtFileCopier::CannotOpenDestinationFile | 8 | The destination file cannot be opened. |
| QtFileCopier::CannotRemoveDestinationFile | 9 | The destination file cannot be removed (this error occurs when the QtFileCopier::Force flag is specified). |
| QtFileCopier::CannotCreateSymLink | 10 | The requested symbolic link (or shortcut on Windows) cannot be created. |
| QtFileCopier::CannotReadSourceFile | 11 | The source file cannot be read. |
| QtFileCopier::CannotWriteDestinationFile | 12 | The destination file cannot be written. |
| QtFileCopier::CannotRemoveSource | 13 | The source file cannot be removed (this error occurs when performing move operations). |
| QtFileCopier::Canceled | 14 | The operation was canceled. |
See also error().
This enum type defines the various states a file copier can have.
An instance of the QtFileCopier class is always in one of the states specified by this enum. You are notified about transitions from one state to another by the stateChanged() signal. The default state is QtFileCopier::Idle.
| Constant | Value | Description |
|---|---|---|
| QtFileCopier::Idle | 0 | The file copier is not performing any operation and has an empty pending list. |
| QtFileCopier::Busy | 1 | The file copier is performing an operation. |
| QtFileCopier::WaitingForInteraction | 2 | The file copier is waiting for the user's respons. To resume the operation use the skip(), skipAll(), overwrite(), overwriteAll() or retry() functions. |
See also state() and stateChanged().
This property holds whether the file copier's default behavior is automatically reset when all pending operations are completed, or not.
The default is true.
Note that if this property is set to false, and for example, the last failing operation before the file copier entered the idle state was resolved by skipping all subsequent operations with the same error, the file copier will continue to skip operations with this error unless the reset() function is called explicitly.
Access functions:
See also reset().
This property holds the time that must pass before the next dataTransferProgress() signal is emitted.
The default is 100 miliseconds.
Access functions:
See also dataTransferProgress().
Creates a file copier with the given parent. The file copier's default state is QtFileCopier::Idle.
Destroys the file copier.
If there are pending operations, they will be still completed after the file copier's destruction. If the file copier was in the QtFileCopier::WaitingForInteraction state, the halted operation is resolved, but no operations are halted after the file copier is destroyed.
To stop all the pending operations, you must call cancelAll() before destructing the file copier.
Cancels the operation with the given identifier.
Cancels all operations, including the current one.
This signal is emitted when the cancelAll() function is called, i.e. when all pending operations are canceled.
See also started() and pendingRequests().
Schedules an operation copying the sourceFile into the destinationPath, retaining the file name.
The file copier will perform the copy operation according to the specified flags when the program execution returns to the event processing loop. The operation can only be scheduled when the file copier is in the QtFileCopier::Idle state.
If the destinationPath points to an existing directory, the sourceFile is copied into that directory. If the destinationPath doesn't exist, the operation will fail.
The function returns a non negative value as the operation identifier. If the operation is not valid, or the file copier is not in the appropiate state, the function returns -1.
See also copyFiles(), copyDirectory(), and move().
Schedules recursively operations copying the files in sourceDir into the destinationDir, retaining the file names.
The file copier will perform the copy operations according to the specified flags when the program execution returns to the event processing loop. The operations can only be scheduled when the file copier is in the QtFileCopier::Idle state.
If the destinationDir points to an existing directory, the sourceDir is copied into that directory. If the destinationDir doesn't exist, the operation will fail.
The function returns a list of non negative values as the operation identifiers. The returned list can contain less items than the number of files in sourceDir in case some operations were not valid.
See also copy(), copyFiles(), and moveDirectory().
Schedules operations copying the sourceFiles into the destinationDir, retaining the file names.
The file copier will perform the copy operations according to the specified flags when the program execution returns to the event processing loop. The operations can only be scheduled when the file copier is in the QtFileCopier::Idle state.
If a source in the sourceFiles list points to a directory then that source is omitted. If the destinationDir doesn't exist, the function does nothing.
The function returns a list of non negative values as the operation identifiers. The returned list can contain less items than the sourceFiles list in case some operations were not valid.
See also copy(), copyDirectory(), and moveFiles().
Returns the currently performed operation's identifier, or -1 if there is no current operation (e.g. the file copier is in the QtFileCopier::Idle state).
This signal is emitted approximately every 100 miliseconds to indicate the progress of the operation with the given identifier, It is only emitted when the file copier is in the QtFileCopier::Busy state. In addition the signal is emitted at the end of a successful operation, before the finished() signal is emitted.
The progress parameter indicates how many bytes of the source file that are copied or moved.
Returns the destination path of the operation with the given identifier. If there is no matching pending operation, the function returns an empty string.
See also sourceFilePath().
This signal is emitted when an operation is completed and there is no more pending operations. The error parameter is set to true if at least one operation failed, otherwise it is set to false.
Returns the list of recursively generated operations for the operation with the given identifier. If the specified operation doesn't concern a directory, the function returns an empty list.
See also isDir().
This signal is emitted when an error occurs.
The parameters are the identifier of the current operation, the type of error, and stopped which tells whether the operation is waiting for user respons or not. When an operation is halted due to an error (stopped == true), use the retry(), skip(), skipAll(), overwrite() or overwriteAll() slots to resume.
See also QtFileCopier::Error.
This signal is emitted when the operation with the given identifier is completed. The error parameter is set to true if the operation failed, otherwise it is set to false.
If the operation concerns a directory, and the error parameter is set to true, all the recursively generated operations will automatically be canceled.
See also started() and entryList().
Returns whether the source of the operation with the given identifier is a directory. If there is no matching pending operation, the function returns false.
See also sourceFilePath() and entryList().
Schedules an operation moving the sourceFile into the destinationPath, retaining the file name.
The file copier will perform the move operation according to the specified flags when the program execution returns to the event processing loop. The operation can only be scheduled when the file copier is in the QtFileCopier::Idle state.
Warning: QtFileCopier doesn't accept, and ignores, the QtFileCopier::MakeLinks and QtFileCopier::FollowLinks for move operations.
If the destinationPath points to an existing directory, the sourceFile is moved into that directory. If the destinationPath doesn't exist, the operation will fail.
The function returns a non negative value as the operation identifier. If the operation is not valid, or the file copier is not in the appropiate state, the function returns -1.
See also moveFiles(), moveDirectory(), and copy().
Schedules recursively operations moving the files in sourceDir into the destinationDir, retaining the file names.
The file copier performs the move operations according to the specified flags when the program execution returns to the event processing loop. The operations can only be scheduled when the file copier is in the QtFileCopier::Idle state.
Warning: QtFileCopier doesn't accept, and ignores, the QtFileCopier::MakeLinks and QtFileCopier::FollowLinks for move operations.
If the destinationDir points to an existing directory, the sourceDir is moved into that directory. If the destinationDir doesn't exist, the operation will fail.
The function returns a list of non negative values as the operation identifiers. The returned list can contain less items than the number of files in sourceDir in case some operations were not valid.
See also move(), moveFiles(), and copyDirectory().
Schedules operations moving the sourceFiles into the destinationDir, retaining the file names.
The file copier performs the move operations according to the specified flags when the program execution returns to the event processing loop. The operations can only be scheduled when the file copier is in the QtFileCopier::Idle state.
Warning: QtFileCopier doesn't accept, and ignores, the QtFileCopier::MakeLinks and QtFileCopier::FollowLinks for move operations.
If a source in the sourceFiles list points to a directory then that source is omitted. If the destinationDir doesn't exist, the function does nothing.
The function returns a list of non negative values as the operation identifiers. The returned list can contain less items than the sourceFiles list in case some operations were not valid.
See also move(), moveDirectory(), and copyFiles().
Overwrites the current destination path. If the current destination is a directory, all subdirectory paths will be overwritten recursively.
The slot is used to resume when an operation has halted due to an error. For that reason it only applies while waiting for interaction (i.e the file copier is in the QtFileCopier::WaitingForInteraction state). In that case, the file copier changes the state to QtFileCopier::Busy when this function is called.
See also skip() and overwriteAll().
Overwrites all the subsequent destination paths including the current one.
If a destination path is a directory, all subdirectory paths will be overwritten recursively.
The slot is used to resume when an operation has halted due to an error. For that reason it only applies while waiting for interaction (i.e the file copier is in the QtFileCopier::WaitingForInteraction state). In that case the file copier changes the state to QtFileCopier::Busy.
See also overwrite(), skipAll(), and resetOverwrite().
Returns a list of identifiers to the pending operation requests, including the currently performed operation.
See also sourceFilePath() and destinationFilePath().
Resets the file copier's default error handling behavior.
See also autoReset, resetSkip(), and resetOverwrite().
Resets the file copier's default behavior for handling QtFileCopier::DestinationExists errors, i.e. entering the QtFileCopier::WaitingForInteraction state.
See also reset() and overwriteAll().
Resets the file copier's default behavior for error handling, i.e. entering the QtFileCopier::WaitingForInteraction state when any error occurs.
See also reset() and skipAll().
Tries to perform the current (failing) operation once more.
The slot only applies while waiting for interaction (i.e the file copier is in the QtFileCopier::WaitingForInteraction state). In that case the file copier changes the state to QtFileCopier::Busy.
See also skip() and overwrite().
Skips the current operation.
If the current operation is applied to a directory, all recursively generated operations will also be skipped.
The slot is used to resume when an operation has halted due to an error. For that reason it only applies while waiting for interaction (i.e the file copier is in the QtFileCopier::WaitingForInteraction state). In that case the file copier changes the state to QtFileCopier::Busy.
See also overwrite() and skipAll().
Skips all the subsequent operations resulting in the same error, including the current one.
If an operation is applied to a directory, all recursively generated operations will also be skipped.
The slot is used to resume when an operation has halted due to an error. For that reason it only applies while waiting for interaction (i.e the file copier is in the QtFileCopier::WaitingForInteraction state). In that case the file copier changes the state to QtFileCopier::Busy.
See also skip(), overwriteAll(), and resetSkip().
Returns the source path of the operation with the given identifier. If there is no matching pending operation, the function returns an empty string.
See also destinationFilePath().
This signal is emitted when the operation with the given identifier starts.
For each operation, two signals are emitted: the started() and finished() signals. Between those signals there can be emitted error() and dataTransferProgress() signals concerning the operation. When the operation concerns a directory, recursively generated started() and finished() signals can occur in between the inital signal pair as well.
See also finished().
Returns the current state of the file copier.
This signal is emitted when the state of the copier changes. The new state is passed as the signals argument.
Note that the file copier's state changes after the signal is emitted.
See also state().
| Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) | Trademarks | Qt Solutions |