Provides useful services like timers, data type conversions, path and file manipulation, etc. More...

Inheritance diagram for MUtilities:

Public Member Functions
	MUtilities ()
	Construct utilities object. More...

virtual	~MUtilities ()
	Destroy utilities object.

Public Member Functions inherited from MTimer
	MTimer (TimerIntegerType expireInMilliseconds=0)
	Construct the timer and set its event to the given number of milliseconds. More...

	MTimer (const MTimer &other)
	Construct a copy of timer with the same timer event time.

virtual	~MTimer ()
	Destroy the timer.

MTimer &	operator= (const MTimer &other)
	Assignment operator that makes the timer moment of the timer match the other timer start.

bool	IsExpired () const
	Whether the timer moment has happened. More...

void	ResetTimer ()
	Sets the timer event into the exact moment this call is made. More...

virtual unsigned	GetEmbeddedSizeof () const
	Timer is an embedded object type, therefore return its size in bytes. More...

bool	operator== (TimerIntegerType duration) const

bool	operator!= (TimerIntegerType duration) const

bool	operator>= (TimerIntegerType duration) const

bool	operator<= (TimerIntegerType duration) const

bool	operator> (TimerIntegerType duration) const

bool	operator< (TimerIntegerType duration) const

int	GetTimer () const

void	SetTimer (int)

Mint64	GetTimer64 () const

void	SetTimer64 (Mint64)

Public Member Functions inherited from MObject
virtual	~MObject ()
	Object destructor.

virtual const MClass *	GetClass () const =0
	Get the final class of the object. More...

bool	IsEmbeddedObject () const
	Tell if the object is of embedded kind. More...

SHOW_INTERNAL MVariant	Call (const MStdString &name, const MVariant &params)
	Call the object service with parameters, given as variant. More...

MVariant	Call0 (const MStdString &name)
	Call the object service with no parameters. More...

MVariant	Call1 (const MStdString &name, const MVariant &p1)
	Call the object service with one parameter. More...

MVariant	Call2 (const MStdString &name, const MVariant &p1, const MVariant &p2)
	Call the object service with two parameter. More...

MVariant	Call3 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3)
	Call the object service with three parameter. More...

MVariant	Call4 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4)
	Call the object service with four parameter. More...

MVariant	Call5 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5)
	Call the object service with five parameter. More...

MVariant	Call6 (const MStdString &name, const MVariant &p1, const MVariant &p2, const MVariant &p3, const MVariant &p4, const MVariant &p5, const MVariant &p6)
	Call the object service with six parameter. More...

virtual MVariant	CallV (const MStdString &name, const MVariant::VariantVector &params)
	Call the object service with parameters, given as variant vector. More...

virtual bool	IsPropertyPresent (const MStdString &name) const
	Tell if the property with the given name exists.

virtual bool	IsServicePresent (const MStdString &name) const
	Tell if the service with the given name exists.

virtual MVariant	GetProperty (const MStdString &name) const
	Get the property value using name of the property. More...

virtual void	SetProperty (const MStdString &name, const MVariant &value)
	Set the property using name of the property, and value. More...

virtual MStdStringVector	GetAllPropertyNames () const
	Return the list of publicly available properties, persistent or not. More...

virtual MStdStringVector	GetAllPersistentPropertyNames () const
	Return the list of persistent properties. More...

virtual void	SetPersistentPropertiesToDefault ()
	Set the persistent properties of the object to their default values. More...

virtual MVariant	GetPersistentPropertyDefaultValue (const MStdString &name) const
	Get the default value of persistent property with the name given. More...

virtual void	SetPersistentPropertyToDefault (const MStdString &name)
	Set the persistent property with the name given to default value. More...

virtual const char *	GetType () const
	Get the name of the type for the object (could be the same as class name).

virtual void	SetType (const MStdString &)
	Intentionally, it will set the name of the type for the object, but the service will not allow setting the name to anything other than the current name. More...

virtual void	Validate ()
	Validate internal structures of the object. More...

Static Public Member Functions
static MStdString	GetLocalHostName ()
	Returns the host name for the local machine, identification for the computer. More...

static void	ToBCDBuffer (unsigned intValue, char *buffer, unsigned size, bool littleEndian=false)
	Converts the number given as unsigned integer into a BCD buffer. More...

static void	ToBCDBuffer (double value, char *buffer, unsigned size, bool littleEndian=false)
	Converts the number given as double into a BCD buffer. More...

static double	FromBCDBuffer (const char *data, unsigned size, bool littleEndian=false)
	Convert the Binary Coded Decimal number given as data buffer and its size to double. More...

static double	FromBCD (const MByteString &bytes, bool littleEndian=false)
	Convert BCD number given as byte string to double. More...

static MByteString	ToBCD (double value, unsigned size=0u, bool littleEndian=false)
	Convert a positive double to a BCD coded byte string. More...

static unsigned	UnsignedFromUINT (const MByteString &bytes, bool littleEndian)
	Converts given byte string into an unsigned. More...

static MVariant	FromUINT (const MByteString &bytes, bool littleEndian)
	Converts given byte string into the number it represents according to rules for UINT fields. More...

static MByteString	ToUINT (const MVariant &value, unsigned size, bool littleEndian)
	Convert a positive number to byte string representation of this number as UINT. More...

static MVariant	FromINT (const MByteString &bytes, bool littleEndian)
	Converts given byte string into the number it represents according to rules for INT fields. More...

static MByteString	ToINT (const MVariant &value, unsigned size, bool littleEndian)
	Convert an integer number to byte string representation of this number as INT. More...

