Records DataMessage streams to disk and replays them with original timing. More...

#include <MessagePlayer.h>

Public Member Functions
	MessagePlayer ()
	Create an uninitialised player; call initRead() or initWrite() before use.
	~MessagePlayer ()
	Destructor; releases buffers (does not delete messages already handed out).
bool	initRead (const char *root, uint32 interval, bool rotate=false)
	Open a recording for replay with a fixed playback interval.
bool	initRead (const char *root, bool rotate=false)
	Open a recording for replay using the original recorded timing.
bool	initWrite (const char *root, uint32 maxCount, uint64 maxSize)
	Open a recording for writing.
bool	setSubTypeList (std::map< uint16, std::string > &subtypes)
	Provide readable names for type level ids, used in metadata/CSV export.
bool	setSubContextList (std::map< uint16, std::string > &subcontexts)
	Provide readable names for context level ids, used in metadata/CSV export.
bool	setComponentNameList (std::map< uint32, std::string > &names)
	Provide readable names for component ids, used in metadata/CSV export.
bool	writeMetadata ()
	Write the metadata (name lists etc.) files alongside the recording.
bool	readMetadata ()
	Load the metadata files of an opened recording.
bool	setSystemIDs (DataMessage *msg)
	Stamp system-identifying header fields onto `msg` for recording.
bool	exportToCSVFile (const char filename, const char separator=NULL)
	Export the whole recording to a CSV file.
std::string	exportToCSV (const char *separator=NULL)
	Export the whole recording as a CSV string.
bool	addMessage (const char name, DataMessage msg)
	Append a message to the recording (write mode).
DataMessage *	waitForNextMessage (uint32 ms, const char *&triggerName)
	Wait for and return the next message in the recording (read mode), honouring the replay timing.
DataMessage *	waitForNextMessage (uint32 ms, uint32 &msToNext)
	As waitForNextMessage(uint32, const char*&) but also reports the delay to the following message.
DataMessage *	waitForNextMessage (uint32 ms, const char *&triggerName, uint32 &msToNext)
	As above, returning both the trigger name and the delay to the following message.
DataMessage *	waitForNextMessage (uint32 ms)
	Wait for and return the next message without extra outputs.
std::string	getCurrentTriggerName ()
bool	flushToDisk ()
	Force buffered messages and the index out to disk (write mode).
std::string	printAllString (const char *format=NULL)
	Render a human-readable dump of all recorded messages.

Detailed Description

Records DataMessage streams to disk and replays them with original timing.

A MessagePlayer instance is used in either write mode (initWrite(), then addMessage() repeatedly, finally flushToDisk()) or read mode (initRead(), then waitForNextMessage() in a loop until it returns NULL).

Ownership: addMessage() copies the message content — the caller keeps ownership of the message it passes in. Messages returned by waitForNextMessage() are owned by the caller and must be deleted.

Warning: Not thread-safe; use one instance per thread/stream.

Definition at line 65 of file MessagePlayer.h.

Constructor & Destructor Documentation

◆ MessagePlayer()

cmlabs::MessagePlayer::MessagePlayer ( )

Create an uninitialised player; call initRead() or initWrite() before use.

Definition at line 10 of file MessagePlayer.cpp.

References cmlabs::GetTimeNow().

◆ ~MessagePlayer()

cmlabs::MessagePlayer::~MessagePlayer ( )

Destructor; releases buffers (does not delete messages already handed out).

Definition at line 32 of file MessagePlayer.cpp.

Member Function Documentation

◆ addMessage()

bool cmlabs::MessagePlayer::addMessage	(	const char *	name,
		DataMessage *	msg )

Append a message to the recording (write mode).

The message content is copied; the caller keeps ownership of msg.

Parameters

name	name of the trigger that produced the message
msg	the message to record

Returns: true if successful

Definition at line 189 of file MessagePlayer.cpp.

