Reading from a FileStream Instance

The class GATFileStream implements the interface GATInterface_IStreamable, as can bee seen in figure . It is through this interface that the application programmer can read, write, and seek on the physical file corresponding to the particular GATFileStream instance.

As mentioned in Chapter , there exist a set of functions corresponding to the GAT interface GATInterface_IStreamable which ease the task of the application programmer trying to make use this interface. As mentioned in the Chapter this set of functions can loosely be thought of representing the interface GATInterface_IStreamable. This set of functions is given by the figure .

In reading from a GATFileStream instance we will make use of this set of utility functions instead of dealing directly with the interface GATInterface_IStreamable as, truthfully, its much easier.

So to read from a given GATFileStream instance we will make use of the function

GATResult GATStreamable_Read(GATObject object, 
                             void *buffer,
                             GATuint32 size, 
                             GATuint32 *read_bytes)

The first argument to this function is a GATObject instance. This GATObject instance must realize the interface GATInterface_IStreamable. For our immediate concerns this first object will always be an instance of a GATFileStream. The second argument to this function is a void * this pointer points to a buffer into which the read should occur. The next argument is a GATuint32, a primitive type covered in Appendix , which passes the this function the length of the buffer in bytes. The final argument to this function is a GATuint32 * which passes the caller the actual number of bytes read. Finally, the function returns a GATResult, covered in Appendix , which indicates the completion status of the function.

As an example, let us consider using the above function to read from a GATFileStream instance fileStream into a buffer buffer of size bufferSize. This call would look as follows

void *buffer;
GATResult result;
GATObject object;
GATuint32 readBytes;
GATuint32 bufferSize;
GATFileStream fileStream;

buffer = ...
bufferSize = ...

fileStream = ...

object = GATFileStream_ToGATObject( fileStream );

result = GATStreamable_Read( object, buffer, bufferSize, &readBytes );

if( GAT_SUCCEEDED( result ) )
{
  /* Do something with readBytes bytes in buffer */
}