static double	FromDSPFloatBuffer (const char *buffer, unsigned size)
	Convert DSP specific floating point number given as data buffer to double. More...

static double	FromDSPFloat (const MByteString &buffer)
	Convert DSP specific floating point number given as byte string to double. More...

static double	FromDSPIntBuffer (const char *buffer, unsigned size)
	Convert DSP specific "integer" number given as data buffer to double. More...

static double	FromDSPInt (const MByteString &buffer)
	Convert DSP specific "integer" number given as byte string to double. More...

static double	FromINSTRBuffer (const char *data, unsigned size)
	Converts INSTR value stored in the buffer to double. More...

static void	ToINSTRBuffer (double value, char *data, unsigned size)
	Converts double value to given buffer. More...

static double	FromINSTR (const MByteString &buffer)
	Converts INSTR value given as byte string to double. More...

static MByteString	ToINSTR (double value)
	Converts double value to the byte string.

static void	ToDSPFloatBuffer (double value, char *buffer, unsigned size)
	Convert a DSP float double to a byte string. More...

static MByteString	ToDSPFloat (double value, unsigned size)
	Convert a DSP float double to a byte string. More...

static void	ToDSPIntBuffer (double value, char *buffer, unsigned size)
	Convert a DSP_INT double to a byte buffer. More...

static MByteString	ToDSPInt (double value, unsigned size)
	Convert a DSP float double to a byte string. More...

static MStdString	FromRAD40Buffer (const char *data, int byteLen)
	Convert RAD40 buffer given as data and length to a standard string which it represents. More...

static MStdString	FromRAD40 (const MByteString &data)
	Convert RAD40 buffer given as byte string to a standard string which it represents. More...

static void	ToRAD40Buffer (const MStdString &str, char *rad, unsigned radSize)
	Convert the given string of characters to RAD40 buffer. More...

static MByteString	ToRAD40 (const MStdString &str, unsigned radSize)
	Convert the given string of characters to RAD40 number returned as byte string. More...

static MStdString	GetPathExtension (const MStdString &path)
	Get the extension from the path specified, if the extension is present. More...

static MStdString	GetPathFileName (const MStdString &path)
	Get the file name from the path specified, if the file name is present. More...

static MStdString	GetPathFileNameAndExtension (const MStdString &path)
	Get the file name and extension from the path specified, if the file name and extension is present. More...

static MStdString	GetPathDirectory (const MStdString &path)
	Get the directory path from the path specified, if the directory path is present. More...

static MStdString	GetPath (const MStdString &dir, const MStdString &name, const MStdString &extension)
	Construct the path from the directory, file name and extension.

static MStdString	MergePaths (const MStdString &fullDirOrName, const MStdString &dirOrName)
	Merge two paths together. More...

static bool	IsPathFull (const MStdString &path)
	Tells if a given path is a full path. More...

static bool	IsPathDirectory (const MStdString &path)
	Return true if a given path is present, and it is a directory. More...

static bool	IsPathExisting (const MStdString &path)
	Tell if a given path is an existing file of any sort. More...

static MStdString	GetFullPath (const MStdString &fileName)
	Get the full path of a file. More...

static void	CopyFile (const MStdString &source, const MStdString &destination)
	Copy a file to a destination file. More...

static void	DeleteFile (const MStdString &path)
	Delete a file with the given name. More...

static void	MoveFile (const MStdString &source, const MStdString &destination)
	Move a file to a new location. More...

static void	CreateDirectory (const MStdString &path)
	Create a directory with the given name. More...

static void	EnsureDirectoryExistsForFile (const MStdString &path)
	Ensures the necessary directory tree is created so the file with the given path can be created. More...

static MStdStringVector	FindFiles (const MStdString &directory, const MStdString &fileMask)
	Find all files under the specified directory using the given mask. More...

static MStdStringVector	FindDirectories (const MStdString &directory, const MStdString &directoryMask)
	Find all subdirectories under the specified directory using the given mask. More...

static MStdString	GetModulePath ()
	Return the path to this module, one which is currently running.

static MStdString	GetInstallationPath ()
	Return the path to installation directory. More...

static char	NumberToHexChar (unsigned n)
	Return a single hexadecimal character that represents the given unsigned number. More...

static Muint8	NumberToHexByte (unsigned n)
	Return a single hexadecimal byte that represents the given unsigned number. More...

static unsigned	HexCharToNumber (char c)
	Return a number for a single hexadecimal character given. More...

static unsigned	HexByteToNumber (Muint8 c)
	Return a number for a single hexadecimal byte given. More...

static MByteString	HexToBytes (const MByteString &hexString)
	Convert hexadecimal byte string into binary byte string. More...

static MByteString	HexStringToBytes (const MStdString &hexString)
	Convert hexadecimal string into binary byte string. More...

static MByteString	HexBufferToBytes (const char *buff, unsigned length)
	Convert hexadecimal string into byte string. More...

static MStdString	BytesToNumericString (const MByteString &bytes, const MStdString &format=MVariant::s_emptyString)
	Convert the given byte string into numeric string representation. More...

static MStdString	BufferToNumericString (const char buff, unsigned length, const char format=NULL)
	Convert the given bytes array and length into numeric string representation. More...

static MByteString	NumericStringToBytes (const MStdString &numericString)
	Convert numeric string into binary byte string. More...

static MByteString	NumericBufferToBytes (const char *buff, unsigned length)
	Convert numeric byte buffer into byte string. More...

static MStdString	ToMDLConstant (const MVariant &)
	Convert the variant given to a constant with a proper MDL syntax. More...

