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