fwXML.ctl File Reference
|
const int | fwXml_SAXSTARTELEMENT = 2 |
const int | fwXml_SAXENDELEMENT = 3 |
const int | fwXml_SAXCHARACTERS = 6 |
const string | fwXml_CHILDNODESTYPE = "fwXml_ChildNodesType" |
const string | fwXml_CHILDSUBTREEID = "fwXml_ChildSubTreeId" |
public string | fwXml_trim (string value) |
private void | _fwXml_parseSaxRecursive (int document, mapping callBacks, int level, int nodes_id, dyn_string &exceptionInfo) |
public int | fwXml_parseSaxFromFile (string xml_file, mapping callBacks, string &errMsg, string &errLin, string &errCol, dyn_string &exceptionInfo) |
void | _fwXml_elementsRecursive (unsigned doc, int node, string tag, dyn_int &elements, dyn_string &exceptionInfo) |
dyn_int | fwXml_elementsByTagName (unsigned doc, int node, string tag, dyn_string &exceptionInfo) |
int | fwXml_childNodesContent (unsigned doc, int node, dyn_string &node_names, dyn_anytype &attributes, dyn_string &nodevalues, dyn_string &exceptionInfo) |
int | fwXml_appendChildContent (unsigned doc, int node, dyn_string node_names, dyn_anytype attributes, dyn_string nodevalues, dyn_string &exceptionInfo) |
Detailed Description
This library contains the XML SAX function call and some additional XML DOM function calls.
- Creation Date
- 01/12/2008
- Modification History
- 19/08/2013: Generalise fwXml_appendChildContent Bug in recovery mechanism of fwXml_appendChildContent 06/04/2010: Removed .dll extension from uses 22/06/2009: Added fwXml_appendChildContent 01/12/2008: Initial version
- Constraints
- For PVSS 3.6 SP2 and later versions
- Usage
- Public
- PVSS managers
- UI, CTRL
- Author:
- Daniel Davids (IT-CO)
Function Documentation
void _fwXml_elementsRecursive |
( |
unsigned |
doc, |
|
|
int |
node, |
|
|
string |
tag, |
|
|
dyn_int & |
elements, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'_fwXml_elementsRecursive' called by '' and itself in a recursive way.
- Constraints
- None
- Usage
- Private
- PVSS managers
- UI, CTRL
- Parameters:
-
| doc | input, the document identifier |
| node | input, the node identifier of the parent or -1 (root-node) |
| tag | input, the tag-name of the children which need to be returned |
| elements | inout, the elements satisfying the tag-name condition |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- void
Referenced by fwXml_elementsByTagName().
private void _fwXml_parseSaxRecursive |
( |
int |
document, |
|
|
mapping |
callBacks, |
|
|
int |
level, |
|
|
int |
nodes_id, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'_fwXml_parseSaxRecursive' called by 'fwXml_parseSaxFromFile' and itself in a recursive way.
- Constraints
- None
- Usage
- Private
- PVSS managers
- UI, CTRL
- Parameters:
-
| document | input, the document-ident of the loaded Xml file |
| callBacks | input, the callback functions to be called while parsing |
| level | input, the current nesting-level of the recursive calls |
| nodes_id | input, the node-ident from which the sub-tree is parsed |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- void
References fwXml_SAXCHARACTERS, fwXml_SAXENDELEMENT, and fwXml_SAXSTARTELEMENT.
Referenced by fwXml_parseSaxFromFile().
int fwXml_appendChildContent |
( |
unsigned |
doc, |
|
|
int |
node, |
|
|
dyn_string |
node_names, |
|
|
dyn_anytype |
attributes, |
|
|
dyn_string |
nodevalues, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'fwXml_appendChildContent' appends element-nodes, attributes and contained data to the Xml Tree
- Constraints
- None
- Usage
- Public
- PVSS managers
- UI, CTRL
- Parameters:
-
| doc | input, the document identifier |
| node | input, the node identifier of the parent element-node container |
| node_names | input, tag-names for element-nodes |
| attributes | input, the attributes of element-nodes |
| nodevalues | input, the values of the unique child's text-node |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- output, 0 on success and -1 if an error during construction occurred
- Used for simple and more complex Xml-file structures
- This function constructs underneath the given node an ordered list of children element-nodes, or other types of nodes like: text-nodes, cdata-section nodes or comment nodes. Each of these children element-nodes gets their corresponding attributes and if defined and not the empty-string their corresponding child text-node.
- A typical example is included in the example-panel "xmlCreateChildContentExample.pnl". The first push-button creates a list of element-nodes. The second push-button creates a list of element-nodes with most of them having a unique child's text-node. The third push-button creates a list of element-nodes with some of them having one or more qualifying attributes. The fourth push-button combines all the above examples together and creates a list of element-nodes with some of them attributes and most of them a unique child's text-node. The fifth push-button shows you how to add more exotic elements like text-nodes, cdata-section nodes and comment nodes.
References fwXml_CHILDNODESTYPE.
int fwXml_childNodesContent |
( |
unsigned |
doc, |
|
|
int |
node, |
|
|
dyn_string & |
node_names, |
|
|
dyn_anytype & |
attributes, |
|
|
dyn_string & |
nodevalues, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'fwXml_childNodesContent' returns tags, attributes and contained data of all children
- Constraints
- None
- Usage
- Public
- PVSS managers
- UI, CTRL
- Parameters:
-
| doc | input, the document identifier |
| node | input, the node identifier of the parent element-node container |
| node_names | output, the node-names or tag-names for element-nodes |
| attributes | output, the attributes of element-nodes and added infomation |
| nodevalues | output, the node-values or values of the unique child's text-node |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- output, the combined types of the type of children which data is returned
- When used for simple Xml-file structures
- If the function returns '0' (zero), then the child-nodes are all element-nodes which contain at most one text-node as their child. The following is returned via the three output-parameters: 'node_names' returns the tag-names of the element-nodes, 'attributes' returns all the attributes of the element-nodes, 'nodevalues' returns the value (character-data) of the contained text-node if present, otherwise it returns the empty string.
- A typical example is included in the example-panel "xmlChildNodesContentExample.pnl" (first push-button). The Xml-file "xmlExampleFlatListing.xml" can be completely read by issuing one single call to this function - specify for the 'node' variable the node-identifier of the element-node called "<room>".
- Note that this function was created especially for users who want to parse Xml-files of a structure which corresponds to the above description. Only read further if you want to use this function to parse more complex Xml-file structures.
- When used for complex Xml-file structures
- If any of the child-nodes is different from an element-node which contains at most one text-node as its child, then the return-code will be different from '0' and will be more specific the bitwise OR-ed values which are obtained by shifting the value '1' to the left by a number of places which corresponds to the internal enumerated value of the node-type.
- An example will illustrate this much easier. Refer again to the example-panel "xmlChildNodesContentExample.pnl" (second push-button). The Xml-file corresponds this time to "xmlExampleGreatText.xml". In this example there is in addition to the above at least one text-node as a direct child (not as a child of an element-node). In that case, the return-code is '8' - this is obtained by shifting '1' to the left by XML_TEXT_NODE places (1<<XML_TEXT_NODE) [1<<3].
- For nodes which are not element-nodes, the returned values are: 'node_names' returns the node-name of the node as queried by 'xmlNodeName', 'attributes' returns a single mapping "[fwXml_CHILDNODESTYPE;(int)<node-type>]" which indicates the node-type of the node, 'nodevalues' returns the node-value of the node as queried by 'xmlNodeValue'.
- If there is additionally at least one child-node with more than one child or with a child which is not a text-node then the return-code will have the bit-value '2' also set. The same example-panel "xmlChildNodesContentExample.pnl" illustrates this. Third button parses the "xmlExampleHierarchical.xml" Xml-file - return-code corresponds to '2' (1<<XML_ELEMENT_NODE) [1<<1]. Fourth button parses the Xml-file "xmlExampleMoreComplex.xml" - return-code corresponds to '10' - obtained by bitwise OR-ing of (1<<XML_ELEMENT_NODE) and (1<<XML_TEXT_NODE) which is [(1<<1)|(1<<3)].
- For element-nodes with more than one child or with a child which is not a text-node, the returned values are: 'node_names' returns the tag-name of the node, 'attributes' returns all the attributes of the element-nodes with additionally the two following added mappings "[fwXml_CHILDNODESTYPE;(int)XML_ELEMENT_NODE]" which is the node-type and "[fwXml_CHILDSUBTREEID;(int)<element-node-identifier>]", 'nodevalues' returns the empty string.
References fwXml_CHILDNODESTYPE, and fwXml_CHILDSUBTREEID.
dyn_int fwXml_elementsByTagName |
( |
unsigned |
doc, |
|
|
int |
node, |
|
|
string |
tag, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'fwXml_elementsByTagName' returns all children which have a specific element's tag-name
- Constraints
- None
- Usage
- Public
- PVSS managers
- UI, CTRL
- Parameters:
-
| doc | input, the document identifier |
| node | input, the node identifier of the parent or -1 (root-node) |
| tag | input, the tag-name of the children which need to be returned |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- output, all children which have a specific element's tag-name
- Returns a dynamic-integer array containing all descendent elements of this element that are called tag-name. The order they are in the dynamic-integer array is the order they are encountered in a pre-order traversal of the element tree. If '-1' is given to the node-identifier's value, then the whole document is searched.
- A typical example is included in the example-panel "xmlElementsByTagNameExample.pnl". The Xml-file "xmlExampleProcessTags.xml" is parsed by the two programs in this panel. The first push-button gets the element-nodes with tagnames 'home', 'room' and 'floor'. The second push-button gets only the element-nodes of the 'room's which are within 'bedrooms's.
References _fwXml_elementsRecursive().
public int fwXml_parseSaxFromFile |
( |
string |
xml_file, |
|
|
mapping |
callBacks, |
|
|
string & |
errMsg, |
|
|
string & |
errLin, |
|
|
string & |
errCol, |
|
|
dyn_string & |
exceptionInfo | |
|
) |
| | |
'fwXml_parseSaxFromFile' parses an Xml-file according to the SAX mechanism with user-defined callbacks.
- Constraints
- None
- Usage
- Public
- PVSS managers
- UI, CTRL
- Parameters:
-
| xml_file | input, the file-name of the Xml file to be parsed |
| callBacks | input, the callback functions to be called while parsing |
| errMsg | output, the error message if the Xml file cannot be parsed |
| errLin | output, the line in the Xml file at which the error occurred |
| errCol | output, the column in the Xml file at which the error occurred |
| exceptionInfo | inout, returns details of any exceptions |
- Returns:
- output, 0 on success and -1 if an error during parsing occurred
- SAX Callback Mechanism
- The callback function-names are passed to the 'fwXml_parseSaxFromFile' function as a PVSS mapping. Three different callbacks are currently implemented which can be activated by associating them to corresponding function-names in the PVSS mapping. The parameter passing of the callback functions follow very closely the Qt-implementation of the 'QXmlContentHandler'. These three types are the following:
- Type 'fwXml_StartElement' called when an Xml element-node is encountered.
Activate: 'callBacks[fwXml_StartElement] = "<start-element-callback>";'
Declaration: 'void <start-element-callback> ( string elementName , mapping elementAttributes )'
- Type 'fwXml_EndElement' called when an Xml element-node is left (exited).
Activate: 'callBacks[fwXml_EndElement] = "<end-element-callback>";'
Declaration: 'void <end-element-callback> ( string elementName )'
- Type 'fwXml_Characters' called when an Xml text-node is encountered.
Activate: 'callBacks[fwXml_Characters] = "<characters-callback>";'
Declaration: 'void <characters-callback> ( string characters )'
- A typical example is included in the example-panel "xmlParseSaxFromFileExample.pnl". The Xml-file "xmlExampleSaxParsing.xml" is parsed by the program in this panel. The push-button parses the Xml-file in a pre-order traversal of the element tree and calls the user-defined callbacks on encountering the various node-boundaries.
References _fwXml_parseSaxRecursive().
public string fwXml_trim |
( |
string |
value |
) |
|
'fwXml_trim' to trim a string, especially to be used for trimming an Xml-Node's value.
- Constraints
- None
- Usage
- Public
- PVSS managers
- UI, CTRL
- Parameters:
-
| value | inout, the value to be trimmed |
- Returns:
- output, the trimmed value
Variable Documentation
fwXml_CHILDSUBTREEID Constant used in the mapping that identifies the node-identifier of the node in question
Referenced by fwXml_childNodesContent().
fwXml_Characters Constant used in the mapping that associates the user-defined callback to an Xml text-node
Referenced by _fwXml_parseSaxRecursive().
fwXml_EndElement Constant used in the mapping that associates the user-defined callback to the end of an Xml element-node
Referenced by _fwXml_parseSaxRecursive().
fwXml_StartElement Constant used in the mapping that associates the user-defined callback to the start of an Xml element-node
Referenced by _fwXml_parseSaxRecursive().