Examining File Instances

In addition to the relatively pedestrian tasks of copying, moving and deleting a file, GAT allows for one to determine various properties of a file through one simple interface. In particular, GAT allows for one to determine if the file is readable or writable. Also, GAT allows for one to obtain the length of a file in bytes, a GATTime indicating the last write time of a file, or a GATLocation indicating the location of a file. Lets take a look at how to root about in the internals of a GATFile.

First lets look at how to determine if we can read a file. This is accomplished through a call to the function

GATResult GATFile_IsReadable(GATFile_const file)

The passed GATFile instance is the file one wishes to examine for readability. If this passed file is readable, then this function returns a GATResult of GAT_SUCCESS. If the passed file is not readable, then this function returns a value equal to GAT_FALSE. The signature for this function is a bit perverse. A cleaner signature for this function would have been the following

GATResult GATFile_IsReadable(GATFile_const file, GATBool *isReadable)

But hey, no one is perfect.

To determine if a file is writable one plays a similar game using the function

GATResult GATFile_IsWritable(GATFile_const file)

The passed GATFile instance is the file one wishes to examine for writability. If this passed file is writable, then this function returns a GATResult of GAT_SUCCESS. If the passed file is not writable, then this function returns a value equal to GAT_FALSE. Again, GAT sticks to this perverse, if not a bit confusing, function signature.

To see how these functions work, lets take a look at a call to determine if a GATFile instance file is readable. A code snippet for such a task is as follows

GATFile file;
GATResult result; 

file = ...

result = GATFile_IsReadable( file );
if( GAT_SUCCESS == result )
{
  /* File is readable, you can read it here */
  ...
}

if( GAT_FALSE == result )
{
  /* File is not readable, you can not read it here */
}

In addition to determining if a file is readable or writable one can determine other properties of the physical file corresponding to a GATFile instance. For example one can determine the length of the physical file corresponding to a GATFile instance using the function

GATResult GATFile_GetLength(GATFile_const file, unsigned long *length)

The passed GATFile instance corresponds to the file one wishes to examine the length of and upon successful completion of this function the unsigned long returns the number of bytes in the physical file corresponding to the passed GATFile instance. Finally, the returned GATResult corresponds to the comletion status of this function, GATResult is covered in Appendix .

So, for example, to obtain the length of a GATFile instance one would proceed as in this code snippet

GATFile file;
GATResult result;
unsigned long length;

file = ...

result = GATFile_GetLength( file, &length );

if( GAT_SUCCEEDED( result ) )
{
  /* File is length bytes long */
}

Similarly, we can determine the most recent time at which the physical file corresponding to a GATFile instance was written to using the function

GATResult GATFile_LastWriteTime(GATFile_const file, GATTime *lw_time)

The passed GATFile instance is the file one wishes to examine the last write time of and upon successful completion of this function the GATTime returns the last write time of the physical file corresponding to the passed GATFile instance. Finally, the returned GATResult corresponds to the comletion status of this function, GATResult is covered in Appendix .

As an example of using this function in practice we can take a look at this code snippet which obtains the last write time of the GATFile instance file

GATFile file;
GATResult result;
GATTime lastWriteTime;

file = ...

result = GATFile_LastWriteTime( file, &lastWriteTime );

if( GAT_SUCCEEDED( result ) )
{
  /* File was last written at lastWriteTime */
}

Finally, one can obtain the location of a physical file corresponding to a GATFile instance using the following function

GATLocation_const GATFile_GetLocation(GATFile_const file)

The passed GATFile instance is the file one wishes to examine the location of and the returned GATLocation is the location of the passed GATFile instance.

For example, to obtain the GATLocation instance corresponding to a GATFile instance file one would proceed as follows

GATFile file;
GATLocation_const location;

file = ...

location = GATFile_GetLocation( file );