#include "mlUtilsSystemC.h"

Macros
#define	ML_DISABLE_CPP
	Defines a C-Application Programming Interface (API) for ML Utility library mlUtils, see also mlAPI.h.

Functions
ML_UTILS_EXPORT void *	MLMemDup (const void *src, MLuint numBytes, MLMemoryErrorHandling handleFailure)
	Copies the memory pointed to by `src` of size `numBytes` in a newly allocated buffer which must be freed by the caller with `MLFree()`.

ML_UTILS_EXPORT char *	MLStrDup (const char *str, MLMemoryErrorHandling handleFailure)
	Copies the passed null terminated string `str` in a newly allocated buffer which must be freed by the caller with `MLFree()`.

ML_UTILS_EXPORT int	MLSetHighPrecisionMessageTimeStampsEnabled (int enabled)
	Sets if high precision message time stamps, which provide microseconds, are enabled.

ML_UTILS_EXPORT MLuint32	MLGetRandomNumber ()
	Get a (weak) random number in the range 0 to 2^32-2.

Library initialization and destruction.
ML_UTILS_EXPORT MLint32	MLInitializeUtils ()
	Initializes library. returns 0 on error, 1 on success.

ML_UTILS_EXPORT MLint32	MLIsUtilsInitialized ()
	Returns 1 if mlUtils is initialized, 0 otherwise.

ML_UTILS_EXPORT MLint32	MLUtilsDestroy ()
	Destroys MLUtils library. Returns 0 on error, 1 on success.

Bit mask (de)activating runtime and final checks.
ML_UTILS_EXPORT MLuint32	MLGetCheckBitMask ()
	Returns the bit mask specifying runtime and final checks of the ML; the default is 0 = no active checks.

ML_UTILS_EXPORT void	MLSetCheckBitMask (MLuint32 bitMask)
	Enables/disables runtime and final checks in the ML; see MLCheckBits enumerator in mlTypeDefs.h for details about available tests.

Flag which indicates that the ML currently runs some threads in parallel.
ML_UTILS_EXPORT MLint32	MLIsMultithreadingActive ()
	Returns `true` if more than one ML thread is running, otherwise `false`.

ML_UTILS_EXPORT void	_MLSetMultithreadingActive (MLint32 isActive)
	Pass 1 to specify that more than one ML thread is running, otherwise pass 0.

String utility functions
ML_UTILS_EXPORT char *	MLIntToStringCopy (int intValue)
	Returns an integer value `intValue` as C-String.

ML_UTILS_EXPORT char *	MLInt64ToStringCopy (MLint64 int64Value)
	Returns a 64 bit integer value `int64Value` as C-String.

ML_UTILS_EXPORT char *	MLDoubleToStringCopy (double doubleValue)
	Returns a double value `doubleValue` as C-String.

Core ML memory handling
ML_UTILS_EXPORT void *	MLAlloc (MLuint numBytes, MLMemoryErrorHandling handleFailure)
	Allocates a memory block of `numBytes`.

ML_UTILS_EXPORT void *	MLRealloc (void *ptr, MLuint numBytes, MLMemoryErrorHandling handleFailure)
	The memory block pointed to by `ptr` is resized and copied so that it has at least `numBytes`.

ML_UTILS_EXPORT void	MLFree (void *ptr)
	Free function to be use instead of free if code is written which uses/bases on the ML.

ML_UTILS_EXPORT void	MLFreeMemoryManagerCallback (void ptr, const size_t size, void userData)

Handling/setting/getting of ML messages callbacks
ML_UTILS_EXPORT void	MLSetMessageCB (void userData, MLMessageCB callback)
	Registers an `MLMessage` callback `callback` and a user data pointer `userData`.

ML_UTILS_EXPORT void	MLGetMessageCB (void userData, MLMessageCB callback)
	Get the currently registered message callback.

Managing the list of global debug environment names
ML_UTILS_EXPORT void	MLDebugAddEnvName (const char *envName)
	Adds the debug environment string given by the null terminated string `envName`.

ML_UTILS_EXPORT void	MLDebugRemoveEnvName (const char *envName)
	Removes a registered debug environment string given by the null terminated string `envName`.

ML_UTILS_EXPORT MLint32	MLDebugHasEnvName (const char *envName)
	Returns true (=1) if the debug environment name given by the null terminated string `envName` exists.

ML_UTILS_EXPORT const char *	MLDebugGetEnvName (MLuint32 envNameIdx)
	Get pointer to nth debug environment name.

ML_UTILS_EXPORT void	MLDebugRemoveAllEnvNames ()
	Removes all registered debug environment strings from list.

ML_UTILS_EXPORT size_t	MLDebugGetNumEnvNames ()
	Returns number of registered debug environment names.

Passing messages to the ML error handling system.
ML_UTILS_EXPORT void	MLPrintAndNotify (MLMessageType messageType, const char libraryPrefix, const char fPrefix, const char functionName, const char reason, const char handling, const char file, int line, MLErrorCode errCode)
	Core error printing function which can be used by other applications.

