IFileOperation

This is an abstract base class for recursive file system operations.

IFileOperation provides virtual member functions which may be overridden to provide customized error handling and progress indicators

Do not derive your own classes from this class.


IFileOperation - Member Functions and Data by Group

Constructors & Destructor

Construct or destruct file operation objects.


[view class]
~IFileOperation
public:
virtual ~IFileOperation()
Destructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFileOperation
Constructor for use by subclasses.


Overload 1
protected:
IFileOperation()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
IFileOperation( EFailureAction action, unsigned int tellMeTimes )

action
What to do if the operation encounters an error.
tellMeTimes
The number of times that reportProgress should be called during the operation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Accessing Member Functions

The functions in this group provide access to member functions.


[view class]
failureAction
public:
EFailureAction failureAction() const
Returns the behavior of an operation when an unhandled error occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
reportFrequency
public:
unsigned int reportFrequency() const
Returns the progress report frequency for this operation. The frequency is the number of times that reportProgress is called during the operation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setFailureAction
public:
void setFailureAction(EFailureAction actionOnFailure)
Specifies the behavior of an operation when an unhandled error occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Callback Functions

This group contains callback functions that handle periodic or special operations.


[view class]
handleFailure
public:
virtual bool handleFailure( const IException& reason, const IFileSystemEntity& current )
Called when a failure other than a name conflict occurs.

This member function is called if the operation fails for some reason other than a name conflict. The exception is passed in, along with the entity that caused the failure.

reason
The exception that caused the failure.
current
The entity being operated upon when the failure occurred.

Return
true to retry the operation on the current entity or false to simply throw the exception. This implementation returns false. Even if an exception is thrown, the operation first attempts to process all remaining entities if failureAction is set to kContinue.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Subclassing
Overrides might report failures to the user, append to a log or list of failures, take steps to allow a retry, etc.

[view class]
renameNeeded
public:
virtual bool renameNeeded( IFileName& modifyThisName, const IFileSystemEntity& currentEntity )
Called whenever a name conflict arises during the operation. Developers may override this and provide a mechanism for resolving name conflicts, e.g. by prompting the user for a new name.

modifyThisName
The name of the entity that resulted in a conflict. To continue the operation, set this parameter to a new name and return true.
currentEntity
The entity currently being operated upon.

Return
true to continue the operation or false to terminate it. This implementation returns false. If true is returned, the modifyThisName parameter must be set to a new name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Subclassing
Third parties who want to attempt resolution of name conflicts need to create a direct or indirect subclass and override this member function.

[view class]
reportProgress
public:
virtual bool reportProgress( double fractionDone, const IFileSystemEntity& currentEntity )
Called to report the progress of this operation. As the operation progresses, reportProgress is called as many times as specified in the tellMeTimes argument to the constructor.

fractionDone
The portion of the operation that has been completed, expressed as a floating point number between 0 and 1.
currentEntity
The entity currently being operated upon. You may want to show its name in your progress indicator.

Return
true to continue the operation or false to terminate it. This implementation returns true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Subclassing
Third parties who want to provide progress indicators for long operations need to create a direct or indirect subclass and override this member function.

Subclass Interface

The functions in this group are provided to be overridden by subclasses.


[view class]
doOneDirectory
protected:
virtual IDirectory doOneDirectory( const IDirectory& dir, IDirectory& dest, const IFileName& newName )
Callback to perform the operation on a single directory.

dir
The directory on which to operate.
dest
The target directory for this entity. In an operation like move or copy, this is the destination to which the directory should be moved or copied. Other operations may choose to ignore this parameter.
newName
If non-empty, the new name desired for the directory in its target location.

Return
An IDirectory pointing to the new location of the original directory (e.g. the moved or copied directory) If this operation does not affect the directory's location, the same IDirectory should be returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Subclassing
This implementation of doOneDirectory simply creates a new directory in the destination location that has the same attributes as the original directory. If your subclass performs an operation for which this is not appropriate, you may override this to do something else. If you need to create a new directory and also perform some other action, write an override which calls up to this member function.

[view class]
doOneEntity
Callback to perform the operation on a single file.
protected:
virtual IFileSystemEntity doOneEntity( const IFileSystemEntity& entity, IDirectory& target, const IFileName& newName ) = 0

Subclasses must override this function to perform whatever action is desired for each entity affected by the operation. For example, a move operation uses this function to move the file to the destination directory.

entity
The entity on which to operate.
target
The target directory for this entity. In an operation like move or copy, this is the destination to which the file should be moved or copied. Other operations may choose to ignore this parameter.
newName
If non-empty, the new name desired for the entity in its target location.

Return
An entity pointing to the new location of the original entity (e.g. the moved or copied object). If this operation does not affect the entity's location, the same entity should be returned.

Overriding
always

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
execute
Member function called by subclasses to start the operation.
protected:
IFileSystemEntity execute( const IFileSystemEntity& entity, IDirectory& target, const IFileName& newName )
This member function calls the doOneDirectory function for every directory at or under the specified entity. It calls the doOneFile function for every file at or under entity. Depending on the arguments passed to the constructor, it also does error handling and progress reporting.

entity
The entity on which to operate.
target
The target directory, e.g. the destination directory for a move or copy operation.
newName
If non-empty, the new name desired for the entity in its target location.

Return
An entity pointing to the new location of the original entity (e.g. the moved or copied object). If this operation does not affect the entity's location, the same entity is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
postProcess
protected:
virtual void postProcess( IFileSystemEntity& source, IFileSystemEntity& result )
Callback to clean up after the operation.

This is called after doOneEntity has been called for an entity and all of its children. It can be used to perform any necessary cleanup actions, such as deleting the original entity after a move operation.

source
The original entity that was operated upon.
result
The entity that was a result of the operation, i.e. that was returned from execute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFileOperation - Enumerations


[view class]
EFailureAction
enum EFailureAction { kContinue, 
                      kStop }
Specifies the behavior of an operation when an unhandled error occurs.

kStop throws the exception immediately.

kContinue attempts to complete the operation on all remaining entities, and only then throws the exception.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFileOperation - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data