Xalan-C++ API Reference 1.12.0
XalanCAPI.h
Go to the documentation of this file.
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18#if !defined(XALAN_CAPI_HEADER_GUARD_1357924680)
19#define XALAN_CAPI_HEADER_GUARD_1357924680
20
21
22
24
25
26
27/**
28 * This is a simple C interface for the class XalanTransformer. It's
29 * the user's responsibility to call XalanInitialize() before making
30 * any other API calls, and to call XalanTerminate() when finished
31 * with the API.
32 *
33 * After calling XalanTransformToData or XalanTransformToDataCSS, the user
34 * should call XalanFreeData to release the memory allocated by that
35 * operation.
36 */
37#if defined(__cplusplus)
38extern "C"
39{
40#endif
41
42 /**
43 * Handle used to store the address of XalanTransformer instance.
44 */
45 typedef void* XalanHandle;
46
47 /**
48 * Handle used to store the address of Compiled Stylesheet instance.
49 */
50 typedef const void* XalanCSSHandle;
51
52 /**
53 * Handle used to store the address of Parsed Source instance.
54 */
55 typedef const void* XalanPSHandle;
56
57 /**
58 * This is a typedef to work around limitations with
59 * the XALAN_TRANSFORMER_EXPORT_FUNCTION macro.
60 */
61 typedef const char* XalanCCharPtr;
62
63 /**
64 * This is a typedef for characters encoded in UTF-16.
65 */
66 typedef XMLCh XalanUTF16Char;
67
68 /**
69 * Initialize Xerces and Xalan.
70 *
71 * Should be called only once per process before making
72 * any other API calls.
73 *
74 * @return 0 if successful, -1 if initialization fails.
75 */
77#if defined(__cplusplus)
79#else
81#endif
82
83 /**
84 * Terminate Xalan and Xerces.
85 *
86 * Should be called only once per process after deleting all
87 * instances of XalanTransformer.
88 *
89 * Once a process has called this function, it cannot use the
90 * API until another call to XalanInitialize has been made.
91 *
92 * Optionally, if the ICU has been integrated, this will
93 * call the ICU clean up function. This must only be done
94 * if the ICU will no longer be used by the process, since
95 * the ICU will no longer be in a usable state. See the
96 * ICU documentation for more details.
97 *
98 * This is handy when using leak-detection software, as all
99 * static data allocated by Xalan (and optionally, the ICU)
100 * will be freed.
101 *
102 * @param fCleanUpICU If true, call the ICU clean up function.
103 */
105 XalanTerminate(int fCleanUpICU);
106
107 /**
108 * Create a XalanTransformer instance.
109 *
110 * @return the XalanTransformer handle
111 */
114
115
116 /**
117 * Delete a XalanTransformer instance.
118 *
119 * @param theXalanHandle The XalanTransformer to destroy.
120 */
123
124 /**
125 * Transform the XML source tree to the given result file.
126 * The processor will apply the stylesheet file to the input
127 * file and write the transformation result to a new output file.
128 *
129 * @param theXMLFileName The file name of the XML document.
130 * @param theXSLFileName The file name of the stylesheet XML document.
131 * @param theOutFileName The file name for the output.
132 * @param theXalanHandle The handle of a XalanTransformer instance.
133 * @return 0 for success
134 */
137 const char* theXMLFileName,
138 const char* theXSLFileName,
139 const char* theOutFileName,
140 XalanHandle theXalanHandle);
141
142 /**
143 * Transform the XML source tree to the given result file.
144 * The processor will apply the compiled stylesheet to the input
145 * file and write the transformation result to a new output file.
146 *
147 * @param theParsedSource The handle of a parsed source
148 * @param theCSSHandle The handle of a compiled stylesheet
149 * @param theOutFileName The file name for the output.
150 * @param theXalanHandle The handle of a XalanTransformer instance.
151 * @return 0 for success
152 */
155 XalanPSHandle theParsedSource,
156 XalanCSSHandle theCSSHandle,
157 const char* theOutFileName,
158 XalanHandle theXalanHandle);
159
160 /**
161 * Transform the XML source tree to a dynamically allocated buffer.
162 * The processor will apply the stylesheet file to the input file
163 * and assign the address of the dynamically allocated result to a
164 * user-supplied pointer. The user must call XalanFreeData with this
165 * pointer to free the memory.
166 *
167 * @param theXMLFileName The file name of the XML document.
168 * @param theXSLFileName The file name of the stylesheet XML document.
169 * @param theOutput a pointer to a char*
170 * @param theXalanHandle handle of XalanTransformer instance.
171 * @return 0 for success
172 */
175 const char* theXMLFileName,
176 const char* theXSLFileName,
177 char** theOutput,
178 XalanHandle theXalanHandle);
179
180 /**
181 * Transform the XML source tree to a dynamically-allocated buffer.
182 * The processor will apply the compiled stylesheet to the input file
183 * and assign the address of the dynamically allocated result to a
184 * user supplied pointer. The user must call XalanFreeData with this
185 * pointer to free the memory.
186 *
187 * @param theParsedSource The handle of a parsed source
188 * @param theCSSHandle The handle of compiled stylesheet
189 * @param theOutput a pointer to a char*
190 * @param theXalanHandle handle of XalanTransformer instance.
191 * @return 0 for success
192 */
195 XalanPSHandle theParsedSource,
196 XalanCSSHandle theCSSHandle,
197 char** theOutput,
198 XalanHandle theXalanHandle);
199
200 /**
201 * Free memory allocated as a result of calling
202 * XalanTransformToData.
203 *
204 * @param theData The address of character data.
205 */
207 XalanFreeData(char* theData);
208
209 /**
210 * Transform the XML source tree to a callback function.
211 * The processor will apply the stylesheet file to the input file
212 * and allocate the transformation result to a callback function
213 * in pre-allocated blocks. Once the transformation is complete,
214 * a second callback, to flush the buffer, is called. You can pass
215 * in NULL if you do not wish to implement a flush callback. Xalan
216 * will release any memory allocated upon termination, and data passed
217 * to the callback is not guaranteed to be null terminated.
218 *
219 * See XalanTransformerDefinitions.hpp for more details.
220 *
221 * @param theXMLFileName The file name of XML input source
222 * @param theXSLFileName The file name of stylesheet source
223 * @param theXalanHandle The handle of a XalanTransformer instance.
224 * @param theOutputHandle A void pointer passed through to callback.
225 * @param theOutputHandler A user-defined callback function pointer.
226 * @param theFlushHandler A user-defined callback function pointer, which can be null.
227 * @return 0 for success
228 */
231 const char* theXMLFileName,
232 const char* theXSLFileName,
233 XalanHandle theXalanHandle,
234 void* theOutputHandle,
235 XalanOutputHandlerType theOutputHandler,
236 XalanFlushHandlerType theFlushHandler);
237
238 /**
239 * Transform the XML source tree to a callback function.
240 * The processor will apply the compiled stylesheet to the input file
241 * and allocate the transformation result to a callback function
242 * in pre-allocated blocks. Once the transformation is complete,
243 * a second callback, to flush the buffer, is called. You can pass
244 * in NULL if you do not wish to implement a flush callback. Xalan
245 * will release any memory allocated upon termination, and data passed
246 * to the callback is not guaranteed to be null terminated.
247 *
248 * See XalanTransformerDefinitions.hpp for more details.
249 *
250 * @param thePSHandle The handle of parsed source
251 * @param theCSSHandle The handle of compiled stylesheet
252 * @param theXalanHandle The handle of XalanTransformer instance.
253 * @param theOutputHandle A void pointer passed through to callback.
254 * @param theOutputHandler A user-defined callback function pointer.
255 * @param theFlushHandler A user-defined callback function pointer, which can be null.
256 * @return 0 for success
257 */
260 XalanPSHandle thePSHandle,
261 XalanCSSHandle theCSSHandle,
262 XalanHandle theXalanHandle,
263 void* theOutputHandle,
264 XalanOutputHandlerType theOutputHandler,
265 XalanFlushHandlerType theFlushHandler);
266
267 /**
268 * Creates a compiled stylesheet.
269 *
270 * @param theXSLFileName The file name of stylesheet source
271 * @param theXalanHandle The handle of XalanTransformer instance.
272 * @param theCSSHandle a pointer to a XalanCSSHandle
273 * @return 0 for success.
274 */
277 const char* theXSLFileName,
278 XalanHandle theXalanHandle,
279 XalanCSSHandle* theCSSHandle);
280
281 /**
282 * Creates a compiled stylesheet.
283 *
284 * @param theXSLFileName The stream that contains the stylesheet xml
285 * @param theXSLStreamLength The length of the stream.
286 * @param theXalanHandle handle of XalanTransformer instance.
287 * @param theCSSHandle a pointer to a XalanCSSHandle
288 * @return 0 for success.
289 */
292 const char* theXSLStream,
293 unsigned long theXSLStreamLength,
294 XalanHandle theXalanHandle,
295 XalanCSSHandle* theCSSHandle);
296
297 /**
298 * Destroys a compiled stylesheet.
299 *
300 * @param theCSSHandle The handle of the compiled stylesheet.
301 * @param theXalanHandle The handle of XalanTransformer instance.
302 * @return 0 for success
303 */
306 XalanCSSHandle theCSSHandle,
307 XalanHandle theXalanHandle);
308
309 /**
310 * Parse source document.
311 *
312 * @param theXMLFileName The name of the file containing the source document
313 * @param theXalanHandle The handle of XalanTransformer instance.
314 * @param thePSHandle A pointer to a XalanPSHandle
315 * @return 0 for success.
316 */
319 const char* theXMLFileName,
320 XalanHandle theXalanHandle,
321 XalanPSHandle* thePSHandle);
322
323 /**
324 * Parse source document from a stream.
325 *
326 * @param theXMLStream The stream that contains the source xml
327 * @param theXSLStreamLength The length of the stream
328 * @param theXalanHandle The handle of XalanTransformer instance
329 * @param thePSHandle A pointer to a XalanPSHandle
330 * @return 0 for success.
331 */
334 const char* theXMLStream,
335 unsigned long theXMLStreamLength,
336 XalanHandle theXalanHandle,
337 XalanPSHandle* thePSHandle);
338
339 /**
340 * Destroys a parsed source.
341 * a file name, a stream or a root node.
342 *
343 * @param thePSHandle The handle of parsed source
344 * @param theXalanHandle The handle of XalanTransformer instance.
345 * @return 0 for success
346 */
349 XalanPSHandle thePSHandle,
350 XalanHandle theXalanHandle);
351
352 /**
353 * Set a top-level stylesheet parameter. This value can be evaluated via
354 * xsl:param-variable.
355 *
356 * @param key The name of the param
357 * @param expression The expression that will be evaluated
358 * @param theXalanHandle The handle of XalanTransformer instance.
359 */
362 const char* key,
363 const char* expression,
364 XalanHandle theXalanHandle);
365
366 /**
367 * Set a top-level stylesheet parameter. This value can be evaluated via
368 * xsl:param-variable. The key and expression parameters must be
369 * encoded in UTF-16.
370 *
371 * @param key name of the param
372 * @param expression expression that will be evaluated
373 * @param theXalanHandle handle of XalanTransformer instance.
374 */
377 const XalanUTF16Char* key,
378 const XalanUTF16Char* expression,
379 XalanHandle theXalanHandle);
380
381
382 /**
383 * Set a top-level stylesheet nodeset parameter. This value can be
384 * evaluated via xsl:param-variable. The value is a parsed document.
385 *
386 * @param key name of the param
387 * @param theNodeset a preparsed document
388 * @param theXalanHandle handle of the XalanTransformer instance.
389 */
392 const char* key,
393 XalanPSHandle theNodeset,
394 XalanHandle theXalanHandle);
395
396 /**
397 * Set a top-level stylesheet nodeset parameter. This value can be
398 * evaluated via xsl:param-variable. The value is a parsed document.
399 * The key name is a UTF-16 string.
400 *
401 * @param key name of the param
402 * @param theNodeset a preparsed document
403 * @param theXalanHandle handle of the XalanTransformer instance.
404 */
407 const XalanUTF16Char* key,
408 XalanPSHandle theNodeset,
409 XalanHandle theXalanHandle);
410
411 /**
412 * Set a top-level stylesheet number parameter. This value can be
413 * evaluated via xsl:param-variable. The value is a parsed document.
414 *
415 * @param key name of the param
416 * @param theNumber a double floating point number
417 * @param theXalanHandle handle of the XalanTransformer instance.
418 */
421 const char* key,
422 double theNumber,
423 XalanHandle theXalanHandle);
424
425 /**
426 * Set a top-level stylesheet number parameter. This value can be
427 * evaluated via xsl:param-variable. The value is a parsed document.
428 * The key name is a UTF-16 string.
429 *
430 * @param key name of the param
431 * @param theNumber a double floating point number
432 * @param theXalanHandle handle of the XalanTransformer instance.
433 */
436 const XalanUTF16Char* key,
437 double theNumber,
438 XalanHandle theXalanHandle);
439
440 /**
441 * Clear the top-level stylesheet parameters. Top-level stylesheet
442 * parameters are sticky. When set, they can be used for multiple
443 * transformations. Use the XalanClearStylesheetParams function
444 * to clear or reset the top-level stylesheet parameters.
445 *
446 * @param theXalanHandle handle of the XalanTransformer instance.
447 */
450 XalanHandle theXalanHandle);
451
452 /**
453 * Returns the last error that occurred as a
454 * result of calling transform.
455 *
456 * The signature for following function is really:
457 * const char*
458 * XalanGetLastError(XalanHandle theXalanHandle) const;
459 *
460 * @return error message const character pointer.
461 */
464
465#if defined(__cplusplus)
466}
467#endif
468
469
470
471#endif // XALAN_CAPI_HEADER_GUARD_1357924680
XalanCompileStylesheet(const char *theXSLFileName, XalanHandle theXalanHandle, XalanCSSHandle *theCSSHandle)
Creates a compiled stylesheet.
XalanCompileStylesheetFromStream(const char *theXSLStream, unsigned long theXSLStreamLength, XalanHandle theXalanHandle, XalanCSSHandle *theCSSHandle)
Creates a compiled stylesheet.
CreateXalanTransformer()
Create a XalanTransformer instance.
XalanClearStylesheetParams(XalanHandle theXalanHandle)
Clear the top-level stylesheet parameters.
const void * XalanCSSHandle
Handle used to store the address of Compiled Stylesheet instance.
Definition XalanCAPI.h:50
const void * XalanPSHandle
Handle used to store the address of Parsed Source instance.
Definition XalanCAPI.h:55
DeleteXalanTransformer(XalanHandle theXalanHandle)
Delete a XalanTransformer instance.
XalanSetStylesheetParamUTFNumber(const XalanUTF16Char *key, double theNumber, XalanHandle theXalanHandle)
Set a top-level stylesheet number parameter.
void * XalanHandle
This is a simple C interface for the class XalanTransformer.
Definition XalanCAPI.h:45
const char * XalanCCharPtr
This is a typedef to work around limitations with the XALAN_TRANSFORMER_EXPORT_FUNCTION macro.
Definition XalanCAPI.h:61
XalanSetStylesheetParamNumber(const char *key, double theNumber, XalanHandle theXalanHandle)
Set a top-level stylesheet number parameter.
XalanTransformToFile(const char *theXMLFileName, const char *theXSLFileName, const char *theOutFileName, XalanHandle theXalanHandle)
Transform the XML source tree to the given result file.
XMLCh XalanUTF16Char
This is a typedef for characters encoded in UTF-16.
Definition XalanCAPI.h:66
XalanParseSourceFromStream(const char *theXMLStream, unsigned long theXMLStreamLength, XalanHandle theXalanHandle, XalanPSHandle *thePSHandle)
Parse source document from a stream.
XalanTransformToHandler(const char *theXMLFileName, const char *theXSLFileName, XalanHandle theXalanHandle, void *theOutputHandle, XalanOutputHandlerType theOutputHandler, XalanFlushHandlerType theFlushHandler)
Transform the XML source tree to a callback function.
XalanFreeData(char *theData)
Free memory allocated as a result of calling XalanTransformToData.
XalanDestroyCompiledStylesheet(XalanCSSHandle theCSSHandle, XalanHandle theXalanHandle)
Destroys a compiled stylesheet.
XalanParseSource(const char *theXMLFileName, XalanHandle theXalanHandle, XalanPSHandle *thePSHandle)
Parse source document.
XalanTerminate(int fCleanUpICU)
Terminate Xalan and Xerces.
XalanSetStylesheetParamUTF(const XalanUTF16Char *key, const XalanUTF16Char *expression, XalanHandle theXalanHandle)
Set a top-level stylesheet parameter.
XalanDestroyParsedSource(XalanPSHandle thePSHandle, XalanHandle theXalanHandle)
Destroys a parsed source.
XalanInitialize(void)
Initialize Xerces and Xalan.
XalanGetLastError(XalanHandle theXalanHandle)
Returns the last error that occurred as a result of calling transform.
XalanTransformToHandlerPrebuilt(XalanPSHandle thePSHandle, XalanCSSHandle theCSSHandle, XalanHandle theXalanHandle, void *theOutputHandle, XalanOutputHandlerType theOutputHandler, XalanFlushHandlerType theFlushHandler)
Transform the XML source tree to a callback function.
XalanTransformToData(const char *theXMLFileName, const char *theXSLFileName, char **theOutput, XalanHandle theXalanHandle)
Transform the XML source tree to a dynamically allocated buffer.
XalanSetStylesheetParamUTFNodeset(const XalanUTF16Char *key, XalanPSHandle theNodeset, XalanHandle theXalanHandle)
Set a top-level stylesheet nodeset parameter.
XalanTransformToFilePrebuilt(XalanPSHandle theParsedSource, XalanCSSHandle theCSSHandle, const char *theOutFileName, XalanHandle theXalanHandle)
Transform the XML source tree to the given result file.
XalanSetStylesheetParamNodeset(const char *key, XalanPSHandle theNodeset, XalanHandle theXalanHandle)
Set a top-level stylesheet nodeset parameter.
XalanSetStylesheetParam(const char *key, const char *expression, XalanHandle theXalanHandle)
Set a top-level stylesheet parameter.
XalanTransformToDataPrebuilt(XalanPSHandle theParsedSource, XalanCSSHandle theCSSHandle, char **theOutput, XalanHandle theXalanHandle)
Transform the XML source tree to a dynamically-allocated buffer.
CallbackSizeType(* XalanOutputHandlerType)(const char *, CallbackSizeType, void *)
Callback function passed to the XalanTransformer APIs.
#define XALAN_TRANSFORMER_EXPORT_FUNCTION(T)
void(* XalanFlushHandlerType)(void *)
Callback function passed to the XalanTransformer APIs.