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;
130 /****f* silcutil/silc_xml_parser_create
134 * SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
135 * SilcXMLParserHandler handler,
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.
147 SilcXMLParser silc_xml_parser_create(SilcXMLParams params,
148 SilcXMLParserHandler handler,
151 /****f* silcutil/silc_xml_parser_free
155 * void silc_xml_parser_free(SilcXMLParser parser);
162 void silc_xml_parser_free(SilcXMLParser parser);
164 /****f* silcutil/silc_xml_parse
168 * SilcBool silc_xml_parse(SilcXMLParser parser,
169 * const unsigned char *data,
170 * SilcUInt32 data_len);
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.
178 * Returns FALSE and set silc_errno and silc_errno_reason if error
182 SilcBool silc_xml_parse(SilcXMLParser parser,
183 const unsigned char *data,
184 SilcUInt32 data_len);
186 /****f* silcutil/silc_xml_parse_file
190 * SilcBool silc_xml_parse_file(SilcXMLParser parser,
191 * const char *filename);
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.
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.
204 SilcBool silc_xml_parse_file(SilcXMLParser parser,
205 const char *filename);
207 /****f* silcutil/silc_xml_get_attribute
211 * const char *silc_xml_get_attribute(SilcXMLParser parser,
212 * SilcHashTable attributes,
217 * Returns the value of the attributes namaed `name' or NULL if no such
218 * attribute exist in the hash table of `attributes'.
221 const char *silc_xml_get_attribute(SilcXMLParser parser,
222 SilcHashTable attributes,
225 /****f* silcutil/silc_xml_current_location
229 * void silc_xml_current_location(SilcXMLParser parser,
230 * SilcUInt32 *current_line,
231 * SilcUInt32 *current_column);
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
241 void silc_xml_current_location(SilcXMLParser parser,
242 SilcUInt32 *current_line,
243 SilcUInt32 *current_column);
245 #endif /* SILCXML_H */