dtGame::BinaryLogStream Class Reference

This is a log stream class which supports a binary log file format. More...

#include <binarylogstream.h>

Inheritance diagram for dtGame::BinaryLogStream:

List of all members.

Public Member Functions
	BinaryLogStream (MessageFactory &msgFactory)
	Constructs a new log stream.
virtual void	Close ()
	Flushes any write buffers, closes an open file handles, and frees any read/write buffers currently in use.
virtual void	Create (const std::string &logsPath, const std::string &logResourceName)
	Implementations should create the necessary resources to support log streaming.
virtual void	Open (const std::string &logsPath, const std::string &logResourceName)
	Opens an existing log.
virtual void	Delete (const std::string &logsPAth, const std::string &logResourceName)
	Deletes the specified log resource.
virtual void	GetAvailableLogs (const std::string &logsPath, std::vector< std::string > &logs)
	Gets a list of the current logs available to the log stream by searching the specified directory.
virtual void	WriteMessage (const Message &msg, double timeStamp)
	Writes a game message to the message database file.
virtual dtCore::RefPtr< Message >	ReadMessage (double &timeStamp)
	Reads a game message from the messages database file.
virtual void	InsertTag (LogTag &newTag)
	Creates and inserts a new tag into the current log stream.
virtual void	InsertKeyFrame (LogKeyframe &newKeyFrame)
	Creates and inserts a new keyframe into the current log stream.
virtual void	JumpToKeyFrame (const LogKeyframe &keyFrame)
	This method causes the current read position in the messages database file to be positioned at the location indicated by the keyframe.
virtual void	GetTagIndex (std::vector< LogTag > &tags)
	Gets the list of tags in this log stream.
virtual void	GetKeyFrameIndex (std::vector< LogKeyframe > &keyFrames)
	Gets the list of keyframes contained within the log stream.
virtual void	Flush ()
	Ensures the all outstanding messages, tags, and keyframes are written to the appropriate files.
Static Public Attributes
static const std::string	LOGGER_MSGDB_MAGIC_NUMBER
	Used to identify logger message database files.
static const std::string	LOGGER_INDEX_MAGIC_NUMBER
	Used to identify logger index table files.
static const unsigned char	LOGGER_MAJOR_VERSION = 1
	Logger major version number. Equals 1.
static const unsigned char	LOGGER_MINOR_VERSION = 1
	Logger minor version number. Equals 1.
Protected Member Functions
void	ReadMessageDataBaseHeader (MessageDataBaseHeader &header)
	Reads the file header located in the message database file.
void	WriteMessageDataBaseHeader (MessageDataBaseHeader &header)
	Writes the file header to the message database file.
void	ReadIndexTableHeader (IndexTableHeader &header)
	Reads the file header located in the index table file.
void	WriteIndexTableHeader (IndexTableHeader &header)
	Writes the file header to the index table file.
virtual	~BinaryLogStream ()
	Destructor.
void	ReadIndexTables ()
	This method loads all the tags and keyframe entries found in the current log index tables file.
void	CheckFileStatus (FILE *fp)
	Checks the stream for any errors, throwing an exception if an error occurs.
void	WriteKeyFrame (const LogKeyframe &keyFrame)
	Writes a keyframe to the index tables file.
LogKeyframe	ReadKeyFrame ()
	Reads a keyframe from the current read position in the index tables file.
void	WriteTag (const LogTag &tag)
	Writes a tag to the index tables file.
LogTag	ReadTag ()
	Reads a tag from the current read position in the index tables file.
Static Protected Attributes
static const std::string	MESSAGE_DB_EXT
	The postfix string attached to the base log file name corresponding to the file containing the database of messages.
static const std::string	INDEX_EXT
	File extension for all log files.
static const unsigned char	MESSAGE_DEID = 0
static const unsigned char	TAG_DEID = 1
static const unsigned char	KEYFRAME_DEID = 2
static const unsigned char	END_SECTION_DEID = 255
Classes
struct	IndexTableHeader
	This structure corresponds to the header located at the beginning of the logs index table file. More...
struct	MessageDataBaseHeader
	This structure corresponds to the header located at the beginning of the messages database file. More...

