Class for writing and reading binary data to/from log files, with support for playback in different modes. More...

#include <pibinarylog.h>

Inheritance diagram for PIBinaryLog:

Classes
struct	BinLogIndex
	Indexed location of a record inside a log file. More...

struct	BinLogInfo
	Summary information about a log file and its indexed record types. More...

struct	BinLogRecordInfo
	Statistics for records sharing the same record ID. More...

Public Types
enum	PlayMode { PlayRealTime , PlayVariableSpeed , PlayStaticDelay }
	Playback modes used by PIBinaryLog. More...

enum	SplitMode { SplitNone , SplitTime , SplitSize , SplitCount }
	File splitting modes used while writing logs. More...

Public Types inherited from PIIODevice
enum	DeviceMode { ReadOnly = 0x01 , WriteOnly = 0x02 , ReadWrite = 0x03 }
	Open modes for PIIODevice. More...

enum	DeviceOption { BlockingRead = 0x01 , BlockingWrite = 0x02 }
	Generic options supported by some devices. More...

enum	DeviceInfoFlag { Sequential = 0x01 , Reliable = 0x02 }
	Characteristics of the device channel. More...

typedef PIFlags< DeviceOption >	DeviceOptions
	Bitmask of DeviceOption values.

typedef PIFlags< DeviceInfoFlag >	DeviceInfoFlags
	Bitmask of DeviceInfoFlag values.

Public Member Functions
	PIBinaryLog ()
	Constructs PIBinaryLog with default playback and split settings.

virtual	~PIBinaryLog ()
	Stops background activity and closes the current log.

PlayMode	playMode () const
	Returns current PlayMode.

SplitMode	splitMode () const
	Returns current SplitMode.

PIString	logDir () const
	Returns directory used for new log files.

PIString	filePrefix () const
	Returns filename prefix used for new log files.

int	defaultID () const
	Returns default record ID used by write(). More...

double	playSpeed () const
	Returns current playback speed multiplier.

PISystemTime	playDelay () const
	Returns static delay used in PlayStaticDelay mode.

PISystemTime	splitTime () const
	Returns elapsed-time threshold for SplitTime mode. More...

llong	splitFileSize () const
	Returns size threshold for SplitSize mode. More...

int	splitRecordCount () const
	Returns record-count threshold for SplitCount mode. More...

bool	rapidStart () const
	Returns whether the first threaded-read record is emitted without initial delay.

bool	createIndexOnFly () const
	Returns whether index data is collected while writing. More...

void	createNewFile (const PIString &path)
	Creates or reopens a log file at exact path "path" for writing. More...

void	setPlayMode (PlayMode mode)
	Sets current PlayMode.

void	setSplitMode (SplitMode mode)
	Sets current SplitMode.

void	setLogDir (const PIString &path)
	Sets directory used for newly created log files.

void	setFilePrefix (const PIString &prefix)
	Sets filename prefix used for newly created log files. More...

void	setDefaultID (int id)
	Sets default record ID used by write(). More...

void	setRapidStart (bool enabled)
	Enables immediate delivery of the first record in threaded playback. More...

void	setCreateIndexOnFly (bool yes)
	Enables or disables index collection while writing. More...

void	setPlaySpeed (double speed)
	Sets playback speed multiplier and switches mode to PlayVariableSpeed. More...

void	setPlayDelay (const PISystemTime &delay)
	Sets fixed delay between records and switches mode to PlayStaticDelay. More...

void	setPlayRealTime ()
	Switches playback to PlayRealTime. More...

void	setSplitTime (const PISystemTime &time)
	Sets time threshold for file splitting and switches mode to SplitTime. More...

void	setSplitFileSize (llong size)
	Sets size threshold for file splitting and switches mode to SplitSize. More...

void	setSplitRecordCount (int count)
	Sets record-count threshold for file splitting and switches mode to SplitCount. More...

void	setPause (bool pause)
	Pauses or resumes threaded playback and direct writes.

void	setFuncGetNewFilePath (std::function< PIString()> f)
	Sets custom path generator used for split files and implicit file creation. More...

int	writeBinLog (int id, PIByteArray data)
	Writes one record with explicit ID and payload. More...

int	writeBinLog (int id, const void *data, int size)
	Writes one record with explicit ID and payload buffer. More...

int	writeBinLog_raw (int id, const PISystemTime &time, const PIByteArray &data)
	Write one RAW record to BinLog file, with ID = id, Timestamp = time. More...

int	writeBinLog_raw (int id, const PISystemTime &time, const void *data, int size)
	Write one RAW record to BinLog file, with ID = id, Timestamp = time. More...

int	writeCount () const
	Returns number of records successfully written in current session.

PIByteArray	readBinLog (int id=0, PISystemTime time=0, int readed_id=0)
	Read one record from BinLog file, with ID = id, if id = 0 than any id will be readed. More...

int	readBinLog (int id, void read_to, int max_size, PISystemTime time=0, int *readed_id=0)
	Read one record from BinLog file, with ID = id, if id = 0 than any id will be readed. More...

llong	logSize () const
	Returns current log file size in bytes.

llong	logPos () const
	Returns current byte position in the opened log file.

bool	isEnd () const
	Returns true when reading position is at end of file or the log is closed.

bool	isEmpty () const
	Returns whether the log contains no records beyond the file header.

bool	isPause () const
	Returns current pause state.

int	lastReadedID () const
	Returns ID of the last record read from the file.

PISystemTime	lastReadedTimestamp () const
	Returns timestamp of the last record read from the file.

PISystemTime	logStartTimestamp () const
	Returns session start timestamp used for playback timing.

void	setHeader (const PIByteArray &header)
	Sets custom file header for subsequently created log files. More...

PIByteArray	getHeader () const
	Returns custom header stored in the currently opened log.

int	read (void *read_to, int max_size)
	Reads one message using filterID when it is not empty.

int	write (const void *data, int size)
	Writes one record using defaultID().

