MeVisLab Toolbox Reference
mlUtilsAPI.h
Go to the documentation of this file.
1 /*************************************************************************************
2 **
3 ** Copyright 2007, MeVis Medical Solutions AG
4 **
5 ** The user may use this file in accordance with the license agreement provided with
6 ** the Software or, alternatively, in accordance with the terms contained in a
7 ** written agreement between the user and MeVis Medical Solutions AG.
8 **
9 ** For further information use the contact form at https://www.mevislab.de/contact
10 **
11 **************************************************************************************/
12 
13 #ifndef ML_UTILS_API_H
14 #define ML_UTILS_API_H
15 
18 
19 // Attention: All includes must be pure C!
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 #ifndef ML_DISABLE_CPP
26 #define ML_DISABLE_CPP
27 #endif
28 
29 #include "mlUtilsSystemC.h"
30 
31 //--------------------------------------------------------------------------------------------
32 //
35 //
36 //--------------------------------------------------------------------------------------------
37 
40 
45 
49 [[nodiscard]]
51 
54 [[nodiscard]]
56 
59 
65 
66 
67 //-----------------------------------------------------------------------------------
68 //
71 //
72 //-----------------------------------------------------------------------------------
73 
76 
79 
83 
84 
85 //-----------------------------------------------------------------------------------
86 //
89 //
90 //-----------------------------------------------------------------------------------
91 
96 
103 
104 
105 
106 //-----------------------------------------------------------------------------------
107 //
110 //
111 //-----------------------------------------------------------------------------------
112 
115 
120 
121 
122 //-----------------------------------------------------------------------------------
123 //
126 //
127 //-----------------------------------------------------------------------------------
128 
131 
134 
137 
142 
145 
149 
151 ML_UTILS_EXPORT void MLSetThreadName(const char* threadName);
152 
154 
155 
156 //-----------------------------------------------------------------------------------
157 //
160 //
161 //-----------------------------------------------------------------------------------
162 
168 ML_UTILS_EXPORT char* MLIntToStringCopy(int intValue);
169 
176 
182 ML_UTILS_EXPORT char* MLDoubleToStringCopy(double doubleValue);
184 
185 
186 
187 //--------------------------------------------------------------------------------------------------
188 //
191 //
192 //--------------------------------------------------------------------------------------------------
193 
198 [[nodiscard]]
199 ML_UTILS_EXPORT void* MLAlloc(MLuint numBytes, MLMemoryErrorHandling handleFailure);
200 
206 [[nodiscard]]
207 ML_UTILS_EXPORT void* MLRealloc(void* ptr, MLuint numBytes, MLMemoryErrorHandling handleFailure);
208 
213 ML_UTILS_EXPORT void MLFree(void* ptr);
214 ML_UTILS_EXPORT void MLFreeMemoryManagerCallback(void* ptr, const size_t size, void* userData);
216 
222 [[nodiscard]]
223 ML_UTILS_EXPORT void* MLMemDup(const void* src, MLuint numBytes, MLMemoryErrorHandling handleFailure);
224 
228 [[nodiscard]]
229 ML_UTILS_EXPORT char* MLStrDup(const char* str, MLMemoryErrorHandling handleFailure);
231 
232 
233 
234 
235 
236 //-----------------------------------------------------------------------------------
237 //
240 //
241 //-----------------------------------------------------------------------------------
249 // void MLMessageCB(void* usrData,
250 // MLErrorCode errCode,
251 // MLMessageType messageType,
252 // const char* messStr,
253 // int line,
254 // const char** infos)
278 ML_UTILS_EXPORT void MLSetMessageCB(void* userData, MLMessageCB* callback);
279 
283 ML_UTILS_EXPORT void MLGetMessageCB(void** userData, MLMessageCB** callback);
285 
286 
287 
288 //-----------------------------------------------------------------------------------
289 //
292 //
293 //-----------------------------------------------------------------------------------
296 ML_UTILS_EXPORT void MLDebugAddEnvName(const char* envName);
297 
301 ML_UTILS_EXPORT void MLDebugRemoveEnvName(const char* envName);
302 
306 
309 ML_UTILS_EXPORT const char * MLDebugGetEnvName(MLuint32 envNameIdx);
310 
314 
318 
319 
320 
321 //-----------------------------------------------------------------------------------
322 //
325 //
326 //-----------------------------------------------------------------------------------
348  const char* libraryPrefix,
349  const char* fPrefix,
350  const char* functionName,
351  const char* reason,
352  const char* handling,
353  const char* file,
354  int line,
355  MLErrorCode errCode);
356 
361  int line,
362  MLErrorCode errCode);
363 
371 ML_UTILS_EXPORT void MLHandleDebugPrint(const char* envVar,
372  const char* libraryPrefix,
373  const char* outStr,
374  const char* file,
375  int line);
377 
378 
379 //-----------------------------------------------------------------------------------
380 //
383 //
384 //-----------------------------------------------------------------------------------
390 
395 
396 
397 //-----------------------------------------------------------------------------------
398 //
401 //
402 //-----------------------------------------------------------------------------------
407 
411 
412 
413 //-----------------------------------------------------------------------------------
414 //
417 //
418 //-----------------------------------------------------------------------------------
425 
430 
431 
432 //-----------------------------------------------------------------------------------
433 //
436 //
437 //-----------------------------------------------------------------------------------
446 
450 
451 
452 //-----------------------------------------------------------------------------------
453 //
456 //
457 //-----------------------------------------------------------------------------------
458 
472  MLuint32 fromMessageId, MLuint32 toMessageId);
473 
479 
480 
481 //-----------------------------------------------------------------------------------
482 //
485 //
486 //-----------------------------------------------------------------------------------
487 
493 
498 
499 
505 
508 
512 
513 //-----------------------------------------------------------------------------------
514 //
517 //
518 //-----------------------------------------------------------------------------------
519 
523 
527 
531 
532 
533 //-----------------------------------------------------------------------------------
534 //
537 //
538 //-----------------------------------------------------------------------------------
539 
567 ML_UTILS_EXPORT void* MLStringToPtr(const char* valueString, int postError, const char* errFunc);
569 
570 
571 
572 //--------------------------------------------------------------------------------------------------
573 //
576 //
577 //--------------------------------------------------------------------------------------------------
580 
584 ML_UTILS_EXPORT void MLMakeLittleEndian(unsigned char* data, size_t numBytes, size_t dTypeSize);
585 
589 ML_UTILS_EXPORT void MLMakeBigEndian(unsigned char* data, size_t numBytes, size_t dTypeSize);
590 
596 ML_UTILS_EXPORT void MLSwapBytes(unsigned char* data, size_t numBytes, size_t dTypeSize);
598 
599 
600 //-----------------------------------------------------------------------------------
601 //
604 //
605 //-----------------------------------------------------------------------------------
608 
612 
613 //-----------------------------------------------------------------------------------
614 //
617 //
618 //-----------------------------------------------------------------------------------
621 
625 
626 //-----------------------------------------------------------------------------------
627 //
630 //
631 //-----------------------------------------------------------------------------------
634 
638 
639 
645 
646 
647 #ifdef __cplusplus
648 }
649 #endif
650 
651 #undef ML_DISABLE_CPP
652 
653 #endif // __mlUtilsAPI_H
MLint32 MLErrorCode
Type of an ML Error code.
Definition: mlTypeDefs.h:716
MLTerminator
Termination types for error handling.
Definition: mlTypeDefs.h:1060
@ MLNumTerminators
Definition: mlTypeDefs.h:1065
MLMemoryErrorHandling
Enumerator to specify memory error handling.
Definition: mlTypeDefs.h:676
MLuint32 MLThreadId
Definition: mlTypeDefs.h:604
unsigned int MLuint32
Definition: mlTypeDefs.h:185
MLuint64 MLuint
An unsigned ML integer type with at least 64 bits used for index calculations on very large images ev...
Definition: mlTypeDefs.h:506
void MLEventFilterApplicationHookCB(void *applicationUsrData, MLEventFilterApplicationMessage type, MLEventFilterCB *cb, void *usrData, MLuint32 fromMessageId, MLuint32 toMessageId)
Internal application event filter callback type.
Definition: mlTypeDefs.h:1273
INT64 MLint64
Include 64-bit integer support for Windows or Unix.
Definition: mlTypeDefs.h:412
void MLMessageCB(void *usrData, MLErrorCode errCode, MLMessageType messageType, const char *messStr, int line, const char **infos)
Handling/setting/getting of ML messages callbacks.
Definition: mlTypeDefs.h:1173
MLint32 MLEventFilterCB(void *usrData, void *event)
Callback function type for events that are passed to the user.
Definition: mlTypeDefs.h:1236
signed int MLint32
Definition: mlTypeDefs.h:161
MLMessageType
Message types handled by the ErrorOutput class.
Definition: mlTypeDefs.h:696
#define ML_UTILS_EXPORT
Definition: mlUtilities.h:18
ML_UTILS_EXPORT size_t MLDebugGetNumEnvNames()
Returns number of registered debug environment names.
ML_UTILS_EXPORT void * MLAlloc(MLuint numBytes, MLMemoryErrorHandling handleFailure)
Allocates a memory block of numBytes.
ML_UTILS_EXPORT const char * MLTerminatorStrings[MLNumTerminators]
Strings for MLTerminator enumeration.
ML_UTILS_EXPORT MLThreadId MLGetCurrentThreadID()
Returns the thread ID for the current thread.
ML_UTILS_EXPORT void MLRemoveEventFilterCB(MLEventFilterCB *cb, void *usrData)
Removes the callback that was added with MLAddEventFilterCB by calling a hook function registered by ...
ML_UTILS_EXPORT MLint32 MLIsCurrentThreadMainThread()
Returns whether the current thread equals the main thread (MLGetMainThreadID() == MLGetCurrentThreadI...
ML_UTILS_EXPORT void MLSetTraceDumpMessageBits(MLuint32 messageBitMask)
Sets the trace dump mask to messageBitMask.
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 MLint32 MLDebugHasEnvName(const char *envName)
Returns true (=1) if the debug environment name given by the NULL-terminated string envName exists.
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 that can be used by other applications.
ML_UTILS_EXPORT void MLSetApplicationPropertiesHook(MLApplicationPropertyCallbacks *callbacks)
Sets the callbacks to grant access to properties of the host application, the passed struct is copied...
ML_UTILS_EXPORT MLuint32 MLIsFullDebuggingEnabled()
Returns 1 if full debugging is enabled; otherwise, 0 is returned.
ML_UTILS_EXPORT MLuint32 MLGetMessageFilter()
Returns the bit mask specifying the message filter that is composed from binary ORed MLMessageTypes e...
ML_UTILS_EXPORT char * MLInt64ToStringCopy(MLint64 int64Value)
Returns a 64-bit integer value int64Value as a C-string.
ML_UTILS_EXPORT void MLMakeLittleEndian(unsigned char *data, size_t numBytes, size_t dTypeSize)
If the dataset pointed to by data of size numBytes, consisting of a data type of size dTypeSize,...
ML_UTILS_EXPORT MLuint32 MLGetRandomNumber()
Returns a (weak) random number in the range 0 to 2^32-2.
ML_UTILS_EXPORT MLint32 MLUtilsDestroy()
Destroys MLUtils library. Returns 0 on error, 1 on success.
ML_UTILS_EXPORT MLuint32 MLIsExceptionHandlingEnabled()
Returns 1 if exception handling is enabled; otherwise, 0 is returned.
ML_UTILS_EXPORT const char * MLDebugGetEnvName(MLuint32 envNameIdx)
Returns the pointer to nth debug environment name.
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 MLIsUtilsInitialized()
Returns 1 if mlUtils is initialized, 0 otherwise.
ML_UTILS_EXPORT void MLHandleDebugPrint(const char *envVar, const char *libraryPrefix, const char *outStr, const char *file, int line)
Core debug printing function that can be used by other applications.
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 const char *const * MLGetErrorCodeDescriptionTable()
Returns the table of available error code descriptions.
ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceListDumps()
Returns the maximum number of trace list entries to be shown on fatal error outputs.
ML_UTILS_EXPORT void MLDebugAddEnvName(const char *envName)
Adds the debug environment string given by the NULL-terminated string envName.
ML_UTILS_EXPORT void MLSetTerminationType(MLMessageType level, MLTerminator term)
Sets the way the ML shall handle messages.
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 that must be freed b...
ML_UTILS_EXPORT MLuint32 MLGetMaxNumTraceStackDumps()
Returns the maximum number of trace stack entries to be shown on fatal error outputs.
ML_UTILS_EXPORT MLEventFilterApplicationHookCB * MLGetEventFilterApplicationHookCB()
Returns the current MLEventFilterApplicationHookCB.
ML_UTILS_EXPORT MLuint32 MLGetCheckBitMask()
Returns the bit mask specifying runtime and final checks of the ML; the default is 0 = no active chec...
ML_UTILS_EXPORT void MLSetEventFilterApplicationHook(MLEventFilterApplicationHookCB *cb, void *usrData)
Sets an application hook function cb that is called for each MLAddEventFilterCB and MLRemoveEventFilt...
ML_UTILS_EXPORT const char * MLGetErrorCodeDescription(MLErrorCode errCode)
String names for each error code.
ML_UTILS_EXPORT MLint32 MLIsMultithreadingActive()
Returns true if more than one ML thread is running; otherwise, it returns false.
ML_UTILS_EXPORT const MLApplicationPropertyCallbacks * MLGetApplicationPropertiesHook()
Returns access to the application property callbacks.
ML_UTILS_EXPORT MLint32 MLSetNotifyEnabled(MLint32 flag)
Enables (flag=1) / disables (flag=0) the internal state change notifications (MLNotify),...
ML_UTILS_EXPORT MLErrorCode MLFindErrorCodeDescription(const char *errorString)
Returns the error code for an error string errorString.
ML_UTILS_EXPORT void MLMakeBigEndian(unsigned char *data, size_t numBytes, size_t dTypeSize)
If the dataset pointed to by data of size numBytes, consisting of a data type of size dTypeSize,...
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 MLThreadId MLGetMainThreadID()
Returns the thread ID of the main thread, which is the thread from which the DLL was loaded.
ML_UTILS_EXPORT void MLDebugRemoveAllEnvNames()
Removes all registered debug environment strings from list.
ML_UTILS_EXPORT void MLSetThreadName(const char *threadName)
Sets the name of the thread for debugging purposes. This is currently only implemented for Windows & ...
ML_UTILS_EXPORT void MLSetCheckBitMask(MLuint32 bitMask)
Enables/disables runtime and final checks in the ML.
ML_UTILS_EXPORT void MLSetMessageCB(void *userData, MLMessageCB *callback)
Registers an MLMessage callback callback and a user data pointer userData.
ML_UTILS_EXPORT void MLSetMainThreadID(MLThreadId threadId)
Sets the thread ID that is considered to be the main thread ID.
ML_UTILS_EXPORT MLint32 MLInitializeUtils()
Initializes library. Returns 0 on error, 1 on success.
ML_UTILS_EXPORT MLTerminator MLGetTerminationType(MLMessageType level)
Returns the way the ML shall handle messages.
ML_UTILS_EXPORT MLuint32 MLGetTraceDumpMessageBits()
Returns the trace dump bit mask.
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 channel...
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 MLThreadId _MLMainThreadId
The thread ID that the ML considers to be the main thread ID.
ML_UTILS_EXPORT char * MLStrDup(const char *str, MLMemoryErrorHandling handleFailure)
Copies the passed NULL-terminated string str in a newly allocated buffer that must be freed by the ca...
ML_UTILS_EXPORT MLuint32 MLGetNumErrorCodes()
Returns the number of available error codes.
ML_UTILS_EXPORT void MLSetMessageFilter(MLuint32 messageTypes)
Sets messages to be handled by MLErrorOutput as set bits in messageType.
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 to a 64-bit unsigned ...
ML_UTILS_EXPORT int MLSetHighPrecisionMessageTimeStampsEnabled(int enabled)
Sets whether high precision message time stamps, which provide microseconds, are enabled.
ML_UTILS_EXPORT void MLFreeMemoryManagerCallback(void *ptr, const size_t size, void *userData)
ML_UTILS_EXPORT char * MLIntToStringCopy(int intValue)
Returns an integer value intValue as a C-string.
ML_UTILS_EXPORT void MLPrintAndNotifyFatal(const char *file, int line, MLErrorCode errCode)
Similar to MLPrintAndNotify, where messageType is ML_FATAL, libraryPrefix is "ML",...
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 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 numByte...
ML_UTILS_EXPORT char * MLDoubleToStringCopy(double doubleValue)
Returns a double value doubleValue as a C-string.
ML_UTILS_EXPORT void MLGetMessageCB(void **userData, MLMessageCB **callback)
Returns the currently registered message callback.
ML_UTILS_EXPORT MLint32 MLIsNotifyEnabled()
Returns 1 if MLNotify is enabled, 0 otherwise.
ML_UTILS_EXPORT MLErrorCode MLAddNewErrorCodeDescription(const char *errorString)
Adds a new (NULL-terminated) error code errorString to the existing error codes and returns a positiv...
ML_UTILS_EXPORT void _MLSetMultithreadingActive(MLint32 isActive)
Passes 1 to specify that more than one ML thread is running; otherwise, it passes 0.
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 void * MLGetEventFilterApplicationHookCBUserData()
Returns the user data for the current MLEventFilterApplicationHookCB.
ML_UTILS_EXPORT MLint32 MLIsLittleEndian()
Returns 1 (=true) if machine is little endian; otherwise, 0 (=false) is returned.
ML_UTILS_EXPORT void MLFree(void *ptr)
Free function to be use instead of free if code is written that uses/bases on the ML.
MLCSO_EXPORT void level(CSO *cso)
Determines the normal and the center of gravity of the given CSO.
Defines all callbacks that an application has to support for property access.
Definition: mlTypeDefs.h:1243