Class GorgonChunkFileWriter

A writer that will lay out and write the contents of a Gorgon Chunk File Format (GCFF) file.

Inheritance
object
GorgonChunkFile<GorgonBinaryWriter>
GorgonChunkFileWriter
Inherited Members
Namespace: Gorgon.IO
Assembly: Gorgon.Core.dll
Syntax
public sealed class GorgonChunkFileWriter : GorgonChunkFile<GorgonBinaryWriter>
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.

Examples

The following is an example of how to write out the contents of an object into a chunked file format:

// An application defined file header ID. Useful for identifying the contents of the file.
const ulong FileHeader = 0xBAADBEEFBAADF00D;	

const string StringsChunk = "STRNGLST";
const string IntChunk = "INTGRLST"; 

string[] strings = { "Cow", "Pig", "Dog", "Cat", "Slagathor" };
int[] ints { 1, 2, 9, 100, 122, 129, 882, 82, 62, 42 };

Stream myStream = File.Open("<<Path to your file>>", FileMode.Create, FileAccess.Write, FileShare.None);
GorgonChunkFileWriter file = new GorgonChunkFileWriter(myStream, FileHeader);

try
{
	// Open the file for writing within the stream.
	file.Open();

	// Write the chunk that will contain strings.
	// Alternatively, we could pass in an ulong value for the chunk ID instead of a string.
	using (GorgonBinaryWriter writer = file.OpenChunk(StringsChunk))
	{
		writer.Write(strings.Length);
		for (int = 0; i < strings.Length; ++i)
		{
			writer.Write(strings[i]);
		}
	}			

	// Write the chunk that will contain integers.
	using (GorgonBinaryWriter writer = file.OpenChunk(IntChunk))
	{
		writer.Write(ints.Length);
		for (int i = 0; i < ints.Length; ++i)
		{
			writer.Write(ints[i]);
		}
	}
}
finally
{
	// Ensure that we close the file, otherwise it'll be corrupt because the 
	// chunk table will not be persisted.
	file.Close();

	if (myStream is not null)
	{
		myStream.Dispose();
	}
}

Constructors

| Edit this page View Source

GorgonChunkFileWriter(Stream, ulong)

Initializes a new instance of the GorgonChunkFileWriter class.

Declaration
public GorgonChunkFileWriter(Stream stream, ulong appHeaderId)
Parameters
Type Name Description
Stream stream

The stream that contains the chunk file to write.
ulong appHeaderId

An application specific header ID to write to the file for validation.
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.
ArgumentException

Thrown when the stream is has its CanSeek property set to false.

-or-

Thrown when the stream is read-only.

IOException

Methods

| Edit this page View Source

CloseChunk()

Function to close an open chunk.

Declaration
public override void CloseChunk()
Overrides
Remarks

This will close the active chunk, and add it to the chunk table list. It will reposition the stream pointer for the stream passed to the constructor of this object to the next position for a chunk, or the end of the chunk data.

If this method is not called, then the chunk will not be added to the chunk table in the file and the file will lose that chunk. This, however, does not mean the file is necessarily corrupt, just that the chunk will not exist. Regardless, this method should always be called when OpenChunk(ulong) is called.

| Edit this page View Source

OnClose()

Function called when a chunk file is closing.

Declaration
protected override long OnClose()
Returns
Type Description
long

The total number of bytes written to the stream.
Overrides
| Edit this page View Source

OnOpen()

Function to write the header information for the chunk file.

Declaration
protected override void OnOpen()
Overrides
| Edit this page View Source

OpenChunk(ulong)

Function to open a chunk for reading.

Declaration
public override GorgonBinaryWriter OpenChunk(ulong chunkId)
Parameters
Type Name Description
ulong chunkId

The ID of the chunk to open.
Returns
Type Description
GorgonBinaryWriter

A GorgonBinaryWriter that will allow writing within the chunk.
Overrides
Remarks

Use this to write data to a chunk within the file. This method will add a new chunk to the chunk table represented by the Chunks collection. Note that the chunkId is not required to be unique, but must not be the same as the header for the file, or the chunk table identifier. There are constants in the GorgonChunkFile<T> type that expose these values.

Important

This method should always be paired with a call to CloseChunk(). Failure to do so will keep the chunk table from being updated properly, and corrupt the file.

Exceptions
Type Condition
IOException

Thrown if the chunk was opened without calling Open() first.

Extension Methods