Class GorgonChunkFileReader

A reader that will read in and parse the contents of a Gorgon Chunk File Format (GCFF) file.

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

This example builds on the example provided in the GorgonChunkFileWriter example and shows how to read in the file created by that example:

// 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;
int[] ints;

Stream myStream = File.Open("<<Path to your file>>", FileMode.Open, FileAccess.Read, FileShare.Read);

// Notice that we're passing in an array of file header ID values. This allows us to allow the formatter to 
// read the file with multiple versions of the header ID. This gives us an ability to provide backwards 
// compatibility with file types.
GorgonChunkFileReader file = new GorgonChunkFileReader(myStream, new [] { FileHeader });

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

	// Read the chunk that contains the integers. Note that this is different than the writer example,
	// we wrote these items last, and in a sequential file read, we'd have to read the values last when 
	// reading the file. But with this format, we can find the chunk and read it from anywhere in the file.
	// Alternatively, we could pass in an ulong value for the chunk ID instead of a string.
	using (GorgonBinaryReader reader = file.OpenChunk(IntChunk))
	{
		ints = new int[reader.ReadInt32()];

		for (int = 0; i < ints.Length; ++i)
		{
			ints[i] = reader.ReadInt32();
		}
	}			

	// Read the chunk that contains strings.
	using (GorgonBinaryReader reader = file.OpenChunk(StringsChunk))
	{
		strings = new string[reader.ReadInt32()];

		for (int i = 0; i < strings.Length; ++i)
		{
			strings[i] = reader.ReadString();
		}
	}
}
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

GorgonChunkFileReader(Stream, IEnumerable<ulong>)

Initializes a new instance of the GorgonChunkFileReader class.

Declaration
public GorgonChunkFileReader(Stream stream, IEnumerable<ulong> appSpecificIds)
Parameters
Type Name Description
Stream stream

The stream containing the chunk file to read.
IEnumerable<ulong> appSpecificIds

The allowable application specific ids for file validation.
Exceptions
Type Condition
ArgumentNullException

Thrown when the stream, or the appSpecificIds parameters are null.
ArgumentEmptyException

Thrown when the appSpecificIds contains no values.

-or-

Thrown when the stream is write-only
EndOfStreamException

Thrown when the stream is at its end.

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 reposition the stream to the end of the file header.

| Edit this page View Source

IsReadable(Stream)

Function to determine if the data in the stream is a chunk file.

Declaration
public static bool IsReadable(Stream stream)
Parameters
Type Name Description
Stream stream

The stream containing the data.
Returns
Type Description
bool

true if the stream data contains a chunk file, false if not.
Exceptions
Type Condition
ArgumentNullException

Thrown when the stream parameter is null.
IOException

Thrown when the stream is write-only.
| 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 read from the stream.
Overrides
| Edit this page View Source

OnOpen()

Function to read in the header information from the chunk file and validate it.

Declaration
protected override void OnOpen()
Overrides
Exceptions
Type Condition
GorgonException

Thrown when the chunked file format header ID does not match.

-or-

Thrown when application specific header ID in the file was not found in the list passed to the constructor.

-or-

Thrown if the chunk file table offset is less than or equal to the size of the header.

-or-

Thrown if the file size recorded in the header is less than the size of the header.
| Edit this page View Source

OpenChunk(ulong)

Function to open a chunk for reading.

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

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

A GorgonBinaryReader that will allow reading within the chunk.
Overrides
Remarks

Use this to read data from a chunk within the file. If the chunkId is not found, then this method will throw an exception. To mitigate this, check for the existence of a chunk in the Chunks collection.

This method will provide minimal validation for the chunk in that it will only check the chunkId to see if it matches what's in the file, beyond that, the user is responsible for validating the data that lives within the chunk.

Exceptions
Type Condition
IOException

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

Thrown when the chunkId does not match the chunk in the file.
KeyNotFoundException

Thrown when the chunkId was not found in the chunk table.

Extension Methods