Seeking on a FileStream Instance

As one may guess by now, as a result of the class GATFileStream realizes the interface GATInterface_IStreamable, seeking on a GATFileStream is as easy as reading or writing to one. One need only make use of the proper utility function. In tis case it is

GATResult GATStreamable_Seek(GATObject object, 
                             GATOrigin origin,
                             GATuint32 offset, 
                             GATuint32 *new_position)

The first argument to this function is a GATObject instance. This GATObject instance must realize the interface GATInterface_IStreamable. For our immediate goals this instance will always be an instance of a GATFileStream. Do you have that strange sense déjà vu that I do? The second argument is an enumeration GATOrigin which indicates where this seek is to occur from. The possible values for the enumeration GATOrigin and their associated semantics are as follows

The next argument to this function is a GATuint32, offset, indicating the number of bytes to position the current ``cursor'' from the specified GATOrigin. If GATOrigin_Set is the specified GATOrigin, then upon success the ``cursor'' is placed offset bytes after the stream's begining. If GATOrigin_Current is the specified GATOrigin, then upon success the ``cursor'' is placed offset bytes from the stream's current ``cursor'' position. If GATOrigin_End is the specified GATOrigin, then upon success the ``cursor'' is placed offset bytes before the stream's end. The final argument of this function is a GATuint32 * which passes back to the caller the new position of the ``cursor'' as a byte offset from the stream's beginning.

To get a feel for the use of this function, let us consider its use in seeking offset bytes from the beginning of a GATFileStream instance fileStream. The code which implements this little idea looks a bit like this

GATResult result;
GATuint32 offset;
GATObject object;
GATuint32 newPosition;
GATFileStream fileStream;

offset = ...

fileStream = ...

object = GATFileStream_ToGATObject( fileStream );

result = GATStreamable_Seek( object, GATOrigin_Set, offset, &newPosition );

if( GAT_SUCCEEDED( result ) )
{
  /* Do something as the cursor is at newPosition */
}