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_conv.h 28 * @ingroup wbxml_conv 29 * 30 * @author Aymerick Jehanne <aymerick@jehanne.org> 31 * @date 03/02/23 32 * 33 * @brief WBXML Convertion Library (XML to WBXML, and WBXML to XML) 34 */ 35 36 #ifndef WBXML_CONV_H 37 #define WBXML_CONV_H 38 39 #include "wbxml.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif /* __cplusplus */ 44 45 /** @addtogroup wbxml_conv 46 * @{ 47 */ 48 49 /** WBXML Versions (WBXML tokens) */ 50 typedef enum WBXMLVersion_e { 51 WBXML_VERSION_UNKNOWN = -1, /**< Unknown WBXML Version */ 52 WBXML_VERSION_10 = 0x00, /**< WBXML 1.0 Token */ 53 WBXML_VERSION_11 = 0x01, /**< WBXML 1.1 Token */ 54 WBXML_VERSION_12 = 0x02, /**< WBXML 1.2 Token */ 55 WBXML_VERSION_13 = 0x03 /**< WBXML 1.3 Token */ 56 } WBXMLVersion; 57 58 59 /* 60 * Possible Compilation Flags: 61 * --------------------------- 62 * 63 * WBXML_SUPPORT_WML 64 * WBXML_SUPPORT_WTA 65 * WBXML_SUPPORT_SI 66 * WBXML_SUPPORT_SL 67 * WBXML_SUPPORT_CO 68 * WBXML_SUPPORT_PROV 69 * WBXML_SUPPORT_EMN 70 * WBXML_SUPPORT_DRMREL 71 * WBXML_SUPPORT_OTA_SETTINGS 72 * WBXML_SUPPORT_SYNCML 73 * WBXML_SUPPORT_WV 74 * WBXML_SUPPORT_AIRSYNC 75 * WBXML_SUPPORT_CONML 76 */ 77 78 79 /** Supported WBXML Languages */ 80 typedef enum WBXMLLanguage_e { 81 WBXML_LANG_UNKNOWN = 0, /**< Unknown / Not Specified */ 82 83 /* WAP */ 84 #if defined( WBXML_SUPPORT_WML ) 85 WBXML_LANG_WML10 = 1101, /**< WML 1.0 */ 86 WBXML_LANG_WML11 = 1102, /**< WML 1.1 */ 87 WBXML_LANG_WML12 = 1103, /**< WML 1.2 */ 88 WBXML_LANG_WML13 = 1104, /**< WML 1.3 */ 89 #endif /* WBXML_SUPPORT_WML */ 90 91 #if defined( WBXML_SUPPORT_WTA ) 92 WBXML_LANG_WTA10 = 1201, /**< WTA 1.0 */ 93 WBXML_LANG_WTAWML12 = 1202, /**< WTAWML 1.2 */ 94 WBXML_LANG_CHANNEL11 = 1203, /**< CHANNEL 1.1 */ 95 WBXML_LANG_CHANNEL12 = 1204, /**< CHANNEL 1.2 */ 96 #endif /* WBXML_SUPPORT_WTA */ 97 98 #if defined( WBXML_SUPPORT_SI ) 99 WBXML_LANG_SI10 = 1301, /**< SI 1.0 */ 100 #endif /* WBXML_SUPPORT_SI */ 101 102 #if defined( WBXML_SUPPORT_SL ) 103 WBXML_LANG_SL10 = 1401, /**< SL 1.0 */ 104 #endif /* WBXML_SUPPORT_SL */ 105 106 #if defined( WBXML_SUPPORT_CO ) 107 WBXML_LANG_CO10 = 1501, /**< CO 1.0 */ 108 #endif /* WBXML_SUPPORT_CO */ 109 110 #if defined( WBXML_SUPPORT_PROV ) 111 WBXML_LANG_PROV10 = 1601, /**< PROV 1.0 */ 112 #endif /* WBXML_SUPPORT_PROV */ 113 114 #if defined( WBXML_SUPPORT_EMN ) 115 WBXML_LANG_EMN10 = 1701, /**< EMN 1.0 */ 116 #endif /* WBXML_SUPPORT_EMN */ 117 118 #if defined( WBXML_SUPPORT_DRMREL ) 119 WBXML_LANG_DRMREL10 = 1801, /**< DRMREL 1.0 */ 120 #endif /* WBXML_SUPPORT_DRMREL */ 121 122 #if defined( WBXML_SUPPORT_OTA_SETTINGS ) 123 /* Ericsson / Nokia OTA Settings v7.0 */ 124 WBXML_LANG_OTA_SETTINGS = 1901, /**< OTA Settings */ 125 #endif /* WBXML_SUPPORT_OTA_SETTINGS */ 126 127 /* SyncML */ 128 #if defined( WBXML_SUPPORT_SYNCML ) 129 WBXML_LANG_SYNCML_SYNCML10 = 2001, /**< SYNCML 1.0 */ 130 WBXML_LANG_SYNCML_DEVINF10 = 2002, /**< DEVINF 1.0 */ 131 WBXML_LANG_SYNCML_METINF10 = 2003, /**< METINF 1.0 */ 132 133 WBXML_LANG_SYNCML_SYNCML11 = 2101, /**< SYNCML 1.1 */ 134 WBXML_LANG_SYNCML_DEVINF11 = 2102, /**< DEVINF 1.1 */ 135 WBXML_LANG_SYNCML_METINF11 = 2103, /**< METINF 1.1 */ 136 137 WBXML_LANG_SYNCML_SYNCML12 = 2201, /**< SYNCML 1.2 */ 138 WBXML_LANG_SYNCML_DEVINF12 = 2202, /**< DEVINF 1.2 */ 139 WBXML_LANG_SYNCML_METINF12 = 2203, /**< METINF 1.2 */ 140 WBXML_LANG_SYNCML_DMDDF12 = 2204, /**< DMDDF 1.2 */ 141 #endif /* WBXML_SUPPORT_SYNCML */ 142 143 /* Wireless-Village */ 144 #if defined( WBXML_SUPPORT_WV ) 145 WBXML_LANG_WV_CSP11 = 2301, /**< WV CSP 1.1 */ 146 WBXML_LANG_WV_CSP12 = 2302, /**< WV CSP 1.2 */ 147 #endif /* WBXML_SUPPORT_WV */ 148 149 /* Microsoft AirSync */ 150 #if defined( WBXML_SUPPORT_AIRSYNC ) 151 WBXML_LANG_AIRSYNC = 2401, /**< AirSync */ 152 WBXML_LANG_ACTIVESYNC = 2402, /**< ActiveSync */ 153 #endif /* WBXML_SUPPORT_AIRSYNC */ 154 155 /* Nokia ConML */ 156 #if defined( WBXML_SUPPORT_CONML ) 157 WBXML_LANG_CONML = 2501 /**< ConML */ 158 #endif /* WBXML_SUPPORT_CONML */ 159 } WBXMLLanguage; 160 161 162 /** Supported WBXML Charsets MIBEnum */ 163 typedef enum WBXMLCharsetMIBEnum_e { 164 WBXML_CHARSET_UNKNOWN = 0, /**< Unknown Charset */ 165 WBXML_CHARSET_US_ASCII = 3, /**< US-ASCII */ 166 WBXML_CHARSET_ISO_8859_1 = 4, /**< ISO-8859-1 */ 167 WBXML_CHARSET_ISO_8859_2 = 5, /**< ISO-8859-2 */ 168 WBXML_CHARSET_ISO_8859_3 = 6, /**< ISO-8859-3 */ 169 WBXML_CHARSET_ISO_8859_4 = 7, /**< ISO-8859-4 */ 170 WBXML_CHARSET_ISO_8859_5 = 8, /**< ISO-8859-5 */ 171 WBXML_CHARSET_ISO_8859_6 = 9, /**< ISO-8859-6 */ 172 WBXML_CHARSET_ISO_8859_7 = 10, /**< ISO-8859-7 */ 173 WBXML_CHARSET_ISO_8859_8 = 11, /**< ISO-8859-8 */ 174 WBXML_CHARSET_ISO_8859_9 = 12, /**< ISO-8859-9 */ 175 WBXML_CHARSET_SHIFT_JIS = 17, /**< Shift_JIS */ 176 WBXML_CHARSET_UTF_8 = 106, /**< UTF-8 */ 177 WBXML_CHARSET_ISO_10646_UCS_2 = 1000, /**< ISO-10646-UCS-2 */ 178 WBXML_CHARSET_UTF_16 = 1015, /**< UTF-16 */ 179 WBXML_CHARSET_BIG5 = 2026 /**< Big5 */ 180 } WBXMLCharsetMIBEnum; 181 182 183 /** 184 * @brief Type of XML Generation 185 * @note Canonical Form is defined here: http://www.jclark.com/xml/canonxml.html 186 */ 187 typedef enum WBXMLGenXMLType_e { 188 WBXML_GEN_XML_COMPACT = 0, /**< Compact XML generation */ 189 WBXML_GEN_XML_INDENT = 1, /**< Indented XML generation */ 190 WBXML_GEN_XML_CANONICAL = 2 /**< Canonical XML generation */ 191 } WBXMLGenXMLType; 192 193 194 /** 195 * @brief Parameters when generating an XML document 196 */ 197 typedef struct WBXMLGenXMLParams_s { 198 WBXMLGenXMLType gen_type; /**< WBXML_GEN_XML_COMPACT | WBXML_GEN_XML_INDENT | WBXML_GEN_XML_CANONICAL (Default: WBXML_GEN_XML_INDENT) */ 199 WBXMLLanguage lang; /**< Force document Language (overwrite document Public ID) */ 200 WBXMLCharsetMIBEnum charset; /**< Set document Language (does not overwrite document character set) */ 201 WB_UTINY indent; /**< Indentation Delta, when using WBXML_GEN_XML_INDENT Generation Type (Default: 0) */ 202 WB_BOOL keep_ignorable_ws; /**< Keep Ignorable Whitespaces (Default: FALSE) */ 203 } WBXMLGenXMLParams; 204 205 /** 206 * @brief Parameters when generating a WBXML document 207 */ 208 typedef struct WBXMLGenWBXMLParams_s { 209 WBXMLVersion wbxml_version; /**< WBXML Version */ 210 WB_BOOL keep_ignorable_ws; /**< Keep Ignorable Whitespaces (Default: FALSE) */ 211 WB_BOOL use_strtbl; /**< Generate String Table (Default: TRUE) */ 212 WB_BOOL produce_anonymous; /**< Produce an anonymous document (Default: FALSE) */ 213 } WBXMLGenWBXMLParams; 214 215 /** 216 * Wrapper around wbxml_conv_wbxml2_withlen() 217 * 218 * This macro is provided for backward compatibility. You can use it if you are 219 * sure that the output XML document will be encoded in a charset that is NULL 220 * terminated and that can't contains any NULL character in it. For example 221 * this macro works for US-ASCII or UTF-8 encoded documents, but not for UTF-16 222 * encoded documents. 223 */ 224 #define wbxml_conv_wbxml2xml(a,b,c,d) wbxml_conv_wbxml2xml_withlen(a,b,c,NULL,d) 225 226 /** 227 * @brief Convert WBXML to XML 228 * @param wbxml [in] WBXML Document to convert 229 * @param wbxml_len [in] Length of WBXML Document 230 * @param xml [out] Resulting XML Document 231 * @param xml_len [out] XML Document length 232 * @param params [in] Parameters (if NULL, default values are used) 233 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 234 */ 235 WBXML_DECLARE(WBXMLError) wbxml_conv_wbxml2xml_withlen(WB_UTINY *wbxml, 236 WB_ULONG wbxml_len, 237 WB_UTINY **xml, 238 WB_ULONG *xml_len, 239 WBXMLGenXMLParams *params) LIBWBXML_DEPRECATED; 240 241 /** 242 * Wrapper around wbxml_conv_xml2wbxml_withlen() 243 * 244 * This macro is provided for backward compatibility. You can use it if you are 245 * sure that the input XML document is encoded in a charset that is NULL terminated 246 * and that can't contains any NULL character in it. For example this macro 247 * works for US-ASCII or UTF-8 encoded documents, but not for UTF-16 encoded 248 * documents. 249 */ 250 #define wbxml_conv_xml2wbxml(a,b,c,d) wbxml_conv_xml2wbxml_withlen(a,WBXML_STRLEN(a),b,c,d) 251 252 /** 253 * @brief Convert XML to WBXML 254 * @param xml [in] XML Document to convert 255 * @param xml_len [in] Length of XML Document 256 * @param wbxml [out] Resulting WBXML Document 257 * @param wbxml_len [out] Length of resulting WBXML Document 258 * @param params [in] Parameters (if NULL, default values are used) 259 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 260 */ 261 WBXML_DECLARE(WBXMLError) wbxml_conv_xml2wbxml_withlen(WB_UTINY *xml, 262 WB_ULONG xml_len, 263 WB_UTINY **wbxml, 264 WB_ULONG *wbxml_len, 265 WBXMLGenWBXMLParams *params) LIBWBXML_DEPRECATED; 266 267 /** 268 * @description This is a container for the WBXML to XML conversion parameters. 269 * An object style is used because it is much better expandable 270 * in terms of downward binary compatibility. 271 */ 272 typedef struct WBXMLConvWBXML2XML_s WBXMLConvWBXML2XML; 273 274 /** 275 * @brief Create a new WBXML to XML converter with the default configuration. 276 * @param conv [out] a reference to the pointer of the new converter 277 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 278 */ 279 WBXML_DECLARE(WBXMLError) wbxml_conv_wbxml2xml_create(WBXMLConvWBXML2XML **conv); 280 281 /** 282 * @brief Set the XML generation type (default: WBXML_GEN_XML_INDENT). 283 * @param conv [in] the converter 284 * @param gen_type [in] generation type 285 */ 286 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_set_gen_type(WBXMLConvWBXML2XML *conv, WBXMLGenXMLType gen_type); 287 288 /** 289 * @brief Set the used WBXML language. 290 * The language is usually detected by the specified public ID in the document. 291 * If the public ID is set then it overrides the language. 292 * @param conv [in] the converter 293 * @param lang [in] language (e.g. SYNCML12) 294 */ 295 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_set_language(WBXMLConvWBXML2XML *conv, WBXMLLanguage lang); 296 297 /** 298 * @brief Set the used character set. 299 * The default character set is UTF-8. 300 * If the document specifies a character set by it own 301 * then this character set overrides the parameter charset. 302 * @param conv [in] the converter 303 * @param charset [in] the character set 304 */ 305 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_set_charset(WBXMLConvWBXML2XML *conv, WBXMLCharsetMIBEnum charset); 306 307 /** 308 * @brief Set the indent of the generated XML document (please see EXPAT default). 309 * @param conv [in] the converter 310 * @param indent [in] the number of blanks 311 */ 312 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_set_indent(WBXMLConvWBXML2XML *conv, WB_UTINY indent); 313 314 /** 315 * @brief Enable whitespace preservation (default: FALSE). 316 * @param conv [in] the converter 317 */ 318 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_enable_preserve_whitespaces(WBXMLConvWBXML2XML *conv); 319 320 /** 321 * @brief Convert WBXML to XML 322 * @param conv [in] the converter 323 * @param wbxml [in] WBXML Document to convert 324 * @param wbxml_len [in] Length of WBXML Document 325 * @param xml [out] Resulting XML Document 326 * @param xml_len [out] XML Document length 327 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 328 */ 329 WBXML_DECLARE(WBXMLError) wbxml_conv_wbxml2xml_run(WBXMLConvWBXML2XML *conv, 330 WB_UTINY *xml, 331 WB_ULONG xml_len, 332 WB_UTINY **wbxml, 333 WB_ULONG *wbxml_len); 334 335 /** 336 * @brief Destroy the converter object. 337 * @param [in] the converter 338 */ 339 WBXML_DECLARE(void) wbxml_conv_wbxml2xml_destroy(WBXMLConvWBXML2XML *conv); 340 341 /** 342 * @description This is a container for the XML to WBXML conversion parameters. 343 * An object style is used because it is much better expandable 344 * in terms of downward binary compatibility. 345 */ 346 typedef struct WBXMLConvXML2WBXML_s WBXMLConvXML2WBXML; 347 348 /** 349 * @brief Create a new WBXML to XML converter with the default configuration. 350 * @param conv [out] a reference to the pointer of the new converter 351 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 352 */ 353 WBXML_DECLARE(WBXMLError) wbxml_conv_xml2wbxml_create(WBXMLConvXML2WBXML **conv); 354 355 /** 356 * @brief Set the WBXML version (default: 1.3). 357 * @param conv [in] the converter 358 * @param indent [in] the number of blanks 359 */ 360 WBXML_DECLARE(void) wbxml_conv_xml2wbxml_set_version(WBXMLConvXML2WBXML *conv, 361 WBXMLVersion wbxml_version); 362 363 /** 364 * @brief Enable whitespace preservation (default: FALSE/DISABLED). 365 * @param conv [in] the converter 366 */ 367 WBXML_DECLARE(void) wbxml_conv_xml2wbxml_enable_preserve_whitespaces(WBXMLConvXML2WBXML *conv); 368 369 /** 370 * @brief Disable string table (default: TRUE/ENABLED). 371 * @param conv [in] the converter 372 */ 373 WBXML_DECLARE(void) wbxml_conv_xml2wbxml_disable_string_table(WBXMLConvXML2WBXML *conv); 374 375 /** 376 * @desription: Disable public ID (default: TRUE/ENABLED). 377 * Usually you don't want to produce WBXML documents which are 378 * really anonymous. You want a known public ID or a DTD name 379 * to determine the document type. Some specifications like 380 * Microsoft's ActiveSync explicitely require fully anonymous 381 * WBXML documents. If you need this then you must disable 382 * the public ID mechanism. 383 * @param conv [in] the converter 384 */ 385 WBXML_DECLARE(void) wbxml_conv_xml2wbxml_disable_public_id(WBXMLConvXML2WBXML *conv); 386 387 /** 388 * @brief Convert XML to WBXML 389 * @param conv [in] the converter 390 * @param xml [in] XML Document to convert 391 * @param xml_len [in] Length of XML Document 392 * @param wbxml [out] Resulting WBXML Document 393 * @param wbxml_len [out] Length of resulting WBXML Document 394 * @return WBXML_OK if conversion succeeded, an Error Code otherwise 395 */ 396 WBXML_DECLARE(WBXMLError) wbxml_conv_xml2wbxml_run(WBXMLConvXML2WBXML *conv, 397 WB_UTINY *xml, 398 WB_ULONG xml_len, 399 WB_UTINY **wbxml, 400 WB_ULONG *wbxml_len); 401 402 /** 403 * @brief Destroy the converter object. 404 * @param [in] the converter 405 */ 406 WBXML_DECLARE(void) wbxml_conv_xml2wbxml_destroy(WBXMLConvXML2WBXML *conv); 407 408 /** @} */ 409 410 #ifdef __cplusplus 411 } 412 #endif /* __cplusplus */ 413 414 #endif /* WBXML_CONV_H */ 415