Defines a MDF channel (CN) block.

#include <ichannel.h>

Inheritance diagram for mdf::IChannel:

Collaboration diagram for mdf::IChannel:

Public Member Functions
virtual void	Name (const std::string &name)=0
	Sets channel name.

virtual std::string	Name () const =0
	Returns channel name.

virtual void	DisplayName (const std::string &name)=0
	Sets display name.

virtual std::string	DisplayName () const =0
	Display name.

virtual void	Description (const std::string &description)=0
	Sets the description.

virtual std::string	Description () const =0
	Returns the description.

virtual void	Unit (const std::string &unit)=0
	Sets unit string or or the MIME text string.

virtual std::string	Unit () const =0
	Returns the unit string or the MIME content type string.

virtual void	Flags (uint32_t flags)
	Sets channel flags. Flags are defined in the CnFlag namespace

virtual uint32_t	Flags () const
	Channel flags are defined in the CnFlag namespace

virtual bool	IsUnitValid () const =0
	True if unit exists.

virtual void	Type (ChannelType type)=0
	Sets the type of channel.

virtual ChannelType	Type () const =0
	Type of channel.

virtual void	Sync (ChannelSyncType type)
	Sets the type of sync.

virtual ChannelSyncType	Sync () const
	Type of sync.

virtual void	DataType (ChannelDataType type)=0
	Sets the data type.

virtual ChannelDataType	DataType () const =0
	Data type.

virtual void	DataBytes (uint64_t nof_bytes)=0
	Sets the data size (bytes)

virtual uint64_t	DataBytes () const =0
	Data size (bytes);.

virtual void	Decimals (uint8_t precision)
	Sets number of decimals (floating points only)

virtual uint8_t	Decimals () const =0
	Number of decimals (floating points)

virtual bool	IsDecimalUsed () const =0
	Returns true if decimals is used

virtual void	Range (double min, double max)
	Sets the ranges.

virtual std::optional< std::pair< double, double > >	Range () const
	Returns the ranges.

virtual void	Limit (double min, double max)
	Sets the limits.

virtual std::optional< std::pair< double, double > >	Limit () const
	Returns the limits.

virtual void	ExtLimit (double min, double max)
	Sets the extended limits.

virtual std::optional< std::pair< double, double > >	ExtLimit () const
	Returns the extended limits.

virtual void	SamplingRate (double sampling_rate)=0
	Sets the sample rate (s). This is a MDF 3 feature.

virtual double	SamplingRate () const =0
	Returns the sample rate (s). This is a MDF 3 feature.

virtual ISourceInformation *	SourceInformation () const
	Returns the source information, if any.

virtual ISourceInformation *	CreateSourceInformation ()
	Creates a source information block.

virtual IChannelArray *	ChannelArray () const
	Returns the channel array object if any exist in this channel.

virtual IChannelArray *	CreateChannelArray ()
	Create or returns an existing channel array (CA) block.

virtual IChannelConversion *	ChannelConversion () const =0
	Returns the conversion block, if any.

virtual IChannelConversion *	CreateChannelConversion ()=0
	Creates a conversion block.

virtual IChannel *	CreateChannelComposition ()=0
	Creates a composition channel.

virtual IChannel *	CreateChannelComposition (const std::string_view &name)
	Creates a composition channel with a specific name or returns an existing channel.

virtual std::vector< IChannel * >	ChannelCompositions ()=0
	Creates a composition channel.

bool	IsNumber () const
	Returns true if the channel is a number.

virtual IMetaData *	CreateMetaData ()
	Creates a metadata (MD) block.

virtual IMetaData *	MetaData () const
	Returns the meta-data (MD) block if it exist.

virtual void	AddAttachmentReference (const IAttachment *attachment)
	Adds an attachment reference to the channel.

virtual std::vector< const IAttachment * >	AttachmentList () const
	Returns a list of attachment pointers.