ML_UTILS_EXPORT void	MLPrintAndNotifyFatal (const char *file, int line, MLErrorCode errCode)
	Like MLPrintAndNotify, where `messageType` is ML_FATAL, `libraryPrefix` is "ML", `fPrefix`, `functionName`, `reason` and `handling` are "".

ML_UTILS_EXPORT void	MLHandleDebugPrint (const char envVar, const char libraryPrefix, const char outStr, const char file, int line)
	Core debug printing function which can be used by other applications.

The way how the ML shall handle messages.
ML_UTILS_EXPORT void	MLSetTerminationType (MLMessageType level, MLTerminator term)
	Sets the way the ML shall handle messages.

ML_UTILS_EXPORT MLTerminator	MLGetTerminationType (MLMessageType level)
	Returns the way the ML shall handle messages.

Enable/disable exception handling in the ML.
ML_UTILS_EXPORT MLErrorCode	MLEnableExceptionHandling (MLuint32 enable)
	If 1 is passed, exception handling is activated, if 0 is passed, exception catching is disabled.

ML_UTILS_EXPORT MLuint32	MLIsExceptionHandlingEnabled ()
	Returns 1 if exception handling is enabled, otherwise 0 is returned.

Specifies which kinds of messages are handled y the \c ErrorOutput class.
ML_UTILS_EXPORT void	MLSetMessageFilter (MLuint32 messageTypes)
	Sets messages to be handled by `MLErrorOutput` as set bits in `messageType`.

ML_UTILS_EXPORT MLuint32	MLGetMessageFilter ()
	Returns the bit mask specifying the message filter which is composed from binary ORed `MLMessageTypes` enums.

Enable/disable handling of all debug messages.
ML_UTILS_EXPORT MLErrorCode	MLEnableFullDebugging (MLuint32 enable)
	If `enable` is 1, all debug messages are handled by the ML errorOutput and passed to the output channels.

ML_UTILS_EXPORT MLuint32	MLIsFullDebuggingEnabled ()
	Returns 1 if full debugging is enabled, otherwise 0 is returned.

Specifies the possibility to register a native window event handler
ML_UTILS_EXPORT void	MLAddEventFilterCB (MLEventFilterCB cb, void usrData, MLuint32 fromMessageId, MLuint32 toMessageId)
	Adds a user callback `cb` to the native window event handler that is called for every window message.

ML_UTILS_EXPORT void	MLRemoveEventFilterCB (MLEventFilterCB cb, void usrData)
	Removes the callback that was added with `MLAddEventFilterCB` by calling a hook function registered by `MLEventFilterApplicationHookCB` (if available, otherwise these calls are ignored).

Internal Application API (used by MeVisLab)
ML_UTILS_EXPORT void	MLSetApplicationPropertiesHook (MLApplicationPropertyCallbacks *callbacks)
	Sets the callbacks to supply access to properties of the host application, the passed struct is copied to internal global and singleton storage.

ML_UTILS_EXPORT const MLApplicationPropertyCallbacks *	MLGetApplicationPropertiesHook ()
	Returns access to the application property callbacks.

ML_UTILS_EXPORT void	MLSetEventFilterApplicationHook (MLEventFilterApplicationHookCB cb, void usrData)
	Sets an application hook function `cb` which is called for each `MLAddEventFilterCB` and `MLRemoveEventFilterCB` call with the user data given by `usrData`.

ML_UTILS_EXPORT MLEventFilterApplicationHookCB *	MLGetEventFilterApplicationHookCB ()
	Returns the current MLEventFilterApplicationHookCB.

ML_UTILS_EXPORT void *	MLGetEventFilterApplicationHookCBUserData ()
	Returns the user data for the current MLEventFilterApplicationHookCB.

Internal state change notification
ML_UTILS_EXPORT MLint32	MLSetNotifyEnabled (MLint32 flag)
	Enable(flag == 1) / Disable (flag ==0) the internal state change notifications (MLNotify), returns the previous state.

ML_UTILS_EXPORT MLint32	MLIsNotifyEnabled ()
	Returns 1 if MLNotify is enabled, 0 otherwise.

Convenience functions
ML_UTILS_EXPORT void *	MLStringToPtr (const char valueString, int postError, const char errFunc)
	Converts the valueString to a 32 or 64 bit pointer if possible by parsing it a 64 bit unsigned integer value and casting it to a pointer.

Support for conversions between little and big endian. *‍/
ML_UTILS_EXPORT MLint32	MLIsLittleEndian ()
	Returns 1(=true) if machine is little endian; otherwise 0(=false) is returned.

ML_UTILS_EXPORT void	MLMakeLittleEndian (unsigned char *data, size_t numBytes, size_t dTypeSize)
	If the data set pointed to by `data` of size `numBytes` consisting of a `dTypeSize'd` data type which is in big endian format, the data set is converted to little endian.

ML_UTILS_EXPORT void	MLMakeBigEndian (unsigned char *data, size_t numBytes, size_t dTypeSize)
	If the data set pointed to by `data` of size `numBytes` consisting of a `dTypeSize'd` data type which is in little endian format, the data set is converted to big endian.