References cmlabs::DataMessage::getCreatedTime(), cmlabs::DataMessage::getSize(), LogPrint, MAXKEYNAMELEN, cmlabs::ReplayIndexEntry::msg, cmlabs::ReplayIndexEntry::msgTime, cmlabs::ReplayIndexEntry::msgTriggerName, cmlabs::ReplayIndexEntry::reset(), cmlabs::ReplayIndexEntry::serial, cmlabs::ReplayIndexEntry::size, and cmlabs::utils::strcpyavail().

◆ exportToCSV()

std::string cmlabs::MessagePlayer::exportToCSV ( const char * separator = NULL )

Export the whole recording as a CSV string.

Parameters

separator separator string, defaults to comma

Returns: CSV text

Definition at line 455 of file MessagePlayer.cpp.

References cmlabs::DataMessage::GetCSVHeader(), cmlabs::ReplayIndexEntry::msgTriggerName, cmlabs::utils::ReadAFile(), cmlabs::ReplayIndexEntry::serial, cmlabs::ReplayIndexEntry::size, cmlabs::utils::StringFormat(), and cmlabs::DataMessage::toCSV().

Referenced by exportToCSVFile().

◆ exportToCSVFile()

bool cmlabs::MessagePlayer::exportToCSVFile	(	const char *	filename,
		const char *	separator = NULL )

Export the whole recording to a CSV file.

Parameters

filename	output file path
separator	separator string, defaults to comma

Returns: true if successful

Definition at line 448 of file MessagePlayer.cpp.

References exportToCSV(), and cmlabs::utils::WriteAFile().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1exportToCSVFile_1_1SWIG_10(), and Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1exportToCSVFile_1_1SWIG_11().

◆ flushToDisk()

bool cmlabs::MessagePlayer::flushToDisk ( )

Force buffered messages and the index out to disk (write mode).

Returns: true if successful.

Definition at line 239 of file MessagePlayer.cpp.

Referenced by _wrap_MessagePlayer_flushToDisk(), _wrap_MessagePlayer_flushToDisk(), and Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1flushToDisk().

◆ getCurrentTriggerName()

std::string cmlabs::MessagePlayer::getCurrentTriggerName ( )

Returns: the trigger name of the most recently returned message.

Definition at line 327 of file MessagePlayer.cpp.

◆ initRead() [1/2]

bool cmlabs::MessagePlayer::initRead	(	const char *	root,
		bool	rotate = false )

Open a recording for replay using the original recorded timing.

Parameters

root	directory (or file base) of the recording
rotate	if true, restart from the beginning when the end is reached

Returns: true if the recording was found and the index loaded

Definition at line 40 of file MessagePlayer.cpp.

References initRead().

◆ initRead() [2/2]

bool cmlabs::MessagePlayer::initRead	(	const char *	root,
		uint32	interval,
		bool	rotate = false )

Open a recording for replay with a fixed playback interval.

Parameters

root	directory (or file base) of the recording
interval	fixed inter-message interval in ms, overriding recorded timing
rotate	if true, restart from the beginning when the end is reached

Returns: true if the recording was found and the index loaded

Definition at line 44 of file MessagePlayer.cpp.

References cmlabs::utils::FileDetails::doesExist, cmlabs::utils::GetFileDetails(), cmlabs::ReplayIndexEntry::isValid(), LogPrint, cmlabs::utils::ReadAFile(), readMetadata(), cmlabs::ReplayIndexEntry::reset(), cmlabs::ReplayIndexEntry::size, cmlabs::utils::StringFormat(), and cmlabs::utils::TextEndsWith().

Referenced by initRead(), Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1initRead_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1initRead_1_1SWIG_11(), Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1initRead_1_1SWIG_12(), and Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1initRead_1_1SWIG_13().

◆ initWrite()

bool cmlabs::MessagePlayer::initWrite	(	const char *	root,
		uint32	maxCount,
		uint64	maxSize )

Open a recording for writing.

Parameters