static MStdString	ToRelaxedMDLConstant (const MVariant &)
	Convert the variant given to a constant with a relaxed MDL syntax. More...

static MVariant	FromMDLConstant (const MStdString &)
	Convert the given string into a variant with a proper MDL syntax. More...

static MVersion &	GetVersion ()
	Get the version of the MeteringSDK library. More...

static MVersion &	GetProductVersion ()
	Get the version of the product that is the client of this library. More...

static MStdString	GetProductName ()
	Return product name, as available at compile time. More...

static MStdString	GetOperatingSystemName ()
	Return the operating system name. More...

static MVersion &	GetOperatingSystemVersion ()
	Return the operating system version. More...

static MStdString	GetTempDirectory ()
	This function retrieves the path of the directory designated for temporary files.

static MStdString	GetHomeDirectory ()
	This function retrieves the user's home directory.

static MStdString	GetEnv (const MStdString &variable)
	This function searches the environment list to find the environment variable, and returns a corresponding value string.

static void	SetEnv (const MStdString &variable, const MStdString &value)
	This function changes or adds an environment variable.

static MStdString	ExpandEnvVars (const MStdString &source)
	Replace environment variables with their values. More...

static MStdString	MakeTempFileName (const MStdString &prefix)
	This function generates a unique temporary filename from template 'prefix', creates the file, and returns a file pathname.

static MStdString	MakeTempDirectoryName (const MStdString &prefix)
	This function generates a uniquely named temporary directory from templates 'prefix', creates the directory and return a directory pathname.

static int	GetNumberOfProcessors ()
	Get the number of processors or simultaneously handled threads. More...

static int	GetNumberOfAddressBits ()
	Get the number of address bits for target platform. More...

static MStdString	Base64Encode (const MByteString &data)
	Encode binary data given as Base 64. More...

static MByteString	Base64Decode (const MStdString &text)
	Decode Base 64 string into binary data. More...


static MStdString	GetCurrentPath ()

static void	SetCurrentPath (const MStdString &path)


static MByteString	BytesToHex (const MByteString &bytes, const MVariant &format=true)

static MStdString	BytesToHexString (const MByteString &bytes, const MVariant &format=true)


static MByteString	BufferToHex (const char *bytes, unsigned length, bool useBlanks=true)

static MByteString	BufferToHexString (const char *bytes, unsigned length, bool useBlanks=true)


static MByteString	BufferToHex (const char *bytes, unsigned length, const MByteString &format)

static MStdString	BufferToHexString (const char *bytes, unsigned length, const MByteString &format)

Static Public Member Functions inherited from MTimer
static void	Sleep (unsigned milliseconds)
	Sleep for the given number of milliseconds. More...

static TimerIntegerType	SecondsToTimerMilliseconds (TimerIntegerType seconds)
	Convert seconds into milliseconds, respecting the internal representation of the timer. More...

static unsigned	GetTickCount ()

static Muint64	GetTickCount64 ()

static int	SecondsToMilliseconds (int seconds)

Static Public Member Functions inherited from MObject
static const MClass *	GetStaticClass ()
	Get the declared class of this particular object. More...

static bool	IsClassPresent (const MStdString &name)
	Tells if the given class name is available. More...

Additional Inherited Members
Public Types inherited from MTimer
typedef Mint64	TimerIntegerType

typedef Muint64	TimerUnsignedType

Static Public Attributes inherited from MObject
static const MClass	s_class
	Class of MObject.

Protected Member Functions inherited from MObject
	MObject ()
	Object constructor, protected as the class is abstract.

void	DoSetPersistentPropertiesToDefault (const MClass *staticClass)
	Set the persistent properties to their default values for one object provided the class for that object. More...

Detailed Description

Provides useful services like timers, data type conversions, path and file manipulation, etc.

The MUtilities class inherits from MTimer for compatibility reasons.

MeteringSDK extends regular file path syntax:

On every operating system it is possible to use both forward slash and back slash as file name separators. It is recommended though to always use a regular slash /.

Constructor & Destructor Documentation

MUtilities::MUtilities ( )

Construct utilities object.

There is little reason to create the utilities object, and all the other methods of utilities class are static.

Member Function Documentation

static MByteString MUtilities::Base64Decode ( const MStdString & text )

static

Decode Base 64 string into binary data.

This method for decoding Base 64 text into binary. The correspondent standard for this encoding is RFC-4648, http://tools.ietf.org/html/rfc4648.

Parameters

text	Text encoded with Base 64.

Returns: Result binary data.

See also: Base64Encode

static MStdString MUtilities::Base64Encode ( const MByteString & data )

static

Encode binary data given as Base 64.

This method for encoding binary data into text that can have only a very limited set of ASCII characters that can be safely transferred through any media. The correspondent standard for this encoding is RFC-4648, http://tools.ietf.org/html/rfc4648.

Parameters

data	Binary data to encode.

Returns: Result text data encoded with Base 64.

See also: Base64Decode

static MByteString MUtilities::BufferToHex	(	const char *	bytes,
		unsigned	length,
		bool	useBlanks = `true`
	)

static

Convert a buffer given as pointer and length into hexadecimal string.

The function behaves in the same way as BytesToHex except it takes character pointer and length as parameters.

Parameters

bytes	Pointer to buffer.
length	Length of the buffer.
useBlanks	Whether to separate bytes with blanks like '00 00 00' or have them like '000000'.

Returns: Result string.

static MByteString MUtilities::BufferToHex	(	const char *	bytes,
		unsigned	length,
		const MByteString &	format
	)

static

Convert a buffer given as pointer and length into hexadecimal string.