ML_UTILS_EXPORT void	MLSwapBytes (unsigned char *data, size_t numBytes, size_t dTypeSize)
	Takes `numBytes` starting at position `data` and swaps byte 0 with byte `numBytes` - 1, byte 1 with `numBytes` - 2, etc.

Specifies maximum number of trace list entries to be shown on error outputs.
ML_UTILS_EXPORT void	MLSetMaxNumTraceListDumps (MLuint32 numMaxEntries)
	Sets the maximum number of trace list entries to be shown on fatal error outputs to `numMaxEntries`.

ML_UTILS_EXPORT MLuint32	MLGetMaxNumTraceListDumps ()
	Returns the maximum number of trace list entries to be shown on fatal error outputs.

Specifies maximum number of trace stack entries to be shown on error outputs.
ML_UTILS_EXPORT void	MLSetMaxNumTraceStackDumps (MLuint32 numMaxEntries)
	Sets the maximum number of trace stack entries to be shown on fatal error outputs to `numMaxEntries`.

ML_UTILS_EXPORT MLuint32	MLGetMaxNumTraceStackDumps ()
	Returns the maximum number of trace stack entries to be shown on fatal error outputs.

Specifies mask of message types on which a trace list/stack shall be dumped.
ML_UTILS_EXPORT void	MLSetTraceDumpMessageBits (MLuint32 messageBitMask)
	Sets the trace dump mask to `messageBitMask`.

ML_UTILS_EXPORT MLuint32	MLGetTraceDumpMessageBits ()
	Returns the trace dump bit mask.

Stuff defining basics for the ML and other libraries.
ML_UTILS_EXPORT const char *	MLTerminatorStrings [MLNumTerminators]
	Strings for MLTerminator enumeration.

ML_UTILS_EXPORT const char *	MLGetErrorCodeDescription (MLErrorCode errCode)
	String names for each error code.

ML_UTILS_EXPORT MLErrorCode	MLAddNewErrorCodeDescription (const char *errorString)
	Adds a new (null terminated) error code `errorString` to the existing error codes and return a positive index to it.

ML_UTILS_EXPORT MLErrorCode	MLFindErrorCodeDescription (const char *errorString)
	Returns the error code for an error string `errorString`.

ML_UTILS_EXPORT MLuint32	MLGetNumErrorCodes ()
	Returns the number of available error codes.

ML_UTILS_EXPORT const char const	MLGetErrorCodeDescriptionTable ()
	Returns the table of available error code descriptions.

Identifying and comparing threads
ML_UTILS_EXPORT MLThreadId	_MLMainThreadId
	The thread id that the ML considers to be the main thread, it is exported for performance reasons and should not be changed directly.

ML_UTILS_EXPORT MLThreadId	MLGetCurrentThreadID ()
	Returns the thread id for the current thread.

ML_UTILS_EXPORT MLint32	MLIsCurrentThreadMainThread ()
	Returns if the current thread equals the main thread (MLGetMainThreadID() == MLGetCurrentThreadID)

ML_UTILS_EXPORT MLThreadId	MLGetMainThreadID ()
	Returns the thread id of the main thread (which is the thread from which the DLL was loaded)

ML_UTILS_EXPORT void	MLSetMainThreadID (MLThreadId threadId)
	Sets the thread id that is considered to be the main thread id (WARNING: this should typically never be called, since it is initialized on DLL initialization, but it might be desired to manually change the id that the ML considers to be the main thread in some multithreading scenario).

ML_UTILS_EXPORT MLint32	MLCompareThreadIDs (const MLThreadId &id1, const MLThreadId &id2)
	Returns 1 if the thread ids `id1` and `id2` reference the same thread, 0 otherwise.

ML_UTILS_EXPORT void	MLSetThreadName (const char *threadName)
	Set the name of the thread for debugging purposes (currently only implemented on Windows & OSX)

Macro Definition Documentation

◆ ML_DISABLE_CPP

#define ML_DISABLE_CPP

Defines a C-Application Programming Interface (API) for ML Utility library mlUtils, see also mlAPI.h.

Definition at line 26 of file mlUtilsAPI.h.

Function Documentation

◆ _MLSetMultithreadingActive()

ML_UTILS_EXPORT void _MLSetMultithreadingActive ( MLint32 isActive )

Pass 1 to specify that more than one ML thread is running, otherwise pass 0.

Only to be used by the ML itself, and not by application or module programmers!

◆ MLAddEventFilterCB()

ML_UTILS_EXPORT void MLAddEventFilterCB	(	MLEventFilterCB *	cb,
		void *	usrData,
		MLuint32	fromMessageId,
		MLuint32	toMessageId )

Adds a user callback cb to the native window event handler that is called for every window message.

Be careful with this callback, the callback function has to be as short as possible, since it is a potential performance problem. It is called very often, e.g., for all mouse events. [fromMessageId, toMessageId] defines the range of the message ids that are passed to the filter (e.g., to reduce the number of event types which need to be checked within the callback for performance reasons). Setting toMessageId smaller than fromMessageId suppresses all messages. If set to 0 and 0, all events are passed to the callback. The ids are typically defined by the windowing system. Calls to this function are executed by redirecting the call to a hook function registered by MLEventFilterApplicationHookCB (if available, otherwise these calls are ignored).