void	restart ()
	Restarts reading and playback from the beginning of the current log.

BinLogInfo	logInfo () const
	Returns cached index info when available, otherwise reparses current file info. More...

const PIVector< BinLogIndex > &	logIndex () const
	Returns current record index data. More...

bool	createIndex ()
	Builds record index for the current log file. More...

bool	isIndexed ()
	Returns whether the current log has loaded index data.

int	posForTime (const PISystemTime &time)
	Returns index of the first indexed record at or after "time". More...

void	seekTo (int rindex)
	Seeks to indexed record number "rindex". More...

bool	seek (const PISystemTime &time)
	Seeks to the first indexed record at or after "time". More...

bool	seek (llong filepos)
	Seeks to the first indexed record whose file position is at or after "filepos". More...

int	pos () const
	Returns current indexed record position, or -1 when not indexed.

PIByteArray	saveIndex () const
	Serializes current index data.

bool	loadIndex (PIByteArray saved)
	Loads previously serialized index data for the current readable log. More...

Public Member Functions inherited from PIIODevice
	PIIODevice ()
	Constructs an empty PIIODevice.

	PIIODevice (const PIString &path, DeviceMode mode=ReadWrite)
	Constructs PIIODevice with path "path" and open mode "mode".

virtual	~PIIODevice ()
	Destroys the device base object.

DeviceMode	mode () const
	Returns current open mode.

void	setMode (DeviceMode m)
	Sets open mode without reopening the device.

DeviceOptions	options () const
	Returns current device options.

bool	isOptionSet (DeviceOption o) const
	Returns whether option "o" is enabled.

void	setOptions (DeviceOptions o)
	Replaces all current device options with "o".

bool	setOption (DeviceOption o, bool yes=true)
	Sets option "o" to "yes" and returns its previous state.

DeviceInfoFlags	infoFlags () const
	Returns device channel characteristics.

PIString	path () const
	Returns current device path.

void	setPath (const PIString &path)
	Sets device path without reopening the device.

bool	isReadable () const
	Returns whether the current mode allows reading.

bool	isWriteable () const
	Returns whether the current mode allows writing.

bool	isOpened () const
	Returns whether the device is currently opened.

bool	isClosed () const
	Returns whether the device is currently closed.

virtual bool	canRead () const
	Returns whether reading is possible right now.

virtual bool	canWrite () const
	Returns whether writing is possible right now.

void	setReopenEnabled (bool yes=true)
	Enables or disables automatic reopen attempts during threaded read.

void	setReopenTimeout (PISystemTime timeout)
	Sets delay between automatic reopen attempts.

bool	isReopenEnabled () const
	Returns whether automatic reopen is enabled.

PISystemTime	reopenTimeout ()
	Returns delay between automatic reopen attempts.

void	setThreadedReadSlot (ReadRetFunc func)
	Sets callback invoked after successful threaded reads. More...

void	setThreadedReadData (void *d)
	Sets custom user data passed to threaded read callback.

void	setThreadedReadBufferSize (int new_size)
	Sets background read buffer size in bytes. More...

int	threadedReadBufferSize () const
	Returns background read buffer size in bytes.

const uchar *	threadedReadBuffer () const
	Returns pointer to the internal threaded-read buffer.

void *	threadedReadData () const
	Returns custom data passed to threaded read callback.

bool	isThreadedRead () const
	Returns whether threaded read is running.

bool	isThreadedReadStopping () const
	Returns whether threaded read is stopping.

void	startThreadedRead ()
	Starts threaded read.

void	startThreadedRead (ReadRetFunc func)
	Sets threaded read callback to "func" and starts threaded read.

void	stopThreadedRead ()
	Requests threaded read stop.

void	terminateThreadedRead ()
	Terminate threaded read. More...

bool	waitThreadedReadFinished (PISystemTime timeout={})
	Waits until threaded read finishes or "timeout" expires.

uint	threadedReadTimeout () const
	Returns delay between unsuccessful threaded read attempts in milliseconds.

void	setThreadedReadTimeout (uint ms)
	Sets delay between unsuccessful threaded read attempts in milliseconds.

bool	isThreadedWrite () const
	Returns whether threaded write is running.

void	startThreadedWrite ()
	Starts threaded write.

void	stopThreadedWrite ()
	Requests threaded write stop.

void	terminateThreadedWrite ()
	Terminate threaded write. More...

bool	waitThreadedWriteFinished (PISystemTime timeout={})
	Waits until threaded write finishes or "timeout" expires.

void	clearThreadedWriteQueue ()
	Clears queued threaded-write tasks.

void	start ()
	Starts both threaded read and threaded write.

void	stop ()
	Requests stop for both threaded read and threaded write.

void	stopAndWait (PISystemTime timeout={})
	Stops both background threads and waits for completion.

virtual void	interrupt ()
	Interrupts a blocking device operation.

ssize_t	read (void *read_to, ssize_t max_size)
	Reads at most "max_size" bytes into "read_to".

ssize_t	read (PIMemoryBlock mb)
	Reads data into memory block "mb".

PIByteArray	read (ssize_t max_size)
	Reads at most "max_size" bytes and returns them as PIByteArray.

virtual ssize_t	bytesAvailable () const
	Returns the number of bytes that are available for reading. More...

ssize_t	write (const void *data, ssize_t max_size)
	Writes at most "max_size" bytes from "data".

PIByteArray	readForTime (PISystemTime timeout)
	Reads data for up to "timeout" and returns collected bytes.

ullong	writeThreaded (const void *data, ssize_t max_size)
	Queues "data" for threaded write and returns task ID.

ullong	writeThreaded (const PIByteArray &data)
	Queues byte array "data" for threaded write and returns task ID.

bool	configure (const PIString &config_file, const PIString &section, bool parent_section=false)
	Configures the device from section "section" of file "config_file". More...