The function behaves in the same way as BytesToHex except it takes character pointer and length as parameters.

Parameters

bytes	Pointer to buffer.
length	Length of the buffer.
format	Format, as described in BytesToHex.

Returns: Result string.

static MByteString MUtilities::BufferToHexString	(	const char *	bytes,
		unsigned	length,
		bool	useBlanks = `true`
	)

inlinestatic

Convert a buffer given as pointer and length into hexadecimal string.

The function behaves in the same way as BytesToHex except it takes character pointer and length as parameters.

Parameters

bytes	Pointer to buffer.
length	Length of the buffer.
useBlanks	Whether to separate bytes with blanks like '00 00 00' or have them like '000000'.

Returns: Result string.

static MStdString MUtilities::BufferToHexString	(	const char *	bytes,
		unsigned	length,
		const MByteString &	format
	)

inlinestatic

Convert a buffer given as pointer and length into hexadecimal string.

The function behaves in the same way as BytesToHex except it takes character pointer and length as parameters.

Parameters

bytes	Pointer to buffer.
length	Length of the buffer.
format	Format, as described in BytesToHex.

Returns: Result string.

static MStdString MUtilities::BufferToNumericString	(	const char *	buff,
		unsigned	length,
		const char *	format = `NULL`
	)

static

Convert the given bytes array and length into numeric string representation.

Parameters

buff	Pointer to the buffer.
length	Length of the buffer.
format	Conversion format, see the description.

Returns: Result byte string.

See also: BytesToNumericString Equivalent of this call that takes string objects.

static MByteString MUtilities::BytesToHex	(	const MByteString &	bytes,
		const MVariant &	format = `true`
	)

static

Convert the given byte string into hexadecimal string representation.

Parameter 'format' can be either a string, or anything convertible to a boolean. With boolean format, TRUE means that the bytes will be separated with blanks.

String format specifies a conversion template, which is interpreted as follows:

Each 'X' or 'x' character is replaced with a single hexadecimal digit.
Any white space character is copied to the output string.
Any other characters are illegal.

Format string can be of any length. If it is shorter than the available input, it is cyclically repeated until the input is exhausted. If it is longer than the available input, the rest of format string is silently ignored.

Example of format string: "XXXX XXXX "; produces output like: "1234 5678 9ABC DEF0" Another example: "xx "; produces: "12 34 56 78 9a bc de f0" The following formats are illegal: "X X", "Xx"

Precondition: Format string must conform to the above mentioned rules.

static MStdString MUtilities::BytesToHexString	(	const MByteString &	bytes,
		const MVariant &	format = `true`
	)

static

Convert the given byte string into hexadecimal string representation.

Parameter 'format' can be either a string, or anything convertible to a boolean. With boolean format, TRUE means that the bytes will be separated with blanks.

String format specifies a conversion template, which is interpreted as follows:

Each 'X' or 'x' character is replaced with a single hexadecimal digit.
Any white space character is copied to the output string.
Any other characters are illegal.

Format string can be of any length. If it is shorter than the available input, it is cyclically repeated until the input is exhausted. If it is longer than the available input, the rest of format string is silently ignored.

Example of format string: "XXXX XXXX "; produces output like: "1234 5678 9ABC DEF0" Another example: "xx "; produces: "12 34 56 78 9a bc de f0" The following formats are illegal: "X X", "Xx"

Precondition: Format string must conform to the above mentioned rules.

static MStdString MUtilities::BytesToNumericString	(	const MByteString &	bytes,
		const MStdString &	format = `MVariant::s_emptyString`
	)

static

Convert the given byte string into numeric string representation.

String format specifies a conversion template, which is interpreted as follows:

Empty format string is equivalent to format "b.", bytes separated with '.', as in the IP address.
Each 'B' or 'b' character is replaced with a decimal value of the byte. These cannot appear in sequence such as "bb", "BB" or "bB" as there has to be a separator in between.
Non ASCII codes (above 0x7F), and letters or digits are not permitted in the format.
Any other characters, such as punctuation or space, are copied to the output.

At present only decimal representation of single bytes is supported, while in the future the other formats for words and double words can be added. Hexadecimal, binary or octal numbers can also be considered.

Format string can be of any length. If it is shorter than the available input, it is cyclically repeated until the input is exhausted. If it is longer than the available input, the rest of format string is silently ignored.

Example of format string: "[b:b]"; produces output like: "[123:255][0:0]" Another example: "b."; produces: "12.34.56.78.91.234" An example format for an OBIS code with class number is "b.b.b.b.b.b b-b"

Parameters

bytes	Raw bytes to convert.
format	Conversion format, see the description.

Returns: Result string such as "1.0.64.0.0.255".

static void MUtilities::CopyFile	(	const MStdString &	source,
		const MStdString &	destination
	)

static

Copy a file to a destination file.

Parameters

source	Source file, either relative or absolute path. For more information, refer to MeteringSDK path syntax. File should exist, or an exception is thrown.
destination	Path where to copy the source. File name should be valid, and it should be possible to create files in the destination, or an exception is thrown. This way, MeteringSDK path syntax is not valid for this argument.

static void MUtilities::CreateDirectory ( const MStdString & path )

static

Create a directory with the given name.

Multilevel creation is supported, so if a deep path of directories has to be created, it will be.

Parameters

path	Path for the new directory. If this is a relative path, current process directory is used. It shall be possible to create directory with such path, or an exception is thrown.

static void MUtilities::DeleteFile ( const MStdString & path )

static

Delete a file with the given name.

Parameters

path	Path to a file or directory. File or directory with such path should exist, and it should be possible to delete it.

