org.simantics.fmil.core/native/FMILibrary/src/XML/include/FMI2/fmi2_xml_model_description.h

   1 /*\r
   2     Copyright (C) 2012 Modelon AB\r
   3 \r
   4     This program is free software: you can redistribute it and/or modify\r
   5     it under the terms of the BSD style license.\r
   6 \r
   7     This program is distributed in the hope that it will be useful,\r
   8     but WITHOUT ANY WARRANTY; without even the implied warranty of\r
   9     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  10     FMILIB_License.txt file for more details.\r
  11 \r
  12     You should have received a copy of the FMILIB_License.txt file\r
  13     along with this program. If not, contact Modelon AB <http://www.modelon.com>.\r
  14 */\r
  15 \r
  16 \r
  17 \r
  18 /** \file fmi2_xml_model_description.h\r
  19 *  \brief Public interface to the FMI XML C-library.\r
  20 */\r
  21 \r
  22 #ifndef FMI2_XML_MODELDESCRIPTION_H_\r
  23 #define FMI2_XML_MODELDESCRIPTION_H_\r
  24 \r
  25 #include <stddef.h>\r
  26 #include <JM/jm_callbacks.h>\r
  27 #include <JM/jm_named_ptr.h>\r
  28 #include <FMI/fmi_xml_context.h>\r
  29 #include <FMI2/fmi2_types.h>\r
  30 #include <FMI2/fmi2_enums.h>\r
  31 #include <FMI2/fmi2_xml_callbacks.h>\r
  32 \r
  33 #ifdef __cplusplus\r
  34 extern "C" {\r
  35 #endif\r
  36 /**\r
  37 \addtogroup fmi_xml\r
  38   @{\r
  39         \addtogroup fmi2_xml\r
  40   @}\r
  41 */\r
  42 /**\r
  43   \addtogroup fmi2_xml FMI 2.0 XML parsing library.\r
  44    \brief The FMI 2.0 XML parsing library supports processing of model description XML files.\r
  45    @{\r
  46   \name Declarations of structs used in the interface.\r
  47   \brief All the structures used in the interfaces are intended to\r
  48    be treated as opaque objects by the client code.\r
  49   @{  */\r
  50 \r
  51 /** \brief Model structure object */\r
  52 typedef struct fmi2_xml_model_structure_t fmi2_xml_model_structure_t;\r
  53 \r
  54 /**\name  Type definitions supporting structures\r
  55 @{ */\r
  56 typedef struct fmi2_xml_real_typedef_t fmi2_xml_real_typedef_t;\r
  57 typedef struct fmi2_xml_integer_typedef_t fmi2_xml_integer_typedef_t;\r
  58 typedef struct fmi2_xml_enumeration_typedef_t fmi2_xml_enumeration_typedef_t;\r
  59 typedef struct fmi2_xml_variable_typedef_t fmi2_xml_variable_typedef_t;\r
  60 \r
  61 typedef struct fmi2_xml_type_definitions_t fmi2_xml_type_definitions_t;\r
  62 /** @} */\r
  63 \r
  64 /**\name Scalar Variable types */\r
  65 /** @{ */\r
  66 /**General variable type is convenien to unify all the variable list operations */\r
  67 typedef struct fmi2_xml_variable_t fmi2_xml_variable_t;\r
  68 \r
  69 /**Typed variables are needed to support specific attributes */\r
  70 typedef struct fmi2_xml_real_variable_t fmi2_xml_real_variable_t;\r
  71 typedef struct fmi2_xml_integer_variable_t fmi2_xml_integer_variable_t;\r
  72 typedef struct fmi2_xml_string_variable_t fmi2_xml_string_variable_t;\r
  73 typedef struct fmi2_xml_enum_variable_t fmi2_xml_enum_variable_t;\r
  74 typedef struct fmi2_xml_bool_variable_t fmi2_xml_bool_variable_t;\r
  75 /** @} */\r
  76 \r
  77 /**\name Structures encapsulating unit information */\r
  78 /**@{ */\r
  79 typedef struct fmi2_xml_unit_t fmi2_xml_unit_t;\r
  80 typedef struct fmi2_xml_display_unit_t fmi2_xml_display_unit_t;\r
  81 typedef struct fmi2_xml_unit_definitions_t fmi2_xml_unit_definitions_t;\r
  82 /**@} */\r
  83 \r
  84 /**\name FMU capabilities flags */\r
  85 /**@{ */\r
  86 typedef struct fmi2_xml_capabilities_t fmi2_xml_capabilities_t;\r
  87 /**@} */\r
  88 /**     \addtogroup fmi2_xml_gen General information retrieval*/\r
  89 /**     \addtogroup fmi2_xml_init  Constuction, destruction and error checking */\r
  90 \r
  91 /** @} */\r
  92 \r
  93 /**     \addtogroup fmi2_xml_init\r
  94 @{ */\r
  95 /**\r
  96    \brief Allocate the ModelDescription structure and initialize as empty model.\r
  97    @return NULL pointer is returned if memory allocation fails.\r
  98    @param callbacks - Standard FMI callbacks may be sent into the module. The argument is optional (pointer can be zero).\r
  99 */\r
 100 fmi2_xml_model_description_t* fmi2_xml_allocate_model_description( jm_callbacks* callbacks);\r
 101 \r
 102 /**\r
 103     \brief If this configuration option is set, the model description will be\r
 104     checked to follow the variable naming conventions. Variables not following\r
 105     the convention will be logged.\r
 106 */\r
 107 #define FMI2_XML_NAME_CHECK 1\r
 108 \r
 109 /**\r
 110    \brief Parse XML file\r
 111    Repeaded calls invalidate the data structures created with the previous call to fmiParseXML,\r
 112    i.e., fmiClearModelDescrition is automatically called before reading in the new file.\r
 113 \r
 114     @param md A model description object as returned by fmi2_xml_allocate_model_description.\r
 115     @param fileName A name (full path) of the XML file name with model definition.\r
 116         @param xml_callbacks Callbacks to use for processing annotations (may be NULL).\r
 117     @param configuration Specifies how to parse the model description, 0 is\r
 118            default. Other possible configuration is FMI_XML_NAME_CHECK.\r
 119    @return 0 if parsing was successfull. Non-zero value indicates an error.\r
 120 */\r
 121 int fmi2_xml_parse_model_description( fmi2_xml_model_description_t* md,\r
 122                                       const char* fileName,\r
 123                                       fmi2_xml_callbacks_t* xml_callbacks,\r
 124                                       int configuration);\r
 125 \r
 126 /**\r
 127    Clears the data associated with the model description. This is useful if the same object\r
 128    instance is used repeatedly to work with different XML files.\r
 129     @param md A model description object as returned by fmi2_xml_allocate_model_description.\r
 130 */\r
 131 void fmi2_xml_clear_model_description( fmi2_xml_model_description_t* md);\r
 132 \r
 133 /*\r
 134 *    @param md A model description object as returned by fmi2_xml_allocate_model_description.\r
 135 *    @return 1 if model description is empty and 0 if there is some content associated.\r
 136 */\r
 137 int fmi2_xml_is_model_description_empty(fmi2_xml_model_description_t* md);\r
 138 \r
 139 /**Error handling:\r
 140 *  Many functions in the library return pointers to struct. An error is indicated by returning NULL/0-pointer.\r
 141 *  If error is returned than fmiGetLastError() functions can be used to retrieve the error message.\r
 142 *  If logging callbacks were specified then the same information is reported via logger.\r
 143 *  Memory for the error string is allocated and deallocated in the module.\r
 144 *  Client code should not store the pointer to the string since it can become invalid.\r
 145 *    @param md A model description object as returned by fmi2_xml_allocate_model_description.\r
 146 *    @return NULL-terminated string with an error message.\r
 147 */\r
 148 const char* fmi2_xml_get_last_error(fmi2_xml_model_description_t* md);\r
 149 \r
 150 /**\r
 151 fmiClearLastError clears the error message .\r
 152 */\r
 153 void fmi2_xml_clear_last_error(fmi2_xml_model_description_t* md);\r
 154 \r
 155 /**Release the memory allocated\r
 156 @param md A model description object as returned by fmi2_xml_allocate_model_description.\r
 157 */\r
 158 void fmi2_xml_free_model_description(fmi2_xml_model_description_t* md);\r
 159 \r
 160 /** @} */\r
 161 /** \addtogroup fmi2_xml_gen\r
 162  * \brief Functions for retrieving general model information. Memory for the strings is allocated and deallocated in the module.\r
 163  *   All the functions take a model description object as returned by fmi2_xml_allocate_model_description() as a parameter. \r
 164  *   The information is retrieved from the XML file.\r
 165  * @{\r
 166 */\r
 167 const char* fmi2_xml_get_model_name(fmi2_xml_model_description_t* md);\r
 168 \r
 169 const char* fmi2_xml_get_model_identifier_ME(fmi2_xml_model_description_t* md);\r
 170 \r
 171 const char* fmi2_xml_get_model_identifier_CS(fmi2_xml_model_description_t* md);\r
 172 \r
 173 const char* fmi2_xml_get_GUID(fmi2_xml_model_description_t* md);\r
 174 \r
 175 const char* fmi2_xml_get_description(fmi2_xml_model_description_t* md);\r
 176 \r
 177 const char* fmi2_xml_get_author(fmi2_xml_model_description_t* md);\r
 178 const char* fmi2_xml_get_license(fmi2_xml_model_description_t* md);\r
 179 \r
 180 const char* fmi2_xml_get_copyright(fmi2_xml_model_description_t* md);\r
 181 \r
 182 const char* fmi2_xml_get_model_version(fmi2_xml_model_description_t* md);\r
 183 const char* fmi2_xml_get_model_standard_version(fmi2_xml_model_description_t* md);\r
 184 const char* fmi2_xml_get_generation_tool(fmi2_xml_model_description_t* md);\r
 185 const char* fmi2_xml_get_generation_date_and_time(fmi2_xml_model_description_t* md);\r
 186 \r
 187 fmi2_variable_naming_convension_enu_t fmi2_xml_get_naming_convention(fmi2_xml_model_description_t* md);\r
 188 \r
 189 size_t fmi2_xml_get_number_of_continuous_states(fmi2_xml_model_description_t* md);\r
 190 \r
 191 size_t fmi2_xml_get_number_of_event_indicators(fmi2_xml_model_description_t* md);\r
 192 \r
 193 double fmi2_xml_get_default_experiment_start(fmi2_xml_model_description_t* md);\r
 194 \r
 195 double fmi2_xml_get_default_experiment_stop(fmi2_xml_model_description_t* md);\r
 196 \r
 197 double fmi2_xml_get_default_experiment_tolerance(fmi2_xml_model_description_t* md);\r
 198 \r
 199 double fmi2_xml_get_default_experiment_step(fmi2_xml_model_description_t* md);\r
 200 \r
 201 fmi2_fmu_kind_enu_t fmi2_xml_get_fmu_kind(fmi2_xml_model_description_t* md);\r
 202 \r
 203 /** \brief Get a pointer to the internal capabilities array */\r
 204 unsigned int* fmi2_xml_get_capabilities(fmi2_xml_model_description_t* md);\r
 205 \r
 206 /** \brief Get a capability flag by ID */\r
 207 unsigned int fmi2_xml_get_capability(fmi2_xml_model_description_t* , fmi2_capabilities_enu_t id);\r
 208 \r
 209 jm_vector(jm_voidp)* fmi2_xml_get_variables_original_order(fmi2_xml_model_description_t* md);\r
 210 \r
 211 jm_vector(jm_named_ptr)* fmi2_xml_get_variables_alphabetical_order(fmi2_xml_model_description_t* md);\r
 212 \r
 213 jm_vector(jm_voidp)* fmi2_xml_get_variables_vr_order(fmi2_xml_model_description_t* md);\r
 214 \r
 215 /**\r
 216         \brief Get variable by variable name.\r
 217         \param md - the model description\r
 218         \param name - variable name\r
 219         \return variable pointer.\r
 220 */\r
 221 fmi2_xml_variable_t* fmi2_xml_get_variable_by_name(fmi2_xml_model_description_t* md, const char* name);\r
 222 \r
 223 /**\r
 224         \brief Get variable by value reference.\r
 225         \param md - the model description\r
 226         \param baseType - basic data type\r
 227         \param vr - value reference\r
 228         \return variable pointer.\r
 229 */\r
 230 fmi2_xml_variable_t* fmi2_xml_get_variable_by_vr(fmi2_xml_model_description_t* md, fmi2_base_type_enu_t baseType, fmi2_value_reference_t vr);\r
 231 \r
 232 /** \brief Get the number of vendors that had annotations in the XML*/\r
 233 size_t fmi2_xml_get_vendors_num(fmi2_xml_model_description_t* md);\r
 234 \r
 235 /** \brief Get the name of the vendor with that had annotations in the XML by index */\r
 236 const char* fmi2_xml_get_vendor_name(fmi2_xml_model_description_t* md, size_t  index);\r
 237 \r
 238 /** \brief Get the log categories defined in the XML */\r
 239 jm_vector(jm_string)* fmi2_xml_get_log_categories(fmi2_xml_model_description_t* md);\r
 240 \r
 241 /** \brief Get descriptions for the log categories defined in the XML */\r
 242 jm_vector(jm_string)* fmi2_xml_get_log_category_descriptions(fmi2_xml_model_description_t* md);\r
 243 \r
 244 /** \brief Get the source files for ME defined in the XML */\r
 245 jm_vector(jm_string)* fmi2_xml_get_source_files_me(fmi2_xml_model_description_t* md);\r
 246 \r
 247 /** \brief Get the source files for CS defined in the XML */\r
 248 jm_vector(jm_string)* fmi2_xml_get_source_files_cs(fmi2_xml_model_description_t* md);\r
 249 \r
 250 /** \brief Get the model structure pointer. NULL pointer means there was no information present in the XML */\r
 251 fmi2_xml_model_structure_t* fmi2_xml_get_model_structure(fmi2_xml_model_description_t* md);\r
 252 \r
 253 void fmi2_check_variable_naming_conventions(fmi2_xml_model_description_t *md);\r
 254 \r
 255 /** @} */\r
 256 #ifdef __cplusplus\r
 257 }\r
 258 #endif\r
 259 \r
 260 #include "fmi2_xml_type.h"\r
 261 #include "fmi2_xml_unit.h"\r
 262 #include "fmi2_xml_variable.h"\r
 263 #include "fmi2_xml_capabilities.h"\r
 264 #include "fmi2_xml_cosim.h"\r
 265 #include "fmi2_xml_model_structure.h"\r
 266 \r
 267 #endif\r