void	VlsdRecordId (uint64_t record_id) const
	Sets the VLSD record id.

uint64_t	VlsdRecordId () const
	Returns the VLSD record id.

template<typename T >
bool	GetChannelValue (const std::vector< uint8_t > &record_buffer, T &dest, uint64_t array_index=0) const
	Parse out the channel value from a data record.

template<typename T >
void	SetChannelValue (const T &value, bool valid=true, uint64_t array_index=0)
	Sets a channel value.

template<typename T >
void	SetChannelValues (const std::vector< T > &values)
	Sets channel array values.

bool	GetUnsignedValue (const std::vector< uint8_t > &record_buffer, uint64_t &dest, uint64_t array_index=0) const
	Internally used function mainly for fetching VLSD index values.

virtual bool	GetTextValue (const std::vector< uint8_t > &record_buffer, std::string &dest) const
	Internally used function mainly for fetching VLSD text values.

void	SetTimestamp (double timestamp, std::vector< uint8_t > &record_buffer) const
	The function change the supplied records time channel value.

virtual void	BitCount (uint32_t bits)=0
	Sets the size of data in bits.

virtual uint32_t	BitCount () const =0
	Returns the data size in number of bits.

virtual void	BitOffset (uint16_t bits)=0
	Sets the offset to data in bits.

virtual uint16_t	BitOffset () const =0
	Returns offset to data (0..7).

virtual void	ByteOffset (uint32_t bytes)=0
	Sets the byte offset in record to to data.

virtual uint32_t	ByteOffset () const =0
	Returns the byte offset to data in the record.

virtual const IChannelGroup *	ChannelGroup () const =0
	Support function that returns its channel group.

uint64_t	RecordId () const
	Returns th channel group (CG) record ID.

void	CalculateMasterTime (bool calculate_master)
	Defines if the master channel time should be calculated or not.

bool	CalculateMasterTime () const
	Defines if the master channel time is calculated or user defined.

void	ArraySize (uint64_t array_size)
	Sets the array size for the channel.

uint64_t	ArraySize () const
	Returns 1 if no array and > 1 if it is an array.

template<>
bool	GetChannelValue (const std::vector< uint8_t > &record_buffer, std::vector< uint8_t > &dest, uint64_t array_index) const
	Support function that gets an array value from a record buffer.

template<>
bool	GetChannelValue (const std::vector< uint8_t > &record_buffer, std::string &dest, uint64_t array_index) const
	Support function that gets a string value from a record buffer.

template<>
void	SetChannelValue (const std::string &value, bool valid, uint64_t array_index)
	Support function that sets a string value to a record buffer.

template<>
void	SetChannelValue (const std::vector< uint8_t > &values, bool valid, uint64_t array_index)
	Support function that sets a string value to a record buffer.

Public Member Functions inherited from mdf::IBlock
virtual	~IBlock ()=default
	Default destructor.

virtual int64_t	Index () const =0
	File position within the file.

virtual std::string	BlockType () const =0
	Returns the block type.

Static Public Member Functions
template<typename V >
static bool	GetVirtualSample (uint64_t sample, V &value)
	Returns the value for a virtual sample.

template<typename V = std::string>
static bool	GetVirtualSample (uint64_t sample, std::string &value)
	Specialization that returns virtual sample values.

Protected Member Functions
bool	GetSignedValue (const std::vector< uint8_t > &record_buffer, int64_t &dest, uint64_t array_index) const
	Support function that get signed integer from a record.

bool	GetFloatValue (const std::vector< uint8_t > &record_buffer, double &dest, uint64_t array_index) const
	Support function that get float values from a record.

virtual bool	GetByteArrayValue (const std::vector< uint8_t > &record_buffer, std::vector< uint8_t > &dest) const
	Support function that get array values from a record.

bool	GetCanOpenDate (const std::vector< uint8_t > &record_buffer, uint64_t &dest) const
	Support function that get CANOpen date values from a record.

