Class: TFileSystemCopier

Declaration: FileSystemInterface.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

This class provides support for copying files and directories.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes may override any or all of the ReportProgress, RenameNeeded, and CopyFailed member functions to obtain customized behavior. TFileSystemCopier can also be used as is to obtain the default behavior.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TFileSystemCopier::~TFileSystemCopier

virtual ~ TFileSystemCopier ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::operator=

TFileSystemCopier & operator =(const TFileSystemCopier & right)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TFileSystemCopier & right -The object to assign from.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::GetPropertiesForCurrentEntity

bool GetPropertiesForCurrentEntity (TPropertySet & fillin) const

Interface Category:

API.

Purpose:

Used during a copy operation to fetch the requested properties for the entity currently being copied.

Calling Context:

Called from any of the callback routines (for example, ReportProgress, RenameNeeded, and CopyFailed) during a copy operation.

Parameters:

TPropertySet & fillin -The property set to be filled in with the current entity's properties.

Return Value:

Returns true if any of the requested properties were successfully read.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::RenameNeeded

virtual bool RenameNeeded (TFileSystemEntityName & modifyThisName, const TFileSystemEntity & theCurrentEntity)

Interface Category:

API.

Purpose:

A callback member function for coping with name clashes during a copy operation. TFileSystemCopier never deletes or overwrites an existing entity with a copy; this routine allows such a copy to be either skipped or renamed to avoid the clash.

Calling Context:

Do not call this member function directly. To use it, derive a class from TFileSystemCopier and override this member function; it will be called whenever a name clash occurs.

Parameters:

TFileSystemEntityName & modifyThisName -The name of the entity to be copied. This parameter can be modified to provide a different name for the copy.
const TFileSystemEntity & theCurrentEntity -The entity to be copied.

Return Value:

Returns true to retry the copy after modifyThisName has been modified, or false to skip copying this entity.

Exceptions:

Throws no exceptions. Overrides of this member function also throw no exceptions.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

TFileSystemCopier::RenameNeeded (the default implementation) simply returns false. If RenameNeeded returns false, TFileSystemCopier considers it a failure and calls CopyFailed to report the failure. Overrides can call GetPropertiesForCurrentEntity to obtain properties for the entity, if needed.

Member Function: TFileSystemCopier::ReportProgress

virtual bool ReportProgress (int percentDone, const TFileSystemEntity & theCurrentEntity)

Interface Category:

API.

Purpose:

A callback member function for reporting the progress of a copy operation, and for allowing cancellation (aborting, early termination) of a copy in progress.

Calling Context:

Do not call this member function directly. To use it, derive a class from TFileSystemCopier and override this member function; it will be called at intervals during copy operations. The intervals are partly dependent on the EProgressFrequency specified to the constructor, and partly on efficiency considerations.

Parameters:

int percentDone -The percentage of completion (between 0 and 100).
const TFileSystemEntity & theCurrentEntity -The entity currently being copied.

Return Value:

Returns true to continue the copy operation; returns false to abort the copy.

Exceptions:

Throws no exceptions. Overrides of this member function also throw no exceptions.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

TFileSystemCopier::ReportProgress (the default implementation) simply returns true. Copies successfully completed before an abort are not removed. However, partial copies interrupted by an abort are removed: any copies left behind after an abort are guaranteed to be complete and correct. An aborted copy is not considered a failure. CopyFailed is not called and no exception is thrown. Overrides can call GetPropertiesForCurrentEntity to obtain properties for the entity, if needed. One obvious use for overriding this member function is to provide a visible progress indicator to a user, with a Cancel button to allow an impatient user to halt a long-running copy.

Member Function: TFileSystemCopier::SetActionOnCopyFailure

void SetActionOnCopyFailure (EActionOnCopyFailure actionOnFailure)

Interface Category:

API.

Purpose:

Controls the response of the object when a failure occurs during copying.

Calling Context:

Call this function directly.

Parameters:

EActionOnCopyFailure actionOnFailure -The action to take on failure: kStopCopying to stop copying, or kContinueCopying to skip the entity that could not be copied and continue with any remaining copies.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

None.

Member Function: TFileSystemCopier::Copy

virtual TFileSystemEntity Copy (const TFileSystemEntity & source, TDirectory & destination)

Interface Category:

API.

Purpose:

Copies a file or a directory tree into a destination directory.

Calling Context:

Call this function directly.

