1 /* 2 * libwbxml, the WBXML Library. 3 * Copyright (C) 2002-2008 Aymerick Jehanne <aymerick@jehanne.org> 4 * Copyright (C) 2011 Michael Bell <michael.bell@opensync.org> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 19 * 20 * LGPL v2.1: http://www.gnu.org/copyleft/lesser.txt 21 * 22 * Contact: aymerick@jehanne.org 23 * Home: http://libwbxml.aymerick.com 24 */ 25 26 /** 27 * @file wbxml_parser.h 28 * @ingroup wbxml_parser 29 * 30 * @author Aymerick Jehanne <aymerick@jehanne.org> 31 * @date 02/03/12 32 * 33 * @brief WBXML Parser - Parse a WBXML document and call user defined Callbacks 34 */ 35 36 #ifndef WBXML_PARSER_H 37 #define WBXML_PARSER_H 38 39 #include "wbxml.h" 40 #include "wbxml_handlers.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif /* __cplusplus */ 45 46 /** @addtogroup wbxml_parser 47 * @{ 48 */ 49 50 /** 51 * Default charset of the WBXML document. Used only in this case : 52 * - No charset found in WBXML document 53 * - No charset was indicated thanks to the function 'wbxml_parser_set_meta_charset()' 54 */ 55 #define WBXML_PARSER_DEFAULT_CHARSET WBXML_CHARSET_UTF_8 56 57 58 typedef struct WBXMLParser_s WBXMLParser; 59 60 /** 61 * @brief Create a WBXML Parser 62 * @return Return the newly created WBXMLParser, or NULL if not enough memory 63 */ 64 WBXML_DECLARE(WBXMLParser *) wbxml_parser_create(void); 65 66 /** 67 * @brief Destroy a WBXML Parser 68 * @param parser The WBXMLParser to destroy 69 */ 70 WBXML_DECLARE(void) wbxml_parser_destroy(WBXMLParser *parser); 71 72 /** 73 * @brief Parse a WBXML document, using User Defined callbacks 74 * @param parser The WBXML Parser to use for parsing 75 * @param wbxml The WBXML document to parse 76 * @param wbxml_len The WBXML document length 77 * @brief Return WBXML_OK if no error, an error code otherwise 78 */ 79 WBXML_DECLARE(WBXMLError) wbxml_parser_parse(WBXMLParser *parser, WB_UTINY *wbxml, WB_ULONG wbxml_len); 80 81 /** 82 * @brief Set User Data for a WBXML Parser 83 * @param parser The WBXML Parser 84 * @param user_data User data (returned as a parameter in every Content Handler callbacks) 85 */ 86 WBXML_DECLARE(void) wbxml_parser_set_user_data(WBXMLParser *parser, void *user_data); 87 88 /** 89 * @brief Set Content Handler for a WBXML Parser 90 * @param parser The WBXML Parser 91 * @param content_handler The Content Handler structure 92 */ 93 WBXML_DECLARE(void) wbxml_parser_set_content_handler(WBXMLParser *parser, WBXMLContentHandler *content_handler); 94 95 /** 96 * @brief Set Main WBXML Languages Table 97 * @param parser The WBXML Parser 98 * @param main_table The Main WBXML Languages Table to set 99 */ 100 WBXML_DECLARE(void) wbxml_parser_set_main_table(WBXMLParser *parser, const WBXMLLangEntry *main_table); 101 102 /** 103 * @brief Force to parse the Document of a given Language 104 * @param parser The WBXML Parser 105 * @param lang The Language 106 * @return TRUE if Language is set, FALSE otherwise 107 * @note This permits to force the WBXML Parser to parse a WBXML Document of a given LanguageD. 108 * If this fonction is used, the internal Public ID of the WBXML Document is ignored. 109 * It is sometimes needed for documents that don't have any WBXML Public ID. 110 */ 111 WBXML_DECLARE(WB_BOOL) wbxml_parser_set_language(WBXMLParser *parser, WBXMLLanguage lang); 112 113 /** 114 * @brief Set additionnal meta-information to help determining the Charset Encoding of the Document to parse 115 * @param parser The WBXML Parser 116 * @param charset The Charset MIBEnum 117 * @return TRUE if Charset is set, FALSE otherwise 118 * @note This information is only used if the Charset Encoding is not specified in WBXML Document: 119 * "The binary XML format contains a representation of the XML document character encoding. 120 * This is the WBXML equivalent of the XML document format encoding attribute, 121 * which is specified in the ?xml processing instruction ... In the case of 122 * an unknown encoding, transport meta-information should be used to determine the character 123 * encoding. If transport meta-information is unavailable, the default encoding of UTF-8 124 * should be assumed." 125 */ 126 WBXML_DECLARE(WB_BOOL) wbxml_parser_set_meta_charset(WBXMLParser *parser, WBXMLCharsetMIBEnum charset); 127 128 /** 129 * @brief Get WBXML Public ID 130 * @param parser The WBXML Parser 131 * @return The WBXML Public ID of current parsing document 132 */ 133 WBXML_DECLARE(WB_ULONG) wbxml_parser_get_wbxml_public_id(WBXMLParser *parser); 134 135 /** 136 * @brief Get XML Public ID 137 * @param parser The WBXML Parser 138 * @return The XML Public ID of current parsing document, or NULL if not found 139 */ 140 WBXML_DECLARE(const WB_UTINY *) wbxml_parser_get_xml_public_id(WBXMLParser *parser); 141 142 /** 143 * @brief Get WBXML Version 144 * @param parser The WBXML Parser 145 * @return The WBXML Version of current parsing document 146 */ 147 WBXML_DECLARE(WBXMLVersion) wbxml_parser_get_wbxml_version(WBXMLParser *parser); 148 149 /** 150 * @brief Return current parsing position in WBXML 151 * @param parser The WBXML Parser 152 * @return The parsing position in WBXML 153 */ 154 WBXML_DECLARE(WB_LONG) wbxml_parser_get_current_byte_index(WBXMLParser *parser); 155 156 /** @} */ 157 158 #ifdef __cplusplus 159 } 160 #endif /* __cplusplus */ 161 162 #endif /* WBXML_PARSER_H */ 163