◆ MLAddNewErrorCodeDescription()

ML_UTILS_EXPORT MLErrorCode MLAddNewErrorCodeDescription ( const char * errorString )

Adds a new (null terminated) error code errorString to the existing error codes and return a positive index to it.

If an error code exists or and invalid NULL string is passed, ML_INVALID_ERROR_CODE (-1) is returned.

◆ MLAlloc()

ML_UTILS_EXPORT void * MLAlloc	(	MLuint	numBytes,
		MLMemoryErrorHandling	handleFailure )

Allocates a memory block of numBytes.

Should be used instead of normal malloc if code is written which uses/bases on the ML. For handleFailure see MLMemoryErrorHandling.

◆ MLCompareThreadIDs()

ML_UTILS_EXPORT MLint32 MLCompareThreadIDs	(	const MLThreadId &	id1,
		const MLThreadId &	id2 )

Returns 1 if the thread ids id1 and id2 reference the same thread, 0 otherwise.

◆ MLDebugAddEnvName()

ML_UTILS_EXPORT void MLDebugAddEnvName ( const char * envName )

Adds the debug environment string given by the null terminated string envName.

If envName is NULL or empty it will be ignored.

◆ MLDebugGetEnvName()

ML_UTILS_EXPORT const char * MLDebugGetEnvName ( MLuint32 envNameIdx )

Get pointer to nth debug environment name.

NULL is returned if envNameIndex does not point to a valid one. The returned value is only valid until any call of an MLDebug* call.

◆ MLDebugGetNumEnvNames()

ML_UTILS_EXPORT size_t MLDebugGetNumEnvNames ( )

Returns number of registered debug environment names.

◆ MLDebugHasEnvName()

ML_UTILS_EXPORT MLint32 MLDebugHasEnvName ( const char * envName )

Returns true (=1) if the debug environment name given by the null terminated string envName exists.

Otherwise 0 is returned.

◆ MLDebugRemoveAllEnvNames()

ML_UTILS_EXPORT void MLDebugRemoveAllEnvNames ( )

Removes all registered debug environment strings from list.

Avoid using this because all registered functions from other applications or modules are also removed.

◆ MLDebugRemoveEnvName()

ML_UTILS_EXPORT void MLDebugRemoveEnvName ( const char * envName )

Removes a registered debug environment string given by the null terminated string envName.

If envName is NULL or empty or if the name is not found then nothing id done.

◆ MLDoubleToStringCopy()

ML_UTILS_EXPORT char * MLDoubleToStringCopy ( double doubleValue )

Returns a double value doubleValue as C-String.

Return value must be removed by caller with MLFree()! This function can be used for multithreading! If allocation fails ML_PRINT_FATAL_ERROR with ML_NO_MEMORY is performed and NULL is returned.

◆ MLEnableExceptionHandling()

ML_UTILS_EXPORT MLErrorCode MLEnableExceptionHandling ( MLuint32 enable )

If 1 is passed, exception handling is activated, if 0 is passed, exception catching is disabled.

On other values a ML_BAD_PARAMETER error code will be returned.

◆ MLEnableFullDebugging()

ML_UTILS_EXPORT MLErrorCode MLEnableFullDebugging ( MLuint32 enable )

If enable is 1, all debug messages are handled by the ML errorOutput and passed to the output channels.

Otherwise only selective debug prints are passed to the output (if enabled). By default debug printing is off (enabled is 0). Note that during ML initialization the variable ML_DEBUG_ALL is evaluated which might lead to enabled full debug printing. On other values than 0 or 1 a ML_BAD_PARAMETER error code will be returned.

◆ MLFindErrorCodeDescription()

ML_UTILS_EXPORT MLErrorCode MLFindErrorCodeDescription ( const char * errorString )

Returns the error code for an error string errorString.

Returns ML_INVALID_ERROR_CODE (-1) on an invalid error string or the error code.

◆ MLFree()

ML_UTILS_EXPORT void MLFree ( void * ptr )

Free function to be use instead of free if code is written which uses/bases on the ML.

NULL pointers may be passed safely; they are simple ignored.

◆ MLFreeMemoryManagerCallback()

ML_UTILS_EXPORT void MLFreeMemoryManagerCallback	(	void *	ptr,
		const size_t	size,
		void *	userData )

◆ MLGetApplicationPropertiesHook()

ML_UTILS_EXPORT const MLApplicationPropertyCallbacks * MLGetApplicationPropertiesHook ( )

Returns access to the application property callbacks.

The returned pointer is always non NULL but members of MLApplicationPropertyCallbacks may all be NULL, e.g., in reset or default state.

◆ MLGetCheckBitMask()

ML_UTILS_EXPORT MLuint32 MLGetCheckBitMask ( )

Returns the bit mask specifying runtime and final checks of the ML; the default is 0 = no active checks.

See MLCheckBits enumerator in mlTypeDefs.h for details about available tests.

◆ MLGetCurrentThreadID()

