### 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.

~IFileOperation

      public:
      virtual ~IFileOperation()

  Destructor.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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

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

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.

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.

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.

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.

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.

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

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

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

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

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None