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(const 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 program.
  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 program.
  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(void *, const char *);
  75
  76 /**
  77  * Get the number of elements  with the same name from a specified xml path
  78  *
  79  * @param xid XML-id
  80  * @param path path to the xml node
  81  * @return the number count of the nodename
  82  */
  83 unsigned int xmlGetNumElements(void *, const char *);
  84
  85 /**
  86  * Get the next occurrence of element in the parent node
  87  *
  88  * @param pid XML-id of the parent node of this node
  89  * @param xid XML-id
  90  * @param element name of the element to search for
  91  * @return XML-subsection-id for further processing
  92  */
  93 void *xmlGetNextElement(const void *, void *, const char *);
  94
  95 /**
  96  * Compare the value of this element to a reference string.
  97  * Comparing is done in a case insensitive way.
  98  *
  99  * @param xid XML-id
 100  * @param s the string to compare to.
 101  * @return an integer less than, equal to, ro greater than zero if the value
 102  * of the node is found, respectively, to be less than, to match, or be greater
 103  * than s
 104  */
 105 int xmlCompareString(const void *, const char *);
 106
 107
 108 /**
 109  * Get a string of characters from a specified xml path
 110  * This function has the advantage of not allocating its own return buffer,
 111  * keeping the memory management to an absolute minimum but the disadvantage
 112  * is that it's unreliable in multithread environments.
 113  *
 114  * @param xid XML-id
 115  * @param path path to the xml node
 116  * @param buffer the buffer to copy the string to
 117  * @param buflen length of the destination buffer
 118  * @return the length of the string
 119  */
 120 unsigned int xmlCopyNodeString(void *, const char *, char *, const unsigned int);
 121
 122 /**
 123  * Get a string of characters from the current node
 124  * The returned string has to be freed by the calling program.
 125  *
 126  * @param xid XML-id
 127  * @return a newly alocated string containing the contents of the node.
 128  */
 129 char *xmlGetString(void *);
 130
 131 /**
 132  * Get a string of characters from a specified xml path
 133  * The returned string has to be freed by the calling program.
 134  *
 135  * @param xid XML-id
 136  * @param path path to the xml node
 137  * @return a newly alocated string containing the contents of the node.
 138  */
 139 char *xmlGetNodeString(void *, const char *);
 140
 141 /**
 142  * Compare the value of a node to a reference string.
 143  * Comparing is done in a case insensitive way.
 144  *
 145  * @param xid XML-id
 146  * @param path path to the xml node to compare to
 147  * @param s the string to compare to.
 148  * @return an integer less than, equal to, ro greater than zero if the value
 149  * of the node is found, respectively, to be less than, to match, or be greater
 150  * than s
 151  */
 152 int xmlCompareNodeString(const void *, const char *, const char *);
 153
 154 /**
 155  * Get the integer value from the current node
 156  *
 157  * @param xid XML-id
 158  * @return the contents of the node converted to an integer value.
 159  */
 160 long int xmlGetInt(void *);
 161
 162 /**
 163  * Get an integer value from a specified xml path
 164  *
 165  * @param xid XML-id
 166  * @param path path to the xml node
 167  * @return the contents of the node converted to an integer value.
 168  */
 169 long int xmlGetNodeInt(void *, const char *);
 170
 171 /**
 172  * Get the double value from the curent node
 173  *
 174  * @param xid XML-id
 175  * @return the contents of the node converted to a double value.
 176  */
 177 double xmlGetDouble(void *);
 178
 179 /**
 180  * Get a double value from a specified xml path
 181  *
 182  * @param xid XML-id
 183  * @param path path to the xml node
 184  * @return the contents of the node converted to a double value.
 185  */
 186 double xmlGetNodeDouble(void *, const char *);
 187
 188 void *xmlMarkId(void *);
 189
 190 #endif /* __XML_CONFIG */
 191