static void MUtilities::EnsureDirectoryExistsForFile ( const MStdString & path )

static

Ensures the necessary directory tree is created so the file with the given path can be created.

Multilevel creation is supported, so if a deep path of directories has to be created, it will be.

Parameters

path	Full path to a file. It shall be possible to create a directory for such file, or an exception is thrown.

static MStdString MUtilities::ExpandEnvVars ( const MStdString & source )

static

Replace environment variables with their values.

The format is $VARNAME or ${VARNAME} or on Posix and VARNAME% on Windows, where VARNAME contains alphanumeric characters and '_' only.

static MStdStringVector MUtilities::FindDirectories	(	const MStdString &	directory,
		const MStdString &	directoryMask
	)

static

Find all subdirectories under the specified directory using the given mask.

Only directories are returned. To get files use FindFiles. Files that start with a period, such as ".." or ".svn", are not returned.

Parameters

directory	Directory where to search for subdirectories.
directoryMask	Directory file name mask to match.

static MStdStringVector MUtilities::FindFiles	(	const MStdString &	directory,
		const MStdString &	fileMask
	)

static

Find all files under the specified directory using the given mask.

Only files are returned. To get directories use FindDirectories. Files that start with a period, such as ".myconfig", are not returned.

Parameters

directory	Directory to search for files.
fileMask	File mask to match.

static double MUtilities::FromBCD	(	const MByteString &	bytes,
		bool	littleEndian = `false`
	)

static

Convert BCD number given as byte string to double.

Binary coded decimal is a way of representing decimal numbers so that each byte has a pair of numbers, each in range 0 to 9. A BCD with hex representation x"00123456" represents a number 123456. No special codes allowed in the BCD, only 0 .. 9.

Parameters

bytes	Bytes of the BCD number.
littleEndian	Whether the BCD number is little endian, which is the default. Little endian BCD number is by far the most usual case.

Returns: The result number.

Precondition: The given BCD shall be a proper BCD number consisting of an even number of digits. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromBCDBuffer	(	const char *	data,
		unsigned	size,
		bool	littleEndian = `false`
	)

static

Convert the Binary Coded Decimal number given as data buffer and its size to double.

Binary coded decimal is a way of representing decimal numbers so that each byte has a pair of numbers, each in range 0 to 9. A BCD with hex representation x"00123456" represents a number 123456. No special codes allowed in the BCD, only 0 .. 9.

Parameters

data	Pointer to the beginning of BCD number in memory.
size	Size of the data in memory.
littleEndian	Whether the BCD number is little endian, which is the default. Little endian BCD number is by far the most usual case.

Precondition: The given BCD shall be a proper BCD number consisting of an even number of digits. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromDSPFloat ( const MByteString & buffer )

static

Convert DSP specific floating point number given as byte string to double.

Precondition: The given DSP_FLOAT shall be a proper DSP float number as defined by the hardware specifications. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromDSPFloatBuffer	(	const char *	buffer,
		unsigned	size
	)

static

Convert DSP specific floating point number given as data buffer to double.

The size is in bytes, either 3 or 4.

Precondition: The given DSP_FLOAT shall be a proper DSP float number as defined by the hardware specifications. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromDSPInt ( const MByteString & buffer )

static

Convert DSP specific "integer" number given as byte string to double.

The length is in bytes, the DSP integer is really a double in range -1.0 .. 1.0.

Precondition: The given DSP_INT shall be a proper DSP integer number as defined by the hardware specifications. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromDSPIntBuffer	(	const char *	buffer,
		unsigned	size
	)

static

Convert DSP specific "integer" number given as data buffer to double.

The length is in bytes, the DSP integer is really a double in range -1.0 inclusive to 1.0 not inclusive.

Precondition: The given DSP_INT shall be a proper DSP integer number as defined by the hardware specifications. Otherwise an exception is thrown. The double overflow is not watched.

static double MUtilities::FromINSTR ( const MByteString & buffer )

static

Converts INSTR value given as byte string to double.

Precondition: Length of the string must be equal to 2.

static double MUtilities::FromINSTRBuffer	(	const char *	data,
		unsigned	size
	)

static

Converts INSTR value stored in the buffer to double.

Precondition: Size must be equal to 2.

static MVariant MUtilities::FromINT	(	const MByteString &	bytes,
		bool	littleEndian
	)

static

Converts given byte string into the number it represents according to rules for INT fields.

Parameters

bytes	Byte string to convert, size is in range 1 to 8 bytes.
littleEndian	Whether the given bytes are of little endian format, big endian otherwise.

Returns: MVariant of type INT (int) or double, if the bytes given are bigger than 4-byte size.

static MVariant MUtilities::FromMDLConstant ( const MStdString & )

static

Convert the given string into a variant with a proper MDL syntax.

Precondition: The string shall represent an MDL constant, otherwise an exception will be raised.

static MStdString MUtilities::FromRAD40 ( const MByteString & data )

static

Convert RAD40 buffer given as byte string to a standard string which it represents.

It is not an error if the byte length is not an even number as the last odd byte will be truncated.

Precondition: The given buffer shall have a valid RAD40 representation, or a bad character is reported.

static MStdString MUtilities::FromRAD40Buffer	(	const char *	data,
		int	byteLen
	)

static

Convert RAD40 buffer given as data and length to a standard string which it represents.

It is not an error if the byte length is not an even number as the last odd byte will be truncated.

Precondition: The given buffer shall have a valid RAD40 representation, or a bad character is reported.

static MVariant MUtilities::FromUINT	(	const MByteString &	bytes,
		bool	littleEndian
	)

