TiXI  3.3.0
Functions
Miscellaneous Functions

Functions

DLL_EXPORT ReturnCode tixiAddExternalLink (const TixiDocumentHandle handle, const char *parentPath, const char *pathOrUrl, const char *filename, AddLinkMode mode)
 Adds a link to an external xml file. More...
 
DLL_EXPORT ReturnCode tixiRemoveExternalLinks (TixiDocumentHandle handle)
 Removes all link attributes to external files. More...
 
DLL_EXPORT ReturnCode tixiAddHeader (const TixiDocumentHandle handle, const char *toolName, const char *version, const char *authorName)
 Add header to XML-file. More...
 
DLL_EXPORT ReturnCode tixiAddCpacsHeader (const TixiDocumentHandle handle, const char *name, const char *creator, const char *version, const char *description, const char *cpacsVersion)
 Add CPACS header to XML-file. More...
 
DLL_EXPORT ReturnCode tixiCheckElement (const TixiDocumentHandle handle, const char *elementPath)
 Checks if the given element exists. More...
 
DLL_EXPORT ReturnCode tixiCheckDocumentHandle (const TixiDocumentHandle handle)
 Checks for validity of a document handle. More...
 
DLL_EXPORT ReturnCode tixiUsePrettyPrint (TixiDocumentHandle handle, int usePrettyPrint)
 Sets Pretty print on or off. More...
 
DLL_EXPORT ReturnCode tixiSetPrintMsgFunc (TixiPrintMsgFnc func)
 Reroutes all messages of tixi to the message function func. More...
 
DLL_EXPORT TixiPrintMsgFnc tixiGetPrintMsgFunc ()
 Returns the currently registered message handler function. More...
 
DLL_EXPORT ReturnCode tixiSetCacheEnabled (TixiDocumentHandle handle, int enabled)
 Enables the internal xPath cache. More...
 

Detailed Description

These function simply do not fit into one of the other categories.

Function Documentation

DLL_EXPORT ReturnCode tixiAddCpacsHeader ( const TixiDocumentHandle  handle,
const char *  name,
const char *  creator,
const char *  version,
const char *  description,
const char *  cpacsVersion 
)

Add CPACS header to XML-file.

Inserts a header containing information on the data set in this file. If an strings equals to NULL an empty element is inserted. This routine should be called right after tixiCreateDocument. An timestamp is automaticly added to the header.

Fortran syntax:

tixi_add_cpacs_header( integer handle, character*n name, character*n creator, character*n version, character*n descripton, character*n cpacs_version, integer error )

Parameters
[in]handleas returned by tixiCreateDocument
[in]namename of the data set
[in]creatorstring to identify the creator of the file
[in]versionstring to identify the version of the file
[in]descriptionoptional string to set a description to the file
[in]cpacsVersionCPACS version number
Returns
  • SUCCESS if successfully added the header
  • FAILED if an internal error occured
  • INVALID_HANDLE if the handle is not valid
  • ALREADY_SAVED if the header should be added to an already saved document
DLL_EXPORT ReturnCode tixiAddExternalLink ( const TixiDocumentHandle  handle,
const char *  parentPath,
const char *  pathOrUrl,
const char *  filename,
AddLinkMode  mode 
)

Adds a link to an external xml file.

The file is linked in the XML as

<externaldata>
      <path>https://dlr.de/myxmlstore</path>
      <filename>externaldata-included-1.xml</filename>
</externaldata>

Note: the linked external file is not automatically loaded into the document.

Fortran syntax:

tixi_add_external_link( integer handle, character*n parent_path, character*n path, character*n filename, integer error )

Parameters
[in]handleas returned by tixiCreateDocument
[in]parentPathThe Path to the element into which the element holding the url should be inserted.
[in]pathOrUrlThe parent path or url to the file.
[in]filenameThe actual name of the xml file.
[in]modeMode whether to create only the link or load the files into the document.
Returns
  • SUCCESS if successfully added the header
  • FAILED if an internal error occured
  • INVALID_HANDLE if the handle is not valid
  • ALREADY_SAVED if the header should be added to an already saved document
DLL_EXPORT ReturnCode tixiAddHeader ( const TixiDocumentHandle  handle,
const char *  toolName,
const char *  version,
const char *  authorName 
)

Add header to XML-file.

Inserts a header containing information on the tool used to create the file, its version and the user. Additionally, the TIXI version is inserted. If an strings equals to NULL an empty element is inserted. This routine shold be called right after tixiCreateDocument.

Fortran syntax:

tixi_add_header( integer handle, character*n tool_name, character*n version, character*n author_name, integer error )

Parameters
[in]handleas returned by tixiCreateDocument
[in]toolNamename of the tool used to write the file
[in]authorNamestring to identify the creator of the file
[in]versionstring to identify the version of the tool
Returns
  • SUCCESS if successfully added the header
  • FAILED if an internal error occured
  • INVALID_HANDLE if the handle is not valid
  • ALREADY_SAVED if the header should be added to an already saved document
DLL_EXPORT ReturnCode tixiCheckDocumentHandle ( const TixiDocumentHandle  handle)

Checks for validity of a document handle.

Fortran syntax:

tixi_check_handle( integer handle )

