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