ML_UTILS_EXPORT MLThreadId MLGetCurrentThreadID ( )

Returns the thread id for the current thread.

◆ MLGetErrorCodeDescription()

ML_UTILS_EXPORT const char * MLGetErrorCodeDescription ( MLErrorCode errCode )

String names for each error code.

MLErrorCodeDescription(errCode) delivers null terminated string name of the error or "InvalidErrorCode" on invalid errCode parameters.

◆ MLGetErrorCodeDescriptionTable()

ML_UTILS_EXPORT const char *const * MLGetErrorCodeDescriptionTable ( )

Returns the table of available error code descriptions.

It size is given by MLGetNumErrorCodes(). The return value is usually stable unless new error codes are added.

◆ MLGetEventFilterApplicationHookCB()

ML_UTILS_EXPORT MLEventFilterApplicationHookCB * MLGetEventFilterApplicationHookCB ( )

Returns the current MLEventFilterApplicationHookCB.

◆ MLGetEventFilterApplicationHookCBUserData()

ML_UTILS_EXPORT void * MLGetEventFilterApplicationHookCBUserData ( )

Returns the user data for the current MLEventFilterApplicationHookCB.

◆ MLGetMainThreadID()

ML_UTILS_EXPORT MLThreadId MLGetMainThreadID ( )

Returns the thread id of the main thread (which is the thread from which the DLL was loaded)

◆ MLGetMaxNumTraceListDumps()

ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceListDumps ( )

Returns the maximum number of trace list entries to be shown on fatal error outputs.

◆ MLGetMaxNumTraceStackDumps()

ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceStackDumps ( )

Returns the maximum number of trace stack entries to be shown on fatal error outputs.

◆ MLGetMessageCB()

ML_UTILS_EXPORT void MLGetMessageCB	(	void **	userData,
		MLMessageCB **	callback )

Get the currently registered message callback.

If userData or callback are passed as NULL they will not be set; so only one parameter can also be retrieved.

◆ MLGetMessageFilter()

ML_UTILS_EXPORT MLuint32 MLGetMessageFilter ( )

Returns the bit mask specifying the message filter which is composed from binary ORed MLMessageTypes enums.

◆ MLGetNumErrorCodes()

ML_UTILS_EXPORT MLuint32 MLGetNumErrorCodes ( )

Returns the number of available error codes.

◆ MLGetRandomNumber()

ML_UTILS_EXPORT MLuint32 MLGetRandomNumber ( )

Get a (weak) random number in the range 0 to 2^32-2.

The random number function is seeded with the system time on initialization.

This function is not thread-safe and should only be called from the main (GUI) thread.

◆ MLGetTerminationType()

ML_UTILS_EXPORT MLTerminator MLGetTerminationType ( MLMessageType level )

Returns the way the ML shall handle messages.

Default is ML_CONTINUE for all types. In debug and release mode ML_ABORT is default for ML_FATAL.

◆ MLGetTraceDumpMessageBits()

ML_UTILS_EXPORT MLuint32 MLGetTraceDumpMessageBits ( )

Returns the trace dump bit mask.

◆ MLHandleDebugPrint()

ML_UTILS_EXPORT void MLHandleDebugPrint	(	const char *	envVar,
		const char *	libraryPrefix,
		const char *	outStr,
		const char *	file,
		int	line )

Core debug printing function which can be used by other applications.

envVar is the environment variable string used to enable the printing of this debug information, outStr is the debugging string to be printed. file is the file name the print comes from and line the line number. libraryPrefix is a string identifier for the application printing the debug information. All character string pointers may be NULL; if not then they must point to a null terminated character string.

◆ MLInitializeUtils()

ML_UTILS_EXPORT MLint32 MLInitializeUtils ( )

Initializes library. returns 0 on error, 1 on success.

◆ MLInt64ToStringCopy()

ML_UTILS_EXPORT char * MLInt64ToStringCopy ( MLint64 int64Value )

Returns a 64 bit integer value int64Value as C-String.

Return value must be removed by caller with MLFree()! This function can be used for multithreading! If allocation fails ML_PRINT_FATAL_ERROR with ML_NO_MEMORY is performed and NULL is returned.

◆ MLIntToStringCopy()

ML_UTILS_EXPORT char * MLIntToStringCopy ( int intValue )

Returns an integer value intValue as C-String.

Return value must be removed by caller with MLFree()! This function can be used for multithreading! If allocation fails ML_PRINT_FATAL_ERROR with ML_NO_MEMORY is performed and NULL is returned.

◆ MLIsCurrentThreadMainThread()

ML_UTILS_EXPORT MLint32 MLIsCurrentThreadMainThread ( )

Returns if the current thread equals the main thread (MLGetMainThreadID() == MLGetCurrentThreadID)

◆ MLIsExceptionHandlingEnabled()

ML_UTILS_EXPORT MLuint32 MLIsExceptionHandlingEnabled ( )

Returns 1 if exception handling is enabled, otherwise 0 is returned.

◆ MLIsFullDebuggingEnabled()

ML_UTILS_EXPORT MLuint32 MLIsFullDebuggingEnabled ( )