---

Detailed Description

This is a log stream class which supports a binary log file format.

The stream actually manages two separate files. The first file contains a dump of game messages in addition to key-frame captures. The second file contains two index tables, one for the tags, and one for the key-frames.

---

Constructor & Destructor Documentation

dtGame::BinaryLogStream::BinaryLogStream

(

MessageFactory &

msgFactory

)

Constructs a new log stream.

dtGame::BinaryLogStream::~BinaryLogStream

(

)

[protected, virtual]

Destructor.

Calls the Close() method.

---

Member Function Documentation

void dtGame::BinaryLogStream::Close

(

)

[virtual]

Flushes any write buffers, closes an open file handles, and frees any read/write buffers currently in use.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::Create	(	const std::string &	logsPath,
		const std::string &	logResourceName
	)			[virtual]

Implementations should create the necessary resources to support log streaming.

Parameters:

logResourceName

The base name of the new log resource. Implementations should use this in some form in their naming conventions for log files.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::Open	(	const std::string &	logsPath,
		const std::string &	logResourceName
	)			[virtual]

Opens an existing log.

Again, this implies that two physical files are opened for reading. These files follow the same naming convention as described in BinaryLogStream::Create().

Note:

This method implicitly opens the log stream for reading. Any attempts to write to the stream after this method is called results in an ILLEGAL_OPERATION exception.

If any error occurs while creating the stream, a LogStream::LOGGER_IO_EXCEPTION is thrown.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::Delete	(	const std::string &	logsPAth,
		const std::string &	logResourceName
	)			[virtual]

Deletes the specified log resource.

Parameters:

	logsPath	The absolute path containing the logs.
	logResourceName	The base name of the log resource to destroy. Implementation should use this in some form in their naming conventions for log files.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::GetAvailableLogs	(	const std::string &	logsPath,
		std::vector< std::string > &	logs
	)			[virtual]

Gets a list of the current logs available to the log stream by searching the specified directory.

Parameters:

	logsPath	An absolute path to the directory containing the available logs.
	logs	Filled with the available logs.

Note:

The log format for the binary log stream actually stores the log in two files. Therefore, each entry in the resulting logs list contains the base name of each log. This name is used by the other methods in the BinaryLogStream to identity logs for reading and writing.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::WriteMessage	(	const Message &	msg,
		double	timeStamp
	)			[virtual]

Writes a game message to the message database file.

Parameters:

	msg	The message to write.
	timeStamp	The time stamp matched to this message.

Implements dtGame::LogStream.

dtCore::RefPtr< Message > dtGame::BinaryLogStream::ReadMessage

(

double &

timeStamp

)

[virtual]

Reads a game message from the messages database file.

Parameters:

This

parameter will contain the time stamp of the read message.

Returns:

The next game message in file.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::InsertTag

(

LogTag &

newTag

)

[virtual]

Creates and inserts a new tag into the current log stream.

Parameters:

newTag

The new tag to insert.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::InsertKeyFrame

(

LogKeyframe &

newKeyFrame

)

[virtual]

Creates and inserts a new keyframe into the current log stream.

Parameters:

newKeyFrame

The new keyframe to insert.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::JumpToKeyFrame

(

const LogKeyframe &

keyFrame

)

[virtual]

This method causes the current read position in the messages database file to be positioned at the location indicated by the keyframe.

Parameters:

keyFrame

The keyframe to go to.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::GetTagIndex

(

std::vector< LogTag > &

tags

)

[virtual]

Gets the list of tags in this log stream.

The tags are located in the index table.

Parameters:

tags

This vector is filled with the tags currently in the log stream.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::GetKeyFrameIndex

(

std::vector< LogKeyframe > &

keyFrames

)

[virtual]

Gets the list of keyframes contained within the log stream.

The keyframes are located in the index table.

Parameters:

keyFrames

This vector is filled with the tags currently in the log stream.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::Flush

(

)

[virtual]

Ensures the all outstanding messages, tags, and keyframes are written to the appropriate files.

Implements dtGame::LogStream.

void dtGame::BinaryLogStream::ReadMessageDataBaseHeader