static

Converts given byte string into the number it represents according to rules for UINT fields.

Parameters

bytes	Byte string to convert, size is in range 1 to 8 bytes.
littleEndian	Whether the given bytes are of little endian format, big endian otherwise.

Returns: MVariant of type UINT (unsigned) or double, if the bytes given are bigger than 4-byte size.

static MStdString MUtilities::GetCurrentPath ( )

static

Current application path.

Most often, the current path is a global property of the process, as determined by OS. Some operating systems such as Windows CE do not have per process current path, and for such cases there is a special global variable to emulate this functionality. Property manipulation can result in a number of system errors.

static MStdString MUtilities::GetFullPath ( const MStdString & fileName )

static

Get the full path of a file.

Precondition: A file should exist, otherwise the result file name will be empty.

static MStdString MUtilities::GetInstallationPath ( )

static

Return the path to installation directory.

This call does a certain amount of guessing, and might not return the correct data. In a simplest case it is equivalent to GetModulePath. For products that store their executables under "bin" subdirectory, the directory above "bin" is returned. Further, if products define registry entry "PATH", its value will be taken.

static MStdString MUtilities::GetLocalHostName ( )

static

Returns the host name for the local machine, identification for the computer.

Either the sockets library is used, if available, or if it is not, "localhost" is returned.

static int MUtilities::GetNumberOfAddressBits ( )

static

Get the number of address bits for target platform.

Returns: int, a positive number (currently 32 or 64), amount of bits in address field.

static int MUtilities::GetNumberOfProcessors ( )

static

Get the number of processors or simultaneously handled threads.

This returns the number of simultaneously executing units in the machine. Therefore, this is not necessarily the number of chips or the number of kernels. The chip can have many kernels, and each kernel can support many simultaneously executing threads in hyperthreading architecture. For example, an Intel i7 processor, which is a single chip with four kernels can return eight as its "number of processors."

Returns: int, a positive number, maximum number of simultaneously executing threads in the system.

static MStdString MUtilities::GetOperatingSystemName ( )

static

Return the operating system name.

The name of the operating system is case sensitive, as given in the below list.

Possible values:

"Android"
"NuttX" - Embedded/real-time POSIX compatible operating system
"Linux"
"BSD" - Berkley Software Distribution *NIX
"CMX" - Embedded operating system
"QNX" - Embedded/real-time POSIX compatible operating system
"Windows CE" - Windows CE, Pocket PC, and so on
"Windows" - Any windows, including Windows Server, but not Windows CE

Returns: String that represents the operating system.

static MVersion& MUtilities::GetOperatingSystemVersion ( )

static

Return the operating system version.

The operating system version is determined at runtime. The version can have a different number of fractions, typically two or three, depending on the operating system:

"Android" returns the Android version such as 4.0.2.
"Linux" returns the version of the kernel, such as "3.14.1".
"Windows" and "Windows CE" return the output of GetVersionEx call, two digits.

In case of Windows there is a mapping between the version and the OS release, as defined here:

https://msdn.microsoft.com/ru-ru/library/windows/desktop/ms724833%28v=vs.85%29.aspx

The version value of Windows 8.1 and later will depend on whether the manifest is present. If there is no manifest, these operating systems return the version of "Windows 8". The short version of the page is:

Windows 10 and Windows Server 2016: "10.0" ("6.2" if the manifest is absent)
Windows 8.1 and Windows Server 2012 R2: "6.3" ("6.2" if the manifest is absent)
Windows 8 and Windows Server 2012: "6.2"
Windows 7 and Windows Server 2008 R2: "6.1"
Windows Vista and Windows Server 2008: "6.0"
Windows XP Professional x64 and Windows Server 2003: "5.2"
Windows XP: "5.1"

The returned version object will have IsReadOnly property on, therefore, the changes to this object are protected. The caller can remove such protection by making the version read/write and modify the version, should it be considered a good idea.

Returns: Read-only product version object.

static MStdString MUtilities::GetPathDirectory ( const MStdString & path )

static

Get the directory path from the path specified, if the directory path is present.

The disk letter is returned together with the path, done for OS independence.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

See also: GetPathFileName; GetPathFileNameAndExtension; GetPathExtension

static MStdString MUtilities::GetPathExtension ( const MStdString & path )

static

Get the extension from the path specified, if the extension is present.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

See also: GetPathFileName; GetPathFileNameAndExtension; GetPathDirectory

static MStdString MUtilities::GetPathFileName ( const MStdString & path )

static

Get the file name from the path specified, if the file name is present.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

See also: GetPathFileNameAndExtension; GetPathDirectory; GetPathExtension

static MStdString MUtilities::GetPathFileNameAndExtension ( const MStdString & path )

static

Get the file name and extension from the path specified, if the file name and extension is present.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

See also: GetPathFileName; GetPathDirectory; GetPathExtension

static MStdString MUtilities::GetProductName ( )

static

Return product name, as available at compile time.

This is a reflected equivalent of C++ macro M_PRODUCT_NAME. Product name is defined at compile time, a string.

Returns: String that represents the product name.

static MVersion& MUtilities::GetProductVersion ( )

static

Get the version of the product that is the client of this library.

This is based on C++ macro string M_PRODUCT_VERSION, but returns a MVersion object.

The returned version object will have IsReadOnly property on, therefore, the changes to this object are protected. The caller can remove such protection by making the version read/write and modify the version, should it be considered a good idea.

Returns: Read-only product version object.

static MVersion& MUtilities::GetVersion ( )

static

Get the version of the MeteringSDK library.