virtual PIConstChars	fullPathPrefix () const
	Returns device prefix used in full-path notation. Creating devices by unambiguous string.

PIString	constructFullPath () const
	Returns full-path representation of this device, fullPathPrefix() + "://" + ...

void	configureFromFullPath (const PIString &full_path)
	Configures the device from full-path parameters.

PIVariantTypes::IODevice	constructVariant () const
	Builds PIVariantTypes::IODevice description for this device.

void	configureFromVariant (const PIVariantTypes::IODevice &d)
	Configures the device from PIVariantTypes::IODevice.

ssize_t	write (const PIMemoryBlock &mb)
	Writes memory block "mb" to the device.

bool	open ()
	Opens the device with current path and mode.

bool	open (const PIString &_path)
	Opens the device with path "path".

bool	open (DeviceMode _mode)
	Opens the device with mode "mode".

bool	open (const PIString &_path, DeviceMode _mode)
	Opens the device with path "path" and mode "mode".

bool	close ()
	Closes the device.

ssize_t	write (PIByteArray data)
	Writes "data" to the device.

virtual void	flush ()
	Immediately flushes device buffers.

void	opened ()
	Raised after successful opening.

void	closed ()
	Raised after successful closing.

void	threadedReadEvent (const uchar *readed, ssize_t size)
	Raised after threaded read receives some data.

void	threadedWriteEvent (ullong id, ssize_t written_size)
	Raised after threaded write processes task with ID "id".

Public Member Functions inherited from PIObject
	PIObject (const PIString &name=PIString())
	Constructs an object and initializes its `name` property.

virtual	~PIObject ()
	Destroys the object, raises deleted() and disconnects it from the event graph.

PIString	name () const
	Returns the `name` property of this object.

virtual const char *	className () const
	Returns the registered class name of this object.

virtual uint	classNameID () const
	Returns the hash of className().

virtual const char *	parentClassName () const
	Returns the registered parent class name, or an empty string for the root.

bool	debug () const
	Returns whether piCoutObj output is enabled for this object.

void	setName (const PIString &name)
	Sets the `name` property of this object.

void	setDebug (bool debug)
	Enables or disables piCoutObj output for this object.

PIVariant	property (const char *name) const
	Returns the property with name "name".

void	setProperty (const char *name, const PIVariant &value)
	Sets the property "name" to "value" and creates it if needed. More...

bool	isPropertyExists (const char *name) const
	Returns whether the property "name" exists.

void	setThreadSafe (bool yes)
	Enables or disables the internal object mutex during handler execution. More...

bool	isThreadSafe () const
	Returns whether the internal object mutex is enabled for handler execution.

bool	execute (const PIString &method, const PIVector< PIVariantSimple > &vl)
	Executes a registered method or handler method by name with the supplied arguments. More...

bool	execute (const PIString &method)
	Overload of execute() for a method without arguments.

bool	execute (const PIString &method, const PIVariantSimple &v0)
	Overload of execute() for one argument.

bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Overload of execute() for two arguments.

bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Overload of execute() for three arguments.

bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Overload of execute() for four arguments.

bool	executeQueued (PIObject *performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Queues execution of a registered method on the performer object. More...

bool	executeQueued (PIObject *performer, const PIString &method)
	Overload of executeQueued() for a method without arguments.

bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0)
	Overload of executeQueued() for one argument.

bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Overload of executeQueued() for two arguments.

bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Overload of executeQueued() for three arguments.

bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Overload of executeQueued() for four arguments.

void	dump (const PIString &line_prefix=PIString()) const
	Dumps object diagnostics to the project output stream.

PIStringList	scopeList () const
	Returns the registered inheritance scope of this object, including its own class.

PIStringList	methodsEH () const
	Returns full signatures of all registered event and handler methods for this class scope.

bool	isMethodEHContains (const PIString &name) const
	Returns whether a registered event or handler method with this name exists.

PIString	methodEHArguments (const PIString &name) const
	Returns the comma-separated argument type list of a registered method.

PIString	methodEHFullFormat (const PIString &name) const
	Returns the full registered signature of a method.

PIString	methodEHFromAddr (const void *addr) const
	Returns the registered method name for the specified entry-point address.

void	piDisconnect (const PIString &sig, PIObject dest, void ev_h)
	Disconnects this source object from a specific destination handler for event "sig".

void	piDisconnect (const PIString &sig, PIObject *dest)
	Disconnects this source object from all connections of event "sig" to destination object "dest".

void	piDisconnect (const PIString &sig)
	Disconnects this source object from all connections of event "sig".

bool	isPIObject () const
	Returns whether this pointer still refers to a live PIObject instance.

template<typename T >
bool	isTypeOf () const
	Returns whether this object belongs to class "T" or one of its registered descendants.

template<typename T >
T *	cast () const
	Returns this object cast to "T" when isTypeOf<T>() succeeds, otherwise `nullptr`.

void	callQueuedEvents ()
	Executes all queued deliveries posted to this performer object.

bool	maybeCallQueuedEvents ()
	Executes queued deliveries only when this object was used as a performer. More...

void	deleteLater ()
	Schedules the object for deferred deletion. More...

void	deleted (PIObject *o)
	Raised immediately before object destruction. More...

Static Public Member Functions
static BinLogInfo	getLogInfo (const PIString &path)
	Get binlog info and statistic. More...

static bool	cutBinLog (const BinLogInfo &src, const PIString &dst, int from, int to)
	Create new binlog from part of "src" with allowed IDs and "from" to "to" file position. More...

static bool	joinBinLogsSerial (const PIStringList &src, const PIString &dst, std::function< bool(const PIString &, PISystemTime)> progress=nullptr)
	Create new binlog from serial splitted binlogs "src". More...

Static Public Member Functions inherited from PIIODevice
static PIIODevice *	createFromFullPath (const PIString &full_path)
	Try to create new device by prefix, configure it with configureFromFullPath() and returns it. More...