Parameters
[in]handlehandle as returned by tixiCreateDocument, tixiOpenDocumentRecursive or tixiOpenDocumentFromHTTP
Returns
  • SUCCESS if handle is valid
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
DLL_EXPORT ReturnCode tixiCheckElement ( const TixiDocumentHandle  handle,
const char *  elementPath 
)

Checks if the given element exists.

Parameters
[in]handlehandle as returned by tixiCreateDocument, tixiOpenDocumentRecursive or tixiOpenDocumentFromHTTP
[in]elementPathan XPath compliant path to an element in the document specified by handle (see section XPath Examples above).
Returns
  • SUCCESS if the element exists
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • FAILED internal error
  • INVALID_XPATH if elementPath is not a well-formed XPath-expression
  • ELEMENT_NOT_FOUND if the elementPath does not point to an existing element
DLL_EXPORT TixiPrintMsgFnc tixiGetPrintMsgFunc ( )

Returns the currently registered message handler function.

Returns
  • Function pointer to the message handler
DLL_EXPORT ReturnCode tixiRemoveExternalLinks ( TixiDocumentHandle  handle)

Removes all link attributes to external files.

This does not remove embedded nodes but the references to the filename etc. if TiXI could successfully embed the external files into the main document before. This is e.g. required, if the XML file should be validated against a schema. The external data attributes make validation impossible. To enable validation, this functions removes those extra attributes.

Note: because links to external files are removed, the document cannot be stored anymore split to multiple files.

Assume a main.xml file

1 <?xml version="1.0" encoding="utf-8"?>
2 <plane>
3  <name>Junkers JU 52</name>
4  <externaldata>
5  <path>file://</path>
6  <filename>extdata.xml</filename>
7  </externaldata>
8  <aPoint>
9  ...
10  </aPoint>
11 </plane>

which links to an external file extdata.xml

1 <?xml version="1.0" encoding="utf-8"?>
2 <testNode>
3  <aVeryTest>
4  <point>
5  <x>22</x>
6  <y>12.2</y>
7  <z>31.3453</z>
8  </point>
9  </aVeryTest>
10 </testNode>

Internally, this external file is embedded into the xml structure after loading the document. Additionally, some metadata attributes are stored into the external nodes to support saving back into the external files. Therefore, when exporting the document to string or saving the complete document into one file the following xml structure is the result:

1 <?xml version="1.0" encoding="utf-8"?>
2 <plane>
3  <name>Junkers JU 52</name>
4  <testNode externalFileName="extdata.xml" externalDataDirectory="file://" externalDataNodePath="/plane">
5  <aVeryTest>
6  <point>
7  <x>22</x>
8  <y>12.2</y>
9  <z>31.3453</z>
10  </point>
11  </aVeryTest>
12  </testNode>
13  <aPoint>
14  ...
15  </aPoint>
16 </plane>

The tixi function tixiRemoveExternalLinks simply removes the attributes "externalFileName", "externalDataDirectory", and "externalDataNodePath"

1 <?xml version="1.0" encoding="utf-8"?>
2 <plane>
3  <name>Junkers JU 52</name>
4  <testNode>
5  <aVeryTest>
6  <point>
7  <x>22</x>
8  <y>12.2</y>
9  <z>31.3453</z>
10  </point>
11  </aVeryTest>
12  </testNode>
13  <aPoint>
14  ...
15  </aPoint>
16 </plane>

Fortran syntax:

tixi_remove_external_links( integer handle, integer error )

Parameters
[in]handleas returned by tixiCreateDocument
Returns
  • SUCCESS if the external links have been removed successfully
  • INVALID_HANDLE if the handle is not valid
DLL_EXPORT ReturnCode tixiSetCacheEnabled ( TixiDocumentHandle  handle,
int  enabled 
)

Enables the internal xPath cache.

This speeds up xpath queries with repeating same xpathes.

Parameters
[in]handleThe document handle of a tixi document.
[in]enabledBoolean, whether to enable the cache or not.
Returns
  • SUCCESS if the cache could be enabled/disabled
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • FAILED otherwise
DLL_EXPORT ReturnCode tixiSetPrintMsgFunc ( TixiPrintMsgFnc  func)

Reroutes all messages of tixi to the message function func.

This can be used, to rerout all tixi messages to a log file, to modify the messages, to parse them etc...

Example to keep tixi silent:

// define the message sink
void tixiSilentMessage(MessageType , const char *, ...){}
// set the message sink
tixiSetPrintMsgFunc(tixiSilentMessage);
Parameters
[in]funcThe new message receiver function
Returns
  • SUCCESS if func is valid
  • FAILED if func is a null pointer
DLL_EXPORT ReturnCode tixiUsePrettyPrint ( TixiDocumentHandle  handle,
int  usePrettyPrint 
)

Sets Pretty print on or off.

Set pretty print on or off. This is used when saing a document to a file, or when exporting to a string. 0 turns pretty print off, 1 turns pretty print on. By default, pretty print is turned on.h

Fortran syntax:

tixi_use_pretty_print( integer handle, integer use_pretty_print, integer error )

Parameters
[in]handlehandle as returned by tixiOpenDocument
[in]usePrettyPrintflag if output should be pretty printed
Returns
  • SUCCESS if a count is computed
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • FAILED for internal errors or if usePrettyPrint had wrong value
Generated Tue Mar 8 2022 14:11:54, by Martin Siggel DLR