Using an Object's Interface

Normally the use of an interface is rather messy, pointers to pointers to pointers to struct's full of function pointers. So, GAT introduces various utility functions which make the use of a given interface easy. These various functions are grouped according to the interface they support. So, for most interfaces in figure there exists a grouping of utility functions which facilitate the use of the given interface. A given group of these various utility functions can loosely be thought of as representing the corresponding interface. So, loosely speaking, we can represent the interfaces in GAT as portrayed in figure .

In this subsection will focus on an example which uses these utility functions. In particular the example will focus on using the grouping of utility functions associated with the GATInterface_ISerialisable interface of a GATTime instance. Through use of these utility functions we will exercise the interface GATInterface_ISerialisable to serialise a GATTime instance, an operation that will be extremely useful in future.

The full code for this section's example is as follows

#include "GAT.h"
#include <stdio.h>

int main(void)
{
  void *buffer;
  GATTime time;
  GATResult result;
  GATuint32 counter;
  GATuint32 bufferSize;
  GATObject timeObject;
  GATObject streamObject;
  GATMemoryStream stream;
  
  /* Create a GATTime corresponding to now */
  time = GATTime_Create( 0 );
  
  /* Create a GATMemoryStream */
  stream = GATMemoryStream_Create(0, 0, GATFalse);
  
  /* Check time and stream are not NULL */
  if( (NULL != time) && (NULL != stream) )
  {
    /* Convert the GATTime to a GATObject */
    timeObject = GATTime_ToGATObject(time);
    
    /* Convert the GATMemoryStream to a GATObject */
    streamObject = GATMemoryStream_ToGATObject(stream);
    
    /* Serialize timeObject to streamObject */
    result = GATSerialisable_Serialise( timeObject, streamObject, GATFalse );
    
    /* Check for serialization success */
    if( GAT_SUCCEEDED( result ) )
    {
      /* Obtain the buffer with the serialized GATTime */
      buffer = GATMemoryStream_GetBuffer( stream, &bufferSize, GATFalse );
      
      /* Print out GATTime serialization */
      for( counter = 0; counter < bufferSize; counter++ )
      {
        printf( "The next four bytes of now are %x\n", ( GATuint32[] buffer )[counter] );
      }
    }
  }
  
 /* Destroy the GATTime */
  GATTime_Destroy( &time );
  
 /* Destroy the GATMemoryStream */
 GATMemoryStream_Destroy( &stream );
 
 return 0;
}

Let us examine this example.

The first lines of the example are now standard

#include "GAT.h"
#include <stdio.h>

int main(void)
{
  void *buffer;
  GATTime time;
  GATResult result;
  GATuint32 counter;
  GATuint32 bufferSize;
  GATObject timeObject;
  GATObject streamObject;
  GATMemoryStream stream;
  
  /* Create a GATTime corresponding to now */
  time = GATTime_Create( 0 );
  ...
}

The only novel part of this code is the introduction of GATMemoryStream. A GATMemoryStream is an internal class used by GAT whose details are not of concern to our current train of thought beyond the fact that an instance of a GATMemoryStream can be though of a buffer which can be used to hold our serialized GATTime. The next lines

/* Create a GATMemoryStream */
stream = GATMemoryStream_Create(0, 0, GATFalse);
  
/* Check time and stream are not NULL */
if( (NULL != time) && (NULL != stream) )
{
  ...
}

create a GATMemoryStream then proceed only if the created GATTime and GATMemoryStream are not NULL. The following lines

/* Convert the GATTime to a GATObject */
timeObject = GATTime_ToGATObject(time);
    
/* Convert the GATMemoryStream to a GATObject */
streamObject = GATMemoryStream_ToGATObject(stream);

use the various conversion utility functions to convert the GATTime and GATMemoryStream to GATObject's. The proceeding lines

/* Serialize timeObject to streamObject */
result = GATSerialisable_Serialise( timeObject, streamObject, GATFalse );

/* Check for serialization success */
if( GAT_SUCCEEDED( result ) )
{
  ...
}

contain the novel code of this example. These lines employ the utility function

GATResult GATSerialisable_Serialise(GATObject o, GATObject s, GATBool c)

which in turn uses the interface GATInterface_ISerialisable, to serialize the passed GATObject instance timeObject to the passed GATObject instance streamObject. The final argument to this function is a GATBool which indicates if the ``dirty'' flag of the GATObject instance timeObject should be cleared upon serialization. For example, this ``dirty'' flag can be used to keep track of the possible difference between a serialized version of a particular instance and the in-memory version of that same instance. In our example we don't care about such distinctions. In addition we should note that the first argument to this function must be a GATObject realizing the GATInterface_ISerialisable interface and the second argument to this function must be a GATObject realizing the GATInterface_IStreamable interface. The very next lines simply check to see that this serialization completed successfully. The following lines

/* Obtain the buffer with the serialized GATTime */
buffer = GATMemoryStream_GetBuffer( stream, &bufferSize, GATFalse );
      
/* Print out GATTime serialization */
for( counter = 0; counter < bufferSize; counter++ )
{
  printf( "The next four bytes of now are %x\n", ( GATuint32[] buffer )[counter] );
}

first obtain the buffer holding the serialized version of the GATTime, the buffer is an array of GATuint32's, then simply proceed to print out each GATuint32 in this buffer. The final lines of the example

/* Destroy the GATTime */
GATTime_Destroy( &time );
  
/* Destroy the GATMemoryStream */
GATMemoryStream_Destroy( &stream );
 
return 0;

are now standard; thus, we will not examine them in detail.