bool	GetCanOpenTime (const std::vector< uint8_t > &record_buffer, uint64_t &dest) const
	Support function that get CANOpen time values from a record.

virtual std::vector< uint8_t > &	SampleBuffer () const =0
	Support function that gets the channel group sample buffer.

virtual void	SetValid (bool valid, uint64_t array_index)
	Support function that sets the valid flag.

virtual bool	GetValid (const std::vector< uint8_t > &record_buffer, uint64_t array_index) const
	Support function that return true if the valid bit is set.

void	SetUnsignedValueLe (uint64_t value, bool valid, uint64_t array_index)
	Support function that sets unsigned little endian values.

void	SetUnsignedValueBe (uint64_t value, bool valid, uint64_t array_index)
	Support function that sets unsigned big endian values.

void	SetSignedValueLe (int64_t value, bool valid, uint64_t array_index)
	Support function that sets signed little endian values.

void	SetSignedValueBe (int64_t value, bool valid, uint64_t array_index)
	Support function that sets signed big endian values.

void	SetFloatValueLe (double value, bool valid, uint64_t array_index)
	Support function that sets float little endian values.

void	SetFloatValueBe (double value, bool valid, uint64_t array_index)
	Support function that sets float big endian values.

virtual void	SetTextValue (const std::string &value, bool valid)
	Support function that sets text values.

virtual void	SetByteArray (const std::vector< uint8_t > &value, bool valid)
	Support function that sets array values.

Member Function Documentation

◆ AddAttachmentReference()

virtual void mdf::IChannel::AddAttachmentReference ( const IAttachment * attachment )

virtual

Adds an attachment reference to the channel. This function is used when writing MDF 4 files.

Note that this function must be called before the any measurement is started and the attachment must also be added before measurement is started. This is a design flaw in the MDF standard why for example video attachments cannot be embedded as they are created after the CN block is written. DBC files will work as they already exist when the measurement is started.

Parameters

attachment Pointer to the attachment.

◆ ArraySize() [1/2]

uint64_t mdf::IChannel::ArraySize ( ) const

inlinenodiscard

Returns: Returns 1 for normal channel and array size for array channels

◆ ArraySize() [2/2]

void mdf::IChannel::ArraySize ( uint64_t array_size )

inline

This is an internal function that speed up the reads of values.

Parameters

array_size Size of the array.

◆ BitCount()

virtual void mdf::IChannel::BitCount ( uint32_t bits )

pure virtual

This function shall only be used for MDF4 files and for composition channels. Composition channels reference their parent byte array channel. For ordinary channels, the bit size and offset is calculated when the measurement is initialized.

Parameters

bits	Number of bits.

◆ BitOffset()

virtual void mdf::IChannel::BitOffset ( uint16_t bits )

pure virtual

This function shall only be used for MDF4 files and for composition channels. Composition channels reference their parent byte array channel. For ordinary channels, the bit size and offset is calculated when the measurement is initialized.

Parameters

bits	Offset to data.

◆ ByteOffset()

virtual void mdf::IChannel::ByteOffset ( uint32_t bytes )

pure virtual

This function shall only be used for MDF4 files and for composition channels. Composition channels reference their parent byte array channel. For ordinary channels, the bit size and offset is calculated when the measurement is initialized.

Parameters

bytes Offset to data.

◆ CalculateMasterTime() [1/2]

bool mdf::IChannel::CalculateMasterTime ( ) const

inlinenodiscard

Returns: True means that the master channel is calculated.

◆ CalculateMasterTime() [2/2]

void mdf::IChannel::CalculateMasterTime ( bool calculate_master )

inline

If the channel is a master channel and the channel sync type is time, this option defines if its channel value should be calculated from the MdfWriter sample queue absolute time. Not used for reader applications.

Default is the option set to true i.e. the channel value will be calculated from the absolute time in the writers sample queue. If it set to false, the user is responsible to set the channels value.