Parameters:

const TFileSystemEntity & source -The file or directory to be copied. Directories and their contents are copied recursively.
TDirectory & destination -The directory into which the copies are placed.

Return Value:

None.

Exceptions:

Throws TFileSystemEntityAlreadyExists if a copy fails because there is already an entity at the destination with the same name as the entity being copied. Throws TFileSystemVolumeAccessError if a copy fails because there is insufficient room on the volume. Throws TFileSystemObjectInvalid if the source entity is uninitialized or is not connected to a valid on-disk entity. Throws TFileSystemAccessDenied if a copy fails because the caller is not privileged to create files or directories in the destination directory, or if the caller is not privileged to access a source entity. Throws TFileSystemEntityInUse if the source or destination are busy.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

Exceptions are thrown only after the copy operation has terminated. If the action on failure is set to kContinueCopying, multiple failures can occur during the copy, in which case only the last such failure results in an exception being thrown. Several callback member functions (CopyFailed, RenameNeeded, and ReportProgress) are called as needed during a copy operation. Derived classes can override these member functions to customize the behavior of the copy operation.

Member Function: TFileSystemCopier::TFileSystemCopier

TFileSystemCopier (EActionOnCopyFailure actionOnFailure =kStopCopying)
TFileSystemCopier (const TFileSystemCopier & copy)
TFileSystemCopier (EProgressFrequency tellMeThisOften, EActionOnCopyFailure actionOnFailure =kStopCopying, const TPropertyIDSet & tellMeAboutThese =kNoProperties)

Interface Category:

API.

Purpose:

Construct a TFileSystemCopier, specifying the action to take on failure.
Copy constructor.
Constructs a TFileSystemCopier, specifying how often to report progress, the action to take on failure, and a set of properties to be prefetched for each entity as it is copied.

Calling Context:

Call this function directly.
Called to copy an object.
Call this function directly.

Parameters:

EActionOnCopyFailure actionOnFailure =kStopCopying -The action to take when a failure occurs during copying.
const TFileSystemCopier & copy -The TFileSystemCopier to be copied.
EProgressFrequency tellMeThisOften -The desired progress report frequency.
EActionOnCopyFailure actionOnFailure =kStopCopying -The action to take when a failure occurs during copying.
const TPropertyIDSet & tellMeAboutThese =kNoProperties -The properties to be fetched during copy, for the use of the callback member functions. (All properties are always copied with their entities, regardless of the setting of this parameter.)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

An EActionOnCopyFailure parameter specifies the action to take when a failure occurs during copying. If kStopCopying is specified, the first failure terminates the copy. If kContinueCopying is specified, source entities that cannot be copied are skipped and the copy continues with the remaining source entities.

Member Function: TFileSystemCopier::CopyFailed

virtual bool CopyFailed (const TStandardException & reasonForFailure, const TFileSystemEntity & theCurrentEntity)

Interface Category:

API.

Purpose:

A callback member function for coping with failures during a copy operation.

Calling Context:

Do not call this member function directly. To use it, derive a class from TFileSystemCopier and override this member function; it is called whenever a failure occurs during a copy operation.

Parameters:

TStandardException & reasonForFailure -A TStandardException object describing the failure.
const TFileSystemEntity & theCurrentEntity -The entity that could not be copied.

Return Value:

Returns true if the copy should be retried, false if the entity should be skipped.

Exceptions:

Throws no exceptions. Overrides of this member function also throw no exceptions.

Concurrency:

Not multithread safe. This handle class is not safe. The master it refers to is.

Other Considerations:

TFileSystemCopier::CopyFailed (the default implementation) records the reasonForFailure for later rethrow when the copy operation is complete. (In the case of multiple failures, only the last failure's exception is thrown.) It returns false to indicate that the failed copy should not be retried. Overrides should call TFileSystemCopier::CopyFailed if they want the failure to be recorded and the exception rethrown later, and should not call TFileSystemCopier::CopyFailed if they want to avoid recording and rethrowing the exception. If the exception is not recorded, TFileSystemCopier does not terminate the copy operation even if kStopCopying was set. Overrides can call GetPropertiesForCurrentEntity to obtain properties for the entity, if needed. Overrides can do anything they want when called: possibilities include taking corrective action and returning true to retry the copy, logging the failure in a customized record, and/or reporting the error to the user.

Click the icon to mail questions or corrections about this material to Taligent personnel.