Creating and Destroying File Instances

Before we can wrangle a GATFile, we first need to create a GATFile, and before we create a GATFile we need to learn how to create instances of a two other classes required in the creation of a GATFile. In particular we need to understand how to create an instance of a GATLocation, and a GATContext. Lets get crackin' with these preliminaries.

Specifying the location of a file is accomplished through the use of the auxiliary class named, appropriately enough, GATLocation. So, taking one step backwards before taking one step forward we'll consider how to create a GATLocation.

A GATLocation is created using the single call GATLocation_Create. This signature of this function is as follows

GATLocation GATLocation_Create(const char *uri)

The uri argument to this function is an char * representation of a URI, see section for more information of URI's. This function returns a NULL, in the case of an error, or a GATLocation corresponding to the passed URI. After creating a GATLocation an bending it to our will, we will need to destroy the GATLocation. A simple call to the function

void GATLocation_Destroy(GATLocation *loc)

destroys the passed GATLocation and frees up any resources it may have held.

The second class we need to learn how to create instances of is a GATContext. An instance of a GATContext is used to store various state information related to GAT calls, such as security information or the errors in the current call stack. A GATContext instance is created using the following function

GATContext GATContext_Create(void)

This function returns a GATContext or NULL upon error. Upon making a such created GATContext jump through the proper hoops, we will need to put it out to pasture. This is done through a call to the function

void GATContext_Destroy(GATContext *ctx)

which destroys the passed GATContext instance and frees up any resources held by the passed GATContext.

Now that we've got these preliminaries under control lets see how to use such to create a GATFile. A GATFile instance is created through a single call to the following function

GATFile 
  GATFile_Create( GATContext context, 
                           GATLocation_const location, 
                           GATPreferences_const preferences )

The first argument to this function is a GATContext instance used to store state information related to the various calls of the created GATFile. The second argument is a GATLocation instance specifying the location which the created GATFile is to correspond. The final argument is a GATPreferences, in most of our examples this final argument will be NULL, the class GATPreferences is covered in detail in Appendix . The return value of this function will be a GATFile instance with the passed location or NULL, on error.

Now that we now how to create a GATFile instance we should learn how to destroy such an instance as we wouldn't want to leave any resources hanging about. This is done through a call to the function

void GATFile_Destroy(GATFile *file)

This function destroys the passed GATFile instance and frees up any resources this instance might have tied up.