root	directory (or file base) to write the recording to
maxCount	maximum number of messages to retain (ring buffer), 0 = unlimited
maxSize	maximum total size in bytes to retain, 0 = unlimited

Returns: true if the storage could be created

Definition at line 110 of file MessagePlayer.cpp.

References cmlabs::utils::BytifySize(), cmlabs::utils::CreateADir(), cmlabs::utils::FileDetails::doesExist, cmlabs::utils::GetFileDetails(), LogPrint, cmlabs::utils::MoveAFile(), cmlabs::ReplayIndexEntry::reset(), cmlabs::utils::StringFormat(), cmlabs::utils::TextEndsWith(), and cmlabs::utils::WriteAFile().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1initWrite().

◆ printAllString()

std::string cmlabs::MessagePlayer::printAllString ( const char * format = NULL )

Render a human-readable dump of all recorded messages.

Parameters

format optional format selector (implementation-defined), NULL for default

Returns: printable text

Definition at line 410 of file MessagePlayer.cpp.

References cmlabs::utils::BytifySize(), cmlabs::DataMessage::getUserEntriesAsString(), cmlabs::ReplayIndexEntry::msgTime, cmlabs::ReplayIndexEntry::msgTriggerName, cmlabs::PrintTimeString(), cmlabs::utils::ReadAFile(), cmlabs::ReplayIndexEntry::serial, cmlabs::ReplayIndexEntry::size, cmlabs::utils::StringFormat(), cmlabs::utils::stristr(), cmlabs::DataMessage::toJSON(), and cmlabs::DataMessage::toXML().

◆ readMetadata()

bool cmlabs::MessagePlayer::readMetadata ( )

Load the metadata files of an opened recording.

Returns: true if successful.

Definition at line 576 of file MessagePlayer.cpp.

References cmlabs::utils::ReadAFile(), and setSystemIDs().

Referenced by _wrap_MessagePlayer_readMetadata(), _wrap_MessagePlayer_readMetadata(), initRead(), and Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1readMetadata().

◆ setComponentNameList()

bool cmlabs::MessagePlayer::setComponentNameList ( std::map< uint32, std::string > & names )

Provide readable names for component ids, used in metadata/CSV export.

Parameters

names component id → name.

Returns: true if stored.

Definition at line 491 of file MessagePlayer.cpp.

References writeMetadata().

◆ setSubContextList()

bool cmlabs::MessagePlayer::setSubContextList ( std::map< uint16, std::string > & subcontexts )

Provide readable names for context level ids, used in metadata/CSV export.

Parameters

subcontexts level id → name.

Returns: true if stored.

Definition at line 486 of file MessagePlayer.cpp.

References writeMetadata().

◆ setSubTypeList()

bool cmlabs::MessagePlayer::setSubTypeList ( std::map< uint16, std::string > & subtypes )

Provide readable names for type level ids, used in metadata/CSV export.

Parameters

subtypes level id → name.

Returns: true if stored.

Definition at line 481 of file MessagePlayer.cpp.

References writeMetadata().

◆ setSystemIDs()

bool cmlabs::MessagePlayer::setSystemIDs ( DataMessage * msg )

Stamp system-identifying header fields onto msg for recording.

Parameters

msg	message to update.

Returns: true if successful.

Definition at line 533 of file MessagePlayer.cpp.

References cmlabs::DataMessage::data, cmlabs::DataMessage::getStringArray(), cmlabs::DataMessageHeader::userCount, and writeMetadata().

Referenced by readMetadata().

◆ waitForNextMessage() [1/4]

DataMessage * cmlabs::MessagePlayer::waitForNextMessage ( uint32 ms )

Wait for and return the next message without extra outputs.

Parameters

ms	maximum time to wait in milliseconds

Returns: the next message (caller owns it), or NULL

Definition at line 322 of file MessagePlayer.cpp.

References waitForNextMessage().

◆ waitForNextMessage() [2/4]

