00001 /* 00002 * Licensed to the Apache Software Foundation (ASF) under one 00003 * or more contributor license agreements. See the NOTICE file 00004 * distributed with this work for additional information 00005 * regarding copyright ownership. The ASF licenses this file 00006 * to you under the Apache License, Version 2.0 (the "License"); 00007 * you may not use this file except in compliance with the License. 00008 * You may obtain a copy of the License at 00009 * 00010 * http://www.apache.org/licenses/LICENSE-2.0 00011 * 00012 * Unless required by applicable law or agreed to in writing, software 00013 * distributed under the License is distributed on an "AS IS" BASIS, 00014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 * See the License for the specific language governing permissions and 00016 * limitations under the License. 00017 */ 00018 #if !defined(XALAN_CAPI_HEADER_GUARD_1357924680) 00019 #define XALAN_CAPI_HEADER_GUARD_1357924680 00020 00021 00022 00023 #include <xalanc/XalanTransformer/XalanTransformerDefinitions.hpp> 00024 00025 00026 00027 /** 00028 * This is a simple C interface for the class XalanTransformer. It's 00029 * the user's responsibility to call XalanInitialize() before making 00030 * any other API calls, and to call XalanTerminate() when finished 00031 * with the API. 00032 * 00033 * After calling XalanTransformToData or XalanTransformToDataCSS, the user 00034 * should call XalanFreeData to release the memory allocated by that 00035 * operation. 00036 */ 00037 #if defined(__cplusplus) 00038 extern "C" 00039 { 00040 #endif 00041 00042 /** 00043 * Handle used to store the address of XalanTransformer instance. 00044 */ 00045 typedef void* XalanHandle; 00046 00047 /** 00048 * Handle used to store the address of Compiled Stylesheet instance. 00049 */ 00050 typedef const void* XalanCSSHandle; 00051 00052 /** 00053 * Handle used to store the address of Parsed Source instance. 00054 */ 00055 typedef const void* XalanPSHandle; 00056 00057 /** 00058 * This is a typedef to work around limitations with 00059 * the XALAN_TRANSFORMER_EXPORT_FUNCTION macro. 00060 */ 00061 typedef const char* XalanCCharPtr; 00062 00063 /** 00064 * This is a typedef for characters encoded in UTF-16. 00065 */ 00066 typedef XMLCh XalanUTF16Char; 00067 00068 /** 00069 * Initialize Xerces and Xalan. 00070 * 00071 * Should be called only once per process before making 00072 * any other API calls. 00073 * 00074 * @return 0 if successful, -1 if initialization fails. 00075 */ 00076 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00077 #if defined(__cplusplus) 00078 XalanInitialize(); 00079 #else 00080 XalanInitialize(void); 00081 #endif 00082 00083 /** 00084 * Terminate Xalan and Xerces. 00085 * 00086 * Should be called only once per process after deleting all 00087 * instances of XalanTransformer. 00088 * 00089 * Once a process has called this function, it cannot use the 00090 * API until another call to XalanInitialize has been made. 00091 * 00092 * Optionally, if the ICU has been integrated, this will 00093 * call the ICU clean up function. This must only be done 00094 * if the ICU will no longer be used by the process, since 00095 * the ICU will no longer be in a usable state. See the 00096 * ICU documentation for more details. 00097 * 00098 * This is handy when using leak-detection software, as all 00099 * static data allocated by Xalan (and optionally, the ICU) 00100 * will be freed. 00101 * 00102 * @param fCleanUpICU If true, call the ICU clean up function. 00103 */ 00104 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00105 XalanTerminate(int fCleanUpICU); 00106 00107 /** 00108 * Create a XalanTransformer instance. 00109 * 00110 * @return the XalanTransformer handle 00111 */ 00112 XALAN_TRANSFORMER_EXPORT_FUNCTION(XalanHandle) 00113 CreateXalanTransformer(); 00114 00115 00116 /** 00117 * Delete a XalanTransformer instance. 00118 * 00119 * @param theXalanHandle The XalanTransformer to destroy. 00120 */ 00121 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00122 DeleteXalanTransformer(XalanHandle theXalanHandle); 00123 00124 /** 00125 * Transform the XML source tree to the given result file. 00126 * The processor will apply the stylesheet file to the input 00127 * file and write the transformation result to a new output file. 00128 * 00129 * @param theXMLFileName The file name of the XML document. 00130 * @param theXSLFileName The file name of the stylesheet XML document. 00131 * @param theOutFileName The file name for the output. 00132 * @param theXalanHandle The handle of a XalanTransformer instance. 00133 * @return 0 for success 00134 */ 00135 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00136 XalanTransformToFile( 00137 const char* theXMLFileName, 00138 const char* theXSLFileName, 00139 const char* theOutFileName, 00140 XalanHandle theXalanHandle); 00141 00142 /** 00143 * Transform the XML source tree to the given result file. 00144 * The processor will apply the compiled stylesheet to the input 00145 * file and write the transformation result to a new output file. 00146 * 00147 * @param theParsedSource The handle of a parsed source 00148 * @param theCSSHandle The handle of a compiled stylesheet 00149 * @param theOutFileName The file name for the output. 00150 * @param theXalanHandle The handle of a XalanTransformer instance. 00151 * @return 0 for success 00152 */ 00153 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00154 XalanTransformToFilePrebuilt( 00155 XalanPSHandle theParsedSource, 00156 XalanCSSHandle theCSSHandle, 00157 const char* theOutFileName, 00158 XalanHandle theXalanHandle); 00159 00160 /** 00161 * Transform the XML source tree to a dynamically allocated buffer. 00162 * The processor will apply the stylesheet file to the input file 00163 * and assign the address of the dynamically allocated result to a 00164 * user-supplied pointer. The user must call XalanFreeData with this 00165 * pointer to free the memory. 00166 * 00167 * @param theXMLFileName The file name of the XML document. 00168 * @param theXSLFileName The file name of the stylesheet XML document. 00169 * @param theOutput a pointer to a char* 00170 * @param theXalanHandle handle of XalanTransformer instance. 00171 * @return 0 for success 00172 */ 00173 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00174 XalanTransformToData( 00175 const char* theXMLFileName, 00176 const char* theXSLFileName, 00177 char** theOutput, 00178 XalanHandle theXalanHandle); 00179 00180 /** 00181 * Transform the XML source tree to a dynamically-allocated buffer. 00182 * The processor will apply the compiled stylesheet to the input file 00183 * and assign the address of the dynamically allocated result to a 00184 * user supplied pointer. The user must call XalanFreeData with this 00185 * pointer to free the memory. 00186 * 00187 * @param theParsedSource The handle of a parsed source 00188 * @param theCSSHandle The handle of compiled stylesheet 00189 * @param theOutput a pointer to a char* 00190 * @param theXalanHandle handle of XalanTransformer instance. 00191 * @return 0 for success 00192 */ 00193 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00194 XalanTransformToDataPrebuilt( 00195 XalanPSHandle theParsedSource, 00196 XalanCSSHandle theCSSHandle, 00197 char** theOutput, 00198 XalanHandle theXalanHandle); 00199 00200 /** 00201 * Free memory allocated as a result of calling 00202 * XalanTransformToData. 00203 * 00204 * @param theData The address of character data. 00205 */ 00206 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00207 XalanFreeData(char* theData); 00208 00209 /** 00210 * Transform the XML source tree to a callback function. 00211 * The processor will apply the stylesheet file to the input file 00212 * and allocate the transformation result to a callback function 00213 * in pre-allocated blocks. Once the transformation is complete, 00214 * a second callback, to flush the buffer, is called. You can pass 00215 * in NULL if you do not wish to implement a flush callback. Xalan 00216 * will release any memory allocated upon termination, and data passed 00217 * to the callback is not guaranteed to be null terminated. 00218 * 00219 * See XalanTransformerDefinitions.hpp for more details. 00220 * 00221 * @param theXMLFileName The file name of XML input source 00222 * @param theXSLFileName The file name of stylesheet source 00223 * @param theXalanHandle The handle of a XalanTransformer instance. 00224 * @param theOutputHandle A void pointer passed through to callback. 00225 * @param theOutputHandler A user-defined callback function pointer. 00226 * @param theFlushHandler A user-defined callback function pointer, which can be null. 00227 * @return 0 for success 00228 */ 00229 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00230 XalanTransformToHandler( 00231 const char* theXMLFileName, 00232 const char* theXSLFileName, 00233 XalanHandle theXalanHandle, 00234 void* theOutputHandle, 00235 XalanOutputHandlerType theOutputHandler, 00236 XalanFlushHandlerType theFlushHandler); 00237 00238 /** 00239 * Transform the XML source tree to a callback function. 00240 * The processor will apply the compiled stylesheet to the input file 00241 * and allocate the transformation result to a callback function 00242 * in pre-allocated blocks. Once the transformation is complete, 00243 * a second callback, to flush the buffer, is called. You can pass 00244 * in NULL if you do not wish to implement a flush callback. Xalan 00245 * will release any memory allocated upon termination, and data passed 00246 * to the callback is not guaranteed to be null terminated. 00247 * 00248 * See XalanTransformerDefinitions.hpp for more details. 00249 * 00250 * @param thePSHandle The handle of parsed source 00251 * @param theCSSHandle The handle of compiled stylesheet 00252 * @param theXalanHandle The handle of XalanTransformer instance. 00253 * @param theOutputHandle A void pointer passed through to callback. 00254 * @param theOutputHandler A user-defined callback function pointer. 00255 * @param theFlushHandler A user-defined callback function pointer, which can be null. 00256 * @return 0 for success 00257 */ 00258 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00259 XalanTransformToHandlerPrebuilt( 00260 XalanPSHandle thePSHandle, 00261 XalanCSSHandle theCSSHandle, 00262 XalanHandle theXalanHandle, 00263 void* theOutputHandle, 00264 XalanOutputHandlerType theOutputHandler, 00265 XalanFlushHandlerType theFlushHandler); 00266 00267 /** 00268 * Creates a compiled stylesheet. 00269 * 00270 * @param theXSLFileName The file name of stylesheet source 00271 * @param theXalanHandle The handle of XalanTransformer instance. 00272 * @param theCSSHandle a pointer to a XalanCSSHandle 00273 * @return 0 for success. 00274 */ 00275 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00276 XalanCompileStylesheet( 00277 const char* theXSLFileName, 00278 XalanHandle theXalanHandle, 00279 XalanCSSHandle* theCSSHandle); 00280 00281 /** 00282 * Creates a compiled stylesheet. 00283 * 00284 * @param theXSLFileName The stream that contains the stylesheet xml 00285 * @param theXSLStreamLength The length of the stream. 00286 * @param theXalanHandle handle of XalanTransformer instance. 00287 * @param theCSSHandle a pointer to a XalanCSSHandle 00288 * @return 0 for success. 00289 */ 00290 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00291 XalanCompileStylesheetFromStream( 00292 const char* theXSLStream, 00293 unsigned long theXSLStreamLength, 00294 XalanHandle theXalanHandle, 00295 XalanCSSHandle* theCSSHandle); 00296 00297 /** 00298 * Destroys a compiled stylesheet. 00299 * 00300 * @param theCSSHandle The handle of the compiled stylesheet. 00301 * @param theXalanHandle The handle of XalanTransformer instance. 00302 * @return 0 for success 00303 */ 00304 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00305 XalanDestroyCompiledStylesheet( 00306 XalanCSSHandle theCSSHandle, 00307 XalanHandle theXalanHandle); 00308 00309 /** 00310 * Parse source document. 00311 * 00312 * @param theXMLFileName The name of the file containing the source document 00313 * @param theXalanHandle The handle of XalanTransformer instance. 00314 * @param thePSHandle A pointer to a XalanPSHandle 00315 * @return 0 for success. 00316 */ 00317 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00318 XalanParseSource( 00319 const char* theXMLFileName, 00320 XalanHandle theXalanHandle, 00321 XalanPSHandle* thePSHandle); 00322 00323 /** 00324 * Parse source document from a stream. 00325 * 00326 * @param theXMLStream The stream that contains the source xml 00327 * @param theXSLStreamLength The length of the stream 00328 * @param theXalanHandle The handle of XalanTransformer instance 00329 * @param thePSHandle A pointer to a XalanPSHandle 00330 * @return 0 for success. 00331 */ 00332 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00333 XalanParseSourceFromStream( 00334 const char* theXMLStream, 00335 unsigned long theXMLStreamLength, 00336 XalanHandle theXalanHandle, 00337 XalanPSHandle* thePSHandle); 00338 00339 /** 00340 * Destroys a parsed source. 00341 * a file name, a stream or a root node. 00342 * 00343 * @param thePSHandle The handle of parsed source 00344 * @param theXalanHandle The handle of XalanTransformer instance. 00345 * @return 0 for success 00346 */ 00347 XALAN_TRANSFORMER_EXPORT_FUNCTION(int) 00348 XalanDestroyParsedSource( 00349 XalanPSHandle thePSHandle, 00350 XalanHandle theXalanHandle); 00351 00352 /** 00353 * Set a top-level stylesheet parameter. This value can be evaluated via 00354 * xsl:param-variable. 00355 * 00356 * @param key The name of the param 00357 * @param expression The expression that will be evaluated 00358 * @param theXalanHandle The handle of XalanTransformer instance. 00359 */ 00360 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00361 XalanSetStylesheetParam( 00362 const char* key, 00363 const char* expression, 00364 XalanHandle theXalanHandle); 00365 00366 /** 00367 * Set a top-level stylesheet parameter. This value can be evaluated via 00368 * xsl:param-variable. The key and expression parameters must be 00369 * encoded in UTF-16. 00370 * 00371 * @param key name of the param 00372 * @param expression expression that will be evaluated 00373 * @param theXalanHandle handle of XalanTransformer instance. 00374 */ 00375 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00376 XalanSetStylesheetParamUTF( 00377 const XalanUTF16Char* key, 00378 const XalanUTF16Char* expression, 00379 XalanHandle theXalanHandle); 00380 00381 00382 /** 00383 * Set a top-level stylesheet nodeset parameter. This value can be 00384 * evaluated via xsl:param-variable. The value is a parsed document. 00385 * 00386 * @param key name of the param 00387 * @param theNodeset a preparsed document 00388 * @param theXalanHandle handle of the XalanTransformer instance. 00389 */ 00390 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00391 XalanSetStylesheetParamNodeset( 00392 const char* key, 00393 XalanPSHandle theNodeset, 00394 XalanHandle theXalanHandle); 00395 00396 /** 00397 * Set a top-level stylesheet nodeset parameter. This value can be 00398 * evaluated via xsl:param-variable. The value is a parsed document. 00399 * The key name is a UTF-16 string. 00400 * 00401 * @param key name of the param 00402 * @param theNodeset a preparsed document 00403 * @param theXalanHandle handle of the XalanTransformer instance. 00404 */ 00405 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00406 XalanSetStylesheetParamUTFNodeset( 00407 const XalanUTF16Char* key, 00408 XalanPSHandle theNodeset, 00409 XalanHandle theXalanHandle); 00410 00411 /** 00412 * Set a top-level stylesheet number parameter. This value can be 00413 * evaluated via xsl:param-variable. The value is a parsed document. 00414 * 00415 * @param key name of the param 00416 * @param theNumber a double floating point number 00417 * @param theXalanHandle handle of the XalanTransformer instance. 00418 */ 00419 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00420 XalanSetStylesheetParamNumber( 00421 const char* key, 00422 double theNumber, 00423 XalanHandle theXalanHandle); 00424 00425 /** 00426 * Set a top-level stylesheet number parameter. This value can be 00427 * evaluated via xsl:param-variable. The value is a parsed document. 00428 * The key name is a UTF-16 string. 00429 * 00430 * @param key name of the param 00431 * @param theNumber a double floating point number 00432 * @param theXalanHandle handle of the XalanTransformer instance. 00433 */ 00434 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00435 XalanSetStylesheetParamUTFNumber( 00436 const XalanUTF16Char* key, 00437 double theNumber, 00438 XalanHandle theXalanHandle); 00439 00440 /** 00441 * Clear the top-level stylesheet parameters. Top-level stylesheet 00442 * parameters are sticky. When set, they can be used for multiple 00443 * transformations. Use the XalanClearStylesheetParams function 00444 * to clear or reset the top-level stylesheet parameters. 00445 * 00446 * @param theXalanHandle handle of the XalanTransformer instance. 00447 */ 00448 XALAN_TRANSFORMER_EXPORT_FUNCTION(void) 00449 XalanClearStylesheetParams( 00450 XalanHandle theXalanHandle); 00451 00452 /** 00453 * Returns the last error that occurred as a 00454 * result of calling transform. 00455 * 00456 * The signature for following function is really: 00457 * const char* 00458 * XalanGetLastError(XalanHandle theXalanHandle) const; 00459 * 00460 * @return error message const character pointer. 00461 */ 00462 XALAN_TRANSFORMER_EXPORT_FUNCTION(XalanCCharPtr) 00463 XalanGetLastError(XalanHandle theXalanHandle); 00464 00465 #if defined(__cplusplus) 00466 } 00467 #endif 00468 00469 00470 00471 #endif // XALAN_CAPI_HEADER_GUARD_1357924680
Doxygen and GraphViz are used to generate this API documentation from the Xalan-C header files.
Xalan-C++ XSLT Processor Version 1.11 |
|