static PIIODevice *	createFromVariant (const PIVariantTypes::IODevice &d)
	Try to create new device by prefix, configure it with configureFromVariant() and returns it.

static PIString	normalizeFullPath (const PIString &full_path)
	Returns normalized full-path representation for "full_path".

static void	splitFullPath (PIString fpwm, PIString full_path, DeviceMode mode=0, DeviceOptions *opts=0)
	Splits full-path string into path, mode and options.

static PIStringList	availablePrefixes ()
	Returns fullPath prefixes of all registered devices.

static PIStringList	availableClasses ()
	Returns class names of all registered devices.

Static Public Member Functions inherited from PIObject
static bool	execute (PIObject *o, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Static convenience wrapper for execute().

static bool	execute (PIObject *o, const PIString &method)
	Static overload of execute() without arguments.

static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0)
	Static overload of execute() for one argument.

static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Static overload of execute() for two arguments.

static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Static overload of execute() for three arguments.

static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Static overload of execute() for four arguments.

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Static convenience wrapper for executeQueued().

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method)
	Static overload of executeQueued() without arguments.

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method, const PIVariantSimple &v0)
	Static overload of executeQueued() for one argument.

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Static overload of executeQueued() for two arguments.

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Static overload of executeQueued() for three arguments.

static bool	executeQueued (PIObject o, PIObject performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Static overload of executeQueued() for four arguments.

static PIObject::Connection	piConnect (PIObject src, const PIString &sig, PIObject dest_o, void dest, void ev_h, void e_h, int args, const char loc)
	Low-level direct connection helper behind the legacy `CONNECT*` macros.

static PIObject::Connection	piConnectU (PIObject src, const PIString &sig, PIObject dest_o, void dest, const PIString &hname, const char loc, PIObject *performer=0)
	Low-level name-based connection helper behind CONNECTU() and CONNECTU_QUEUED().

static PIObject::Connection	piConnectLS (PIObject src, const PIString &sig, std::function< void()> f, const char *loc)
	Low-level helper that connects an event to a lambda or functor wrapper.

static void	piDisconnect (PIObject src, const PIString &sig, PIObject dest, void *ev_h)
	Disconnects source object "src" from a specific destination handler for event "sig".

static void	piDisconnect (PIObject src, const PIString &sig, PIObject dest)
	Disconnects source object "src" from all connections of event "sig" to destination object "dest".

static void	piDisconnect (PIObject *src, const PIString &sig)
	Disconnects source object "src" from all connections of event "sig".

static void	raiseEvent (PIObject *sender, const uint eventID)
	Internal event delivery helper for registered events without arguments.

template<typename T0 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0())
	Internal event delivery helper for registered events with one argument.

template<typename T0 , typename T1 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1())
	Internal event delivery helper for registered events with two arguments.

template<typename T0 , typename T1 , typename T2 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2())
	Internal event delivery helper for registered events with three arguments.

template<typename T0 , typename T1 , typename T2 , typename T3 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2(), const T3 &v3=T3())
	Internal event delivery helper for registered events with four arguments.

static PIObject *	findByName (const PIString &name)
	Returns the first live object with name "name", or `nullptr`.

static bool	isPIObject (const PIObject *o)
	Returns whether "o" points to a live PIObject instance.

static bool	isPIObject (const void *o)
	Overload of isPIObject() for an untyped pointer.

template<typename T >
static bool	isTypeOf (const PIObject *o)
	Returns whether "o" belongs to class "T" or one of its registered descendants.

template<typename T >
static bool	isTypeOf (const void *o)
	Overload of isTypeOf() for an untyped pointer.

static PIString	simplifyType (const char *a, bool readable=true)
	Simplifies a C++ type spelling for registered-method metadata.

Public Attributes
PIVector< int >	filterID
	Optional list of record IDs accepted by read() and threaded playback. More...

Public Attributes inherited from PIIODevice
bool	reopenEnabled
	setReopenEnabled, default "true".

int	reopenTimeout
	setReopenTimeout, default 1_s.

int	threadedReadBufferSize
	setThreadedReadBufferSize in bytes, default 4096.

Protected Member Functions
PIString	constructFullPathDevice () const override
	Construct full device path.

void	configureFromFullPathDevice (const PIString &full_path) override
	Configure from full device path.

PIPropertyStorage	constructVariantDevice () const override
	Construct variant device properties.

void	configureFromVariantDevice (const PIPropertyStorage &d) override
	Configure from variant device properties.

ssize_t	readDevice (void *read_to, ssize_t max_size) override
	Read from device.

ssize_t	writeDevice (const void *data, ssize_t size) override
	Write to device.

bool	openDevice () override
	Open device.

bool	closeDevice () override
	Close device.

void	propertyChanged (const char *s) override
	Property changed callback.

bool	threadedRead (const uchar *readed, ssize_t size) override
	Threaded read callback.

DeviceInfoFlags	deviceInfoFlags () const override
	Get device information flags.

Protected Member Functions inherited from PIIODevice
virtual bool	configureDevice (const void e_main, const void e_parent=0)
	Reimplement to configure the device from "e_main" and optional "e_parent" entries cast to PIConfig::Entry*.

virtual bool	openDevice ()=0
	Reimplement to open device, return value will be set to "opened_" variable. Don't call this function in subclass, use open()!

virtual bool	closeDevice ()
	Reimplement to close the device; inverse return value is stored into "opened_".

virtual ssize_t	readDevice (void *read_to, ssize_t max_size)
	Reimplement this function to read from your device.

virtual ssize_t	writeDevice (const void *data, ssize_t max_size)
	Reimplement this function to write to your device.

virtual bool	threadedRead (const uchar *readed, ssize_t size)
	Called after threaded read receives data; default implementation calls the external callback set by setThreadedReadSlot().

virtual PIString	constructFullPathDevice () const
	Reimplement to build device-specific part of full-path string. Default implementation returns path().