DataMessage * cmlabs::MessagePlayer::waitForNextMessage	(	uint32	ms,
		const char *&	triggerName )

Wait for and return the next message in the recording (read mode), honouring the replay timing.

Parameters

ms	maximum time to wait in milliseconds (blocks up to this long)
triggerName	receives a pointer to the recorded trigger name (owned by the player, valid until the next call)

Returns: the next message (caller owns it, delete when done), or NULL if none became due within ms

Definition at line 244 of file MessagePlayer.cpp.

References waitForNextMessage().

Referenced by waitForNextMessage(), waitForNextMessage(), and waitForNextMessage().

◆ waitForNextMessage() [3/4]

DataMessage * cmlabs::MessagePlayer::waitForNextMessage	(	uint32	ms,
		const char *&	triggerName,
		uint32 &	msToNext )

As above, returning both the trigger name and the delay to the following message.

Parameters

ms	maximum time to wait in milliseconds
triggerName	receives the recorded trigger name (owned by the player)
msToNext	receives the number of ms until the next message is due

Returns: the next message (caller owns it), or NULL

Definition at line 254 of file MessagePlayer.cpp.

References cmlabs::GetTimeNow(), LogPrint, MAXKEYNAMELEN, cmlabs::ReplayIndexEntry::msgTime, cmlabs::ReplayIndexEntry::msgTriggerName, NOCONTEXT, NOTYPE, cmlabs::utils::ReadAFile(), cmlabs::ReplayIndexEntry::serial, cmlabs::DataMessage::setContextChange(), cmlabs::DataMessage::setCreatedTime(), cmlabs::DataMessage::setType(), cmlabs::ReplayIndexEntry::size, cmlabs::utils::Sleep(), cmlabs::utils::strcpyavail(), and cmlabs::utils::StringFormat().

◆ waitForNextMessage() [4/4]

DataMessage * cmlabs::MessagePlayer::waitForNextMessage	(	uint32	ms,
		uint32 &	msToNext )

As waitForNextMessage(uint32, const char*&) but also reports the delay to the following message.

Parameters

ms	maximum time to wait in milliseconds
msToNext	receives the number of ms until the next message is due

Returns: the next message (caller owns it), or NULL

Definition at line 249 of file MessagePlayer.cpp.

References waitForNextMessage().

◆ writeMetadata()

bool cmlabs::MessagePlayer::writeMetadata ( )

Write the metadata (name lists etc.) files alongside the recording.

Returns: true if successful.

Definition at line 496 of file MessagePlayer.cpp.

References cmlabs::DataMessage::data, cmlabs::DataMessage::setString(), cmlabs::DataMessageHeader::size, and cmlabs::utils::WriteAFile().

Referenced by _wrap_MessagePlayer_writeMetadata(), _wrap_MessagePlayer_writeMetadata(), Java_com_cmlabs_cmsdk_cmsdkJNI_MessagePlayer_1writeMetadata(), setComponentNameList(), setSubContextList(), setSubTypeList(), and setSystemIDs().

The documentation for this class was generated from the following files:

/home/ubuntu/c/partner/psyclone2/CMSDK/include/MessagePlayer.h
/home/ubuntu/c/partner/psyclone2/CMSDK/src/MessagePlayer.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ MessagePlayer()

◆ ~MessagePlayer()

Member Function Documentation

◆ addMessage()

◆ exportToCSV()

◆ exportToCSVFile()

◆ flushToDisk()

◆ getCurrentTriggerName()

◆ initRead() [1/2]

◆ initRead() [2/2]

◆ initWrite()

◆ printAllString()

◆ readMetadata()

◆ setComponentNameList()

◆ setSubContextList()

◆ setSubTypeList()

◆ setSystemIDs()

◆ waitForNextMessage() [1/4]

◆ waitForNextMessage() [2/4]

◆ waitForNextMessage() [3/4]

◆ waitForNextMessage() [4/4]

◆ writeMetadata()