5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2008 Pekka Riikonen
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.
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.
20 /****h* silcutil/XML Interface
24 * XML parser interface provides simple stream based interface for parsing
29 * SilcXMLParser parser;
31 * // Create XML parser
32 * parser = silc_xml_parser_create(NULL, &handler, ctx);
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());
41 * silc_xml_parser_free(parser);
48 /****s* silcutil/SilcXMLParser
52 * typedef struct SilcXMLParserStruct *SilcXMLParser;
56 * The XLM parser context allocated by silc_xml_parser_create. It is
57 * freed by calling silc_xml_parser_free.
60 typedef struct SilcXMLParserStruct *SilcXMLParser;
62 /****s* silcutil/SilcXMLParserHandler
66 * typedef struct SilcXMLParserHandlerObject { ... }
67 * SilcXMLParserHandler, SilcXMLParserHandlerStruct;
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.
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,
85 SilcHashTable attributes,
88 /* Called and the end of an XML element. The `name' is the element name. */
89 void (*end_element)(SilcXMLParser parser,
93 /* Called to deliver the characters or whatever data is in the element. */
94 void (*data)(SilcXMLParser parser,
95 const unsigned char *data,
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,
107 } *SilcXMLParserHandler, SilcXMLParserHandlerStruct;
110 /****s* silcutil/SilcXMLParams
114 * typedef struct SilcXMLParamsObject { ... }
115 * *SilcXMLParams, SilcXMLParamsStruct;
119 * The XML parser parameters that can be give as argument to the
120 * silc_xml_parser_create.
124 typedef struct SilcXMLParamsObject {
125 /* Do not process XML namespaces. */
126 SilcBool no_namespace;
127 } *SilcXMLParams, SilcXMLParamsStruct;
129 /****f* silcutil/silc_xml_parser_create
133 * SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
134 * SilcXMLParserHandler handler,
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.
146 SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
147 SilcXMLParserHandler handler,
150 /****f* silcutil/silc_xml_parser_free
154 * void silc_xml_parser_free(SilcXMLParser parser);
161 void silc_xml_parser_free(SilcXMLParser parser);
163 /****f* silcutil/silc_xml_parse
167 * SilcBool silc_xml_parse(SilcXMLParser parser,
168 * const unsigned char *data,
169 * SilcUInt32 data_len);
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.
177 * Returns FALSE and set silc_errno and silc_errno_reason if error
181 SilcBool silc_xml_parse(SilcXMLParser parser,
182 const unsigned char *data,
183 SilcUInt32 data_len);
185 /****f* silcutil/silc_xml_parse_file
189 * SilcBool silc_xml_parse_file(SilcXMLParser parser,
190 * const char *filename);
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.
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.
203 SilcBool silc_xml_parse_file(SilcXMLParser parser,
204 const char *filename);
206 /****f* silcutil/silc_xml_get_attribute
210 * const char *silc_xml_get_attribute(SilcXMLParser parser,
211 * SilcHashTable attributes,
216 * Returns the value of the attributes namaed `name' or NULL if no such
217 * attribute exist in the hash table of `attributes'.
220 const char *silc_xml_get_attribute(SilcXMLParser parser,
221 SilcHashTable attributes,
224 /****f* silcutil/silc_xml_get_attribute
228 * void silc_xml_current_location(SilcXMLParser parser,
229 * SilcUInt32 *current_line,
230 * SilcUInt32 *current_column);
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
240 void silc_xml_current_location(SilcXMLParser parser,
241 SilcUInt32 *current_line,
242 SilcUInt32 *current_column);
244 #endif /* SILCXML_H */