ucs2-interface/ucs-xml/UcsXml.h

   1 /*------------------------------------------------------------------------------------------------*/\r
   2 /* UNICENS XML Parser                                                                             */\r
   3 /* Copyright 2017, Microchip Technology Inc. and its subsidiaries.                                */\r
   4 /*                                                                                                */\r
   5 /* Redistribution and use in source and binary forms, with or without                             */\r
   6 /* modification, are permitted provided that the following conditions are met:                    */\r
   7 /*                                                                                                */\r
   8 /* 1. Redistributions of source code must retain the above copyright notice, this                 */\r
   9 /*    list of conditions and the following disclaimer.                                            */\r
  10 /*                                                                                                */\r
  11 /* 2. Redistributions in binary form must reproduce the above copyright notice,                   */\r
  12 /*    this list of conditions and the following disclaimer in the documentation                   */\r
  13 /*    and/or other materials provided with the distribution.                                      */\r
  14 /*                                                                                                */\r
  15 /* 3. Neither the name of the copyright holder nor the names of its                               */\r
  16 /*    contributors may be used to endorse or promote products derived from                        */\r
  17 /*    this software without specific prior written permission.                                    */\r
  18 /*                                                                                                */\r
  19 /* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"                    */\r
  20 /* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE                      */\r
  21 /* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE                 */\r
  22 /* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE                   */\r
  23 /* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL                     */\r
  24 /* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR                     */\r
  25 /* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER                     */\r
  26 /* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,                  */\r
  27 /* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE                  */\r
  28 /* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */\r
  29 /*------------------------------------------------------------------------------------------------*/\r
  30 #ifndef UCSXML_H_\r
  31 #define UCSXML_H_\r
  32 \r
  33 #ifdef __cplusplus\r
  34 extern "C" {\r
  35 #endif\r
  36 \r
  37 #include <stdbool.h>\r
  38 #include <stdint.h>\r
  39 #include "ucs_api.h"\r
  40 \r
  41 /** Structure holding informations to startup UNICENS (UCS).\r
  42  *  Pass all these variables to the UCS manager structure, but not pInternal.\r
  43  *  */\r
  44 typedef struct\r
  45 {\r
  46     /** The amount of bytes assigned to the async channel*/\r
  47     uint16_t packetBw;\r
  48     /** Array of routes */\r
  49     Ucs_Rm_Route_t *pRoutes;\r
  50     /** Route array size */\r
  51     uint16_t routesSize;\r
  52     /** Array of nodes */\r
  53     Ucs_Rm_Node_t *pNod;\r
  54     /** Node array size */\r
  55     uint16_t nodSize;\r
  56     /** Internal data, to be ignored */\r
  57     void *pInternal;\r
  58 } UcsXmlVal_t;\r
  59 \r
  60 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/\r
  61 /*                            Public API                                */\r
  62 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/\r
  63 \r
  64 /**\r
  65  * \brief Initializes UNICENS XML parser module, parses the given string and\r
  66  *        generate the data needed to run UNICENS (UCS) library.\r
  67  *\r
  68  * \note In case of errors the callback UcsXml_CB_OnError will be raised.\r
  69  * \param xmlString - Zero terminated XML string. The string will not be used\r
  70  *                    after this function call.\r
  71  * \return Structure holding the needed data for UCS. NULL, if there was an error.\r
  72  *         The structure will be created dynamically, to free the data call UcsXml_FreeVal.\r
  73  */\r
  74 UcsXmlVal_t *UcsXml_Parse(const char *xmlString);\r
  75 \r
  76 /**\r
  77  * \brief Frees the given structure, generated by UcsXml_Parse.\r
  78  *\r
  79  * \note In case of errors the callback UcsXml_CB_OnError will be raised.\r
  80  * \param val - The structure to be freed.\r
  81  */\r
  82 void UcsXml_FreeVal(UcsXmlVal_t *val);\r
  83 \r
  84 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/\r
  85 /*                        CALLBACK SECTION                              */\r
  86 /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/\r
  87 \r
  88 /**\r
  89  * \brief Callback whenever a parser error occurs. The message is human readable.\r
  90  * \note This function must be implemented by the integrator.\r
  91  *\r
  92  * \param format - Zero terminated format string (following printf rules)\r
  93  * \param vargsCnt - Amount of parameters stored in "..."\r
  94  */\r
  95 extern void UcsXml_CB_OnError(const char format[], uint16_t vargsCnt, ...);\r
  96 \r
  97 #ifdef __cplusplus\r
  98 }\r
  99 #endif\r
 100 \r
 101 #endif /* UCSXML_H_ */