TiXI  3.3.0
Functions
Namespace Support Functions

Functions

DLL_EXPORT ReturnCode tixiRegisterNamespace (const TixiDocumentHandle handle, const char *namespaceURI, const char *prefix)
 Registers the given namespace and its prefix. More...
 
DLL_EXPORT ReturnCode tixiRegisterNamespacesFromDocument (const TixiDocumentHandle handle)
 Registers all prefixed namespaces of the xml document to the parser. More...
 
DLL_EXPORT ReturnCode tixiSetElementNamespace (const TixiDocumentHandle handle, const char *elementPath, const char *namespaceURI, const char *prefix)
 This function sets the namespace for the specified element. More...
 
DLL_EXPORT ReturnCode tixiDeclareNamespace (const TixiDocumentHandle handle, const char *elementPath, const char *namespaceURI, const char *prefix)
 This function adds a namespace declaration inside the tag of specified element. More...
 

Detailed Description

These functions are used, to register xml namespaces to the parser or add namespaces to existing elements. For the following explanations, consider the following xml file

<root>
  <h:table xmlns:h="http://www.w3.org/TR/html4/">
    <h:tr>
      <h:td>Apples</h:td>
      <h:td>Bananas</h:td>
    </h:tr>
  </h:table>
  <aircraft xmlns="http://www.dlr.de/cpacs">
    <modelname>D150</modelname>
  </aircraft>
</root>

Reading elements with namespaces

This file defines two namespaces - "http://www.w3.org/TR/html4/" and "http://www.dlr.de/cpacs". A query for "/root/h:table" or "/root/aircraft" will result in an error, as no prefix was defined for both namespaces. The prefix inside the xml file exists only in the file, but not in the parser. To successfully query these paths, the namespaces must be registered with some (arbitrary) prefix using tixiRegisterNamespace or tixiRegisterNamespacesFromDocument.

After calling tixiRegisterNamespace(handle, "http://www.w3.org/TR/html4/", "html") the query for "/root/html:table" is now valid. After calling tixiRegisterNamespace(handle, "http://www.dlr.de/cpacs", "cpacs") the query for "/root/cpacs:aircraft" becomes valid.

Writing elements with namespaces

To write elements with namespaces, the following functions are available:

To reproduce the upper xml file, use the following tixi code:

tixiCreateDocument("root", &handle);

// create table element in prefixed html namespace
tixiCreateElementNS(handle, "/root", "h:table", "http://www.w3.org/TR/html4/");
tixiRegisterNamespace(handle, "http://www.w3.org/TR/html4/", "h");

tixiCreateElementNS(handle, "/root/h:table", "tr", "http://www.w3.org/TR/html4/");
tixiAddTextElementNS(handle, "/root/h:table/h:tr", "td", "http://www.w3.org/TR/html4/", "Apples");
tixiAddTextElementNS(handle, "/root/h:table/h:tr", "td", "http://www.w3.org/TR/html4/", "Bananas"):

// create aircraft in default namespace (no prefix!)
tixiCreateElementNS(handle, "/root", "aircraft", "http://www.dlr.de/cpacs");
tixiRegisterNamespace(handle, "http://www.dlr.de/cpacs", "c");
tixiAddTextElementNS(handle, "/root/c:aircraft", "modelname", "http://www.dlr.de/cpacs", "D150");

Function Documentation

DLL_EXPORT ReturnCode tixiDeclareNamespace ( const TixiDocumentHandle  handle,
const char *  elementPath,
const char *  namespaceURI,
const char *  prefix 
)

This function adds a namespace declaration inside the tag of specified element.

This function can be used, after an element was created or read from file to set the namespace of the element.

The namespace is not applied to the element, but can be used from child nodes.

Different to tixiSetElementNamespace the namespace prefix may not be empty!

Fortran syntax:

tixi_add_namespace_attribute( integer handle, character*n element_path, character*n namespace_uri, character*n prefix, integer error )

Returns
  • SUCCESS if the namespace could be set successfully
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • INVALID_NAMESPACE_URI if the namespace URI is invalid
  • ELEMENT_NOT_FOUND if the element at elementPath does not exist
  • INVALID_XPATH if elementPath is not a well-formed XPath-expression
  • ELEMENT_PATH_NOT_UNIQUE if elementPath resolves not to a single element but to a list of elements
  • FAILED If the prefix is empty or the namespace could not be set due to another error.
DLL_EXPORT ReturnCode tixiRegisterNamespace ( const TixiDocumentHandle  handle,
const char *  namespaceURI,
const char *  prefix 
)

Registers the given namespace and its prefix.

When dealing with xml namespaces, elements can only be accessed via xPath when their namespace was registered with a prefix.

To automatically register all namespaces and prefixes in the current document, use tixiRegisterNamespacesFromDocument.

Fortran syntax:

tixi_register_namespace( integer handle, character*n namespace_uri, character*n prefix, integer error )

Parameters
[in]handlehandle as returned by tixiCreateDocument, tixiOpenDocumentRecursive or tixiOpenDocumentFromHTTP
[in]namespaceURIThe URI for the namespace (e.g. "http://www.w3.org/TR/html4/")
[in]prefixThe desired prefix of the namespace (e.g. "html")
Returns
  • SUCCESS if the namespace could be registered successfully
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • FAILED In case of an error
DLL_EXPORT ReturnCode tixiRegisterNamespacesFromDocument ( const TixiDocumentHandle  handle)

Registers all prefixed namespaces of the xml document to the parser.

Default (non-prefixed) namespaces must be still registered using tixiRegisterNamespace manually to be accessible via xPath.

In the example above, the namespace "http://www.w3.org/TR/html4/" would be registered with the prefix "h" and a query to "/root/h:table" becomes successful.

Fortran syntax:

tixi_register_namespaces_from_document( integer handle, integer error )

Parameters
[in]handlehandle as returned by tixiCreateDocument, tixiOpenDocumentRecursive or tixiOpenDocumentFromHTTP
Returns
  • SUCCESS if the namespace could be registered successfully
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • FAILED In case of an error.
DLL_EXPORT ReturnCode tixiSetElementNamespace ( const TixiDocumentHandle  handle,
const char *  elementPath,
const char *  namespaceURI,
const char *  prefix 
)

This function sets the namespace for the specified element.

This function can be used, after an element was created or read from file to set the namespace of the element. To set a default namespace for this element, add NULL as the prefix.

Fortran syntax:

tixi_set_element_namespace( integer handle, character*n element_path, character*n namespace_uri, character*n prefix, integer error )

Returns
  • SUCCESS if the namespace could be set successfully
  • INVALID_HANDLE if the handle is not valid, i.e. does not or no longer exist
  • INVALID_NAMESPACE_URI if the namespace URI is invalid
  • ELEMENT_NOT_FOUND if the element at elementPath does not exist
  • INVALID_XPATH if elementPath is not a well-formed XPath-expression
  • ELEMENT_PATH_NOT_UNIQUE if elementPath resolves not to a single element but to a list of elements
  • FAILED If the namespace could not be set due to another error.
Generated Tue Mar 8 2022 14:11:54, by Martin Siggel DLR