Parameters

calculate_master If set tp false, the user must set the channel value.

◆ ChannelArray()

virtual IChannelArray * mdf::IChannel::ChannelArray ( ) const

nodiscardvirtual

This function is used to get the channel array if any exist on this channel. Channel arrays require quite different handling and treatment of the channel. Normally the channel only handle one value but if the channel have a composite channel array (CA), the channel is now storing an array of values. The array may be multidimensional.

The function is alo used to indicate if the channel is of array type. Channel arrays only exist in MDF 4 files.

Returns: Pointer to the CA block or nullptr.

◆ ChannelCompositions()

virtual std::vector< IChannel * > mdf::IChannel::ChannelCompositions ( )

nodiscardpure virtual

Creates a composition channel block. Composition channels reference their bit length and bit offset to its parent channel. In reality, the parent channel must be a byte array.

◆ ChannelGroup()

virtual const IChannelGroup * mdf::IChannel::ChannelGroup ( ) const

pure virtual

Support function that returns the channel group that this channel belongs to. Note that the function may return nullptr if the channel have not been assigned a group.

Returns: Pointer to the channel group.

◆ CreateChannelArray()

virtual IChannelArray * mdf::IChannel::CreateChannelArray ( )

nodiscardvirtual

Creates or returns the existing channel array (CA) block. The CA blocks are mixed with the composition (CN) blocks, see CreateChannelComposition

Returns: A new or existing channel array (CA) block.

◆ CreateChannelComposition() [1/2]

virtual IChannel * mdf::IChannel::CreateChannelComposition ( )

nodiscardpure virtual

Creates a composition channel block. Composition channels reference their bit length and bit offset to its parent channel. In reality, the parent channel must be a byte array.

◆ CreateChannelComposition() [2/2]

virtual IChannel * mdf::IChannel::CreateChannelComposition ( const std::string_view & name )

nodiscardvirtual

Creates a composition channel block. Composition channels reference their bit length and bit offset to its parent channel. In reality, the parent channel must be a byte array.

◆ GetChannelValue()

template<typename T >

bool mdf::IChannel::GetChannelValue	(	const std::vector< uint8_t > &	record_buffer,
		T &	dest,
		uint64_t	array_index = 0 ) const

Internally used function that parse out the channel value from a sample record.

Template Parameters

T	Type of value to return

Parameters

record_buffer	Data record from a data block.
dest	Destination value.
array_index	Array offset used by channel arrays.

Returns: True if the value is valid.

◆ GetTextValue()

virtual bool mdf::IChannel::GetTextValue	(	const std::vector< uint8_t > &	record_buffer,
		std::string &	dest ) const

virtual

Parameters

record_buffer	The sample record buffer.
dest	Destination value.

Returns: True if the value is valid.

◆ GetUnsignedValue()

bool mdf::IChannel::GetUnsignedValue	(	const std::vector< uint8_t > &	record_buffer,
		uint64_t &	dest,
		uint64_t	array_index = 0 ) const

Parameters

record_buffer	The sample record buffer.
dest	Destination value.
array_index	Array offset used by channel arrays.

Returns: True if the value is valid.

◆ GetVirtualSample() [1/2]

template<typename V = std::string>

static bool mdf::IChannel::GetVirtualSample	(	uint64_t	sample,
		std::string &	value )

inlinestatic

Template Parameters

V	Type of value to return.

Parameters

sample	Sample index.
value	Reference to return string value.

Returns: True if the value is valid.

◆ GetVirtualSample() [2/2]

template<typename V >

static bool mdf::IChannel::GetVirtualSample	(	uint64_t	sample,
		V &	value )

inlinestatic

Virtual samples are calculated from the sample index instead of the channel value as normally.

Template Parameters

V	Type of value to return.

Parameters

sample	Sample index.
value	Reference to return value.

Returns: True if the value is valid.

◆ RecordId()