Returns 1 if full debugging is enabled, otherwise 0 is returned.

◆ MLIsLittleEndian()

ML_UTILS_EXPORT MLint32 MLIsLittleEndian ( )

Returns 1(=true) if machine is little endian; otherwise 0(=false) is returned.

◆ MLIsMultithreadingActive()

ML_UTILS_EXPORT MLint32 MLIsMultithreadingActive ( )

Returns true if more than one ML thread is running, otherwise false.

◆ MLIsNotifyEnabled()

ML_UTILS_EXPORT MLint32 MLIsNotifyEnabled ( )

Returns 1 if MLNotify is enabled, 0 otherwise.

◆ MLIsUtilsInitialized()

ML_UTILS_EXPORT MLint32 MLIsUtilsInitialized ( )

Returns 1 if mlUtils is initialized, 0 otherwise.

◆ MLMakeBigEndian()

ML_UTILS_EXPORT void MLMakeBigEndian	(	unsigned char *	data,
		size_t	numBytes,
		size_t	dTypeSize )

If the data set pointed to by data of size numBytes consisting of a dTypeSize'd data type which is in little endian format, the data set is converted to big endian.

Otherwise nothing is done.

◆ MLMakeLittleEndian()

ML_UTILS_EXPORT void MLMakeLittleEndian	(	unsigned char *	data,
		size_t	numBytes,
		size_t	dTypeSize )

If the data set pointed to by data of size numBytes consisting of a dTypeSize'd data type which is in big endian format, the data set is converted to little endian.

Otherwise nothing is done.

◆ MLMemDup()

ML_UTILS_EXPORT void * MLMemDup	(	const void *	src,
		MLuint	numBytes,
		MLMemoryErrorHandling	handleFailure )

Copies the memory pointed to by src of size numBytes in a newly allocated buffer which must be freed by the caller with MLFree().

For handleFailure see MLMemoryErrorHandling. If src is passed as NULL then NULL is returned without any error handling.

◆ MLPrintAndNotify()

ML_UTILS_EXPORT void MLPrintAndNotify	(	MLMessageType	messageType,
		const char *	libraryPrefix,
		const char *	fPrefix,
		const char *	functionName,
		const char *	reason,
		const char *	handling,
		const char *	file,
		int	line,
		MLErrorCode	errCode )

Core error printing function which can be used by other applications.

It calculates the ErrorOutputInfos and calls all registered callback functions to propagate the ErrorOutputInfos. It redirects an error message or a debug print to all registered routines.

Parameters

messageType	specifies the message type.
libraryPrefix	specifies the library the message comes from.
functionName	specifies the calling function or the environment variable related to the debug print.
reason	is the reason for the error call or the debug information.
handling	is the way how the error is handled.
file	is the file calling this function.
line	is the line number in the file calling this function. All character string pointers may be NULL; if not then they must point to a null terminated character string. Calling example: MLPrintAndNotify(ML_WARNING, "ML_", "MyFunction", "MyFunction had an overflow", FILE, LINE); Note that this routine does not print anything directly. It only converts all parameters into a struct form and calls all registered routines.

◆ MLPrintAndNotifyFatal()

ML_UTILS_EXPORT void MLPrintAndNotifyFatal	(	const char *	file,
		int	line,
		MLErrorCode	errCode )

Like MLPrintAndNotify, where messageType is ML_FATAL, libraryPrefix is "ML", fPrefix, functionName, reason and handling are "".

file, line and err are passed unchanged.

◆ MLRealloc()

ML_UTILS_EXPORT void * MLRealloc	(	void *	ptr,
		MLuint	numBytes,
		MLMemoryErrorHandling	handleFailure )

The memory block pointed to by ptr is resized and copied so that it has at least numBytes.

Should be used instead of normal realloc if code is written which uses/bases on the ML. For handleFailure see MLMemoryErrorHandling.

◆ MLRemoveEventFilterCB()

ML_UTILS_EXPORT void MLRemoveEventFilterCB	(	MLEventFilterCB *	cb,
		void *	usrData )

Removes the callback that was added with MLAddEventFilterCB by calling a hook function registered by MLEventFilterApplicationHookCB (if available, otherwise these calls are ignored).

◆ MLSetApplicationPropertiesHook()

ML_UTILS_EXPORT void MLSetApplicationPropertiesHook ( MLApplicationPropertyCallbacks * callbacks )

Sets the callbacks to supply access to properties of the host application, the passed struct is copied to internal global and singleton storage.

NULL may be passed as callbacks to reset all settings to NULL.

◆ MLSetCheckBitMask()

ML_UTILS_EXPORT void MLSetCheckBitMask ( MLuint32 bitMask )

Enables/disables runtime and final checks in the ML; see MLCheckBits enumerator in mlTypeDefs.h for details about available tests.

Invalid bits in mask will be ignored and cause a post to the ML error handler.

◆ MLSetEventFilterApplicationHook()

ML_UTILS_EXPORT void MLSetEventFilterApplicationHook	(	MLEventFilterApplicationHookCB *	cb,
		void *	usrData )