MeteringSDK version is the same for all clients, that are built on top of it. By convention, the variable is not constant, however changing the version has no side effect on the software behavior.

static MByteString MUtilities::HexBufferToBytes	(	const char *	buff,
		unsigned	length
	)

static

Convert hexadecimal string into byte string.

Precondition: If the hexadecimal string has some bad characters, the exception thrown contains information about what was bad.

static unsigned MUtilities::HexByteToNumber ( Muint8 c )

inlinestatic

Return a number for a single hexadecimal byte given.

In case the byte given has character value '1', 1 will be returned, in case the byte given has character value 'A', 10 will be returned, and so on.

The service works only with ASCII subset.

Precondition: If the number is not a hex byte, an error is thrown.

static unsigned MUtilities::HexCharToNumber ( char c )

static

Return a number for a single hexadecimal character given.

In case the character given is '1', 1 will be returned, in case the character given is 'A', 10 will be returned, and so on.

The service works only with ASCII subset.

Precondition: If the number is not a hex char, an error is thrown.

static MByteString MUtilities::HexStringToBytes ( const MStdString & hexString )

static

Convert hexadecimal string into binary byte string.

Any alphanumerical character in the input string must represent a hexadecimal digit. Any non-alphanumerical characters are skipped by the conversion.

Precondition: If the hexadecimal string has some bad characters, the exception thrown contains information about what was bad.

Parameters

hexString Byte string that has hex characters and possible blank separators.

Returns: Binary representation of the given string.

static MByteString MUtilities::HexToBytes ( const MByteString & hexString )

static

Convert hexadecimal byte string into binary byte string.

Any alphanumerical character in the input string must represent a hexadecimal digit. Any non-alphanumerical characters are skipped by the conversion.

Precondition: If the hexadecimal string has some bad characters, the exception thrown contains information about what was bad.

Parameters

hexString String that has hex characters and possible blank separators.

Returns: Binary representation of the given string.

static bool MUtilities::IsPathDirectory ( const MStdString & path )

static

Return true if a given path is present, and it is a directory.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

static bool MUtilities::IsPathExisting ( const MStdString & path )

static

Tell if a given path is an existing file of any sort.

Parameters

path	Path of a file or directory, relative or absolute. For more information, refer to MeteringSDK path syntax.

static bool MUtilities::IsPathFull ( const MStdString & path )

static

Tells if a given path is a full path.

Parameters

path	Path, relative or absolute. For more information, refer to MeteringSDK path syntax.

static MStdString MUtilities::MergePaths	(	const MStdString &	fullDirOrName,
		const MStdString &	dirOrName
	)

static

Merge two paths together.

If a second parameter is a full path, it is returned as is.

If it is not a full path, directory parameter from the first argument is used.

static void MUtilities::MoveFile	(	const MStdString &	source,
		const MStdString &	destination
	)

static

Move a file to a new location.

Parameters

source	Source file, either relative or absolute path. File should exist, or an exception is thrown.
destination	Path where to move the source. File name should be valid, and it should be possible to create files in the destination, or an exception is thrown.

static Muint8 MUtilities::NumberToHexByte ( unsigned n )

static

Return a single hexadecimal byte that represents the given unsigned number.

In case the number given is 1, byte representation of '1' will be returned, in case the number given is 10, byte representation of 'A' will be returned, and so on.

Precondition: If the number is bigger than 0xF, an error is thrown.

static char MUtilities::NumberToHexChar ( unsigned n )

inlinestatic

Return a single hexadecimal character that represents the given unsigned number.

In case the number given is 1, '1' will be returned, in case the number given is 10, 'A' will be returned, and so on.

Precondition: If the number is bigger than 0xF, an exception is thrown.

static MByteString MUtilities::NumericBufferToBytes	(	const char *	buff,
		unsigned	length
	)

static

Convert numeric byte buffer into byte string.

Any sequence of digits in the input string must represent a decimal value of a byte. No letters or non-ASCII codes are permitted, and any other character such as space or punctuation is ignored. As an example, the input 1.0.64.0.0.255 1-5" will be converted into "01 00 40 00 00 FF 01 05".

Parameters

buff	Pointer to a buffer that has bytes represented in decimal form.
length	Length of the buffer.

Returns: Binary representation of the given numeric buffer.

static MByteString MUtilities::NumericStringToBytes ( const MStdString & numericString )

static

Convert numeric string into binary byte string.

Any sequence of digits in the input string must represent a decimal value of a byte. No letters or non-ASCII codes are permitted, and any other character such as space or punctuation is ignored. As an example, the input 1.0.64.0.0.255 1-5" will be converted into x"01 00 40 00 00 FF 01 05".

Parameters

numericString String that has bytes represented in decimal form.

Returns: Binary representation of the given numeric string.

static void MUtilities::SetCurrentPath ( const MStdString & path )

static

Current application path.

Most often, the current path is a global property of the process, as determined by OS. Some operating systems such as Windows CE do not have per process current path, and for such cases there is a special global variable to emulate this functionality. Property manipulation can result in a number of system errors.

static MByteString MUtilities::ToBCD	(	double	value,
		unsigned	size = `0u`,
		bool	littleEndian = `false`
	)

static

Convert a positive double to a BCD coded byte string.

Size, if specified, shall be the length of the result data in bytes. If the size is not specified, it will be calculated to be the minimum where the value fits.

Parameters

value	Value to convert into BCD string.
size	Size of the result. If zero or default, the size will be the minimum which fits.
littleEndian	Whether the produced BCD number will be little endian, which is the default. Little endian BCD number is by far the most usual case.

Returns: The result number.

