utils/xmlgrep/xml.h

   1 /* Copyright (c) 2007-2009 by Adalin B.V.
   2  * Copyright (c) 2007-2009 by Erik Hofman
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of (any of) the copyrightholder(s) nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  17  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  18  * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  19  * THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef __XML_CONFIG
  29 #define __XML_CONFIG 1
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #undef XML_NONVALIDATING
  36
  37 #ifdef XML_USE_NODECACHE
  38 #include "xml_cache.h"
  39 #else
  40 void *cacheGet(void *);
  41 #endif
  42
  43 enum
  44 {
  45     XML_NO_ERROR = 0,
  46     XML_OUT_OF_MEMORY,
  47     XML_FILE_NOT_FOUND,
  48     XML_INVALID_NODE_NAME,
  49     XML_UNEXPECTED_EOF,
  50     XML_TRUNCATE_RESULT,
  51     XML_INVALID_COMMENT,
  52     XML_INVALID_INFO_BLOCK,
  53     XML_ELEMENT_NO_OPENING_TAG,
  54     XML_ELEMENT_NO_CLOSING_TAG,
  55     XML_ATTRIB_NO_OPENING_QUOTE,
  56     XML_ATTRIB_NO_CLOSING_QUOTE,
  57     XML_MAX_ERROR
  58 };
  59
  60 #ifdef WIN32
  61 # define WIN32_LEAN_AND_MEAN
  62 # include <windows.h>
  63
  64 typedef struct
  65 {
  66     HANDLE m;
  67     void *p;
  68 } SIMPLE_UNMMAP;
  69 #endif
  70
  71 #ifndef XML_NONVALIDATING
  72 struct _xml_error
  73 {
  74     char *pos;
  75     int err_no;
  76 };
  77 #endif
  78
  79 /*
  80  * It is required for both the rood node and the normal xml nodes to both
  81  * have 'char *name' defined as the first entry. The code tests whether
  82  * name == 0 to detect the root node.
  83  */
  84 struct _root_id
  85 {
  86     char *name;
  87     char *start;
  88     size_t len;
  89     int fd;
  90 #ifdef XML_USE_NODECACHE
  91     void *node;
  92 #endif
  93 #ifndef XML_NONVALIDATING
  94     struct _xml_error *info;
  95 #endif
  96 #ifdef WIN32
  97     SIMPLE_UNMMAP un;
  98 #endif
  99 };
 100
 101 struct _xml_id
 102 {
 103     char *name;
 104     char *start;
 105     size_t len;
 106     size_t name_len;
 107 #ifndef XML_NONVALIDATING
 108     struct _root_id *root;
 109 #endif
 110 #ifdef XML_USE_NODECACHE
 111     void *node;
 112 #endif
 113 };
 114
 115
 116
 117 /**
 118  * Open an XML file for processing.
 119  *
 120  * @param fname path to the file
 121  * @return XML-id which is used for further processing
 122  */
 123 void *xmlOpen(const char *);
 124
 125 /**
 126  * Process a section of XML code in a preallocated buffer.
 127  * The buffer may not be free'd until xmlClose has been called.
 128  *
 129  * @param buffer pointer to the buffer
 130  * @param size size of the buffer
 131  * @return XML-id which is used for further processing
 132  */
 133 void *xmlInitBuffer(const char *, size_t);
 134
 135 /**
 136  * Close the XML file after which no further processing is possible.
 137  *
 138  * @param xid XML-id
 139  */
 140 void xmlClose(void *);
 141
 142
 143 /**
 144  * Locate a subsection of the xml tree for further processing.
 145  * This adds processing speed since the reuired nodes will only be searched
 146  * in the subsection.
 147  *
 148  * The memory allocated for the XML-subsection-id has to be freed by the
 149  * calling process.
 150  *
 151  * @param xid XML-id
 152  * @param node path to the node containing the subsection
 153  * @return XML-subsection-id for further processing
 154  */
 155 void *xmlNodeGet(const void *, const char *);
 156
 157 /**
 158  * Copy a subsection of the xml tree for further processing.
 159  * This is useful when it's required to process a section of the XML code
 160  * after the file has been closed. The drawback is the added memory
 161  * requirements.
 162  *
 163  * The memory allocated for the XML-subsection-id has to be freed by the
 164  * calling process.
 165  *
 166  * @param xid XML-id
 167  * @param node path to the node containing the subsection
 168  * @return XML-subsection-id for further processing
 169  */
 170 void *xmlNodeCopy(const void *, const char *);
 171
 172
 173 /**
 174  * Return the name of this node.
 175  * The returned string has to be freed by the calling process.
 176  *
 177  * @param xid XML-id
 178  * @return a newly alocated string containing the node name
 179  */
 180 char *xmlNodeGetName(const void *);
 181
 182 /**
 183  * Copy the name of this node in a pre-allocated buffer.
 184  *
 185  * @param xid XML-id
 186  * @param buffer the buffer to copy the string to
 187  * @param buflen length of the destination buffer
 188  * @return the length of the node name
 189  */
 190 size_t xmlNodeCopyName(const void *, char *, size_t);
 191
 192
 193 /**
 194  * Create a marker XML-id that starts out with the same settings as the
 195  * refference XML-id.
 196  *
 197  * Marker id's are required when xmlNodeGetNum() and xmlNodeGetPos() are used
 198  * to walk a number of nodes. The xmlNodeGetPos function adjusts the contents
 199  * of the provided XML-id to keep track of it's position within the xml section.
 200  * The returned XML-id is limited to the boundaries of the requested XML tag
 201  * and has to be freed by the calling process.
 202  *
 203  * @param xid reference XML-id
 204  * @return a copy of the reference XML-id
 205  */
 206 void *xmlMarkId(const void *);
 207
 208 /**
 209  * Get the number of nodes with the same name from a specified xml path.
 210  *
 211  * @param xid XML-id
 212  * @param path path to the xml node
 213  * @return the number count of the nodename
 214  */
 215 unsigned int xmlNodeGetNum(const void *, const char *);
 216
 217 /**
 218  * Get the nth occurrence of node in the parent node.
 219  * The return value should never be altered or freed by the caller.
 220  *
 221  * @param pid XML-id of the parent node of this node
 222  * @param xid XML-id
 223  * @param node name of the node to search for
 224  * @param num specify which occurence to return
 225  * @return XML-subsection-id for further processing or NULL if unsuccessful
 226  */
 227 void *xmlNodeGetPos(const void *, void *, const char *, size_t);
 228
 229
 230 /**
 231  * Get a string of characters from the current node.
 232  * The returned string has to be freed by the calling process.
 233  *
 234  * @param xid XML-id
 235  * @return a newly alocated string containing the contents of the node
 236  */
 237 char *xmlGetString(const void *);
 238
 239 /**
 240  * Get a string of characters from the current node.
 241  * This function has the advantage of not allocating its own return buffer,
 242  * keeping the memory management to an absolute minimum but the disadvantage
 243  * is that it's unreliable in multithread environments.
 244  *
 245  * @param xid XML-id
 246  * @param buffer the buffer to copy the string to
 247  * @param buflen length of the destination buffer
 248  * @return the length of the string
 249  */
 250 size_t xmlCopyString(const void *, char *, size_t);
 251
 252 /**
 253  * Compare the value of this node to a reference string.
 254  * Comparing is done in a case insensitive way.
 255  *
 256  * @param xid XML-id
 257  * @param str the string to compare to
 258  * @return an integer less than, equal to, ro greater than zero if the value
 259  * of the node is found, respectively, to be less than, to match, or be greater
 260  * than str
 261  */
 262 int xmlCompareString(const void *, const char *);
 263
 264 /**
 265  * Get a string of characters from a specified xml path.
 266  * The returned string has to be freed by the calling process.
 267  *
 268  * @param xid XML-id
 269  * @param path path to the xml node
 270  * @return a newly alocated string containing the contents of the node
 271  */
 272 char *xmlNodeGetString(const void *, const char *);
 273
 274 /**
 275  * Get a string of characters from a specified xml path.
 276  * This function has the advantage of not allocating its own return buffer,
 277  * keeping the memory management to an absolute minimum but the disadvantage
 278  * is that it's unreliable in multithread environments.
 279  *
 280  * @param xid XML-id
 281  * @param path path to the xml node
 282  * @param buffer the buffer to copy the string to
 283  * @param buflen length of the destination buffer
 284  * @return the length of the string
 285  */
 286 size_t xmlNodeCopyString(const void *, const char *, char *, size_t);
 287
 288 /**
 289  * Compare the value of a node to a reference string.
 290  * Comparing is done in a case insensitive way.
 291  *
 292  * @param xid XML-id
 293  * @param path path to the xml node to compare to
 294  * @param str the string to compare to
 295  * @return an integer less than, equal to, ro greater than zero if the value
 296  * of the node is found, respectively, to be less than, to match, or be greater
 297  * than str
 298  */
 299 int xmlNodeCompareString(const void *, const char *, const char *);
 300
 301 /**
 302  * Get a string of characters from a named attribute.
 303  * The returned string has to be freed by the calling process.
 304  *
 305  * @param xid XML-id
 306  * @param name name of the attribute to acquire
 307  * @return the contents of the node converted to an integer value
 308  */
 309 char *xmlAttributeGetString(const void *, const char *);
 310
 311 /**
 312  * Get a string of characters from a named attribute.
 313  * This function has the advantage of not allocating its own return buffer,
 314  * keeping the memory management to an absolute minimum but the disadvantage
 315  * is that it's unreliable in multithread environments.
 316  *
 317  * @param xid XML-id
 318  * @param name name of the attribute to acquire.
 319  * @param buffer the buffer to copy the string to
 320  * @param buflen length of the destination buffer
 321  * @return the length of the string
 322  */
 323 size_t xmlAttributeCopyString(const void *, const char *, char *, size_t);
 324
 325 /**
 326  * Compare the value of an attribute to a reference string.
 327  * Comparing is done in a case insensitive way.
 328  *
 329  * @param xid XML-id
 330  * @param name name of the attribute to acquire.
 331  * @param str the string to compare to
 332  * @return an integer less than, equal to, ro greater than zero if the value
 333  * of the node is found, respectively, to be less than, to match, or be greater
 334  * than str
 335  */
 336 int xmlAttributeCompareString(const void *, const char *, const char *);
 337
 338
 339 /**
 340  * Get the integer value from the current node/
 341  *
 342  * @param xid XML-id
 343  * @return the contents of the node converted to an integer value
 344  */
 345 long int xmlGetInt(const void *);
 346
 347 /**
 348  * Get an integer value from a specified xml path.
 349  *
 350  * @param xid XML-id
 351  * @param path path to the xml node
 352  * @return the contents of the node converted to an integer value
 353  */
 354 long int xmlNodeGetInt(const void *, const char *);
 355
 356 /**
 357  * Get the integer value from the named attribute.
 358  *
 359  * @param xid XML-id
 360  * @param name name of the attribute to acquire
 361  * @return the contents of the node converted to an integer value
 362  */
 363 long int xmlAttributeGetInt(const void *, const char *);
 364
 365
 366 /**
 367  * Get the double value from the curent node/
 368  *
 369  * @param xid XML-id
 370  * @return the contents of the node converted to a double value
 371  */
 372 double xmlGetDouble(const void *);
 373
 374 /**
 375  * Get a double value from a specified xml path/
 376  *
 377  * @param xid XML-id
 378  * @param path path to the xml node
 379  * @return the contents of the node converted to a double value
 380  */
 381 double xmlNodeGetDouble(const void *, const char *);
 382
 383 /**
 384  * Get the double value from the named attribute.
 385  *
 386  * @param xid XML-id
 387  * @param name name of the attribute to acquire
 388  * @return the contents of the node converted to an integer value
 389  */
 390 double xmlAttributeGetDouble(const void *, const char *);
 391
 392
 393 /**
 394  * Get the error number of the last error and clear it.
 395  *
 396  * @param xid XML-id
 397  * @param clear clear the error state if non zero
 398  * @return the numer of the last error, 0 means no error detected.
 399  */
 400 int xmlErrorGetNo(const void *, int);
 401
 402 /**
 403  * Get the line number of the last detected syntax error in the xml file.
 404  *
 405  * @param xid XML-id
 406  * @param clear clear the error state if non zero
 407  * @return the line number of the detected syntax error.
 408  */
 409 size_t xmlErrorGetLineNo(const void *, int);
 410
 411 /**
 412  * Get the column number of the last detected syntax error in the xml file.
 413  *
 414  * @param xid XML-id
 415  * @param clear clear the error state if non zero
 416  * @return the line number of the detected syntax error.
 417  */
 418 size_t xmlErrorGetColumnNo(const void *, int);
 419
 420 /**
 421  * Get a string that explains the last error.
 422  *
 423  * @param xid XML-id
 424  * @param clear clear the error state if non zero
 425  * @return a string that explains the last error.
 426  */
 427 const char *xmlErrorGetString(const void *, int);
 428
 429 #ifdef __cplusplus
 430 }
 431 #endif
 432
 433 #endif /* __XML_CONFIG */
 434