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