virtual void	configureFromFullPathDevice (const PIString &full_path)
	Reimplement to configure the device from device-specific full-path parameters. Default implementation calls setPath().

virtual PIPropertyStorage	constructVariantDevice () const
	Reimplement to build device-specific variant properties. Default implementation returns PIPropertyStorage with "path".

virtual void	configureFromVariantDevice (const PIPropertyStorage &d)
	Reimplement to configure the device from PIPropertyStorage. Mode and options are already applied. Default implementation applies "path".

virtual void	optionsChanged ()
	Reimplement to react to changed device options.

virtual DeviceInfoFlags	deviceInfoFlags () const
	Reimplement to report actual DeviceInfoFlags. Default implementation returns 0.

virtual void	threadedReadBufferSizeChanged ()
	Reimplement to react to new threadedReadBufferSize().

Protected Member Functions inherited from PIObject
PIObject *	emitter () const
	Returns the source object that raised the current event. More...

virtual void	propertyChanged (const char *name)
	Virtual method called after property "name" has been changed by setProperty().

Handlers
PIString	createNewFile ()
	Creates a new log file in logDir() and returns its path, or empty string on failure. More...

Events
void	fileEnd ()
	Raised when reading reaches the end of file.

void	fileError ()
	Raised when file header validation or file creation fails.

void	newFile (const PIString &filename)
	Raised after a new log file is successfully created.

void	posChanged (int pos)
	Raised when current indexed playback position changes.

void	threadedReadRecord (PIByteArray data, int id, PISystemTime time)
	Raised after threaded playback emits one record.

Additional Inherited Members
Related Functions inherited from PIIODevice
template<typename T >
T	readDeviceSetting (const PIString &name, const T &def, const PIConfig::Entry em, const PIConfig::Entry ep)
	Helper for reading device settings from configuration entries. More...

#define	REGISTER_DEVICE(class)
	Enable device instances creation with PIIODevice::createFromFullPath() function. More...

#define	PIIODEVICE(class, prefix)
	Use this macro instead of PIOBJECT when describe your own PIIODevice. More...

Related Functions inherited from PIObject
#define	piCoutObj
	Macro used for conditional (piDebug && PIObject::debug()) output to PICout(StdOut) for subclasses of PIObject.

#define	piCerrObj
	Macro used for conditional (piDebug && PIObject::debug()) output to PICout(StdErr) for subclasses of PIObject.

#define	PIOBJECT(name)
	Put this macro inside a direct PIObject subclass definition to enable registered events, event handlers and class metadata.

#define	PIOBJECT_SUBCLASS(name, parent)
	Put this macro inside a PIObject subclass definition to inherit registered methods and class scope from "parent".

#define	EVENT_HANDLER0(ret, name) ret name()
	Declare a registered event handler method with signature `ret name()`.

#define	EVENT_HANDLER1(ret, name, type0, var0) ret name(type0 var0)
	Declare a registered event handler method with one argument.

#define	EVENT_HANDLER2(ret, name, type0, var0, type1, var1) ret name(type0 var0, type1 var1)
	Declare a registered event handler method with two arguments.

#define	EVENT_HANDLER3(ret, name, type0, var0, type1, var1, type2, var2) ret name(type0 var0, type1 var1, type2 var2)
	Declare a registered event handler method with three arguments.

#define	EVENT_HANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) ret name(type0 var0, type1 var1, type2 var2, type3 var3)
	Declare a registered event handler method with four arguments.

#define	EVENT_HANDLER EVENT_HANDLER0
	Synonym of EVENT_HANDLER0.

#define	EVENT_VHANDLER0(ret, name) virtual ret name()
	Declare a virtual registered event handler method with signature `virtual ret name()`.

#define	EVENT_VHANDLER1(ret, name, type0, var0) virtual ret name(type0 var0)
	Declare a virtual registered event handler method with one argument.

#define	EVENT_VHANDLER2(ret, name, type0, var0, type1, var1) virtual ret name(type0 var0, type1 var1)
	Declare a virtual registered event handler method with two arguments.

#define	EVENT_VHANDLER3(ret, name, type0, var0, type1, var1, type2, var2) virtual ret name(type0 var0, type1 var1, type2 var2)
	Declare a virtual registered event handler method with three arguments.

#define	EVENT_VHANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)
	Declare a virtual registered event handler method with four arguments.

#define	EVENT_VHANDLER EVENT_VHANDLER0
	Synonym of EVENT_VHANDLER0.

#define	EVENT0(name) void name();
	Declare an event method with no arguments.

#define	EVENT1(name, type0, var0) void name(type0 var0);
	Declare an event method with one argument.

#define	EVENT2(name, type0, var0, type1, var1) void name(type0 var0, type1 var1);
	Declare an event method with two arguments.

#define	EVENT3(name, type0, var0, type1, var1, type2, var2) void name(type0 var0, type1 var1, type2 var2);
	Declare an event method with three arguments.

#define	EVENT4(name, type0, var0, type1, var1, type2, var2, type3, var3) void name(type0 var0, type1 var1, type2 var2, type3 var3);
	Declare an event method with four arguments.

#define	EVENT EVENT0
	Synonym of EVENT0.

#define	RAISE_EVENT0(src, event)
	Compatibility helper that raises event "event" on source object "src".

#define	RAISE_EVENT1(src, event, v0)
	Compatibility helper that raises event "event" with one argument.

#define	RAISE_EVENT2(src, event, v0, v1)
	Compatibility helper that raises event "event" with two arguments.

#define	RAISE_EVENT3(src, event, v0, v1, v2)
	Compatibility helper that raises event "event" with three arguments.

#define	RAISE_EVENT4(src, event, v0, v1, v2, v3)
	Compatibility helper that raises event "event" with four arguments.

#define	CONNECTU(src, event, dest, handler)
	Connect event "event" from object "src" to event handler or event "handler" of object "dest". More...