uint64_t mdf::IChannel::RecordId ( ) const

Convenient function that returns the record ID for the channel group which the channel belongs to.

Returns: Returns the record ID.

◆ SetChannelValue()

template<typename T >

void mdf::IChannel::SetChannelValue	(	const T &	value,
		bool	valid = true,
		uint64_t	array_index = 0 )

The function is used when writing MDF files. The function take an unscaled channel value and insert it into the channel groups record buffer. This record buffer is later saved to the MDF file by calling the IChannelGroup::SaveSample() function.

If the channel is a channel array, the array index argument needs to be set.

Template Parameters

T	Type of value.

Parameters

value	The value to transfer.
valid	True if the value is valid.
array_index	Channel array index.

◆ SetChannelValues()

template<typename T >

void mdf::IChannel::SetChannelValues ( const std::vector< T > & values )

The function shall be used to simplify setting channel array values. The function assumes that all values are valid. If values may be invalid, the SetChannelValue() function should be used.

Template Parameters

T	Type of values

Parameters

values 1-Dimensional list of array values.

◆ SetTimestamp()

void mdf::IChannel::SetTimestamp	(	double	timestamp,
		std::vector< uint8_t > &	record_buffer ) const

The function update the record buffer with a new time. This function is for internal use and its purpose is to change the timestamps in the sample cache queue, from absolute time to relative time. This happens when the MdfWriter::StartMeasurement() function is called

Parameters

timestamp	Relative time in seconds.
record_buffer	The record buffer to update.

◆ Unit() [1/2]

virtual std::string mdf::IChannel::Unit ( ) const

nodiscardpure virtual

The unit describes the engineering/scaled value not the channel value itself. This might be considered as a design flaw as the CC block also have a unit.

This function returns the channels unit first and if it doesn't exist, returns the CC blocks unit.

For MIME streams this unit is actually the type of stream content.

Returns: Unit or MIME content string. Returns the unit

◆ Unit() [2/2]

virtual void mdf::IChannel::Unit ( const std::string & unit )

pure virtual

The function sets the unit string for the channel. If the channel data type is a MIME sample or a stream, the unit is a mime content type string.

Note that this unit belongs to the value after scaling (CC) i.e. engineering value.

◆ VlsdRecordId() [1/2]

uint64_t mdf::IChannel::VlsdRecordId ( ) const

inlinenodiscard

This function is mainly used internally and solves the problem if the channel is a variable length and its value is stored in another (VLSD) channel group (CG). This property is set to the record ID of the VLSD block.

Returns: Record id of the block storing the data bytes.

◆ VlsdRecordId() [2/2]

void mdf::IChannel::VlsdRecordId ( uint64_t record_id ) const

inline

This function is mainly used internally and solves the problem if the channel is a variable length and its value is stored in another (VLSD) channel group (CG). This property is set to the record ID of the VLSD block.

Parameters

record_id Record id of the block storing the data bytes.

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

include/mdf/ichannel.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Function Documentation

◆ AddAttachmentReference()

◆ ArraySize() [1/2]

◆ ArraySize() [2/2]

◆ BitCount()

◆ BitOffset()

◆ ByteOffset()

◆ CalculateMasterTime() [1/2]

◆ CalculateMasterTime() [2/2]

◆ ChannelArray()

◆ ChannelCompositions()

◆ ChannelGroup()

◆ CreateChannelArray()

◆ CreateChannelComposition() [1/2]

◆ CreateChannelComposition() [2/2]

◆ GetChannelValue()

◆ GetTextValue()

◆ GetUnsignedValue()

◆ GetVirtualSample() [1/2]

◆ GetVirtualSample() [2/2]

◆ RecordId()

◆ SetChannelValue()

◆ SetChannelValues()

◆ SetTimestamp()

◆ Unit() [1/2]

◆ Unit() [2/2]

◆ VlsdRecordId() [1/2]

◆ VlsdRecordId() [2/2]