Sets an application hook function cb which is called for each MLAddEventFilterCB and MLRemoveEventFilterCB call with the user data given by usrData.

Only one hook can be set per time; after passing NULL for cb (which to deactivates the hook) and calls to MLAddEventFilter and MLRemoveEventFilterCB do not do anything more.

◆ MLSetHighPrecisionMessageTimeStampsEnabled()

ML_UTILS_EXPORT int MLSetHighPrecisionMessageTimeStampsEnabled ( int enabled )

Sets if high precision message time stamps, which provide microseconds, are enabled.

Returns: Returns whether the high precision time stamps were enabled previously.

◆ MLSetMainThreadID()

ML_UTILS_EXPORT void MLSetMainThreadID ( MLThreadId threadId )

Sets the thread id that is considered to be the main thread id (WARNING: this should typically never be called, since it is initialized on DLL initialization, but it might be desired to manually change the id that the ML considers to be the main thread in some multithreading scenario).

◆ MLSetMaxNumTraceListDumps()

ML_UTILS_EXPORT void MLSetMaxNumTraceListDumps ( MLuint32 numMaxEntries )

Sets the maximum number of trace list entries to be shown on fatal error outputs to numMaxEntries.

◆ MLSetMaxNumTraceStackDumps()

ML_UTILS_EXPORT void MLSetMaxNumTraceStackDumps ( MLuint32 numMaxEntries )

Sets the maximum number of trace stack entries to be shown on fatal error outputs to numMaxEntries.

◆ MLSetMessageCB()

ML_UTILS_EXPORT void MLSetMessageCB	(	void *	userData,
		MLMessageCB *	callback )

Registers an MLMessage callback callback and a user data pointer userData.

The callback will be called always if the ML handles messages due to errors, warnings, debug infos etc. A callback is only registered if not NULL. Any previous function is removed by calling this function. If called by the ML the registered callback of type

//      void MLMessageCB(void* usrData,
//                       MLErrorCode errCode,
//                       MLMessageType messageType,
//                       const char* messStr,
//                       int line,
//                       const char** infos)

will receive the following parameters:

Parameters

userData	The same as passed to `MLSetMessageCB`.
errCode	The error code causing this message handling.
messageType	Which message type of information is represented by this class.
messStr	A formatted convenience string containing message information.
line	The line number in the file which caused this message (if available, otherwise -1).
info[0]	Library prefix string to indicate the library from where the message comes. Typically "ML_" or "ILAB_".
info[1]	Prefix string to be printed before the function.
info[2]	Name string of function which caused this information/error/debug/warning or tracing print.
info[3]	Reason string why the this information/error/debug/warning or tracing occurs.
info[4]	String describing how the routine handled the message reason and how it would continue.
info[5]	File name which caused this information/error/debug/warning or tracing print.
info[6]	String containing the time stamp when message arrived. It is printed with the default setting of DateTime (see mlUtils) and the print format Y-m-d H:M:S 4 digit year, month, day, hour minute, second.

All strings are constant character pointers to null terminated strings which are only valid during callback life time.

◆ MLSetMessageFilter()

ML_UTILS_EXPORT void MLSetMessageFilter ( MLuint32 messageTypes )

Sets messages to be handled by MLErrorOutput as set bits in messageType.

Binary adds of MLMessageTypes are allowed e.g., messageType=ML_FATAL | ML_ERROR handles all ML_FATAL and ML_ERROR messages by calling the registered callback functions.

◆ MLSetNotifyEnabled()

ML_UTILS_EXPORT MLint32 MLSetNotifyEnabled ( MLint32 flag )

Enable(flag == 1) / Disable (flag ==0) the internal state change notifications (MLNotify), returns the previous state.

◆ MLSetTerminationType()

ML_UTILS_EXPORT void MLSetTerminationType	(	MLMessageType	level,
		MLTerminator	term )

Sets the way the ML shall handle messages.

For each message type an ML termination mode can be defined. Default is ML_CONTINUE for all types. In debug and release mode ML_ABORT is default for ML_FATAL.

◆ MLSetThreadName()

ML_UTILS_EXPORT void MLSetThreadName ( const char * threadName )

Set the name of the thread for debugging purposes (currently only implemented on Windows & OSX)

◆ MLSetTraceDumpMessageBits()

ML_UTILS_EXPORT void MLSetTraceDumpMessageBits ( MLuint32 messageBitMask )

Sets the trace dump mask to messageBitMask.

◆ MLStrDup()

ML_UTILS_EXPORT char * MLStrDup	(	const char *	str,
		MLMemoryErrorHandling	handleFailure )

Copies the passed null terminated string str in a newly allocated buffer which must be freed by the caller with MLFree().

For handleFailure see MLMemoryErrorHandling.

◆ MLStringToPtr()

ML_UTILS_EXPORT void * MLStringToPtr	(	const char *	valueString,
		int	postError,
		const char *	errFunc )

Converts the valueString to a 32 or 64 bit pointer if possible by parsing it a 64 bit unsigned integer value and casting it to a pointer.

Note that the string is always parsed as a 64 bit unsigned integer even on 32 bit systems.

Parameters

