MeVisLabToolboxReference
mlUtilsAPI.h File Reference

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

#include "mlUtilsSystemC.h"

Go to the source code of this file.

Functions

ML_UTILS_EXPORT void * MLMemDup (const void *src, MLuint numBytes, MLMemoryErrorHandling handleFailure) ML_RETURN_VALUE_SHOULD_BE_USED
 Copies the memory pointed to by src of size numBytes in a newly allocated buffer which must be freed by the caller with MLFree(). More...
 
ML_UTILS_EXPORT char * MLStrDup (const char *str, MLMemoryErrorHandling handleFailure) ML_RETURN_VALUE_SHOULD_BE_USED
 Copies the passed null terminated string str in a newly allocated buffer which must be freed by the caller with MLFree(). More...
 
ML_UTILS_EXPORT int MLSetHighPrecisionMessageTimeStampsEnabled (int enabled)
 Sets if high precision message time stamps, which provide microseconds, are enabled. More...
 
ML_UTILS_EXPORT MLuint32 MLGetRandomNumber ()
 Get a (weak) random number in the range 0 to 2^32-2. More...
 
Library initialization and destruction.
ML_UTILS_EXPORT MLint32 MLInitializeUtils ()
 Initializes library. returns 0 on error, 1 on success. More...
 
ML_UTILS_EXPORT MLint32 MLIsUtilsInitialized ()
 Returns 1 if mlUtils is initialized, 0 otherwise. More...
 
ML_UTILS_EXPORT MLint32 MLUtilsDestroy ()
 Destroys MLUtils library. Returns 0 on error, 1 on success. More...
 
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. More...
 
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. More...
 
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. More...
 
ML_UTILS_EXPORT void _MLSetMultithreadingActive (MLint32 isActive)
 Pass 1 to specify that more than one ML thread is running, otherwise pass 0. More...
 
String utility functions
ML_UTILS_EXPORT char * MLIntToStringCopy (int intValue)
 Returns an integer value intValue as C-String. More...
 
ML_UTILS_EXPORT char * MLInt64ToStringCopy (MLint64 int64Value)
 Returns a 64 bit integer value int64Value as C-String. More...
 
ML_UTILS_EXPORT char * MLDoubleToStringCopy (double doubleValue)
 Returns a double value doubleValue as C-String. More...
 
Core ML memory handling
ML_UTILS_EXPORT void * MLAlloc (MLuint numBytes, MLMemoryErrorHandling handleFailure) ML_RETURN_VALUE_SHOULD_BE_USED
 Allocates a memory block of numBytes. More...
 
ML_UTILS_EXPORT void * MLRealloc (void *ptr, MLuint numBytes, MLMemoryErrorHandling handleFailure) ML_RETURN_VALUE_SHOULD_BE_USED
 The memory block pointed to by ptr is resized and copied so that it has at least numBytes. More...
 
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. More...
 
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. More...
 
ML_UTILS_EXPORT void MLGetMessageCB (void **userData, MLMessageCB **callback)
 Get the currently registered message callback. More...
 
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. More...
 
ML_UTILS_EXPORT void MLDebugRemoveEnvName (const char *envName)
 Removes a registered debug environment string given by the null terminated string envName. More...
 
ML_UTILS_EXPORT MLint32 MLDebugHasEnvName (const char *envName)
 Returns true (=1) if the debug environment name given by the null terminated string envName exists. More...
 
ML_UTILS_EXPORT const char * MLDebugGetEnvName (MLuint32 envNameIdx)
 Get pointer to nth debug environment name. More...
 
ML_UTILS_EXPORT void MLDebugRemoveAllEnvNames ()
 Removes all registered debug environment strings from list. More...
 
ML_UTILS_EXPORT size_t MLDebugGetNumEnvNames ()
 Returns number of registered debug environment names. More...
 
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. More...
 
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 "". More...
 
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. More...
 
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. More...
 
ML_UTILS_EXPORT MLTerminator MLGetTerminationType (MLMessageType level)
 Returns the way the ML shall handle messages. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLIsExceptionHandlingEnabled ()
 Returns 1 if exception handling is enabled, otherwise 0 is returned. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLGetMessageFilter ()
 Returns the bit mask specifying the message filter which is composed from binary ORed MLMessageTypes enums. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLIsFullDebuggingEnabled ()
 Returns 1 if full debugging is enabled, otherwise 0 is returned. More...
 
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. More...
 
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). More...
 
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. More...
 
