1 /* 2 gg_xml.h -- Gaia common support for XML documents 3 4 version 5.0, 2020 August 1 5 6 Author: Sandro Furieri a.furieri@lqt.it 7 8 ------------------------------------------------------------------------------ 9 10 Version: MPL 1.1/GPL 2.0/LGPL 2.1 11 12 The contents of this file are subject to the Mozilla Public License Version 13 1.1 (the "License"); you may not use this file except in compliance with 14 the License. You may obtain a copy of the License at 15 http://www.mozilla.org/MPL/ 16 17 Software distributed under the License is distributed on an "AS IS" basis, 18 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 19 for the specific language governing rights and limitations under the 20 License. 21 22 The Original Code is the SpatiaLite library 23 24 The Initial Developer of the Original Code is Alessandro Furieri 25 26 Portions created by the Initial Developer are Copyright (C) 2008-2021 27 the Initial Developer. All Rights Reserved. 28 29 Contributor(s): 30 31 Alternatively, the contents of this file may be used under the terms of 32 either the GNU General Public License Version 2 or later (the "GPL"), or 33 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 34 in which case the provisions of the GPL or the LGPL are applicable instead 35 of those above. If you wish to allow use of your version of this file only 36 under the terms of either the GPL or the LGPL, and not to allow others to 37 use your version of this file under the terms of the MPL, indicate your 38 decision by deleting the provisions above and replace them with the notice 39 and other provisions required by the GPL or the LGPL. If you do not delete 40 the provisions above, a recipient may use your version of this file under 41 the terms of any one of the MPL, the GPL or the LGPL. 42 43 */ 44 45 46 /** 47 \file gg_xml.h 48 49 Geometry handling functions: XML document 50 */ 51 52 #ifndef _GG_XML_H 53 #ifndef DOXYGEN_SHOULD_SKIP_THIS 54 #define _GG_XML_H 55 #endif 56 57 #ifdef __cplusplus 58 extern "C" 59 { 60 #endif 61 62 /* constant values for XmlBLOB */ 63 64 /** XmlBLOB internal marker: START */ 65 #define GAIA_XML_START 0x00 66 /** XmlBLOB internal marker: END */ 67 #define GAIA_XML_END 0xDD 68 /** XmlBLOB internal marker: HEADER */ 69 #define GAIA_XML_HEADER 0xAC 70 /** XmlBLOB internal marker: LEGACY HEADER */ 71 #define GAIA_XML_LEGACY_HEADER 0xAB 72 /** XmlBLOB internal marker: SCHEMA */ 73 #define GAIA_XML_SCHEMA 0xBA 74 /** XmlBLOB internal marker: FILEID */ 75 #define GAIA_XML_FILEID 0xCA 76 /** XmlBLOB internal marker: PARENTID */ 77 #define GAIA_XML_PARENTID 0xDA 78 /** XmlBLOB internal marker: TITLE */ 79 #define GAIA_XML_NAME 0xDE 80 /** XmlBLOB internal marker: TITLE */ 81 #define GAIA_XML_TITLE 0xDB 82 /** XmlBLOB internal marker: ABSTRACT */ 83 #define GAIA_XML_ABSTRACT 0xDC 84 /** XmlBLOB internal marker: GEOMETRY */ 85 #define GAIA_XML_GEOMETRY 0xDD 86 /** XmlBLOB internal marker: CRC32 */ 87 #define GAIA_XML_CRC32 0xBC 88 /** XmlBLOB internal marker: PAYLOAD */ 89 #define GAIA_XML_PAYLOAD 0xCB 90 91 /* bitmasks for XmlBLOB-FLAG */ 92 93 /** XmlBLOB FLAG - LITTLE_ENDIAN bitmask */ 94 #define GAIA_XML_LITTLE_ENDIAN 0x01 95 /** XmlBLOB FLAG - COMPRESSED bitmask */ 96 #define GAIA_XML_COMPRESSED 0x02 97 /** XmlBLOB FLAG - VALIDATED bitmask */ 98 #define GAIA_XML_VALIDATED 0x04 99 /** XmlBLOB FLAG - ISO METADATA bitmask */ 100 #define GAIA_XML_ISO_METADATA 0x80 101 /** XmlBLOB FLAG - SLDSE VECTOR STYLE bitmask */ 102 #define GAIA_XML_SLD_SE_RASTER_STYLE 0x10 103 /** XmlBLOB FLAG - SLDSE VECTOR STYLE bitmask */ 104 #define GAIA_XML_SLD_SE_VECTOR_STYLE 0x40 105 /** XmlBLOB FLAG - SLD STYLE bitmask */ 106 #define GAIA_XML_SLD_STYLE 0x48 107 /** XmlBLOB FLAG - SVG bitmask */ 108 #define GAIA_XML_SVG 0x20 109 /** XmlBLOB FLAG - GPX bitmask */ 110 #define GAIA_XML_GPX 0x08 111 /** XmlBLOB FLAG - MapConfig bitmask */ 112 #define GAIA_XML_MAP_CONFIG 0x88 113 114 115 /* function prototypes */ 116 117 #ifndef DOXYGEN_SHOULD_IGNORE_THIS 118 #ifdef ENABLE_LIBXML2 /* LIBXML2 enabled: supporting XML documents */ 119 #endif 120 121 /** 122 return the LIBXML2 version string 123 124 \return a text string identifying the current LIBXML2 version 125 126 \note the version string corresponds to dynamically allocated memory: 127 so you are responsible to free() it [unless SQLite will take care 128 of memory cleanup via buffer binding]. 129 */ 130 GAIAGEO_DECLARE char *gaia_libxml2_version (void); 131 132 /** 133 Creates an XmlBLOB buffer 134 135 \param p_cache a memory pointer returned by spatialite_alloc_connection() 136 \param xml pointer to the XML document (XmlBLOB payload). 137 \param xml_len lenght of the XML document (in bytes). 138 \param compressed if TRUE the returned XmlBLOB will be zip-compressed. 139 \param schemaURI if not NULL the XML document will be assumed to be valid 140 only if it successfully passes a formal Schema valitadion. 141 \param result on completion will containt a pointer to XmlBLOB: 142 NULL on failure. 143 \param size on completion this variable will contain the XmlBLOB's size (in bytes) 144 \param parsing_errors on completion this variable will contain all error/warning 145 messages emitted during the XML Parsing step. Can be set to NULL so to ignore any message. 146 \param schema_validation_errors on completion this variable will contain all error/warning 147 messages emitted during the XML Schema Validation step. Can be set to NULL so to ignore any message. 148 149 \sa gaiaXmlFromBlob, gaiaXmlTextFromBlob, gaiaXmlBlobGetLastParseError, 150 gaiaXmlBlobGetLastValidateError 151 152 \note the XmlBLOB buffer corresponds to dynamically allocated memory: 153 so you are responsible to free() it [unless SQLite will take care 154 of memory cleanup via buffer binding]. 155 */ 156 GAIAGEO_DECLARE void gaiaXmlToBlob (const void *p_cache, 157 const unsigned char *xml, int xml_len, 158 int compressed, const char *schemaURI, 159 unsigned char **result, int *size, 160 char **parsing_errors, 161 char **schema_validation_errors); 162 163 /** 164 Extract an XMLDocument from within an XmlBLOB buffer 165 166 \param blob pointer to the XmlBLOB buffer. 167 \param size XmlBLOB's size (in bytes). 168 \param indent if a negative value is passed the XMLDocument will 169 be extracted exactly as it was when loaded. Otherwise it will be 170 properly formatted using the required intenting (max. 8); ZERO 171 means that the whole XML Document will consist of a single line. 172 173 \return the pointer to the newly created XMLDocument buffer: NULL on failure 174 175 \sa gaiaXmlToBlob, gaiaXmlFromBlob 176 177 \note the returned XMLDocument will always be encoded as UTF-8 (irrespectively 178 from the internal encoding declaration), so to allow any further processing as 179 SQLite TEXT. 180 181 \note the XMLDocument buffer corresponds to dynamically allocated memory: 182 so you are responsible to free() it before or after. 183 */ 184 GAIAGEO_DECLARE char *gaiaXmlTextFromBlob (const unsigned char *blob, 185 int size, int indent); 186 187 /** 188 Extract an XMLDocument from within an XmlBLOB buffer 189 190 \param blob pointer to the XmlBLOB buffer. 191 \param size XmlBLOB's size (in bytes). 192 \param indent if a negative value is passed the XMLDocument will 193 be extracted exactly as it was when loaded. Otherwise it will be 194 properly formatted using the required intenting (max. 8); ZERO 195 means that the whole XML Document will consist of a single line. 196 \param result pointer to the memory buffer containing the XML Document 197 \param res_size dimension (in bytes) of the XML Document memory buffer 198 (both values will be passed back after successful completion). 199 200 201 \sa gaiaXmlToBlob, gaiaXmlTextFromBlob 202 203 \note the returned XMLDocument will always respect the internal encoding declaration, 204 and may not support any further processing as SQLite TEXT if it's not UTF-8. 205 206 \note the XMLDocument buffer corresponds to dynamically allocated memory: 207 so you are responsible to free() it before or after. 208 */ 209 GAIAGEO_DECLARE void gaiaXmlFromBlob (const unsigned char *blob, 210 int size, int indent, 211 unsigned char **result, 212 int *res_size); 213 214 /** 215 Checks if a BLOB actually is a valid XmlBLOB buffer 216 217 \param blob pointer to the XmlBLOB buffer. 218 \param size XmlBLOB's size (in bytes). 219 220 \return TRUE or FALSE 221 222 \sa gaiaIsCompressedXmlBlob, gaiaIsSchemaValidatedXmlBlob, 223 gaiaIsIsoMetadataXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 224 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob, 225 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 226 */ 227 GAIAGEO_DECLARE int gaiaIsValidXmlBlob (const unsigned char *blob, 228 int size); 229 230 /** 231 Checks if a valid XmlBLOB buffer is compressed or not 232 233 \param blob pointer to the XmlBLOB buffer. 234 \param size XmlBLOB's size (in bytes). 235 236 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB; -1 in any other case. 237 238 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 239 gaiaIsIsoMetadataXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 240 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob, 241 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 242 */ 243 GAIAGEO_DECLARE int gaiaIsCompressedXmlBlob (const unsigned char *blob, 244 int size); 245 246 /** 247 Checks if a valid XmlBLOB buffer does contain an ISO Metadata or not 248 249 \param blob pointer to the XmlBLOB buffer. 250 \param size XmlBLOB's size (in bytes). 251 252 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB; -1 in any other case. 253 254 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 255 gaiaIsCompressedXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 256 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob, 257 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 258 */ 259 GAIAGEO_DECLARE int gaiaIsIsoMetadataXmlBlob (const unsigned char *blob, 260 int size); 261 262 /** 263 Checks if a valid XmlBLOB buffer does contain an SLD/SE Style or not 264 265 \param blob pointer to the XmlBLOB buffer. 266 \param size XmlBLOB's size (in bytes). 267 268 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB of the 269 Vector type; -1 in any other case. 270 271 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 272 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 273 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob 274 */ 275 GAIAGEO_DECLARE int gaiaIsSldSeVectorStyleXmlBlob (const unsigned char 276 *blob, int size); 277 278 /** 279 Checks if a valid XmlBLOB buffer does contain an SLD/SE Style or not 280 281 \param blob pointer to the XmlBLOB buffer. 282 \param size XmlBLOB's size (in bytes). 283 284 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB of the 285 Raster type; -1 in any other case. 286 287 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 288 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 289 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldStyleXmlBlob, 290 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 291 */ 292 GAIAGEO_DECLARE int gaiaIsSldSeRasterStyleXmlBlob (const unsigned char 293 *blob, int size); 294 295 /** 296 Checks if a valid XmlBLOB buffer does contain an SLD Style or not 297 298 \param blob pointer to the XmlBLOB buffer. 299 \param size XmlBLOB's size (in bytes). 300 301 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB of the 302 SLD type; -1 in any other case. 303 304 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 305 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 306 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldSeRasterXmlBlob, 307 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 308 */ 309 GAIAGEO_DECLARE int gaiaIsSldStyleXmlBlob (const unsigned char 310 *blob, int size); 311 312 /** 313 Checks if a valid XmlBLOB buffer does contain a MapConfig or not 314 315 \param blob pointer to the XmlBLOB buffer. 316 \param size XmlBLOB's size (in bytes). 317 318 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB of the 319 MapConfig type; -1 in any other case. 320 321 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 322 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 323 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldSeRasterXmlBlob, 324 gaiaIsSvgXmlBlob, gaiaIsGpxXmlBlob, gaiaIsSldStyleXmlBlob 325 */ 326 GAIAGEO_DECLARE int gaiaIsMapConfigXmlBlob (const unsigned char 327 *blob, int size); 328 329 /** 330 Checks if a valid XmlBLOB buffer does contain an SVG Symbol or not 331 332 \param blob pointer to the XmlBLOB buffer. 333 \param size XmlBLOB's size (in bytes). 334 335 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB; -1 in any other case. 336 337 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 338 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 339 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldStyleXmlBlob, 340 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsGpxXmlBlob, gaiaIsMapConfigXmlBlob 341 */ 342 GAIAGEO_DECLARE int gaiaIsSvgXmlBlob (const unsigned char *blob, int size); 343 344 /** 345 Checks if a valid XmlBLOB buffer does contain a GPX document or not 346 347 \param blob pointer to the XmlBLOB buffer. 348 \param size XmlBLOB's size (in bytes). 349 350 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB; -1 in any other case. 351 352 \sa gaiaIsValidXmlBlob, gaiaIsSchemaValidatedXmlBlob, 353 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 354 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldStyleXmlBlob, 355 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSvgXmlBlob, gaiaIsMapConfigXmlBlob 356 */ 357 GAIAGEO_DECLARE int gaiaIsGpxXmlBlob (const unsigned char *blob, int size); 358 359 /** 360 Return another XmlBLOB buffer compressed / uncompressed 361 362 \param blob pointer to the input XmlBLOB buffer. 363 \param in_size input XmlBLOB's size (in bytes). 364 \param compressed if TRUE the returned XmlBLOB will be zip-compressed. 365 \param result on completion will containt a pointer to the output XmlBLOB: 366 NULL on failure. 367 \param out_size on completion this variable will contain the output XmlBLOB's size (in bytes) 368 369 \sa gaiaXmlToBlob, gaiaIsCompressedXmlBlob 370 371 \note the XmlBLOB buffer corresponds to dynamically allocated memory: 372 so you are responsible to free() it [unless SQLite will take care 373 of memory cleanup via buffer binding]. 374 */ 375 GAIAGEO_DECLARE void gaiaXmlBlobCompression (const unsigned char *blob, 376 int in_size, int compressed, 377 unsigned char **result, 378 int *out_size); 379 380 /** 381 Checks if a valid XmlBLOB buffer has successfully passed a formal Schema validation or not 382 383 \param blob pointer to the XmlBLOB buffer. 384 \param size XmlBLOB's size (in bytes). 385 386 \return TRUE or FALSE if the BLOB actually is a valid XmlBLOB but not schema-validated; 387 -1 in any other case. 388 389 \sa gaiaIsValidXmlBlob, gaiaIsSvgXmlBlob, 390 gaiaIsCompressedXmlBlob, gaiaIsIsoMetadataXmlBlob, 391 gaiaIsSldSeVectorStyleXmlBlob, gaiaIsSldSeRasterStyleXmlBlob, 392 gaiaIsSldStyleXmlBlob, gaiaIsMapConfigXmlBlob 393 */ 394 GAIAGEO_DECLARE int gaiaIsSchemaValidatedXmlBlob (const unsigned char 395 *blob, int size); 396 397 /** 398 Return the XMLDocument size (in bytes) from a valid XmlBLOB buffer 399 400 \param blob pointer to the XmlBLOB buffer. 401 \param size XmlBLOB's size (in bytes). 402 403 \return the XMLDocument size (in bytes) for any valid XmlBLOB; 404 -1 if the BLOB isn't a valid XmlBLOB. 405 */ 406 GAIAGEO_DECLARE int gaiaXmlBlobGetDocumentSize (const unsigned char *blob, 407 int size); 408 409 /** 410 Return the SchemaURI from a valid XmlBLOB buffer 411 412 \param blob pointer to the XmlBLOB buffer. 413 \param size XmlBLOB's size (in bytes). 414 415 \return the SchemaURI for any valid XmlBLOB containing a SchemaURI; 416 NULL in any other case. 417 418 \sa gaiaXmlGetInternalSchemaURI 419 420 \note the returned SchemaURI corresponds to dynamically allocated memory: 421 so you are responsible to free() it before or after. 422 */ 423 GAIAGEO_DECLARE char *gaiaXmlBlobGetSchemaURI (const unsigned char 424 *blob, int size); 425 426 /** 427 Return the Internal SchemaURI from a valid XmlDocument 428 429 \param p_cache a memory pointer returned by spatialite_alloc_connection() 430 \param xml pointer to the XML document 431 \param xml_len lenght of the XML document (in bytes). 432 433 \return the SchemaURI eventually defined within a valid XMLDocument; 434 NULL if the XMLDocument is invalid, or if it doesn't contain any SchemaURI. 435 436 \sa gaiaXmlBlobGetSchemaURI 437 438 \note the returned SchemaURI corresponds to dynamically allocated memory: 439 so you are responsible to free() it before or after. 440 */ 441 GAIAGEO_DECLARE char *gaiaXmlGetInternalSchemaURI (const void *p_cache, 442 const unsigned char 443 *xml, int xml_len); 444 445 /** 446 Return the FileIdentifier from a valid XmlBLOB buffer 447 448 \param blob pointer to the XmlBLOB buffer. 449 \param size XmlBLOB's size (in bytes). 450 451 \return the FileIdentifier for any valid XmlBLOB containing a FileIdentifier; 452 NULL in any other case. 453 454 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobSetFileId, gaiaXmlBlobAddFileId 455 456 \note the returned FileIdentifier corresponds to dynamically allocated memory: 457 so you are responsible to free() it before or after. 458 */ 459 GAIAGEO_DECLARE char *gaiaXmlBlobGetFileId (const unsigned char 460 *blob, int size); 461 462 /** 463 Return the ParentIdentifier from a valid XmlBLOB buffer 464 465 \param blob pointer to the XmlBLOB buffer. 466 \param size XmlBLOB's size (in bytes). 467 468 \return the ParentIdentifier for any valid XmlBLOB containing a ParentIdentifier; 469 NULL in any other case. 470 471 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobSetParentId, gaiaXmlBlobAddParentId 472 473 \note the returned ParentIdentifier corresponds to dynamically allocated memory: 474 so you are responsible to free() it before or after. 475 */ 476 GAIAGEO_DECLARE char *gaiaXmlBlobGetParentId (const unsigned char 477 *blob, int size); 478 479 /** 480 Return a new XmlBLOB (ISO Metadata) by replacing the FileId value 481 482 \param p_cache a memory pointer returned by spatialite_alloc_connection() 483 \param blob pointer to the input XmlBLOB buffer. 484 \param size input XmlBLOB's size (in bytes). 485 \param identifier the new FileId value to be set. 486 \param new_blob on completion will contain a pointer to the output XmlBLOB buffer. 487 \param new_size on completion will containg the output XmlBlob's size (in bytes). 488 489 \return TRUE for success; FALSE for any failure cause. 490 491 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobGetFileId, gaiaXmlBlobAddFileId 492 493 \note the output XmlBLOB corresponds to dynamically allocated memory: 494 so you are responsible to free() it before or after. 495 */ 496 GAIAGEO_DECLARE int gaiaXmlBlobSetFileId (const void *p_cache, 497 const unsigned char *blob, 498 int size, 499 const char *identifier, 500 unsigned char **new_blob, 501 int *new_size); 502 503 /** 504 Return a new XmlBLOB (ISO Metadata) by replacing the ParentId value 505 506 \param p_cache a memory pointer returned by spatialite_alloc_connection() 507 \param blob pointer to the inputXmlBLOB buffer. 508 \param size input XmlBLOB's size (in bytes). 509 \param identifier the new ParentId value to be set. 510 \param new_blob on completion will contain a pointer to the output XmlBLOB buffer. 511 \param new_size on completion will containg the output XmlBlob's size (in bytes). 512 513 \return TRUE for success; FALSE for any failure cause. 514 515 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobGetParentId, gaiaXmlBlobAddParentId 516 517 \note the returned XmlBLOB corresponds to dynamically allocated memory: 518 so you are responsible to free() it before or after. 519 */ 520 GAIAGEO_DECLARE int gaiaXmlBlobSetParentId (const void *p_cache, 521 const unsigned char *blob, 522 int size, 523 const char *identifier, 524 unsigned char **new_blob, 525 int *new_size); 526 527 /** 528 Return a new XmlBLOB (ISO Metadata) by inserting a FileId value 529 530 \param p_cache a memory pointer returned by spatialite_alloc_connection() 531 \param blob pointer to the input XmlBLOB buffer. 532 \param size input XmlBLOB's size (in bytes). 533 \param identifier the new FileId value to be inserted. 534 \param ns_id prefix corresponding to FileIdentifier NameSpace (may be NULL) 535 \param uri_id URI corresponding to the FileIdentifier NameSpace (may be NULL) 536 \param ns_charstr prefix corresponding to CharacterString NameSpace (may be NULL) 537 \param uri_charstr URI corresponding to CharacterString NameSpace (may be NULL) 538 \param new_blob on completion will contain a pointer to the output XmlBLOB buffer. 539 \param new_size on completion will containg the output XmlBlob's size (in bytes). 540 541 \return TRUE for success; FALSE for any failure cause. 542 543 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobGetFileId, gaiaXmlBlobSetFileId 544 545 \note the output XmlBLOB corresponds to dynamically allocated memory: 546 so you are responsible to free() it before or after. 547 */ 548 GAIAGEO_DECLARE int gaiaXmlBlobAddFileId (const void *p_cache, 549 const unsigned char *blob, 550 int size, 551 const char *identifier, 552 const char *ns_id, 553 const char *uri_id, 554 const char *ns_charstr, 555 const char *uri_charstr, 556 unsigned char **new_blob, 557 int *new_size); 558 559 /** 560 Return a new XmlBLOB (ISO Metadata) by inserting a ParentId value 561 562 \param p_cache a memory pointer returned by spatialite_alloc_connection() 563 \param blob pointer to the inputXmlBLOB buffer. 564 \param size input XmlBLOB's size (in bytes). 565 \param identifier the new ParentId value to be inserted. 566 \param ns_id prefix corresponding to FileIdentifier NameSpace (may be NULL) 567 \param uri_id URI corresponding to the FileIdentifier NameSpace (may be NULL) 568 \param ns_charstr prefix corresponding to CharacterString NameSpace (may be NULL) 569 \param uri_charstr URI corresponding to CharacterString NameSpace (may be NULL) 570 \param new_blob on completion will contain a pointer to the output XmlBLOB buffer. 571 \param new_size on completion will containg the output XmlBlob's size (in bytes). 572 573 \return TRUE for success; FALSE for any failure cause. 574 575 \sa gaiaIsIsoMetadataXmlBlob, gaiaXmlBlobGetParentId, gaiaXmlBlobSetParentId 576 577 \note the returned XmlBLOB corresponds to dynamically allocated memory: 578 so you are responsible to free() it before or after. 579 */ 580 GAIAGEO_DECLARE int gaiaXmlBlobAddParentId (const void *p_cache, 581 const unsigned char *blob, 582 int size, 583 const char *identifier, 584 const char *ns_id, 585 const char *uri_id, 586 const char *ns_charstr, 587 const char *uri_charstr, 588 unsigned char **new_blob, 589 int *new_size); 590 591 /** 592 Return the Name from a valid XmlBLOB buffer 593 594 \param blob pointer to the XmlBLOB buffer. 595 \param size XmlBLOB's size (in bytes). 596 597 \return the Name for any valid XmlBLOB containing a Name; 598 NULL in any other case. 599 600 \sa gaiaIsIsoMetadataXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 601 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob 602 603 \note the returned Name corresponds to dynamically allocated memory: 604 so you are responsible to free() it before or after. 605 */ 606 GAIAGEO_DECLARE char *gaiaXmlBlobGetName (const unsigned char 607 *blob, int size); 608 609 /** 610 Return the Title from a valid XmlBLOB buffer 611 612 \param blob pointer to the XmlBLOB buffer. 613 \param size XmlBLOB's size (in bytes). 614 615 \return the Title for any valid XmlBLOB containing a Title; 616 NULL in any other case. 617 618 \sa gaiaIsIsoMetadataXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 619 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob 620 621 \note the returned Title corresponds to dynamically allocated memory: 622 so you are responsible to free() it before or after. 623 */ 624 GAIAGEO_DECLARE char *gaiaXmlBlobGetTitle (const unsigned char 625 *blob, int size); 626 627 /** 628 Return the Abstract from a valid XmlBLOB buffer 629 630 \param blob pointer to the XmlBLOB buffer. 631 \param size XmlBLOB's size (in bytes). 632 633 \return the Abstract for any valid XmlBLOB containing an Abstract; 634 NULL in any other case. 635 636 \sa gaiaIsIsoMetadataXmlBlob, gaiaIsSldSeVectorStyleXmlBlob, 637 gaiaIsSldSeRasterStyleXmlBlob, gaiaIsSldStyleXmlBlob 638 639 \note the returned Abstract corresponds to dynamically allocated memory: 640 so you are responsible to free() it before or after. 641 */ 642 GAIAGEO_DECLARE char *gaiaXmlBlobGetAbstract (const unsigned char 643 *blob, int size); 644 645 /** 646 Return the Geometry buffer from a valid XmlBLOB buffer 647 648 \param blob pointer to the XmlBLOB buffer. 649 \param size XmlBLOB's size (in bytes). 650 \param blob_geom on completion this variable will contain 651 a pointer to the returned Geometry buffer (NULL if no Geometry 652 was defined within the XmlBLOB) 653 \param blob_size on completion this variable will contain 654 the size (in bytes) of the returned Geometry buffer 655 656 \sa gaiaIsIsoMetadataXmlBlob 657 658 \note the returned Geometry buffer corresponds to dynamically allocated memory: 659 so you are responsible to free() it before or after. 660 */ 661 GAIAGEO_DECLARE void gaiaXmlBlobGetGeometry (const unsigned char 662 *blob, int size, 663 unsigned char **blob_geom, 664 int *blob_size); 665 666 /** 667 Return a MultiLinestring Geometry from a valid GPX XmlBLOB buffer 668 669 \param blob pointer to the XmlBLOB buffer. 670 \param size XmlBLOB's size (in bytes). 671 \param db_handle handle to the current SQLite connection 672 673 \return a Geometry of the MultiLinestring type, or NULL 674 675 \sa gaiaIsIsoMetadataXmlBlob 676 677 \note the returned Geometry corresponds to dynamically allocated memory: 678 so you are responsible to free() it before or after. 679 */ 680 GAIAGEO_DECLARE gaiaGeomCollPtr gaiaXmlBlobMLineFromGPX (const unsigned 681 char *blob, 682 int size, 683 sqlite3 * 684 db_handle); 685 686 /** 687 Return the Charset Encoding from a valid XmlBLOB buffer 688 689 \param blob pointer to the XmlBLOB buffer. 690 \param size XmlBLOB's size (in bytes). 691 692 \return the Charset Encoding for any valid XmlBLOB explicitly defining an Encoding; 693 NULL in any other case. 694 695 \note the returned Encoding corresponds to dynamically allocated memory: 696 so you are responsible to free() it before or after. 697 */ 698 GAIAGEO_DECLARE char *gaiaXmlBlobGetEncoding (const unsigned char 699 *blob, int size); 700 701 /** 702 Return the most recent XML Parse error/warning (if any) 703 704 \param ptr a memory pointer returned by spatialite_alloc_connection() 705 706 \return the most recent XML Parse error/warning message (if any); 707 NULL in any other case. 708 709 \sa gaiaXmlBlobGetLastValidateError, gaiaIsValidXPathExpression, 710 gaiaXmlBlobGetLastXPathError 711 712 \note the returned error/warning message corresponds to dynamically allocated memory: 713 so you are responsible to free() it before or after. 714 */ 715 GAIAGEO_DECLARE char *gaiaXmlBlobGetLastParseError (const void *p_cache); 716 717 /** 718 Return the most recent XML Validate error/warning (if any) 719 720 \param p_cache a memory pointer returned by spatialite_alloc_connection() 721 722 \return the most recent XML Validate error/warning message (if any); 723 NULL in any other case. 724 725 \sa gaiaXmlBlobGetLastParseError, gaiaIsValidXPathExpression, 726 gaiaXmlBlobGetLastXPathError 727 728 \note the returned error/warning message corresponds to dynamically allocated memory: 729 so you are responsible to free() it before or after. 730 */ 731 GAIAGEO_DECLARE char *gaiaXmlBlobGetLastValidateError (const void *p_cache); 732 733 /** 734 Checks if a Text string could be a valid XPathExpression 735 736 \param p_cache a memory pointer returned by spatialite_alloc_connection() 737 \param xpath_expr pointer to the XPathExpression to be checked. 738 739 \return TRUE or FALSE if the Text string actually is a valid XPathExpression; 740 -1 in any other case. 741 742 \sa gaiaXmlBlobGetLastXPathError 743 */ 744 GAIAGEO_DECLARE int gaiaIsValidXPathExpression (const void *p_cache, 745 const char *xpath_expr); 746 747 /** 748 Return the most recent XPath error/warning (if any) 749 750 \param p_cache a memory pointer returned by spatialite_alloc_connection() 751 752 \return the most recent XPath error/warning message (if any); 753 NULL in any other case. 754 755 \sa gaiaXmlBlobGetLastParseError, gaiaXmlBlobGetLastValidateError, 756 gaiaIsValidXPathExpression 757 758 \note the returned error/warning message corresponds to dynamically allocated memory: 759 so you are responsible to free() it before or after. 760 */ 761 GAIAGEO_DECLARE char *gaiaXmlBlobGetLastXPathError (const void *p_cache); 762 763 /** 764 Load an external XML Document 765 766 \param path_or_url pointer to the external XML Document (could be a pathname or an URL). 767 \param result on completion will containt a pointer to a BLOB: 768 NULL on failure. 769 \param size on completion this variable will contain the BLOB's size (in bytes). 770 \param parsing_errors on completion this variable will contain all error/warning 771 messages emitted during the XML Parsing step. Can be set to NULL so to ignore any message. 772 773 \sa gaiaXmlFromBlob, gaiaXmlStore 774 775 \note the BLOB buffer corresponds to dynamically allocated memory: 776 so you are responsible to free() it [unless SQLite will take care 777 of memory cleanup via buffer binding]. 778 */ 779 GAIAGEO_DECLARE int gaiaXmlLoad (const void *p_cache, 780 const char *path_or_url, 781 unsigned char **result, int *size, 782 char **parsing_errors); 783 784 /** 785 Stores an external XML Document 786 787 \param blob pointer to the XmlBLOB buffer. 788 \param size XmlBLOB's size (in bytes). 789 \param path pathname of the export file 790 \param indent if a negative value is passed the XMLDocument will 791 be extracted exactly as it was when loaded. Otherwise it will be 792 properly formatted using the required intenting (max. 8); ZERO 793 means that the whole XML Document will consist of a single line. 794 795 \sa gaiaXmlToBlob, gaiaXmlTextFromBlob 796 797 \note the returned XMLDocument will always respect the internal encoding declaration, 798 and may not support any further processing as SQLite TEXT if it's not UTF-8. 799 800 \note the XMLDocument buffer corresponds to dynamically allocated memory: 801 so you are responsible to free() it before or after. 802 803 \sa gaiaXmlFromBlob, gaiaXmlLoad 804 805 \note the BLOB buffer corresponds to dynamically allocated memory: 806 so you are responsible to free() it [unless SQLite will take care 807 of memory cleanup via buffer binding]. 808 */ 809 GAIAGEO_DECLARE int gaiaXmlStore (const unsigned char *blob, int size, 810 const char *path, int indent); 811 812 #endif /* end LIBXML2: supporting XML documents */ 813 814 #ifdef __cplusplus 815 } 816 #endif 817 818 #endif /* _GG_XML_H */ 819