Constructing and Destroying FileStream Instances

The first step in doing anything at all with a GATFileStream is creating a GATFileStream. The is accomplished through a call to the function

GATFileStream GATFileStream_Create( GATContext context, 
                                    GATPreferences_const preferences,
                                    GATLocation location, 
                                    GATFileStreamMode mode)

The first argument is a GATContext instance the use of which was sketched in the previous chapter. The second argument is a GATPreferences instance which in most of our examples will be NULL, see Appendix for the details of this class. The third argument is a GATLocation instance which specifies the location of the physical file which can be read, wrriten, and seeked upon by the resultant GATFileStream. The final argument is an enumeration GATFileStreamMode. The various values, and the associated semantics, for this enumeration are as follows

As one can see, the value of this enumeration governs the later use of the GATFileStream, if it is used for reading, writing, reading and writing, and where this reading or writing occurs. Finally, this function returns a GATFileStream instance corresponding to all the passed information.

As an example of the use of this creation function let us take a look at the process of creating a GATFileStream which could be used for reading or writing and is opened to read and write from the file's begining

GATContext context;
GATLocation location;
GATFileStream fileStream;

context = ...
location = ...

fileStream = GATFileStream_Create( context, 
                                   NULL, 
                                   location, 
                                   GATFileStreamMode_ReadWrite );

if( NULL != fileStream )
{
  /* Use fileStream here */
}

Upon creating a GATFileStream instance and making it perform like a trained monkey for our pleasure we need to clean upon after the baboon-jester. This is accomplished through use of the function

void GATFileStream_Destroy(GATFileStream *strm)

This function takes as its first argument the GATFileStream which is to be destroyed. Upon return this function all resources which the passed GATFileStream maintained are freed.