2 Copyright (C) 2012 Modelon AB
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the BSD style license.
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.
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>.
16 #ifndef JM_CALLBACKS_H
17 #define JM_CALLBACKS_H
21 #include <fmilib_config.h>
28 /** \file jm_callbacks.h Definition of ::jm_callbacks and supporting functions
30 * \addtogroup jm_utils
32 \addtogroup jm_callbacks
35 /** \addtogroup jm_callbacks Definition of callbacks struct and supporting functions
37 typedef struct jm_callbacks jm_callbacks;
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
44 /** \brief Allocation function type. */
45 typedef jm_voidp (*jm_malloc_f)(size_t size);
47 /** \brief Re-allocation function type. */
48 typedef jm_voidp (*jm_realloc_f)(void *ptr, size_t size);
50 /** \brief Zero-initialized allocation function type. */
51 typedef jm_voidp (*jm_calloc_f)(size_t numitems, size_t itemsize);
53 /** \brief Free memory function type. */
54 typedef void (*jm_free_f)(jm_voidp p);
60 * \brief Logger callback type.
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.
68 typedef void (*jm_logger_f)(jm_callbacks* c, jm_string module, jm_log_level_enu_t log_level, jm_string message);
70 /** \brief Maximum message size that can be stored in the ::jm_callbacks struct */
71 #define JM_MAX_ERROR_MESSAGE_SIZE 2000
\r
73 /** \brief The callbacks struct is sent to all the modules in the library */
75 /** \brief Allocate non-initialized memory */
77 /** \brief Allocate zero initialized memory */
79 /** \brief Re-allocate memory */
81 /** \brief Free-allocated memory */
83 /** \brief Logging callback */
85 /** \brief Logging level */
86 jm_log_level_enu_t log_level;
87 /** \brief Arbitrary context pointer passed to the logger function */
89 /** \brief The buffer used along with jm_get_last_error() */
90 char errMessageBuffer[JM_MAX_ERROR_MESSAGE_SIZE];
94 * \brief Get the last log message produced by the library.
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.
99 static jm_string jm_get_last_error(jm_callbacks* cb) {return cb->errMessageBuffer; }
102 \brief Clear the last generated log message.
104 static void jm_clear_last_error(jm_callbacks* cb) { cb->errMessageBuffer[0] = 0; }
107 \brief Set the structure to be returned by jm_get_default_callbacks().
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.
113 void jm_set_default_callbacks(jm_callbacks* c);
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().
120 jm_callbacks* jm_get_default_callbacks(void);
123 \brief The default logger implementation prints messages to stderr.
126 void jm_default_logger(jm_callbacks* c, jm_string module, jm_log_level_enu_t log_level, jm_string message);
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.
136 void jm_log(jm_callbacks* cb, const char* module, jm_log_level_enu_t log_level, const char* fmt, ...);
138 /** \copydoc jm_log()
139 @param ap - variable size argument list.
142 void jm_log_v(jm_callbacks* cb, const char* module, jm_log_level_enu_t log_level, const char* fmt, va_list ap);
144 /** \brief Send a fatal error message to the logger function. See jm_log() for details.
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.
151 void jm_log_fatal(jm_callbacks* cb, const char* module, const char* fmt, ...);
153 /** \brief Send a error message to the logger function. See jm_log() for details.
156 void jm_log_error_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
158 /** \brief Send a error message to the logger function. See jm_log() for details.
161 void jm_log_error(jm_callbacks* cb, const char* module, const char* fmt, ...);
163 /** \brief Send a warning message to the logger function. See jm_log() for details.
166 void jm_log_warning_v(jm_callbacks* cb, const char* module, const char* fmt, va_list ap);
168 /** \brief Send a warning message to the logger function. See jm_log() for details.
171 void jm_log_warning(jm_callbacks* cb, const char* module, const char* fmt, ...);
173 /** \brief Send an info message to the logger function. See jm_log() for details.
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.
180 void jm_log_info(jm_callbacks* cb, const char* module, const char* fmt, ...);
182 /** \brief Send a verbose message to the logger function. See jm_log() for details.
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.
189 void jm_log_verbose(jm_callbacks* cb, const char* module, const char* fmt, ...);
191 #ifdef FMILIB_ENABLE_LOG_LEVEL_DEBUG
192 /** \brief Send a debug message to the logger function. See jm_log() for details.
194 Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
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.
200 Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
203 void jm_log_debug(jm_callbacks* cb, const char* module, const char* fmt, ...);
205 /** \brief Send a debug message to the logger function. See jm_log() for details.
207 Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
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.
212 Note that the function is only active if the library is configure with FMILIB_ENABLE_LOG_LEVEL_DEBUG=ON
214 static void jm_log_debug(jm_callbacks* cb, const char* module, const char* fmt, ...) {}