ML_UTILS_EXPORT const MLApplicationPropertyCallbacksMLGetApplicationPropertiesHook ()
 Returns access to the application property callbacks. More...
 
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. More...
 
ML_UTILS_EXPORT MLEventFilterApplicationHookCBMLGetEventFilterApplicationHookCB ()
 Returns the current MLEventFilterApplicationHookCB. More...
 
ML_UTILS_EXPORT void * MLGetEventFilterApplicationHookCBUserData ()
 Returns the user data for the current MLEventFilterApplicationHookCB. More...
 
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. More...
 
ML_UTILS_EXPORT MLint32 MLIsNotifyEnabled ()
 Returns 1 if MLNotify is enabled, 0 otherwise. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceListDumps ()
 Returns the maximum number of trace list entries to be shown on fatal error outputs. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceStackDumps ()
 Returns the maximum number of trace stack entries to be shown on fatal error outputs. More...
 
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. More...
 
ML_UTILS_EXPORT MLuint32 MLGetTraceDumpMessageBits ()
 Returns the trace dump bit mask. More...
 

Stuff defining basics for the ML and other libraries.

ML_UTILS_EXPORT const char * MLTerminatorStrings [MLNumTerminators]
 Strings for MLTerminator enumeration. More...
 
ML_UTILS_EXPORT const char * MLGetErrorCodeDescription (MLErrorCode errCode)
 String names for each error code. More...
 
ML_UTILS_EXPORT MLErrorCode MLAddNewErrorCodeDescription (const char *errorString) ML_RETURN_VALUE_SHOULD_BE_USED
 Adds a new (null terminated) error code errorString to the existing error codes and return a positive index to it. More...
 
ML_UTILS_EXPORT MLErrorCode MLFindErrorCodeDescription (const char *errorString) ML_RETURN_VALUE_SHOULD_BE_USED
 Returns the error code for an error string errorString. More...
 
ML_UTILS_EXPORT MLuint32 MLGetNumErrorCodes ()
 Returns the number of available error codes. More...
 
ML_UTILS_EXPORT const char *const * MLGetErrorCodeDescriptionTable ()
 Returns the table of available error code descriptions. More...
 

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. More...
 
ML_UTILS_EXPORT MLThreadId MLGetCurrentThreadID ()
 Returns the thread id for the current thread. More...
 
ML_UTILS_EXPORT MLint32 MLIsCurrentThreadMainThread ()
 Returns if the current thread equals the main thread (MLGetMainThreadID() == MLGetCurrentThreadID) More...
 
ML_UTILS_EXPORT MLThreadId MLGetMainThreadID ()
 Returns the thread id of the main thread (which is the thread from which the DLL was loaded) More...
 
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). More...
 
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. More...
 
ML_UTILS_EXPORT void MLSetThreadName (const char *threadName)
 Set the name of the thread for debugging purposes (currently only implemented on Windows & OSX) More...
 

Detailed Description

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

Author
Wolf Spindler
Date
04/2004

Definition in 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.

Referenced by __ML_KERNEL_CASE_CODE_clearAndHandleError().

◆ 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
messageTypespecifies the message type.
libraryPrefixspecifies the library the message comes from.
functionNamespecifies the calling function or the environment variable related to the debug print.
reasonis the reason for the error call or the debug information.
handlingis the way how the error is handled.
fileis the file calling this function.
lineis 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.

Referenced by ml::determineImageFilterInRegionTN().

◆ 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
userDataThe same as passed to MLSetMessageCB.
errCodeThe error code causing this message handling.
messageTypeWhich message type of information is represented by this class.
messStrA formatted convenience string containing message information.
lineThe 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
valueStringThe 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.
postErrorIf true, all potential errors are posted to the ML error handler.
errFuncAn 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.

Referenced by ml::FileMapWrapper::readValueFromMap(), and ml::FileMapWrapper::readValueFromMapAhead().

◆ MLUtilsDestroy()

ML_UTILS_EXPORT MLint32 MLUtilsDestroy ( )

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

Variable Documentation

◆ _MLMainThreadId

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.

◆ MLTerminatorStrings

ML_UTILS_EXPORT const char* MLTerminatorStrings[MLNumTerminators]

Strings for MLTerminator enumeration.