valueString	The string to be interpreted as 64 bit unsigned integer which is cast to a pointer then. The string can be either hexadecimal using the prefix "0x" or it can be given in decimal notation. Must be a non-NULL pointer to a 0-terminated string. Note that ML_BAD_POINTER_OR_0 errors are posted if valueString is a NULL (even if `postError` is `false`). On 32 bit systems, the parsed 64 bit value is checked for a valid unsigned 32 bit range. On failure, NULL is returned and dependent on postError, an error is posted. The same happens if the value cannot be parsed as an unsigned integer value at all.
postError	If `true`, all potential errors are posted to the ML error handler.
errFunc	An optional string which may be NULL. If it is non-NULL, it is prefixed to all handling strings with a ":" if any error is posted. Useful to identify the calling function in case of errors.

Returns: A 32 pointer value on 32 bit systems or a 64 bit pointer on 64 bit system parsed from valueString or NULL on failure.

◆ MLSwapBytes()

ML_UTILS_EXPORT void MLSwapBytes	(	unsigned char *	data,
		size_t	numBytes,
		size_t	dTypeSize )

Takes numBytes starting at position data and swaps byte 0 with byte numBytes - 1, byte 1 with numBytes - 2, etc.

numBytes numbers not dividable by dTypeSize are rounded to the next lower dividable number. Useful for conversions between little and big endian data.

◆ MLUtilsDestroy()

ML_UTILS_EXPORT MLint32 MLUtilsDestroy ( )

Destroys MLUtils library. Returns 0 on error, 1 on success.

Variable Documentation

◆ _MLMainThreadId

ML_UTILS_EXPORT MLThreadId _MLMainThreadId

extern

The thread id that the ML considers to be the main thread, it is exported for performance reasons and should not be changed directly.

◆ MLTerminatorStrings

ML_UTILS_EXPORT const char* MLTerminatorStrings[MLNumTerminators]

extern

Strings for MLTerminator enumeration.

Macros

Functions

Stuff defining basics for the ML and other libraries.

Identifying and comparing threads

Macro Definition Documentation

◆ ML_DISABLE_CPP

Function Documentation

◆ _MLSetMultithreadingActive()

◆ MLAddEventFilterCB()

◆ MLAddNewErrorCodeDescription()

◆ MLAlloc()

◆ MLCompareThreadIDs()

◆ MLDebugAddEnvName()

◆ MLDebugGetEnvName()

◆ MLDebugGetNumEnvNames()

◆ MLDebugHasEnvName()

◆ MLDebugRemoveAllEnvNames()

◆ MLDebugRemoveEnvName()

◆ MLDoubleToStringCopy()

◆ MLEnableExceptionHandling()

◆ MLEnableFullDebugging()

◆ MLFindErrorCodeDescription()

◆ MLFree()

◆ MLFreeMemoryManagerCallback()

◆ MLGetApplicationPropertiesHook()

◆ MLGetCheckBitMask()

◆ MLGetCurrentThreadID()

◆ MLGetErrorCodeDescription()

◆ MLGetErrorCodeDescriptionTable()

◆ MLGetEventFilterApplicationHookCB()

◆ MLGetEventFilterApplicationHookCBUserData()

◆ MLGetMainThreadID()

◆ MLGetMaxNumTraceListDumps()

◆ MLGetMaxNumTraceStackDumps()

◆ MLGetMessageCB()

◆ MLGetMessageFilter()

◆ MLGetNumErrorCodes()

◆ MLGetRandomNumber()

◆ MLGetTerminationType()

◆ MLGetTraceDumpMessageBits()

◆ MLHandleDebugPrint()

◆ MLInitializeUtils()

◆ MLInt64ToStringCopy()

◆ MLIntToStringCopy()

◆ MLIsCurrentThreadMainThread()

◆ MLIsExceptionHandlingEnabled()

◆ MLIsFullDebuggingEnabled()

◆ MLIsLittleEndian()

◆ MLIsMultithreadingActive()

◆ MLIsNotifyEnabled()

◆ MLIsUtilsInitialized()

◆ MLMakeBigEndian()

◆ MLMakeLittleEndian()

◆ MLMemDup()

◆ MLPrintAndNotify()

◆ MLPrintAndNotifyFatal()

◆ MLRealloc()

◆ MLRemoveEventFilterCB()

◆ MLSetApplicationPropertiesHook()

◆ MLSetCheckBitMask()

◆ MLSetEventFilterApplicationHook()

◆ MLSetHighPrecisionMessageTimeStampsEnabled()

◆ MLSetMainThreadID()

◆ MLSetMaxNumTraceListDumps()

◆ MLSetMaxNumTraceStackDumps()

◆ MLSetMessageCB()

◆ MLSetMessageFilter()

◆ MLSetNotifyEnabled()

◆ MLSetTerminationType()

◆ MLSetThreadName()

◆ MLSetTraceDumpMessageBits()

◆ MLStrDup()

◆ MLStringToPtr()

◆ MLSwapBytes()

◆ MLUtilsDestroy()

Variable Documentation

◆ _MLMainThreadId

◆ MLTerminatorStrings