Precondition: The given double number shall be positive, and if size is specified, it shall fit in the number of bytes given. Otherwise an exception is thrown.

static void MUtilities::ToBCDBuffer	(	unsigned	intValue,
		char *	buffer,
		unsigned	size,
		bool	littleEndian = `false`
	)

static

Converts the number given as unsigned integer into a BCD buffer.

Precondition: buffer must be large enough for given number.

static void MUtilities::ToBCDBuffer	(	double	value,
		char *	buffer,
		unsigned	size,
		bool	littleEndian = `false`
	)

static

Converts the number given as double into a BCD buffer.

Binary coded decimal is a way of representing decimal numbers so that each byte has a pair of numbers, each in range 0 to 9. A BCD with hex representation x"00123456" represents a number 123456. No special codes are allowed in the BCD, only 0 .. 9. Note that the double can keep only 53 bits of mantissa.

Precondition: Buffer must be large enough for the given number.

static MByteString MUtilities::ToDSPFloat	(	double	value,
		unsigned	size
	)

static

Convert a DSP float double to a byte string.

Size shall be the length of the result data in bytes.

Precondition: The given double number shall be within range denoted by the size of the buffer, otherwise an exception is thrown. Size can be either 3 or 4.

static void MUtilities::ToDSPFloatBuffer	(	double	value,
		char *	buffer,
		unsigned	size
	)

static

Convert a DSP float double to a byte string.

Size shall be the length of the result data in bytes. Size can be either 3 or 4.

Precondition: The given double number shall fit within the range denoted by the size of the buffer, otherwise an exception is thrown.

static MByteString MUtilities::ToDSPInt	(	double	value,
		unsigned	size
	)

static

Convert a DSP float double to a byte string.

Size shall be the length of the result data in bytes.

Precondition: The given double number shall fit within the range denoted by the size of the buffer, otherwise an exception is thrown.

static void MUtilities::ToDSPIntBuffer	(	double	value,
		char *	buffer,
		unsigned	size
	)

static

Convert a DSP_INT double to a byte buffer.

Size shall be the length of the result data in bytes.

Precondition: The given double number shall be within range denoted by the buffer size, otherwise an exception is thrown.

static void MUtilities::ToINSTRBuffer	(	double	value,
		char *	data,
		unsigned	size
	)

static

Converts double value to given buffer.

Precondition: Size must be equal to 2.

static MByteString MUtilities::ToINT	(	const MVariant &	value,
		unsigned	size,
		bool	littleEndian
	)

static

Convert an integer number to byte string representation of this number as INT.

Parameters

value	Value to convert. Depending on its type: If the value is numeric its size shall fit in the number of bytes given by size parameter. If value is a byte string its bytes will be reversed if littleEndian is false, or it will be copied as it is if littleEndian is true,
size	Desired byte size of the result, value within range 1 to 8. The number given should be enough to accommodate the value.
littleEndian	Whether the bytes returned should be in little endian format, big endian otherwise.

Returns: MByteString result byte representation of the value.

static MStdString MUtilities::ToMDLConstant ( const MVariant & )

static

Convert the variant given to a constant with a proper MDL syntax.

For example, numeric values are printed as they are, while characters are escaped and enclosed with apostrophes, and strings are escaped and enclosed with double quotes.

Precondition: The variant should not be empty, otherwise an exception will be raised.

See also: ToRelaxedMDLConstant for conversion that meets requirements of the previous implementation.

static MByteString MUtilities::ToRAD40	(	const MStdString &	str,
		unsigned	radSize
	)

static

Convert the given string of characters to RAD40 number returned as byte string.

It is not an error if the RAD length is not an even number as the last odd byte will be truncated.

Precondition: The given string shall have a valid RAD40 representation, or a bad character is reported. The given buffer and size shall denote a valid writable byte chunk.

static void MUtilities::ToRAD40Buffer	(	const MStdString &	str,
		char *	rad,
		unsigned	radSize
	)

static

Convert the given string of characters to RAD40 buffer.

It is not an error if the RAD length is not an even number as the last odd byte will be truncated.

Precondition: The given string shall have a valid RAD40 representation, or a bad character is reported. The given buffer and size shall denote a valid writable byte chunk.

static MStdString MUtilities::ToRelaxedMDLConstant ( const MVariant & )

static

Convert the variant given to a constant with a relaxed MDL syntax.

The difference from ToMDLConstant is that booleans are 0 or 1, and unsigned numbers do not have u added.

Precondition: The variant should not be empty, otherwise an exception will be raised.

static MByteString MUtilities::ToUINT	(	const MVariant &	value,
		unsigned	size,
		bool	littleEndian
	)

static

Convert a positive number to byte string representation of this number as UINT.

Parameters

value	Value to convert. Depending on its type: If the value is numeric it shall be positive, and its size shall fit in the number of bytes given by size parameter. If value is a byte string its bytes will be reversed if littleEndian is false, or it will be copied as it is if littleEndian is true.
size	Desired byte size of the result, value within range 1 to 8. The number given should be enough to accommodate the value.
littleEndian	Whether the bytes returned should be in little endian format, big endian otherwise.

Returns: MByteString result byte representation of the value.

static unsigned MUtilities::UnsignedFromUINT	(	const MByteString &	bytes,
		bool	littleEndian
	)

static

Converts given byte string into an unsigned.

Parameters

bytes	Byte string to convert, size is in range 1 to 4 bytes.
littleEndian	Whether the given bytes are of little endian format, big endian otherwise.

Returns: Result unsigned value.

See also: FromUINT which is capable of converting up to eight bytes as it returns a variant.

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation