ITcSmTreeItem::ConsumeXml
The ConsumeXml() method consumes a BSTR containing the XML representation with item specific data and updates found parameters. This method is used to change item parameters not directly accessible by the ITcSmTreeItem interface.
HRESULT ConsumeXml(BSTRbstrXML);
Parameters
bstrXML | [in] string with the XML representation of the item specific parameter. The corresponding parameter will be updated in the System Manager database. |
Return Values
S_OK | function returns successfully. |
E_FAIL | the bstrXML string does not contain a valid xml document. |
Comments
The document can only contain the specific parameter that should be changed. The document structure must fit to the item specific XML tree, but parameter that should not be changed can be omitted. The following document is a minimal example that can be used to change the specific parameter CheckNumberBoxes of the item (in this case a C1220 fieldbus card). If the parameters in the document are not known by the item, they will be ignored.
<TreeItem>
<DeviceDef>
<DevC1220Def>
<CheckNumberBoxes>0</CheckNumberBoxes>
</DevC1220Def>
</DeviceDef>
</TreeItem>
The set of parameters of a specific tree item is defined in the xml schema document that comes with the TwinCAT System Manager. The parameter of a specific item can also evaluated by calling the ITcSmTreeItem::ProduceXML method. The resulting xml string contains all parameters of that item, but not all of them are changeable. The xml string can contain any number and hierarchical order of xml elements that are valid in terms of the xml schema. It is allowed to change only one parameter at a time (like in the example above), change a set of parameters at once or delivers the full parameter set that ITcSmTreeItem::ProduceXML returns (normally with same parameters changed).
There are some special xml elements that are not corresponding to parameters, they will "execute" a function. An example is the <Rescan> element of a PLC project tree item. The string:
<TreeItem>
<PlcDef>
<ReScan>1</ReScan>
</PlcDef>
</TreeItem>
as a parameter of ConsumeXml will cause the System Manager to rescan the PLC project (like a manually rescan by pressing the "Rescan" button on a PLC project). The parameters and the functions that are available are documented in the xml schema file.