(

MessageDataBaseHeader &

header

)

[protected]

Reads the file header located in the message database file.

Parameters:

header

This structure is filled with the header information.

Note:

If a valid message data base file does not exist or the header is malformed, a LOGGER_IO_EXCEPTION is thrown.

void dtGame::BinaryLogStream::WriteMessageDataBaseHeader

(

MessageDataBaseHeader &

header

)

[protected]

Writes the file header to the message database file.

Parameters:

header

This structure contains the header information.

Note:

If a valid message data base file does not exist or the header is malformed, a LOGGER_IO_EXCEPTION is thrown.

This method automatically seeks to the beginning of the file before writing the header data.

void dtGame::BinaryLogStream::ReadIndexTableHeader

(

IndexTableHeader &

header

)

[protected]

Reads the file header located in the index table file.

Parameters:

header

This structure is filled with the header information.

Note:

If a valid index table file does not exist or the header is malformed, a LOGGER_IO_EXCEPTION is thrown.

void dtGame::BinaryLogStream::WriteIndexTableHeader

(

IndexTableHeader &

header

)

[protected]

Writes the file header to the index table file.

Parameters:

header

This structure contains the header information.

Note:

If a valid index table file does not exist or the header is malformed, a LOGGER_IO_EXCEPTION is thrown.

This method automatically seeks to the beginning of the file before writing the header data.

void dtGame::BinaryLogStream::ReadIndexTables

(

)

[protected]

This method loads all the tags and keyframe entries found in the current log index tables file.

Note:

If an error occurs, a LOGGER_IO_EXCEPTION is thrown.

void dtGame::BinaryLogStream::CheckFileStatus

(

FILE *

fp

)

[protected]

Checks the stream for any errors, throwing an exception if an error occurs.

Parameters:

fp

The file stream to check.

void dtGame::BinaryLogStream::WriteKeyFrame

(

const LogKeyframe &

keyFrame

)

[protected]

Writes a keyframe to the index tables file.

This method assumes a valid index tables file exists.

Parameters:

keyFrame

The keyframe to add to the file.

LogKeyframe dtGame::BinaryLogStream::ReadKeyFrame

(

)

[protected]

Reads a keyframe from the current read position in the index tables file.

Returns:

The keyframe that was read from the file.

void dtGame::BinaryLogStream::WriteTag

(

const LogTag &

tag

)

[protected]

Writes a tag to the index tables file.

This method assumes a valid index tables file exists.

Parameters:

tag

The tag to add to the index tables file.

LogTag dtGame::BinaryLogStream::ReadTag

(

)

[protected]

Reads a tag from the current read position in the index tables file.

Returns:

The tag that was read from the file.

---

Member Data Documentation

const std::string dtGame::BinaryLogStream::LOGGER_MSGDB_MAGIC_NUMBER [static]

Used to identify logger message database files.

The file header must begin with this string identifier. Equals "GMLOGMSGDB"

const std::string dtGame::BinaryLogStream::LOGGER_INDEX_MAGIC_NUMBER [static]

Used to identify logger index table files.

The file header must begin with this string identifier. Equals "GMLOGINDEXTAB"

const unsigned char dtGame::BinaryLogStream::LOGGER_MAJOR_VERSION = 1 [static]

Logger major version number. Equals 1.

const unsigned char dtGame::BinaryLogStream::LOGGER_MINOR_VERSION = 1 [static]

Logger minor version number. Equals 1.

const std::string dtGame::BinaryLogStream::MESSAGE_DB_EXT [static, protected]

The postfix string attached to the base log file name corresponding to the file containing the database of messages.

const std::string dtGame::BinaryLogStream::INDEX_EXT [static, protected]

File extension for all log files.

const unsigned char dtGame::BinaryLogStream::MESSAGE_DEID = 0 [static, protected]

const unsigned char dtGame::BinaryLogStream::TAG_DEID = 1 [static, protected]

const unsigned char dtGame::BinaryLogStream::KEYFRAME_DEID = 2 [static, protected]

const unsigned char dtGame::BinaryLogStream::END_SECTION_DEID = 255 [static, protected]

---