#define	CONNECTU_QUEUED(src, event, dest, handler, performer)
	Connect event "event" from object "src" to event handler or event "handler" of object "dest". More...

#define	CONNECTL(src, event, functor)
	Connect event "event" from object "src" to lambda-expression "functor". More...

#define	CONNECT0(ret, src, event, dest, handler)
	Legacy compatibility helper that connects an event to a registered handler with compile-time signature spelling. More...

#define	CONNECT1(ret, type0, src, event, dest, handler)
	Legacy compatibility helper for a one-argument registered event or handler. More...

#define	CONNECT2(ret, type0, type1, src, event, dest, handler)
	Legacy compatibility helper for a two-argument registered event or handler. More...

#define	CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Legacy compatibility helper for a three-argument registered event or handler. More...

#define	CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Legacy compatibility helper for a four-argument registered event or handler. More...

#define	CONNECT CONNECT0
	Synonym of CONNECT0. More...

#define	WEAK_CONNECT0(ret, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification. More...

#define	WEAK_CONNECT1(ret, type0, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for one argument. More...

#define	WEAK_CONNECT2(ret, type0, type1, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for two arguments. More...

#define	WEAK_CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for three arguments. More...

#define	WEAK_CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for four arguments. More...

#define	WEAK_CONNECT WEAK_CONNECT0
	Synonym of WEAK_CONNECT0. More...

#define	DISCONNECT0(ret, src, event, dest, handler)
	Disconnect a registered event from a registered event handler.

#define	DISCONNECT1(ret, type0, src, event, dest, handler)
	Disconnect a one-argument registered event from a registered event handler.

#define	DISCONNECT2(ret, type0, type1, src, event, dest, handler)
	Disconnect a two-argument registered event from a registered event handler.

#define	DISCONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Disconnect a three-argument registered event from a registered event handler.

#define	DISCONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Disconnect a four-argument registered event from a registered event handler.

#define	DISCONNECT DISCONNECT0
	Synonym of DISCONNECT0.

#define	HANDLER(handler)
	Low-level helper that expands to the registered handler entry point.

Detailed Description

Class for writing and reading binary data to/from log files, with support for playback in different modes.

Class for read and write binary data to logfile, and playback this data in realtime, or custom speed.

The PIBinaryLog class provides functionality to write binary data to log files and read/playback data from them. It supports multiple play modes including real-time, variable speed, and static delay modes. The class also supports splitting log files by size, time, or record count.

Synopsis

Binary Log is a file with simple header, where you can read and write some binary data. Any written data include special header with ID, size and timestamp. This header provides separation different messages from the one file by choosing different IDs. With filterID or special functions, like readBinLog() you can choose IDs what you want to read. With function writeBinLog() or setDefaultID() you can choose ID that mark you data. By default ID = 1, and filterID is empty, that mean you read any ID without filtering. ThreadedRead provide you playback data, with delay that you write data. You can choose different playbak modes by set PlayMode.

Basic usage

This class provide all functions of PIIODevice, such open(), close(), read() ,write(), and threaded read/write. function setLogDir() need to set directory for BinLog files function createNewFile() need to create new binlog file function restart() need start from the begining of binlog file

Member Enumeration Documentation

◆ PlayMode

enum PIBinaryLog::PlayMode

Playback modes used by PIBinaryLog.

Enumerator
PlayRealTime	Playback follows record timestamps in real time, default mode
PlayVariableSpeed	Playback uses recorded timing scaled by setPlaySpeed()
PlayStaticDelay	Playback uses fixed delay from setPlayDelay() and ignores record timestamps

◆ SplitMode

enum PIBinaryLog::SplitMode

File splitting modes used while writing logs.

Enumerator
SplitNone	Do not split files, default mode
SplitTime	Start a new file when elapsed record time exceeds configured limit
SplitSize	Start a new file when file size exceeds configured limit
SplitCount	Start a new file when written record count exceeds configured limit

Member Function Documentation

◆ defaultID()

int PIBinaryLog::defaultID ( ) const

inline

Returns default record ID used by write().

Returns: The default record ID used when writing without explicitly specifying an ID.

◆ splitTime()

PISystemTime PIBinaryLog::splitTime ( ) const

inline

Returns elapsed-time threshold for SplitTime mode.

Returns: The time interval used for splitting log files in SplitTime mode.

◆ splitFileSize()

llong PIBinaryLog::splitFileSize ( ) const

inline

Returns size threshold for SplitSize mode.

Returns: The maximum file size in bytes for splitting log files in SplitSize mode.

◆ splitRecordCount()

int PIBinaryLog::splitRecordCount ( ) const

inline

Returns record-count threshold for SplitCount mode.

Returns: The maximum number of records per file for splitting log files in SplitCount mode.

◆ createIndexOnFly()

bool PIBinaryLog::createIndexOnFly ( ) const

inline

Returns whether index data is collected while writing.

Returns: true if index is created on-the-fly during writing, false otherwise.

◆ createNewFile() [1/2]

void PIBinaryLog::createNewFile ( const PIString & path )

Creates or reopens a log file at exact path "path" for writing.

Creates a new binary log file at the specified path. If a file already exists, it will be overwritten.

◆ setFilePrefix()

void PIBinaryLog::setFilePrefix ( const PIString & prefix )

inline

Sets filename prefix used for newly created log files.

Sets the filename prefix used when generating log file names. Combined with the log directory and timestamp to create unique filenames.

Parameters

prefix The filename prefix.

◆ setDefaultID()

void PIBinaryLog::setDefaultID ( int id )

inline

Sets default record ID used by write().

Sets the default record ID used when calling write without specifying an ID.

Parameters

id	The default record ID. Must be greater than 0.

◆ setRapidStart()

void PIBinaryLog::setRapidStart ( bool enabled )

inline

Enables immediate delivery of the first record in threaded playback.

When enabled, the first record is read immediately at the start of playback without waiting for its timestamp. This reduces initial latency.

Parameters

enabled true to enable rapid start, false to disable.

◆ setCreateIndexOnFly()

void PIBinaryLog::setCreateIndexOnFly ( bool yes )

Enables or disables index collection while writing.

Enables or disables automatic index creation during the writing process. When enabled, the index is built incrementally as data is written.

Parameters

yes	true to enable on-the-fly index creation, false to disable.

◆ setPlaySpeed()

void PIBinaryLog::setPlaySpeed ( double speed )

inline

Sets playback speed multiplier and switches mode to PlayVariableSpeed.

Sets the playback speed multiplier. A value of 1.0 means real-time playback. Values greater than 1.0 speed up playback, while values between 0 and 1.0 slow it down.

Note: This function automatically sets the play mode to PlayVariableSpeed.

Parameters

speed The playback speed multiplier.

◆ setPlayDelay()

void PIBinaryLog::setPlayDelay ( const PISystemTime & delay )

inline

Sets fixed delay between records and switches mode to PlayStaticDelay.

Sets a fixed delay between records during playback, ignoring the original timestamps in the log file.

Note: This function automatically sets the play mode to PlayStaticDelay.

Parameters

delay The static delay between records.

◆ setPlayRealTime()

void PIBinaryLog::setPlayRealTime ( )

inline

Switches playback to PlayRealTime.

Sets the playback mode to real-time, where records are played at their original timestamps.

◆ setSplitTime()

void PIBinaryLog::setSplitTime ( const PISystemTime & time )

inline

Sets time threshold for file splitting and switches mode to SplitTime.

Sets the time interval for splitting log files. When the time difference between records exceeds this value, a new file is created.

Note: This function automatically sets the split mode to SplitTime.

Parameters

time	The time interval for splitting files.

◆ setSplitFileSize()

void PIBinaryLog::setSplitFileSize ( llong size )

inline

Sets size threshold for file splitting and switches mode to SplitSize.

Sets the maximum file size in bytes for splitting log files. When a file reaches this size, a new file is created.

Note: This function automatically sets the split mode to SplitSize.

Parameters

size	The maximum file size in bytes.

◆ setSplitRecordCount()

void PIBinaryLog::setSplitRecordCount ( int count )

inline

Sets record-count threshold for file splitting and switches mode to SplitCount.

Sets the maximum number of records per file for splitting log files. When a file reaches this record count, a new file is created.

Note: This function automatically sets the split mode to SplitCount.

Parameters

count The maximum number of records per file.

◆ setFuncGetNewFilePath()

void PIBinaryLog::setFuncGetNewFilePath ( std::function< PIString()> f )

inline

Sets custom path generator used for split files and implicit file creation.

Sets a custom callback function that returns the path for the next log file when using split mode. This overrides the internal path generator (logdir() + prefix() + current_time()). To restore the internal generator, set this function to nullptr.

Parameters

f	The callback function returning the next file path, or nullptr to use the internal generator.

◆ writeBinLog() [1/2]

int PIBinaryLog::writeBinLog	(	int	id,
		PIByteArray	data
	)

inline

Writes one record with explicit ID and payload.

Writes a single record to the binary log file with the specified ID and data.

Parameters

id	The record ID. Must be greater than 0.
data	The data to write.

Returns: Data size on success, negative value on error.

◆ writeBinLog() [2/2]

int PIBinaryLog::writeBinLog	(	int	id,
		const void *	data,
		int	size
	)

Writes one record with explicit ID and payload buffer.

Returns written payload size, 0 while paused, or negative value on error. ID must be greater than zero.

◆ writeBinLog_raw() [1/2]

int PIBinaryLog::writeBinLog_raw	(	int	id,
		const PISystemTime &	time,
		const PIByteArray &	data
	)

inline

Write one RAW record to BinLog file, with ID = id, Timestamp = time.

Writes a single record with an explicit timestamp to the binary log file. The timestamp is stored as-is, without modification.

Parameters

id	The record ID. Must be greater than 0.
time	The timestamp to associate with this record.
data	The data to write.

Returns: 0 on success, negative value on error.

◆ writeBinLog_raw() [2/2]

int PIBinaryLog::writeBinLog_raw	(	int	id,
		const PISystemTime &	time,
		const void *	data,
		int	size
	)

Write one RAW record to BinLog file, with ID = id, Timestamp = time.

Writes a single record with an explicit timestamp to the binary log file. The timestamp is stored as-is, without modification.

Parameters

id	The record ID. Must be greater than 0.
time	The timestamp to associate with this record.
data	Pointer to the data to write.
size	Size of the data in bytes.

Returns: 0 on success, negative value on error.

◆ readBinLog() [1/2]

PIByteArray PIBinaryLog::readBinLog	(	int	id = `0`,
		PISystemTime *	time = `0`,
		int *	readed_id = `0`
	)

Read one record from BinLog file, with ID = id, if id = 0 than any id will be readed.

Reads a single record from the binary log file. If id is 0, records of any ID can be read. Returns the record data as a byte array.

Parameters

id	The record ID to read, or 0 to read any record.
time	Optional pointer to store the record's timestamp.
readed_id	Optional pointer to store the record's ID.

Returns: The record data as a byte array.

◆ readBinLog() [2/2]

int PIBinaryLog::readBinLog	(	int	id,
		void *	read_to,
		int	max_size,
		PISystemTime *	time = `0`,
		int *	readed_id = `0`
	)

Read one record from BinLog file, with ID = id, if id = 0 than any id will be readed.

Reads a single record from the binary log file into a user-provided buffer. If id is 0, records of any ID can be read.

Parameters

id	The record ID to read, or 0 to read any record.
read_to	Pointer to the buffer where the record data will be stored.
max_size	Maximum size of the buffer in bytes.
time	Optional pointer to store the record's timestamp.
readed_id	Optional pointer to store the record's ID.

Returns: The actual number of bytes read, or negative value on error.

