Adding and Removing File Instances

Upon creating a GATLogicalFile instance, for it to be of any use it must contain reference to byte-for-byte identical physical files. So, there has to be some means of adding, and removing, references to physical files. In this section we will take a look at how to add and remove reference to physical files.

In GAT physical files are represented through GATFile instances. Hence to add a reference to a physical file to a GATLogicalFile instance we need to associate this GATLogicalFile instance with a GATFile instance. This is done through a call to the following function

GATResult GATLogicalFile_AddFile(GATLogicalFile logicalFile, GATFile_const file)

The first argument to this function is a GATLogicalFile, the GATLogicalFile which is to be added to. The next argument is a GATFile_const. This instance represents the physical file which is be associated with the GATLogicalFile instance upon successful completion of this function. The return value of this function is a GATResult, covered in Appendix , which indicates the completion status of this function.

To animate this still-life lets look at this function is use. Consider associating a GATLogicalFile instance logicalFile with a GATFile instance file. A code with performs this little pirouette on command is as follows

GATFile file;
GATResult result;
GATLogicalFile logicalFile;

file = ...
logicalFile = ...

result = GATLogicalFile_AddFile( logicalFile, file );

if( GAT_SUCCEEDED( result ) )
{
  /* The file has been added to the logicalFile */
}

Often it is the case that, well, we simply change our mind or need to modify one of the physical files contained in a a logical file so that it's not byte-for-byte identical to the others. In these cases, and others, we need to remove a physical file from a given GATLogicalFile. This is accomplished through a call to the function

GATResult
  GATLogicalFile_RemoveFile(GATLogicalFile logfile, GATFile_const file)

The first argument to this function is a GATLogicalFile instance containing the GATLogicalFile which is to be modified. The next argument is a GATFile_const instance identifying the GATFile instance which is to be removed, this passed GATFile instance will match and thus remove a contained GATFile instance is and only if the two instances return a GATrue when passed to the ``Equals'' function of GATFile. Finally, this function returns a GATResult, described in Appendix , which indicates it completion status.

To get a better feel for this function in use, consider the code for removing from a GATLogicalFile instance logicalFile a GATFile instance file. The code with performs this little task takes the form

GATFile file;
GATResult result;
GATLogicalFile logicalFile;

file = ...
logicalFile = ...

result = GATLogicalFile_RemoveFile( logicalFile, file );

if( GAT_SUCCEEDED( result ) )
{
  /* The file has been removed from the logicalFile */
}