org.simantics.fmil.core/native/FMILibrary/src/XML/include/FMI1/fmi1_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.
   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 fmi1_xml_model_description.h\r
  19 *  \brief Public interface to the FMI XML C-library.\r
  20 */\r
  21 \r
  22 #ifndef FMI1_XML_MODELDESCRIPTION_H_\r
  23 #define FMI1_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 <FMI1/fmi1_types.h>\r
  30 #include <FMI1/fmi1_enums.h>\r
  31 \r
  32 #ifdef __cplusplus\r
  33 extern "C" {\r
  34 #endif\r
  35 /**\r
  36 \addtogroup fmi_xml\r
  37   @{\r
  38         \addtogroup fmi1_xml\r
  39   @}\r
  40 */\r
  41 /**\r
  42   \addtogroup fmi1_xml FMI 1.0 XML parsing library.\r
  43    \brief The FMI 1.0 XML parsing library supports processing of model description XML files.\r
  44    @{\r
  45   \name Declarations of structs used in the interface.\r
  46   \brief All the structures used in the interfaces are intended to\r
  47    be treated as opaque objects by the client code.\r
  48   @{  */\r
  49 \r
  50 /**\name Vendor annotation supporting structures\r
  51  * @{ \r
  52  */\r
  53 typedef struct fmi1_xml_vendor_list_t fmi1_xml_vendor_list_t;\r
  54 typedef struct fmi1_xml_vendor_t fmi1_xml_vendor_t;\r
  55 typedef struct fmi1_xml_annotation_t fmi1_xml_annotation_t;\r
  56 /** @} */\r
  57 \r
  58 /**\name  Type definitions supporting structures\r
  59 @{ */\r
  60 typedef struct fmi1_xml_real_typedef_t fmi1_xml_real_typedef_t;\r
  61 typedef struct fmi1_xml_integer_typedef_t fmi1_xml_integer_typedef_t;\r
  62 typedef struct fmi1_xml_enumeration_typedef_t fmi1_xml_enumeration_typedef_t;\r
  63 typedef struct fmi1_xml_variable_typedef_t fmi1_xml_variable_typedef_t;\r
  64 \r
  65 typedef struct fmi1_xml_type_definitions_t fmi1_xml_type_definitions_t;\r
  66 /** @} */\r
  67 \r
  68 /**\name Scalar Variable types */\r
  69 /** @{ */\r
  70 /**General variable type is convenien to unify all the variable list operations */\r
  71 typedef struct fmi1_xml_variable_t fmi1_xml_variable_t;\r
  72 \r
  73 /**Typed variables are needed to support specific attributes */\r
  74 typedef struct fmi1_xml_real_variable_t fmi1_xml_real_variable_t;\r
  75 typedef struct fmi1_xml_integer_variable_t fmi1_xml_integer_variable_t;\r
  76 typedef struct fmi1_xml_string_variable_t fmi1_xml_string_variable_t;\r
  77 typedef struct fmi1_xml_enum_variable_t fmi1_xml_enum_variable_t;\r
  78 typedef struct fmi1_xml_bool_variable_t fmi1_xml_bool_variable_t;\r
  79 /** @} */\r
  80 \r
  81 /**\name Structures encapsulating unit information */\r
  82 /**@{ */\r
  83 typedef struct fmi1_xml_unit_t fmi1_xml_unit_t;\r
  84 typedef struct fmi1_xml_display_unit_t fmi1_xml_display_unit_t;\r
  85 typedef struct fmi1_xml_unit_definitions_t fmi1_xml_unit_definitions_t;\r
  86 /**@} */\r
  87 \r
  88 /**\name FMU capabilities flags */\r
  89 /**@{ */\r
  90 typedef struct fmi1_xml_capabilities_t fmi1_xml_capabilities_t;\r
  91 /**@} */\r
  92 /**     \addtogroup fmi1_xml_gen General information retrieval*/\r
  93 /**     \addtogroup fmi1_xml_init  Constuction, destruction and error checking */\r
  94 \r
  95 /** @} */\r
  96 \r
  97 /**     \addtogroup fmi1_xml_init\r
  98 @{ */\r
  99 /**\r
 100    \brief Allocate the ModelDescription structure and initialize as empty model.\r
 101    @return NULL pointer is returned if memory allocation fails.\r
 102    @param callbacks - Standard FMI callbacks may be sent into the module. The argument is optional (pointer can be zero).\r
 103 */\r
 104 fmi1_xml_model_description_t* fmi1_xml_allocate_model_description( jm_callbacks* callbacks);\r
 105 \r
 106 /**\r
 107     \brief If this configuration option is set, the model description will be\r
 108     checked to follow the variable naming conventions. Variables not following\r
 109     the convention will be logged.\r
 110 */\r
 111 #define FMI1_XML_NAME_CHECK 1\r
 112 \r
 113 /**\r
 114    \brief Parse XML file\r
 115    Repeaded calls invalidate the data structures created with the previous call to fmiParseXML,\r
 116    i.e., fmiClearModelDescrition is automatically called before reading in the new file.\r
 117 \r
 118     @param md A model description object as returned by fmi1_xml_allocate_model_description.\r
 119     @param fileName A name (full path) of the XML file name with model definition.\r
 120     @param configuration Specifies how to parse the model description, 0 is\r
 121            default. Other possible configuration is FMI_XML_NAME_CHECK.\r
 122    @return 0 if parsing was successfull. Non-zero value indicates an error.\r
 123 */\r
 124 int fmi1_xml_parse_model_description( fmi1_xml_model_description_t* md,\r
 125                                       const char* fileName,\r
 126                                       int configuration);\r
 127 \r
 128 /**\r
 129    Clears the data associated with the model description. This is useful if the same object\r
 130    instance is used repeatedly to work with different XML files.\r
 131     @param md A model description object as returned by fmi1_xml_allocate_model_description.\r
 132 */\r
 133 void fmi1_xml_clear_model_description( fmi1_xml_model_description_t* md);\r
 134 \r
 135 /*\r
 136 *    @param md A model description object as returned by fmi1_xml_allocate_model_description.\r
 137 *    @return 1 if model description is empty and 0 if there is some content associated.\r
 138 */\r
 139 int fmi1_xml_is_model_description_empty(fmi1_xml_model_description_t* md);\r
 140 \r
 141 /**Error handling:\r
 142 *  Many functions in the library return pointers to struct. An error is indicated by returning NULL/0-pointer.\r
 143 *  If error is returned than fmiGetLastError() functions can be used to retrieve the error message.\r
 144 *  If logging callbacks were specified then the same information is reported via logger.\r
 145 *  Memory for the error string is allocated and deallocated in the module.\r
 146 *  Client code should not store the pointer to the string since it can become invalid.\r
 147 *    @param md A model description object as returned by fmi1_xml_allocate_model_description.\r
 148 *    @return NULL-terminated string with an error message.\r
 149 */\r
 150 const char* fmi1_xml_get_last_error(fmi1_xml_model_description_t* md);\r
 151 \r
 152 /**\r
 153 fmiClearLastError clears the error message .\r
 154 */\r
 155 void fmi1_xml_clear_last_error(fmi1_xml_model_description_t* md);\r
 156 \r
 157 /**Release the memory allocated\r
 158 @param md A model description object as returned by fmi1_xml_allocate_model_description.\r
 159 */\r
 160 void fmi1_xml_free_model_description(fmi1_xml_model_description_t* md);\r
 161 \r
 162 /** @} */\r
 163 /** \addtogroup fmi1_xml_gen\r
 164  * \brief Functions for retrieving general model information. Memory for the strings is allocated and deallocated in the module.\r
 165  *   All the functions take a model description object as returned by fmi1_xml_allocate_model_description() as a parameter. \r
 166  *   The information is retrieved from the XML file.\r
 167  * @{\r
 168 */\r
 169 const char* fmi1_xml_get_model_name(fmi1_xml_model_description_t* md);\r
 170 \r
 171 const char* fmi1_xml_get_model_identifier(fmi1_xml_model_description_t* md);\r
 172 \r
 173 const char* fmi1_xml_get_GUID(fmi1_xml_model_description_t* md);\r
 174 \r
 175 const char* fmi1_xml_get_description(fmi1_xml_model_description_t* md);\r
 176 \r
 177 const char* fmi1_xml_get_author(fmi1_xml_model_description_t* md);\r
 178 \r
 179 const char* fmi1_xml_get_model_version(fmi1_xml_model_description_t* md);\r
 180 const char* fmi1_xml_get_model_standard_version(fmi1_xml_model_description_t* md);\r
 181 const char* fmi1_xml_get_generation_tool(fmi1_xml_model_description_t* md);\r
 182 const char* fmi1_xml_get_generation_date_and_time(fmi1_xml_model_description_t* md);\r
 183 \r
 184 fmi1_variable_naming_convension_enu_t fmi1_xml_get_naming_convention(fmi1_xml_model_description_t* md);\r
 185 \r
 186 unsigned int fmi1_xml_get_number_of_continuous_states(fmi1_xml_model_description_t* md);\r
 187 \r
 188 unsigned int fmi1_xml_get_number_of_event_indicators(fmi1_xml_model_description_t* md);\r
 189 \r
 190 double fmi1_xml_get_default_experiment_start(fmi1_xml_model_description_t* md);\r
 191 \r
 192 void fmi1_xml_set_default_experiment_start(fmi1_xml_model_description_t* md, double);\r
 193 \r
 194 double fmi1_xml_get_default_experiment_stop(fmi1_xml_model_description_t* md);\r
 195 \r
 196 void fmi1_xml_set_default_experiment_stop(fmi1_xml_model_description_t* md, double);\r
 197 \r
 198 double fmi1_xml_get_default_experiment_tolerance(fmi1_xml_model_description_t* md);\r
 199 \r
 200 void fmi1_xml_set_default_experiment_tolerance(fmi1_xml_model_description_t* md, double);\r
 201 \r
 202 fmi1_fmu_kind_enu_t fmi1_xml_get_fmu_kind(fmi1_xml_model_description_t* md);\r
 203 \r
 204 fmi1_xml_capabilities_t* fmi1_xml_get_capabilities(fmi1_xml_model_description_t* md);\r
 205 \r
 206 jm_vector(jm_voidp)* fmi1_xml_get_variables_original_order(fmi1_xml_model_description_t* md);\r
 207 \r
 208 jm_vector(jm_named_ptr)* fmi1_xml_get_variables_alphabetical_order(fmi1_xml_model_description_t* md);\r
 209 \r
 210 jm_vector(jm_voidp)* fmi1_xml_get_variables_vr_order(fmi1_xml_model_description_t* md);\r
 211 \r
 212 /**\r
 213         \brief Get variable by variable name.\r
 214         \param md - the model description\r
 215         \param name - variable name\r
 216         \return variable pointer.\r
 217 */\r
 218 fmi1_xml_variable_t* fmi1_xml_get_variable_by_name(fmi1_xml_model_description_t* md, const char* name);\r
 219 \r
 220 /**\r
 221         \brief Get variable by value reference.\r
 222         \param md - the model description\r
 223         \param baseType - basic data type\r
 224         \param vr - value reference\r
 225         \return variable pointer.\r
 226 */\r
 227 fmi1_xml_variable_t* fmi1_xml_get_variable_by_vr(fmi1_xml_model_description_t* md, fmi1_base_type_enu_t baseType, fmi1_value_reference_t vr);\r
 228 \r
 229 /** @} */\r
 230 #ifdef __cplusplus\r
 231 }\r
 232 #endif\r
 233 \r
 234 #include "fmi1_xml_type.h"\r
 235 #include "fmi1_xml_unit.h"\r
 236 #include "fmi1_xml_variable.h"\r
 237 #include "fmi1_xml_vendor_annotations.h"\r
 238 #include "fmi1_xml_capabilities.h"\r
 239 #include "fmi1_xml_cosim.h"\r
 240 \r
 241 #endif\r