|
996
|
1 /**
|
|
|
2 * @file
|
|
|
3 * genx - C-callable library for generating XML documents
|
|
|
4 */
|
|
|
5
|
|
|
6 #ifndef GENX_H
|
|
|
7 #define GENX_H
|
|
|
8
|
|
|
9 /*
|
|
|
10 * Copyright (c) 2004 by Tim Bray and Sun Microsystems. For copying
|
|
|
11 * permission, see http://www.tbray.org/ongoing/genx/COPYING
|
|
|
12 */
|
|
|
13
|
|
|
14 #include "../../src/global.h"
|
|
|
15
|
|
|
16 #if !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT)
|
|
|
17
|
|
|
18 #include <stdio.h>
|
|
|
19
|
|
|
20 /**
|
|
|
21 * @defgroup genx Genx - XML generation functions
|
|
|
22 * A library for writing XML.
|
|
|
23 */
|
|
|
24 /*@{*/
|
|
|
25
|
|
|
26 /**
|
|
|
27 * Note on error handling: genx routines mostly return
|
|
|
28 * GENX_SUCCESS (guaranteed to be zero) in normal circumstances, one of
|
|
|
29 * these other GENX_ values on a memory allocation or I/O failure or if the
|
|
|
30 * call would result in non-well-formed output.
|
|
|
31 * You can associate an error message with one of these codes explicitly
|
|
|
32 * or with the most recent error using genxGetErrorMessage() and
|
|
|
33 * genxLastErrorMessage(); see below.
|
|
|
34 */
|
|
|
35 typedef enum {
|
|
|
36 GENX_SUCCESS = 0,
|
|
|
37 GENX_BAD_UTF8,
|
|
|
38 GENX_NON_XML_CHARACTER,
|
|
|
39 GENX_BAD_NAME,
|
|
|
40 GENX_ALLOC_FAILED,
|
|
|
41 GENX_BAD_NAMESPACE_NAME,
|
|
|
42 GENX_INTERNAL_ERROR,
|
|
|
43 GENX_DUPLICATE_PREFIX,
|
|
|
44 GENX_SEQUENCE_ERROR,
|
|
|
45 GENX_NO_START_TAG,
|
|
|
46 GENX_IO_ERROR,
|
|
|
47 GENX_MISSING_VALUE,
|
|
|
48 GENX_MALFORMED_COMMENT,
|
|
|
49 GENX_XML_PI_TARGET,
|
|
|
50 GENX_MALFORMED_PI,
|
|
|
51 GENX_DUPLICATE_ATTRIBUTE,
|
|
|
52 GENX_ATTRIBUTE_IN_DEFAULT_NAMESPACE,
|
|
|
53 GENX_DUPLICATE_NAMESPACE,
|
|
|
54 GENX_BAD_DEFAULT_DECLARATION
|
|
|
55 } genxStatus;
|
|
|
56
|
|
|
57 /** character types */
|
|
|
58 #define GENX_XML_CHAR 1
|
|
|
59 /** character types */
|
|
|
60 #define GENX_LETTER 2
|
|
|
61 /** character types */
|
|
|
62 #define GENX_NAMECHAR 4
|
|
|
63
|
|
|
64 /**
|
|
|
65 * @defgroup genx_types Genx's types
|
|
|
66 */
|
|
|
67 /*@{*/
|
|
|
68 /** An UTF-8 string */
|
|
|
69 typedef unsigned char * utf8;
|
|
|
70 /** A const UTF-8 string */
|
|
|
71 typedef const unsigned char * constUtf8;
|
|
|
72
|
|
|
73 /// A writer, the main struct.
|
|
|
74 typedef struct genxWriter_rec * genxWriter;
|
|
|
75 /// A namespace.
|
|
|
76 typedef struct genxNamespace_rec * genxNamespace;
|
|
|
77 /// An element.
|
|
|
78 typedef struct genxElement_rec * genxElement;
|
|
|
79 /// An attribute.
|
|
|
80 typedef struct genxAttribute_rec * genxAttribute;
|
|
|
81 /*@}*/
|
|
|
82
|
|
|
83 /*
|
|
|
84 * Constructors, set/get
|
|
|
85 */
|
|
|
86
|
|
|
87 /**
|
|
|
88 * Create a new writer. For generating multiple XML documents, it's most
|
|
|
89 * efficient to re-use the same genx object. However, you can only write
|
|
|
90 * one document at a time with a writer.
|
|
|
91 * @return NULL if it fails, which can only be due to an allocation failure.
|
|
|
92 */
|
|
|
93 FUNGE_ATTR_FAST FUNGE_ATTR_MALLOC FUNGE_ATTR_WARN_UNUSED
|
|
|
94 genxWriter genxNew(void);
|
|
|
95
|
|
|
96 /**
|
|
|
97 * Dispose of a writer, freeing all associated memory
|
|
|
98 */
|
|
|
99 FUNGE_ATTR_FAST
|
|
|
100 void genxDispose(genxWriter w);
|
|
|
101
|
|
|
102 /*
|
|
|
103 * Set/get
|
|
|
104 */
|
|
|
105
|
|
|
106 /**
|
|
|
107 * Get the prefix associated with a namespace
|
|
|
108 */
|
|
|
109 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
110 utf8 genxGetNamespacePrefix(genxNamespace ns);
|
|
|
111
|
|
|
112 /*
|
|
|
113 * Declaration functions
|
|
|
114 */
|
|
|
115
|
|
|
116 /**
|
|
|
117 * Declare a namespace. The provided prefix is the default but can be
|
|
|
118 * overridden by genxAddNamespace. If no default prefiix is provided,
|
|
|
119 * genx will generate one of the form g-%d.
|
|
|
120 * On error, returns NULL and signals via statusp
|
|
|
121 */
|
|
|
122 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
123 genxNamespace genxDeclareNamespace(genxWriter w,
|
|
|
124 constUtf8 uri, constUtf8 prefix,
|
|
|
125 genxStatus * statusP);
|
|
|
126
|
|
|
127 /**
|
|
|
128 * Declare an element
|
|
|
129 * If something failed, returns NULL and sets the status code via statusP
|
|
|
130 */
|
|
|
131 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
132 genxElement genxDeclareElement(genxWriter w,
|
|
|
133 genxNamespace ns, constUtf8 type,
|
|
|
134 genxStatus * statusP);
|
|
|
135
|
|
|
136 /**
|
|
|
137 * Declare an attribute
|
|
|
138 */
|
|
|
139 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
140 genxAttribute genxDeclareAttribute(genxWriter w,
|
|
|
141 genxNamespace ns,
|
|
|
142 constUtf8 name, genxStatus * statusP);
|
|
|
143
|
|
|
144 /*
|
|
|
145 * Writing XML
|
|
|
146 */
|
|
|
147
|
|
|
148 /**
|
|
|
149 * Start a new document.
|
|
|
150 */
|
|
|
151 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
152 genxStatus genxStartDocFile(genxWriter w, FILE * file);
|
|
|
153
|
|
|
154 /**
|
|
|
155 * Caller-provided I/O package.
|
|
|
156 * First form is for a null-terminated string.
|
|
|
157 * for second, if you have s="abcdef" and want to send "abc", you'd call
|
|
|
158 * sendBounded(userData, s, s + 3)
|
|
|
159 */
|
|
|
160 typedef struct {
|
|
|
161 genxStatus(* send)(void * userData, constUtf8 s);
|
|
|
162 genxStatus(* sendBounded)(void * userData, constUtf8 start, constUtf8 end);
|
|
|
163 genxStatus(* flush)(void * userData);
|
|
|
164 } genxSender;
|
|
|
165
|
|
|
166 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
167 genxStatus genxStartDocSender(genxWriter w, genxSender * sender);
|
|
|
168
|
|
|
169 /**
|
|
|
170 * End a document. Calls "flush"
|
|
|
171 */
|
|
|
172 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
173 genxStatus genxEndDocument(genxWriter w);
|
|
|
174
|
|
|
175 /**
|
|
|
176 * Write a comment
|
|
|
177 */
|
|
|
178 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
179 genxStatus genxComment(genxWriter w, constUtf8 text);
|
|
|
180
|
|
|
181 /**
|
|
|
182 * Write a PI
|
|
|
183 */
|
|
|
184 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
185 genxStatus genxPI(genxWriter w, constUtf8 target, constUtf8 text);
|
|
|
186
|
|
|
187 /**
|
|
|
188 * Start an element
|
|
|
189 */
|
|
|
190 FUNGE_ATTR_FAST
|
|
|
191 genxStatus genxStartElementLiteral(genxWriter w,
|
|
|
192 constUtf8 xmlns, constUtf8 type);
|
|
|
193
|
|
|
194 /**
|
|
|
195 * Start a predeclared element
|
|
|
196 * - element must have been declared
|
|
|
197 */
|
|
|
198 FUNGE_ATTR_FAST
|
|
|
199 genxStatus genxStartElement(genxElement e);
|
|
|
200
|
|
|
201 /**
|
|
|
202 * Write an attribute
|
|
|
203 */
|
|
|
204 FUNGE_ATTR_FAST
|
|
|
205 genxStatus genxAddAttributeLiteral(genxWriter w, constUtf8 xmlns,
|
|
|
206 constUtf8 name, constUtf8 value);
|
|
|
207
|
|
|
208 /**
|
|
|
209 * Write a predeclared attribute
|
|
|
210 */
|
|
|
211 FUNGE_ATTR_FAST
|
|
|
212 genxStatus genxAddAttribute(genxAttribute a, constUtf8 value);
|
|
|
213
|
|
|
214 /**
|
|
|
215 * Add a namespace declaration
|
|
|
216 */
|
|
|
217 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
218 genxStatus genxAddNamespace(genxNamespace ns, utf8 prefix);
|
|
|
219
|
|
|
220 /**
|
|
|
221 * Clear default namespace declaration
|
|
|
222 */
|
|
|
223 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
224 genxStatus genxUnsetDefaultNamespace(genxWriter w);
|
|
|
225
|
|
|
226 /**
|
|
|
227 * Write an end tag
|
|
|
228 */
|
|
|
229 FUNGE_ATTR_FAST
|
|
|
230 genxStatus genxEndElement(genxWriter w);
|
|
|
231
|
|
|
232 /**
|
|
|
233 * Write some text
|
|
|
234 * You can't write any text outside the root element, except with
|
|
|
235 * genxComment and genxPI
|
|
|
236 */
|
|
|
237 FUNGE_ATTR_FAST
|
|
|
238 genxStatus genxAddText(genxWriter w, constUtf8 start);
|
|
|
239 FUNGE_ATTR_FAST
|
|
|
240 genxStatus genxAddCountedText(genxWriter w, constUtf8 start, int byteCount);
|
|
|
241 FUNGE_ATTR_FAST
|
|
|
242 genxStatus genxAddBoundedText(genxWriter w, constUtf8 start, constUtf8 end);
|
|
|
243
|
|
|
244 /**
|
|
|
245 * Write one character. The integer value is the Unicode character
|
|
|
246 * value, as usually expressed in U+XXXX notation.
|
|
|
247 */
|
|
|
248 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
249 genxStatus genxAddCharacter(genxWriter w, int c);
|
|
|
250
|
|
|
251 /*
|
|
|
252 * Utility routines
|
|
|
253 */
|
|
|
254
|
|
|
255 /**
|
|
|
256 * Return the Unicode character encoded by the UTF-8 pointed-to by the
|
|
|
257 * argument, and advance the argument past the encoding of the character.
|
|
|
258 * @returns
|
|
|
259 * -1 if the UTF-8 is malformed, in which case advances the
|
|
|
260 * argument to point at the first byte past the point past the malformed
|
|
|
261 * ones.
|
|
|
262 */
|
|
|
263 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
264 int genxNextUnicodeChar(constUtf8 * sp);
|
|
|
265
|
|
|
266 /**
|
|
|
267 * Scan a buffer allegedly full of UTF-8 encoded XML characters; return
|
|
|
268 * one of GENX_SUCCESS, GENX_BAD_UTF8, or GENX_NON_XML_CHARACTER
|
|
|
269 */
|
|
|
270 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
271 genxStatus genxCheckText(const genxWriter restrict w, constUtf8 s);
|
|
|
272
|
|
|
273 /**
|
|
|
274 * Return character status, the OR of GENX_XML_CHAR,
|
|
|
275 * GENX_LETTER, and GENX_NAMECHAR
|
|
|
276 */
|
|
|
277 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
278 int genxCharClass(const genxWriter restrict w, int c);
|
|
|
279
|
|
|
280 /**
|
|
|
281 * Silently wipe any non-XML characters out of a chunk of text.
|
|
|
282 * If you call this on a string before you pass it addText or
|
|
|
283 * addAttribute, you will never get an error from genx unless
|
|
|
284 * (a) there's a bug in your software, e.g. a malformed element name, or
|
|
|
285 * (b) there's a memory allocation or I/O error
|
|
|
286 * The output can never be longer than the input.
|
|
|
287 * @returns true if any changes were made.
|
|
|
288 */
|
|
|
289 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
290 int genxScrubText(const genxWriter restrict w, constUtf8 in, utf8 out);
|
|
|
291
|
|
|
292 /**
|
|
|
293 * Return a specific error message.
|
|
|
294 * @param w The genxWriter in question.
|
|
|
295 * @param status What status to look up.
|
|
|
296 */
|
|
|
297 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
298 const char * genxGetErrorMessage(const genxWriter restrict w, genxStatus status);
|
|
|
299 /**
|
|
|
300 * Return last error message.
|
|
|
301 * @param w The genxWriter in question.
|
|
|
302 */
|
|
|
303 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
304 const char * genxLastErrorMessage(const genxWriter restrict w);
|
|
|
305
|
|
|
306 /**
|
|
|
307 * Return version of genx.
|
|
|
308 */
|
|
|
309 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
|
|
|
310 const char * genxGetVersion(void);
|
|
|
311
|
|
|
312 /*@}*/
|
|
|
313
|
|
|
314 #ifdef GENX_INTERNAL
|
|
|
315 FUNGE_ATTR_FAST void genxSetCharProps(char * restrict p);
|
|
|
316 #endif
|
|
|
317
|
|
|
318 #endif /* !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT) */
|
|
|
319
|
|
|
320 #endif /* GENX_H */
|
