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 /****f* silcutil/silc_xml_parser_create
 130  *
 131  * SYNOPSIS
 132  *
 133  *    SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
 134  *                                         SilcXMLParserHandler handler,
 135  *                                         void *context);
 136  *
 137  * DESCRIPTION
 138  *
 139  *    Create XML parser and return in.  The `handler' contains the callback
 140  *    functions to be called while parsing XML data.  The `context' is
 141  *    delivered to each callback function.  The `params' define parser
 142  *    parameters, and may be NULL.  The parser parses XML data with UTF-8
 143  *    encoding.  All characters delivered to callbacks are in UTF-8 encoding.
 144  *
 145  ***/
 146 SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
 147                                      SilcXMLParserHandler handler,
 148                                      void *context);
 149
 150 /****f* silcutil/silc_xml_parser_free
 151  *
 152  * SYNOPSIS
 153  *
 154  *    void silc_xml_parser_free(SilcXMLParser parser);
 155  *
 156  * DESCRIPTION
 157  *
 158  *    Free's XML parser.
 159  *
 160  ***/
 161 void silc_xml_parser_free(SilcXMLParser parser);
 162
 163 /****f* silcutil/silc_xml_parse
 164  *
 165  * SYNOPSIS
 166  *
 167  *    SilcBool silc_xml_parse(SilcXMLParser parser,
 168  *                            const unsigned char *data,
 169  *                            SilcUInt32 data_len);
 170  *
 171  * DESCRIPTION
 172  *
 173  *    Parse XML data `data' of length of `data_len' bytes.  Returns TRUE
 174  *    after the data has been parsed.  The handler callback functions set for
 175  *    `parser' will be called while parsing the XML data.
 176  *
 177  *    Returns FALSE and set silc_errno and silc_errno_reason if error
 178  *    occurs.
 179  *
 180  ***/
 181 SilcBool silc_xml_parse(SilcXMLParser parser,
 182                         const unsigned char *data,
 183                         SilcUInt32 data_len);
 184
 185 /****f* silcutil/silc_xml_parse_file
 186  *
 187  * SYNOPSIS
 188  *
 189  *    SilcBool silc_xml_parse_file(SilcXMLParser parser,
 190  *                                 const char *filename);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Parse XML file indicated by `filename'.  Returns TRUE after the file
 195  *    has been parsed.  The handler callback functions set for `parser' will
 196  *    be called while parsing the XML file.
 197  *
 198  *    Returns FALSE and set silc_errno and silc_errno_reason if error
 199  *    occurs.  The silc_errno_location can be used to retrieve the exact
 200  *    location in the file where the error occurred.
 201  *
 202  ***/
 203 SilcBool silc_xml_parse_file(SilcXMLParser parser,
 204                              const char *filename);
 205
 206 /****f* silcutil/silc_xml_get_attribute
 207  *
 208  * SYNOPSIS
 209  *
 210  *    const char *silc_xml_get_attribute(SilcXMLParser parser,
 211  *                                       SilcHashTable attributes,
 212  *                                       const char *name);
 213  *
 214  * DESCRIPTION
 215  *
 216  *    Returns the value of the attributes namaed `name' or NULL if no such
 217  *    attribute exist in the hash table of `attributes'.
 218  *
 219  ***/
 220 const char *silc_xml_get_attribute(SilcXMLParser parser,
 221                                    SilcHashTable attributes,
 222                                    const char *name);
 223
 224 /****f* silcutil/silc_xml_get_attribute
 225  *
 226  * SYNOPSIS
 227  *
 228  *    void silc_xml_current_location(SilcXMLParser parser,
 229  *                                   SilcUInt32 *current_line,
 230  *                                   SilcUInt32 *current_column);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Return the current location of the parsed XML data.  The current line
 235  *    number and columns can be returned.  This may be used also when an
 236  *    error occurs but it is preferred to use silc_errno_location in case
 237  *    of error.
 238  *
 239  ***/
 240 void silc_xml_current_location(SilcXMLParser parser,
 241                                SilcUInt32 *current_line,
 242                                SilcUInt32 *current_column);
 243
 244 #endif /* SILCXML_H */