Class GorgonChunkFile<T>

Base class for a Gorgon chunked formatted data readers/writers.

Inheritance

object

GorgonChunkFile<T>

GorgonChunkFileReader

GorgonChunkFileWriter

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.IO

Assembly: Gorgon.Core.dll

Syntax

public abstract class GorgonChunkFile<T>

Type Parameters

Name	Description
T	The type of read/writer to use when deserializing or serializing the data.

Remarks

This allows access to a file format that uses the concept of grouping sections of an object together into a grouping called a chunk. This chunk will hold binary data associated with an object allows the developer to read/write only the pieces of the object that are absolutely necessary while skipping optional chunks.

A more detailed explanation of the chunk file format can be found in the Gorgon Chunk File Format (GCFF) topic.

A chunk file object will expose a collection of GorgonChunk values, and these give the available chunks in the file and can be looked up either by the ulong value for the chunk ID, or an 8 character string that represents the chunk (this is recommended for readability). This allows an application to do validation on the chunk file to ensure that its format is correct. It also allows an application to discard chunks it doesn't care about or are optional. This allows for some level of versioning between chunk file formats.

Chunks can be accessed in any order, not just the order in which they were written. This allows an application to only take the pieces they require from the file, and leave the rest. It also allows for optional chunks that can be skipped if not present, and read/written when they are.

tip

Gorgon uses the chunked file format for its own file serializing/deserializing of its objects that support persistence.

Constructors

GorgonChunkFile(Stream)

Initializes a new instance of the GorgonChunkFile<T> class.

Declaration

protected GorgonChunkFile(Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream that contains the chunk file to read or write.

Remarks

The stream passed to this method requires that the CanSeek property returns a value of true.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
ArgumentEmptyException	Thrown when the stream is has its CanSeek property set to false.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Fields

ChunkTableID

The chunk table chunk ID (CHUNKTBL)

Declaration

public const ulong ChunkTableID = 5495047177758918723

Field Value

Type	Description
ulong

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

FileFormatHeaderIDv0100

The header ID for the 1.0 version of the chunk file format. (GCFF0100)

Declaration

public const ulong FileFormatHeaderIDv0100 = 3472329396109853511

Field Value

Type	Description
ulong

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Properties

Chunks

Property to return the list of chunks available in the file.

Declaration

public IGorgonReadOnlyChunkCollection Chunks { get; }

Property Value

Type	Description
IGorgonReadOnlyChunkCollection

Remarks

Use this property to determine if a chunk exists when reading a chunk file.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

IsOpen

Property to return whether or not the file is open.

Declaration

public bool IsOpen { get; }

Property Value

Type	Description
bool

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Stream

Property to return the GorgonStreamWrapper that contains the chunked file.

Declaration

public GorgonStreamWrapper Stream { get; }

Property Value

Type	Description
GorgonStreamWrapper

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Methods

Close()

Function to close an open chunk file in the stream.

Declaration

public void Close()

Remarks

Always call this method when a call to Open() is made. Failure to do so could cause the file to become corrupted.

If the file is not open, then this method will do nothing.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

CloseChunk()

Function to close an open chunk.

Declaration

public abstract void CloseChunk()

Remarks

This method should always be called when one of the OpenChunk(ulong) methods are called. Failure to do so may cause file corruption.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

OnClose()

Function called when a chunk file is closing.

Declaration

protected abstract long OnClose()

Returns

Type	Description
long	The total number of bytes read or written.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

OnOpen()

Function called when a chunk file is opening.

Declaration

protected abstract void OnOpen()

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Open()

Function to open a chunked file within the stream.

Declaration

public void Open()

Remarks

This opens a Gorgon chunk file that exists within the Stream passed to the constructor of this object. Typically this would be in a FileStream, but any type of stream is valid and can contain a chunk file.

If the this method is called and the file is already opened, then it will be closed and reopened.

Important

Always pair a call to Open with a call to Close(), otherwise the file may become corrupted or the stream may not be updated to the correct position.

Important

When this file is opened for reading, then validation is performed on the file header to ensure that it is a genuine GCFF file. If it is not, then an exception will be thrown detailing what's wrong with the header.

Exceptions

Type

Condition

GorgonException

Thrown when the chunk file format header ID does not match when reading. -or- Thrown when application specific header ID in the file was not found in the list passed to the constructor when reading. -or- Thrown if the chunk file table offset is less than or equal to the size of the header when reading. -or- Thrown if the file size recorded in the header is less than the size of the header when reading.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

OpenChunk(string)

Function to open a chunk, by the text representation of its ID, for reading or writing.

Declaration

public T OpenChunk(string chunkName)

Parameters

Type	Name	Description
string	chunkName	The name of the chunk.

Returns

Type	Description
T	A GorgonBinaryReader, or GorgonBinaryWriter that will allow reading or writing within the chunk.

Remarks

See the OpenChunk(ulong), or the OpenChunk(ulong) method for more information.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the chunkName parameter is null.
ArgumentEmptyException	Thrown when the chunkName parameter is empty.

See Also

OpenChunk(ulong)

OpenChunk(ulong)

OpenChunk(ulong)

Function to open a chunk for reading or writing.

Declaration

public abstract T OpenChunk(ulong chunkId)

Parameters

Type	Name	Description
ulong	chunkId	The ID of the chunk to open.

Returns

Type	Description
T	A GorgonBinaryReader, or GorgonBinaryWriter that will allow reading or writing within the chunk.

Remarks

See the OpenChunk(ulong), or the OpenChunk(ulong) methods for detailed information on what this method does during reading/writing contexts.

See Also

OpenChunk(ulong)

OpenChunk(ulong)

ValidateChunkID(ulong)

Function to perform validation against the requested chunk ID and the list of reserved values.

Declaration

protected void ValidateChunkID(ulong chunkId)

Parameters

Type	Name	Description
ulong	chunkId	Chunk ID to evaluate.

Exceptions

Type	Condition
ArgumentEmptyException	Thrown when the chunkId is the same as one of the reserved chunk IDs.

See Also

GorgonChunkFileReader

GorgonChunkFileWriter

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)

See Also

GorgonChunkFileReader

GorgonChunkFileWriter