◆ setHeader()

void PIBinaryLog::setHeader ( const PIByteArray & header )

Sets custom file header for subsequently created log files.

Sets custom header data that will be written to the log file and can be retrieved later using getHeader().

Parameters

header The custom header data to write.

◆ logInfo()

BinLogInfo PIBinaryLog::logInfo ( ) const

inline

Returns cached index info when available, otherwise reparses current file info.

Returns: A BinLogInfo structure containing comprehensive information about the log file.

◆ logIndex()

const PIVector< BinLogIndex > & PIBinaryLog::logIndex ( ) const

inline

Returns current record index data.

Meaningful data appears after createIndex(), loadIndex() or indexed writing.

◆ createIndex()

bool PIBinaryLog::createIndex ( )

Builds record index for the current log file.

Builds an index of the log file for fast random access to records. The index stores position, ID, and timestamp for each record.

Returns: true if index creation was successful, false otherwise.

◆ posForTime()

int PIBinaryLog::posForTime ( const PISystemTime & time )

Returns index of the first indexed record at or after "time".

Finds the index of the record with the timestamp closest to the specified time. Requires the file to be indexed first.

Parameters

time	The target timestamp to find.

Returns: The index of the nearest record, or -1 if not indexed or the time is before the first record.

◆ seekTo()

void PIBinaryLog::seekTo ( int rindex )

Seeks to indexed record number "rindex".

Seeks to a specific record by its index position in the log file.

Parameters

rindex The index of the record to seek to.

◆ seek() [1/2]

bool PIBinaryLog::seek ( const PISystemTime & time )

Seeks to the first indexed record at or after "time".

Seeks to the record with the timestamp closest to the specified time. Requires the file to be indexed first.

Parameters

time	The target timestamp to seek to.

Returns: true if the seek was successful, false otherwise.

◆ seek() [2/2]

bool PIBinaryLog::seek ( llong filepos )

Seeks to the first indexed record whose file position is at or after "filepos".

Seeks to a specific byte position in the log file for reading or playing.

Parameters

filepos The byte position in the file.

Returns: true if the seek was successful, false otherwise.

◆ loadIndex()

bool PIBinaryLog::loadIndex ( PIByteArray saved )

Loads previously serialized index data for the current readable log.

Loads an index that was previously saved with saveIndex(). The file must be opened before loading the index.

Parameters

saved The serialized index data to load.

Returns: true if the index was loaded successfully, false otherwise.

◆ createNewFile() [2/2]

PIString PIBinaryLog::createNewFile ( )

Creates a new log file in logDir() and returns its path, or empty string on failure.

Default filenames look like filePrefix() + "yyyy_MM_dd__hh_mm_ss.binlog".

◆ getLogInfo()

PIBinaryLog::BinLogInfo PIBinaryLog::getLogInfo ( const PIString & path )

static

Get binlog info and statistic.

Parses the specified log file and returns comprehensive information including record statistics, file size, and time range. This is a static method that can be called without an instance.

Parameters

path	The path to the log file to analyze.

Returns: A BinLogInfo structure containing the file information and statistics.

◆ cutBinLog()

bool PIBinaryLog::cutBinLog	(	const BinLogInfo &	src,
		const PIString &	dst,
		int	from,
		int	to
	)

static

Create new binlog from part of "src" with allowed IDs and "from" to "to" file position.

Creates a new log file by extracting records from the source log between the specified file positions. Only records within the specified ID filter range are included.

Parameters

src	The source log information containing the path and metadata.
dst	The path where the new log file will be created.
from	The starting file position (inclusive).
to	The ending file position (exclusive).

Returns: true if the cut operation was successful, false otherwise.

◆ joinBinLogsSerial()

bool PIBinaryLog::joinBinLogsSerial	(	const PIStringList &	src,
		const PIString &	dst,
		std::function< bool(const PIString &, PISystemTime)>	progress = `nullptr`
	)

static

Create new binlog from serial splitted binlogs "src".

Concatenates multiple split log files into a single log file. The source files should be in chronological order. An optional progress callback can be provided to track the operation.

Parameters

src	List of source log file paths to join.
dst	The path where the combined log file will be created.
progress	Optional callback function that receives the current file path and timestamp, returning true to continue or false to cancel.

Returns: true if the join operation was successful, false otherwise.

Member Data Documentation

◆ filterID

PIVector<int> PIBinaryLog::filterID

Optional list of record IDs accepted by read() and threaded playback.

A list of record IDs to filter when reading. Only records with these IDs will be read. Empty list means all IDs are read.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Handlers

Events

Additional Inherited Members

Detailed Description

Synopsis

Basic usage

Member Enumeration Documentation

◆ PlayMode

◆ SplitMode

Member Function Documentation

◆ defaultID()

◆ splitTime()

◆ splitFileSize()

◆ splitRecordCount()

◆ createIndexOnFly()

◆ createNewFile() [1/2]

◆ setFilePrefix()

◆ setDefaultID()

◆ setRapidStart()

◆ setCreateIndexOnFly()

◆ setPlaySpeed()

◆ setPlayDelay()

◆ setPlayRealTime()

◆ setSplitTime()

◆ setSplitFileSize()

◆ setSplitRecordCount()

◆ setFuncGetNewFilePath()

◆ writeBinLog() [1/2]

◆ writeBinLog() [2/2]

◆ writeBinLog_raw() [1/2]

◆ writeBinLog_raw() [2/2]

◆ readBinLog() [1/2]

◆ readBinLog() [2/2]

◆ setHeader()

◆ logInfo()

◆ logIndex()

◆ createIndex()

◆ posForTime()

◆ seekTo()

◆ seek() [1/2]

◆ seek() [2/2]

◆ loadIndex()

◆ createNewFile() [2/2]

◆ getLogInfo()

◆ cutBinLog()

◆ joinBinLogsSerial()

Member Data Documentation

◆ filterID