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 *xmlGetNode(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 *xmlCopyNode(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 *xmlGetNodeName(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 xmlCopyNodeName(const void *, char *, size_t);
  95
  96
  97 /**
  98  * Get the number of nodes with the same name from a specified xml path
  99  *
 100  * @param xid XML-id
 101  * @param path path to the xml node
 102  * @return the number count of the nodename
 103  */
 104 unsigned int xmlGetNumNodes(const void *, const char *);
 105
 106 /**
 107  * Get the nth occurrence of node in the parent node.
 108  * The return value should neevr be altered or freed by the caller
 109  *
 110  * @param pid XML-id of the parent node of this node
 111  * @param xid XML-id
 112  * @param node name of the node to search for
 113  * @param num specify which occurence to return
 114  * @return XML-subsection-id for further processing or NULL if unsuccessful
 115  */
 116 void *xmlGetNodeNum(const void *, void *, const char *, int);
 117
 118
 119 /**
 120  * Get a string of characters from the current node.
 121  * The returned string has to be freed by the calling process
 122  *
 123  * @param xid XML-id
 124  * @return a newly alocated string containing the contents of the node
 125  */
 126 char *xmlGetString(const void *);
 127
 128 /**
 129  * Get a string of characters from the current node.
 130  * This function has the advantage of not allocating its own return buffer,
 131  * keeping the memory management to an absolute minimum but the disadvantage
 132  * is that it's unreliable in multithread environments
 133  *
 134  * @param xid XML-id
 135  * @param buffer the buffer to copy the string to
 136  * @param buflen length of the destination buffer
 137  * @return the length of the string
 138  */
 139 size_t xmlCopyString(const void *, char *, size_t);
 140
 141 /**
 142  * Compare the value of this node to a reference string.
 143  * Comparing is done in a case insensitive way
 144  *
 145  * @param xid XML-id
 146  * @param str the string to compare to
 147  * @return an integer less than, equal to, ro greater than zero if the value
 148  * of the node is found, respectively, to be less than, to match, or be greater
 149  * than str
 150  */
 151 int xmlCompareString(const void *, const char *);
 152
 153 /**
 154  * Get a string of characters from a specified xml path.
 155  * The returned string has to be freed by the calling process
 156  *
 157  * @param xid XML-id
 158  * @param path path to the xml node
 159  * @return a newly alocated string containing the contents of the node
 160  */
 161 char *xmlGetNodeString(const void *, const char *);
 162
 163 /**
 164  * Get a string of characters from a specified xml path.
 165  * This function has the advantage of not allocating its own return buffer,
 166  * keeping the memory management to an absolute minimum but the disadvantage
 167  * is that it's unreliable in multithread environments
 168  *
 169  * @param xid XML-id
 170  * @param path path to the xml node
 171  * @param buffer the buffer to copy the string to
 172  * @param buflen length of the destination buffer
 173  * @return the length of the string
 174  */
 175 size_t xmlCopyNodeString(const void *, const char *, char *, size_t);
 176
 177 /**
 178  * Compare the value of a node to a reference string.
 179  * Comparing is done in a case insensitive way
 180  *
 181  * @param xid XML-id
 182  * @param path path to the xml node to compare to
 183  * @param str the string to compare to
 184  * @return an integer less than, equal to, ro greater than zero if the value
 185  * of the node is found, respectively, to be less than, to match, or be greater
 186  * than str
 187  */
 188 int xmlCompareNodeString(const void *, const char *, const char *);
 189
 190
 191 /**
 192  * Get the integer value from the current node
 193  *
 194  * @param xid XML-id
 195  * @return the contents of the node converted to an integer value
 196  */
 197 long int xmlGetInt(const void *);
 198
 199 /**
 200  * Get an integer value from a specified xml path
 201  *
 202  * @param xid XML-id
 203  * @param path path to the xml node
 204  * @return the contents of the node converted to an integer value
 205  */
 206 long int xmlGetNodeInt(const void *, const char *);
 207
 208
 209 /**
 210  * Get the double value from the curent node
 211  *
 212  * @param xid XML-id
 213  * @return the contents of the node converted to a double value
 214  */
 215 double xmlGetDouble(const void *);
 216
 217 /**
 218  * Get a double value from a specified xml path
 219  *
 220  * @param xid XML-id
 221  * @param path path to the xml node
 222  * @return the contents of the node converted to a double value
 223  */
 224 double xmlGetNodeDouble(const void *, const char *);
 225
 226
 227 /**
 228  * Create a marker XML-id that starts out with the same settings as the
 229  * refference XML-id.
 230  * The returned XML-id has to be freed by the calling process
 231  *
 232  * @param xid reference XML-id
 233  * @return a copy of the reference XML-id
 234  */
 235 void *xmlMarkId(const void *);
 236
 237 #endif /* __XML_CONFIG */
 238