org.simantics.fmil.core/native/FMILibrary/src/Util/include/JM/jm_callbacks.h

   1 /*
   2     Copyright (C) 2012 Modelon AB
   3
   4     This program is free software: you can redistribute it and/or modify
   5     it under the terms of the BSD style license.
   6
   7      This program is distributed in the hope that it will be useful,
   8     but WITHOUT ANY WARRANTY; without even the implied warranty of
   9     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10     FMILIB_License.txt file for more details.
  11
  12     You should have received a copy of the FMILIB_License.txt file
  13     along with this program. If not, contact Modelon AB <http://www.modelon.com>.
  14 */
  15
  16 #ifndef JM_CALLBACKS_H
  17 #define JM_CALLBACKS_H
  18 #include <stddef.h>
  19 #include <stdarg.h>
  20
  21 #include <fmilib_config.h>
  22
  23 #include "jm_types.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28 /** \file jm_callbacks.h Definition of ::jm_callbacks and supporting functions
  29         *
  30         * \addtogroup jm_utils
  31         * @{
  32                 \addtogroup jm_callbacks
  33         * @}
  34 */
  35 /** \addtogroup jm_callbacks Definition of callbacks struct and supporting functions
  36 * @{  */
  37 typedef struct jm_callbacks jm_callbacks;
  38
  39 /** \name Memory management callbacks\r
  40 * jm_malloc_f, jm_realloc_f, jm_calloc_f, jm_free_f function
  41 * types correspond to the standard C memory management functions
  42 * @{ \r
  43 */
  44 /** \brief Allocation function type. */
  45 typedef jm_voidp (*jm_malloc_f)(size_t size);
  46
  47 /** \brief Re-allocation function type. */
  48 typedef jm_voidp (*jm_realloc_f)(void *ptr, size_t size);
  49
  50 /** \brief Zero-initialized allocation function type. */
  51 typedef jm_voidp (*jm_calloc_f)(size_t numitems, size_t itemsize);
  52
  53 /** \brief Free memory function type. */
  54 typedef void (*jm_free_f)(jm_voidp p);
  55 /** @}\r
  56 */
  57
  58 /**
  59 *
  60 * \brief Logger callback type.
  61 *
  62 * The logger callback is used to report errors. Note that this function is
  63 * by default only used in FMI standard intependent code (e.g., fmi_import_get_fmi_version()).
  64 * Since logging functions are different between different standard versions separate
  65 * logging functions are necessary for each fmi implementation.\n
  66 * Defaults are provided for each standard.
  67 */
  68 typedef void (*jm_logger_f)(jm_callbacks* c, jm_string module, jm_log_level_enu_t log_level, jm_string message);
  69
  70 /** \brief Maximum message size that can be stored in the ::jm_callbacks struct */
  71 #define JM_MAX_ERROR_MESSAGE_SIZE 2000\r
  72
  73 /** \brief The callbacks struct is sent to all the modules in the library */
  74 struct jm_callbacks {
  75         /** \brief Allocate non-initialized memory */
  76         jm_malloc_f malloc;
  77         /** \brief Allocate zero initialized memory */
  78         jm_calloc_f calloc;
  79         /** \brief Re-allocate memory */
  80         jm_realloc_f realloc;
  81         /** \brief Free-allocated memory */
  82         jm_free_f free;
  83         /** \brief Logging callback */
  84         jm_logger_f logger;
  85         /** \brief Logging level */
  86         jm_log_level_enu_t log_level;
  87         /** \brief Arbitrary context pointer passed to the logger function  */
  88         jm_voidp context;
  89         /** \brief The buffer used along with jm_get_last_error() */
  90         char errMessageBuffer[JM_MAX_ERROR_MESSAGE_SIZE];
  91 };
  92
  93 /**
  94 * \brief Get the last log message produced by the library.
  95 *
  96 * An alternative way to get error information is to use jm_get_last_error(). This is only meaningful
  97 * if logger function is not present.
  98 */
  99 static jm_string jm_get_last_error(jm_callbacks* cb) {return cb->errMessageBuffer; }
 100
 101 /**
 102  \brief Clear the last generated log message.
 103 */
 104 static void jm_clear_last_error(jm_callbacks* cb) { cb->errMessageBuffer[0] = 0; }
 105
 106 /**
 107 \brief Set the structure to be returned by jm_get_default_callbacks().
 108
 109 @param c - a pointer to initialized struct to be used as default later on. If this is NULL
 110         library default implementation will be used.
 111 */
 112 FMILIB_EXPORT
 113 void jm_set_default_callbacks(jm_callbacks* c);
 114
 115 /**
 116 \brief Get default callbacks. The function never returns NULL.
 117 \return Default ::jm_callbacks struture. Either the one supplied by the library of the one set with jm_set_default_callbacks().
 118 */
 119 FMILIB_EXPORT
 120 jm_callbacks* jm_get_default_callbacks(void);
 121
 122 /**
 123 \brief The default logger implementation prints messages to stderr.
 124 */
 125 FMILIB_EXPORT
 126 void jm_default_logger(jm_callbacks* c, jm_string module, jm_log_level_enu_t log_level, jm_string message);
 127
 128 /**
 129 \brief Send a message to the logger function.
 130         @param cb - callbacks to be used for reporting;
 131         @param module - a name of reporting module;
 132         @param log_level - message kind;
 133         @param fmt - "printf" type of format followed by the arguments.
 134 */
 135 FMILIB_EXPORT
 136 void jm_log(jm_callbacks* cb, const char* module, jm_log_level_enu_t log_level, const char* fmt, ...);
 137
 138 /** \copydoc jm_log()
 139         @param ap - variable size argument list.
 140 */
 141 FMILIB_EXPORT
 142 void jm_log_v(jm_callbacks* cb, const char* module, jm_log_level_enu_t log_level, const char* fmt, va_list ap);
 143
 144 /** \brief Send a fatal error message to the logger function. See jm_log() for details.
 145 */
 146 FMILIB_EXPORT
 147 void jm_log_fatal_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 148 /** \brief Send a fatal error message to the logger function. See jm_log() for details.
 149 */
 150 FMILIB_EXPORT
 151 void jm_log_fatal(jm_callbacks* cb, const char* module, const char* fmt, ...);
 152
 153 /** \brief Send a error message to the logger function. See jm_log() for details.
 154 */
 155 FMILIB_EXPORT
 156 void jm_log_error_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 157
 158 /** \brief Send a error message to the logger function. See jm_log() for details.
 159 */
 160 FMILIB_EXPORT
 161 void jm_log_error(jm_callbacks* cb, const char* module, const char* fmt, ...);
 162
 163 /** \brief Send a warning message to the logger function. See jm_log() for details.
 164 */
 165 FMILIB_EXPORT
 166 void jm_log_warning_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 167
 168 /** \brief Send a warning message to the logger function. See jm_log() for details.
 169 */
 170 FMILIB_EXPORT
 171 void jm_log_warning(jm_callbacks* cb, const char* module, const char* fmt, ...);
 172
 173 /** \brief Send an info message to the logger function. See jm_log() for details.
 174 */
 175 FMILIB_EXPORT
 176 void jm_log_info_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 177 /** \brief Send an info message to the logger function. See jm_log() for details.
 178 */
 179 FMILIB_EXPORT
 180 void jm_log_info(jm_callbacks* cb, const char* module, const char* fmt, ...);
 181
 182 /** \brief Send a verbose message to the logger function. See jm_log() for details.
 183 */
 184 FMILIB_EXPORT
 185 void jm_log_verbose_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 186 /** \brief Send a verbose message to the logger function. See jm_log() for details.
 187 */
 188 FMILIB_EXPORT
 189 void jm_log_verbose(jm_callbacks* cb, const char* module, const char* fmt, ...);
 190
 191 #ifdef FMILIB_ENABLE_LOG_LEVEL_DEBUG
 192 /** \brief Send a debug message to the logger function. See jm_log() for details.
 193
 194         Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
 195 */
 196 FMILIB_EXPORT
 197 void jm_log_debug_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
 198 /** \brief Send a debug message to the logger function. See jm_log() for details.
 199
 200         Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
 201 */
 202 FMILIB_EXPORT
 203 void jm_log_debug(jm_callbacks* cb, const char* module, const char* fmt, ...);
 204 #else
 205 /** \brief Send a debug message to the logger function. See jm_log() for details.
 206
 207         Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
 208 */
 209 static void jm_log_debug_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap) {}
 210 /** \brief Send a debug message to the logger function. See jm_log() for details.
 211
 212         Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
 213 */
 214 static void jm_log_debug(jm_callbacks* cb, const char* module, const char* fmt, ...) {}
 215 #endif
 216
 217
 218 /* @}\r
 219 */
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224 /* JM_CONTEXT_H */
 225 #endif