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)
38 extern "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
80  XalanInitialize(void);
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  */
122  DeleteXalanTransformer(XalanHandle theXalanHandle);
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  */
463  XalanGetLastError(XalanHandle theXalanHandle);
464 
465 #if defined(__cplusplus)
466 }
467 #endif
468 
469 
470 
471 #endif // XALAN_CAPI_HEADER_GUARD_1357924680
XalanTransformToHandlerPrebuilt
XalanTransformToHandlerPrebuilt(XalanPSHandle thePSHandle, XalanCSSHandle theCSSHandle, XalanHandle theXalanHandle, void *theOutputHandle, XalanOutputHandlerType theOutputHandler, XalanFlushHandlerType theFlushHandler)
Transform the XML source tree to a callback function.
XalanTerminate
XalanTerminate(int fCleanUpICU)
Terminate Xalan and Xerces.
XalanParseSourceFromStream
XalanParseSourceFromStream(const char *theXMLStream, unsigned long theXMLStreamLength, XalanHandle theXalanHandle, XalanPSHandle *thePSHandle)
Parse source document from a stream.
XalanSetStylesheetParam
XalanSetStylesheetParam(const char *key, const char *expression, XalanHandle theXalanHandle)
Set a top-level stylesheet parameter.
XalanSetStylesheetParamUTFNumber
XalanSetStylesheetParamUTFNumber(const XalanUTF16Char *key, double theNumber, XalanHandle theXalanHandle)
Set a top-level stylesheet number parameter.
XalanPSHandle
const typedef void * XalanPSHandle
Handle used to store the address of Parsed Source instance.
Definition: XalanCAPI.h:55
XalanTransformToData
XalanTransformToData(const char *theXMLFileName, const char *theXSLFileName, char **theOutput, XalanHandle theXalanHandle)
Transform the XML source tree to a dynamically allocated buffer.
XalanCSSHandle
const typedef void * XalanCSSHandle
Handle used to store the address of Compiled Stylesheet instance.
Definition: XalanCAPI.h:50
XALAN_TRANSFORMER_EXPORT_FUNCTION
#define XALAN_TRANSFORMER_EXPORT_FUNCTION(T)
Definition: XalanTransformerDefinitions.hpp:41
XalanUTF16Char
XMLCh XalanUTF16Char
This is a typedef for characters encoded in UTF-16.
Definition: XalanCAPI.h:66
CreateXalanTransformer
CreateXalanTransformer()
Create a XalanTransformer instance.
XalanTransformToFilePrebuilt
XalanTransformToFilePrebuilt(XalanPSHandle theParsedSource, XalanCSSHandle theCSSHandle, const char *theOutFileName, XalanHandle theXalanHandle)
Transform the XML source tree to the given result file.
XalanOutputHandlerType
CallbackSizeType(* XalanOutputHandlerType)(const char *, CallbackSizeType, void *)
Callback function passed to the XalanTransformer APIs.
Definition: XalanTransformerDefinitions.hpp:70
XalanSetStylesheetParamUTF
XalanSetStylesheetParamUTF(const XalanUTF16Char *key, const XalanUTF16Char *expression, XalanHandle theXalanHandle)
Set a top-level stylesheet parameter.
XalanGetLastError
XalanGetLastError(XalanHandle theXalanHandle)
Returns the last error that occurred as a result of calling transform.
XalanCompileStylesheet
XalanCompileStylesheet(const char *theXSLFileName, XalanHandle theXalanHandle, XalanCSSHandle *theCSSHandle)
Creates a compiled stylesheet.
XalanDestroyCompiledStylesheet
XalanDestroyCompiledStylesheet(XalanCSSHandle theCSSHandle, XalanHandle theXalanHandle)
Destroys a compiled stylesheet.
XalanTransformToHandler
XalanTransformToHandler(const char *theXMLFileName, const char *theXSLFileName, XalanHandle theXalanHandle, void *theOutputHandle, XalanOutputHandlerType theOutputHandler, XalanFlushHandlerType theFlushHandler)
Transform the XML source tree to a callback function.
XalanInitialize
XalanInitialize(void)
Initialize Xerces and Xalan.
XalanCompileStylesheetFromStream
XalanCompileStylesheetFromStream(const char *theXSLStream, unsigned long theXSLStreamLength, XalanHandle theXalanHandle, XalanCSSHandle *theCSSHandle)
Creates a compiled stylesheet.
XalanDestroyParsedSource
XalanDestroyParsedSource(XalanPSHandle thePSHandle, XalanHandle theXalanHandle)
Destroys a parsed source.
XalanHandle
void * XalanHandle
This is a simple C interface for the class XalanTransformer.
Definition: XalanCAPI.h:45
XalanSetStylesheetParamNodeset
XalanSetStylesheetParamNodeset(const char *key, XalanPSHandle theNodeset, XalanHandle theXalanHandle)
Set a top-level stylesheet nodeset parameter.
XalanSetStylesheetParamNumber
XalanSetStylesheetParamNumber(const char *key, double theNumber, XalanHandle theXalanHandle)
Set a top-level stylesheet number parameter.
DeleteXalanTransformer
DeleteXalanTransformer(XalanHandle theXalanHandle)
Delete a XalanTransformer instance.
XalanCCharPtr
const typedef char * XalanCCharPtr
This is a typedef to work around limitations with the XALAN_TRANSFORMER_EXPORT_FUNCTION macro.
Definition: XalanCAPI.h:61
XalanFreeData
XalanFreeData(char *theData)
Free memory allocated as a result of calling XalanTransformToData.
XalanClearStylesheetParams
XalanClearStylesheetParams(XalanHandle theXalanHandle)
Clear the top-level stylesheet parameters.
XalanFlushHandlerType
void(* XalanFlushHandlerType)(void *)
Callback function passed to the XalanTransformer APIs.
Definition: XalanTransformerDefinitions.hpp:80
XalanParseSource
XalanParseSource(const char *theXMLFileName, XalanHandle theXalanHandle, XalanPSHandle *thePSHandle)
Parse source document.
XalanTransformerDefinitions.hpp
XalanSetStylesheetParamUTFNodeset
XalanSetStylesheetParamUTFNodeset(const XalanUTF16Char *key, XalanPSHandle theNodeset, XalanHandle theXalanHandle)
Set a top-level stylesheet nodeset parameter.
XalanTransformToFile
XalanTransformToFile(const char *theXMLFileName, const char *theXSLFileName, const char *theOutFileName, XalanHandle theXalanHandle)
Transform the XML source tree to the given result file.
XalanTransformToDataPrebuilt
XalanTransformToDataPrebuilt(XalanPSHandle theParsedSource, XalanCSSHandle theCSSHandle, char **theOutput, XalanHandle theXalanHandle)
Transform the XML source tree to a dynamically-allocated buffer.