Copying, Moving, and Deleting File Instances

As we've now the experience of creating and deleting a GATFile instance corresponding to a physical file at a particular location, we can next move on to some file manipulation routines. The first trinity which we we explore in this realm is that of copying, moving, and deleting a file.

Let us first examine the process of copying a GATFile. Upon creating a GATFile instance one can easily copy such a GATFile instance to a new location using the single call

GATResult GATFile_Copy( GATFile_const file, 
                                      GATLocation_const targetLocation,
                                      GATFileMode mode )

The first argument to this function is the GATFile instance one wishes to copy. The second argument is a GATLocation instance indicating to where one wishes to copy the GATFile instance. The final argument to this function is a GATFileMode. GATFileMode is an enumeration indicating how the copy operation should behave if there exists a physical file in the selected destination location. The possible values that a GATFileMode may take on are as follows

The return value of this function is a GATResult, covered in appendix .

For example, if one has a GATFile instance file that one wishes to copy to a location described by the GATLocation instance targetLocation such that if a destination file exists it is overwritten, then the call would look at follows

GATFile file;
GATResult result;
GATLocation targetLocation;

file = ...
targetLocation = ...

result = GATFile_Copy( file, targetLocation, GATFileMode_Overwrite );

Similarly, if one has a GATFile instance file that one wishes to copy to a location described by the GATLocation instance targetLocation such that the copy call fails if there exists a destination file, then the call would look at follows

GATFile file;
GATResult result;
GATLocation targetLocation;

file = ...
targetLocation = ...

result = GATFile_Copy( file, targetLocation, GATFileMode_FailIfExists );

Lets next move on the the process of moving a GATFile. One moves a GATFile instance through the call

GATResult GATFile_Move( GATFile_const file, 
                                       GATLocation_const targetLocation,
                                       GATFileMode mode)

The first argument to this function is the GATFile instance one wishes to move. The second argument is a GATLocation instance indicating where one wishes to move the GATFile instance. The final argument is a GATFileMode indicating how this function call should behave if there exists a file in the selected destination location. The return value of this function is a GATResult, covered in appendix .

As an example, let us consider a GATFile instance file that one wishes to move to a location described by the GATLocation instance targetLocation such that the move call fails if there exists a destination file. The call would look at follows

GATFile file;
GATResult result;
GATLocation targetLocation;

file = ...
targetLocation = ...

result = GATFile_Move( file, targetLocation, GATFileMode_Overwrite );

If one did not wish to overwrite the destination file, is extant, then one would pass as the final argument in this function the constant GATFileMode_FailIfExists.

Finally let us examine the process of deleting a physical file corresponding to a GATFile instance. This is accomplished using the following function call

GATResult GATFile_Delete(GATFile_const file)

The first and only argument to this function is the GATFile instance representing the physical file that one wishes to delete. The return value, unsurprisingly, is a GATResult, covered in appendix .

As an example of this call in the wild, consider a GATFile instance file corresponding to a physical file that one wishes to delete. Using the above call to do delete this physical file one would use code of the following form

GATFile file;
GATResult result;

file = ...

result = GATFile_Delete( file );

Simple, no?