lib/silcutil/silcxml.h

   1 /*
   2
   3   silcxml.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/XML Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * XML parser interface provides simple stream based interface for parsing
  25  * XML data and files.
  26  *
  27  * EXAMPLE
  28  *
  29  * SilcXMLParser parser;
  30  *
  31  * // Create XML parser
  32  * parser = silc_xml_parser_create(NULL, &handler, ctx);
  33  *
  34  * // Parse XML file
  35  * if (!silc_xml_parse_file(parser, filename)) {
  36  *   silc_errno_location(NULL, &cur_line, NULL);
  37  *   fatal("Error %s:%d: %s", filename, cur_line, silc_errno_reason());
  38  * }
  39  *
  40  * // Free parser
  41  * silc_xml_parser_free(parser);
  42  *
  43  ***/
  44
  45 #ifndef SILCXML_H
  46 #define SILCXML_H
  47
  48 /****s* silcutil/SilcXMLParser
  49  *
  50  * NAME
  51  *
  52  *    typedef struct SilcXMLParserStruct *SilcXMLParser;
  53  *
  54  * DESCRIPTION
  55  *
  56  *    The XLM parser context allocated by silc_xml_parser_create.  It is
  57  *    freed by calling silc_xml_parser_free.
  58  *
  59  ***/
  60 typedef struct SilcXMLParserStruct *SilcXMLParser;
  61
  62 /****s* silcutil/SilcXMLParserHandler
  63  *
  64  * NAME
  65  *
  66  *    typedef struct SilcXMLParserHandlerObject { ... }
  67  *                   SilcXMLParserHandler, SilcXMLParserHandlerStruct;
  68  *
  69  * DESCRIPTION
  70  *
  71  *    The XML parser handler function callbacks are declared in this
  72  *    structure.  The structure is given as argument to the
  73  *    silc_xml_parser_create.
  74  *
  75  * SOURCE
  76  */
  77 typedef struct SilcXMLParserHandlerObject {
  78   /* Called at the start of an XML element.  The `name' is the element name.
  79      The `attributes' is the element attributes or NULL if there were no
  80      attributes.  The `attributes' may be enumerated using the SilcHashTable
  81      API.  The silc_xml_get_attribute can be used to retrieve the attribute
  82      values from the `attributes' by their name. */
  83   void (*start_element)(SilcXMLParser parser,
  84                         const char *name,
  85                         SilcHashTable attributes,
  86                         void *context);
  87
  88   /* Called and the end of an XML element.  The `name' is the element name. */
  89   void (*end_element)(SilcXMLParser parser,
  90                       const char *name,
  91                       void *context);
  92
  93   /* Called to deliver the characters or whatever data is in the element. */
  94   void (*data)(SilcXMLParser parser,
  95                const unsigned char *data,
  96                SilcUInt32 data_len,
  97                void *context);
  98
  99   /* Called to deliver a processing instruction.  The `target' is the first
 100      word in the processing instruction.  The `data' is the rest of the
 101      characters in it skipping all whitespace after the initial word.  This
 102      callback may be NULL if it is not needed. */
 103   void (*pi)(SilcXMLParser parser,
 104              const char *target,
 105              const char *data,
 106              void *context);
 107 } *SilcXMLParserHandler, SilcXMLParserHandlerStruct;
 108 /***/
 109
 110 /****s* silcutil/SilcXMLParams
 111  *
 112  * NAME
 113  *
 114  *    typedef struct SilcXMLParamsObject { ... }
 115  *                                *SilcXMLParams, SilcXMLParamsStruct;
 116  *
 117  * DESCRIPTION
 118  *
 119  *    The XML parser parameters that can be give as argument to the
 120  *    silc_xml_parser_create.
 121  *
 122  * SOURCE
 123  */
 124 typedef struct SilcXMLParamsObject {
 125   /* Do not process XML namespaces. */
 126   SilcBool no_namespace;
 127 } *SilcXMLParams, SilcXMLParamsStruct;
 128 /***/
 129
 130 /****f* silcutil/silc_xml_parser_create
 131  *
 132  * SYNOPSIS
 133  *
 134  *    SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
 135  *                                         SilcXMLParserHandler handler,
 136  *                                         void *context);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Create XML parser and return in.  The `handler' contains the callback
 141  *    functions to be called while parsing XML data.  The `context' is
 142  *    delivered to each callback function.  The `params' define parser
 143  *    parameters, and may be NULL.  The parser parses XML data with UTF-8
 144  *    encoding.  All characters delivered to callbacks are in UTF-8 encoding.
 145  *
 146  ***/
 147 SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
 148                                      SilcXMLParserHandler handler,
 149                                      void *context);
 150
 151 /****f* silcutil/silc_xml_parser_free
 152  *
 153  * SYNOPSIS
 154  *
 155  *    void silc_xml_parser_free(SilcXMLParser parser);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Free's XML parser.
 160  *
 161  ***/
 162 void silc_xml_parser_free(SilcXMLParser parser);
 163
 164 /****f* silcutil/silc_xml_parse
 165  *
 166  * SYNOPSIS
 167  *
 168  *    SilcBool silc_xml_parse(SilcXMLParser parser,
 169  *                            const unsigned char *data,
 170  *                            SilcUInt32 data_len);
 171  *
 172  * DESCRIPTION
 173  *
 174  *    Parse XML data `data' of length of `data_len' bytes.  Returns TRUE
 175  *    after the data has been parsed.  The handler callback functions set for
 176  *    `parser' will be called while parsing the XML data.
 177  *
 178  *    Returns FALSE and set silc_errno and silc_errno_reason if error
 179  *    occurs.
 180  *
 181  ***/
 182 SilcBool silc_xml_parse(SilcXMLParser parser,
 183                         const unsigned char *data,
 184                         SilcUInt32 data_len);
 185
 186 /****f* silcutil/silc_xml_parse_file
 187  *
 188  * SYNOPSIS
 189  *
 190  *    SilcBool silc_xml_parse_file(SilcXMLParser parser,
 191  *                                 const char *filename);
 192  *
 193  * DESCRIPTION
 194  *
 195  *    Parse XML file indicated by `filename'.  Returns TRUE after the file
 196  *    has been parsed.  The handler callback functions set for `parser' will
 197  *    be called while parsing the XML file.
 198  *
 199  *    Returns FALSE and set silc_errno and silc_errno_reason if error
 200  *    occurs.  The silc_errno_location can be used to retrieve the exact
 201  *    location in the file where the error occurred.
 202  *
 203  ***/
 204 SilcBool silc_xml_parse_file(SilcXMLParser parser,
 205                              const char *filename);
 206
 207 /****f* silcutil/silc_xml_get_attribute
 208  *
 209  * SYNOPSIS
 210  *
 211  *    const char *silc_xml_get_attribute(SilcXMLParser parser,
 212  *                                       SilcHashTable attributes,
 213  *                                       const char *name);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Returns the value of the attributes namaed `name' or NULL if no such
 218  *    attribute exist in the hash table of `attributes'.
 219  *
 220  ***/
 221 const char *silc_xml_get_attribute(SilcXMLParser parser,
 222                                    SilcHashTable attributes,
 223                                    const char *name);
 224
 225 /****f* silcutil/silc_xml_current_location
 226  *
 227  * SYNOPSIS
 228  *
 229  *    void silc_xml_current_location(SilcXMLParser parser,
 230  *                                   SilcUInt32 *current_line,
 231  *                                   SilcUInt32 *current_column);
 232  *
 233  * DESCRIPTION
 234  *
 235  *    Return the current location of the parsed XML data.  The current line
 236  *    number and columns can be returned.  This may be used also when an
 237  *    error occurs but it is preferred to use silc_errno_location in case
 238  *    of error.
 239  *
 240  ***/
 241 void silc_xml_current_location(SilcXMLParser parser,
 242                                SilcUInt32 *current_line,
 243                                SilcUInt32 *current_column);
 244
 245 #endif /* SILCXML_H */