utils/xmlgrep/xml.h

   1 /* Copyright (c) 2007, 2008 by Adalin B.V.
   2  * Copyright (c) 2007, 2008 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 enum
  36 {
  37     XML_NO_ERROR = 0,
  38     XML_OUT_OF_MEMORY,
  39     XML_FILE_NOT_FOUND,
  40     XML_INVALID_NODE_NAME,
  41     XML_UNEXPECTED_EOF,
  42     XML_TRUNCATE_RESULT,
  43     XML_INVALID_COMMENT,
  44     XML_INVALID_INFO_BLOCK,
  45     XML_ELEMENT_NO_OPENING_TAG,
  46     XML_ELEMENT_NO_CLOSING_TAG,
  47     XML_ATTRIB_NO_OPENING_QUOTE,
  48     XML_ATTRIB_NO_CLOSING_QUOTE,
  49     XML_MAX_ERROR
  50 };
  51
  52 /**
  53  * Open an XML file for processing.
  54  *
  55  * @param fname path to the file
  56  * @return XML-id which is used for further processing
  57  */
  58 void *xmlOpen(const char *);
  59
  60 /**
  61  * Process a section of XML code in a preallocated buffer.
  62  * The buffer may not be free'd until xmlClose has been called.
  63  *
  64  * @param buffer pointer to the buffer
  65  * @param size size of the buffer
  66  * @return XML-id which is used for further processing
  67  */
  68 void *xmlInitBuffer(const char *, size_t);
  69
  70 /**
  71  * Close the XML file after which no further processing is possible.
  72  *
  73  * @param xid XML-id
  74  */
  75 void xmlClose(void *);
  76
  77
  78 /**
  79  * Locate a subsection of the xml tree for further processing.
  80  * This adds processing speed since the reuired nodes will only be searched
  81  * in the subsection.
  82  *
  83  * The memory allocated for the XML-subsection-id has to be freed by the
  84  * calling process.
  85  *
  86  * @param xid XML-id
  87  * @param node path to the node containing the subsection
  88  * @return XML-subsection-id for further processing
  89  */
  90 void *xmlNodeGet(const void *, const char *);
  91
  92 /**
  93  * Copy a subsection of the xml tree for further processing.
  94  * This is useful when it's required to process a section of the XML code
  95  * after the file has been closed. The drawback is the added memory
  96  * requirements.
  97  *
  98  * The memory allocated for the XML-subsection-id has to be freed by the
  99  * calling process.
 100  *
 101  * @param xid XML-id
 102  * @param node path to the node containing the subsection
 103  * @return XML-subsection-id for further processing
 104  */
 105 void *xmlNodeCopy(const void *, const char *);
 106
 107
 108 /**
 109  * Return the name of this node.
 110  * The returned string has to be freed by the calling process.
 111  *
 112  * @param xid XML-id
 113  * @return a newly alocated string containing the node name
 114  */
 115 char *xmlNodeGetName(const void *);
 116
 117 /**
 118  * Copy the name of this node in a pre-allocated buffer.
 119  *
 120  * @param xid XML-id
 121  * @param buffer the buffer to copy the string to
 122  * @param buflen length of the destination buffer
 123  * @return the length of the node name
 124  */
 125 size_t xmlNodeCopyName(const void *, char *, size_t);
 126
 127
 128 /**
 129  * Create a marker XML-id that starts out with the same settings as the
 130  * refference XML-id.
 131  *
 132  * Marker id's are required when xmlNodeGetNum() and xmlNodeGetPos() are used
 133  * to walk a number of nodes. The xmlNodeGetPos function adjusts the contents
 134  * of the provided XML-id to keep track of it's position within the xml section.
 135  * The returned XML-id is limited to the boundaries of the requested XML tag
 136  * and has to be freed by the calling process.
 137  *
 138  * @param xid reference XML-id
 139  * @return a copy of the reference XML-id
 140  */
 141 void *xmlMarkId(const void *);
 142
 143 /**
 144  * Get the number of nodes with the same name from a specified xml path.
 145  *
 146  * @param xid XML-id
 147  * @param path path to the xml node
 148  * @return the number count of the nodename
 149  */
 150 unsigned int xmlNodeGetNum(const void *, const char *);
 151
 152 /**
 153  * Get the nth occurrence of node in the parent node.
 154  * The return value should never be altered or freed by the caller.
 155  *
 156  * @param pid XML-id of the parent node of this node
 157  * @param xid XML-id
 158  * @param node name of the node to search for
 159  * @param num specify which occurence to return
 160  * @return XML-subsection-id for further processing or NULL if unsuccessful
 161  */
 162 void *xmlNodeGetPos(const void *, void *, const char *, size_t);
 163
 164
 165 /**
 166  * Get a string of characters from the current node.
 167  * The returned string has to be freed by the calling process.
 168  *
 169  * @param xid XML-id
 170  * @return a newly alocated string containing the contents of the node
 171  */
 172 char *xmlGetString(const void *);
 173
 174 /**
 175  * Get a string of characters from the current node.
 176  * This function has the advantage of not allocating its own return buffer,
 177  * keeping the memory management to an absolute minimum but the disadvantage
 178  * is that it's unreliable in multithread environments.
 179  *
 180  * @param xid XML-id
 181  * @param buffer the buffer to copy the string to
 182  * @param buflen length of the destination buffer
 183  * @return the length of the string
 184  */
 185 size_t xmlCopyString(const void *, char *, size_t);
 186
 187 /**
 188  * Compare the value of this node to a reference string.
 189  * Comparing is done in a case insensitive way.
 190  *
 191  * @param xid XML-id
 192  * @param str the string to compare to
 193  * @return an integer less than, equal to, ro greater than zero if the value
 194  * of the node is found, respectively, to be less than, to match, or be greater
 195  * than str
 196  */
 197 int xmlCompareString(const void *, const char *);
 198
 199 /**
 200  * Get a string of characters from a specified xml path.
 201  * The returned string has to be freed by the calling process.
 202  *
 203  * @param xid XML-id
 204  * @param path path to the xml node
 205  * @return a newly alocated string containing the contents of the node
 206  */
 207 char *xmlNodeGetString(const void *, const char *);
 208
 209 /**
 210  * Get a string of characters from a specified xml path.
 211  * This function has the advantage of not allocating its own return buffer,
 212  * keeping the memory management to an absolute minimum but the disadvantage
 213  * is that it's unreliable in multithread environments.
 214  *
 215  * @param xid XML-id
 216  * @param path path to the xml node
 217  * @param buffer the buffer to copy the string to
 218  * @param buflen length of the destination buffer
 219  * @return the length of the string
 220  */
 221 size_t xmlNodeCopyString(const void *, const char *, char *, size_t);
 222
 223 /**
 224  * Compare the value of a node to a reference string.
 225  * Comparing is done in a case insensitive way.
 226  *
 227  * @param xid XML-id
 228  * @param path path to the xml node to compare to
 229  * @param str the string to compare to
 230  * @return an integer less than, equal to, ro greater than zero if the value
 231  * of the node is found, respectively, to be less than, to match, or be greater
 232  * than str
 233  */
 234 int xmlNodeCompareString(const void *, const char *, const char *);
 235
 236 /**
 237  * Get a string of characters from a named attribute.
 238  * The returned string has to be freed by the calling process.
 239  *
 240  * @param xid XML-id
 241  * @param name name of the attribute to acquire
 242  * @return the contents of the node converted to an integer value
 243  */
 244 char *xmlAttributeGetString(const void *, const char *);
 245
 246 /**
 247  * Get a string of characters from a named attribute.
 248  * This function has the advantage of not allocating its own return buffer,
 249  * keeping the memory management to an absolute minimum but the disadvantage
 250  * is that it's unreliable in multithread environments.
 251  *
 252  * @param xid XML-id
 253  * @param name name of the attribute to acquire.
 254  * @param buffer the buffer to copy the string to
 255  * @param buflen length of the destination buffer
 256  * @return the length of the string
 257  */
 258 size_t xmlAttributeCopyString(const void *, const char *, char *, size_t);
 259
 260 /**
 261  * Compare the value of an attribute to a reference string.
 262  * Comparing is done in a case insensitive way.
 263  *
 264  * @param xid XML-id
 265  * @param name name of the attribute to acquire.
 266  * @param str the string to compare to
 267  * @return an integer less than, equal to, ro greater than zero if the value
 268  * of the node is found, respectively, to be less than, to match, or be greater
 269  * than str
 270  */
 271 int xmlAttributeCompareString(const void *, const char *, const char *);
 272
 273
 274 /**
 275  * Get the integer value from the current node/
 276  *
 277  * @param xid XML-id
 278  * @return the contents of the node converted to an integer value
 279  */
 280 long int xmlGetInt(const void *);
 281
 282 /**
 283  * Get an integer value from a specified xml path.
 284  *
 285  * @param xid XML-id
 286  * @param path path to the xml node
 287  * @return the contents of the node converted to an integer value
 288  */
 289 long int xmlNodeGetInt(const void *, const char *);
 290
 291 /**
 292  * Get the integer value from the named attribute.
 293  *
 294  * @param xid XML-id
 295  * @param name name of the attribute to acquire
 296  * @return the contents of the node converted to an integer value
 297  */
 298 long int xmlAttributeGetInt(const void *, const char *);
 299
 300
 301 /**
 302  * Get the double value from the curent node/
 303  *
 304  * @param xid XML-id
 305  * @return the contents of the node converted to a double value
 306  */
 307 double xmlGetDouble(const void *);
 308
 309 /**
 310  * Get a double value from a specified xml path/
 311  *
 312  * @param xid XML-id
 313  * @param path path to the xml node
 314  * @return the contents of the node converted to a double value
 315  */
 316 double xmlNodeGetDouble(const void *, const char *);
 317
 318 /**
 319  * Get the double value from the named attribute.
 320  *
 321  * @param xid XML-id
 322  * @param name name of the attribute to acquire
 323  * @return the contents of the node converted to an integer value
 324  */
 325 double xmlAttributeGetDouble(const void *, const char *);
 326
 327
 328 /**
 329  * Get the error number of the last error and clear it.
 330  *
 331  * @param xid XML-id
 332  * @param clear clear the error state if non zero
 333  * @return the numer of the last error, 0 means no error detected.
 334  */
 335 int xmlErrorGetNo(const void *, int);
 336
 337 /**
 338  * Get the line number of the last detected syntax error in the xml file.
 339  *
 340  * @param xid XML-id
 341  * @param clear clear the error state if non zero
 342  * @return the line number of the detected syntax error.
 343  */
 344 size_t xmlErrorGetLineNo(const void *, int);
 345
 346 /**
 347  * Get the column number of the last detected syntax error in the xml file.
 348  *
 349  * @param xid XML-id
 350  * @param clear clear the error state if non zero
 351  * @return the line number of the detected syntax error.
 352  */
 353 size_t xmlErrorGetColumnNo(const void *, int);
 354
 355 /**
 356  * Get a string that explains the last error.
 357  *
 358  * @param xid XML-id
 359  * @param clear clear the error state if non zero
 360  * @return a string that explains the last error.
 361  */
 362 const char *xmlErrorGetString(const void *, int);
 363
 364 #ifdef __cplusplus
 365 }
 366 #endif
 367
 368 #endif /* __XML_CONFIG */
 369