Member Function Documentation

CDPNode::CDPNode(bool permissionsHandler = false)

Constructs an CDPNode.

Usefulness of directly instantiating CDPNode is limited.

CDPNode is intended to be used as base class to expose simple classes over StudioAPI. Set parameter permissionsHandler to true if you need to enable permissions support for the node.

Note, that you should also call CDPNode::Configure() to load permission defaults from XML configuration at startup.

CDPNode::~CDPNode()

Destructs an CDPNode.

[override virtual] bool CDPNode::AddChild(const std::string &name, const std::string &typeName, const std::string &configuration)

void CDPNode::AddNodeModeFlags(const CDPNodeModeFlags &flags)

Add flags to current node instance.

See also CDPNode::GetMutableNodeFlags and CDPNode::ClearNodeModeFlags.

void CDPNode::AddPermissionsHandler(const std::string &readonlyRolePermissions)

Adds permissions support to the node at runtime, by creating permissions handler and configuring it

Note, that permissions added via this method are runtime only, so that:

• the RolePermissions field is set read-only for StudioAPI user
• any RolePermissions field changes are not written to XML configuration

Note, that you should use CDPNode constructor with permsissionsSupport=true parameter if you want to enable permanent and user configurable permissions support for the node.

void CDPNode::ClearNodeModeFlags(CDPNodeModeFlags flags = ~( CDPNodeModeFlags() ))

Clear flags from current node instance.

Clears all flags when called without argument.

void CDPNode::Configure(XMLElementEx *xml)

Load CDPNode permission defaults from XML configuration

Should always be called when permissions support is enabled in constructor

[override virtual] void CDPNode::FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const

Exposes child nodes of this node to StudioAPI.

Must be overridden if node has child nodes to expose. CDPNode implementation has no default child nodes to expose.

The CDP::StudioAPI::NodeStream argument implements stream operators to facilitate exposing the nodes, it also implements a std container streamer function to help exposing std containers aggregating nodes.

void MyNode::FillNodeChildren(NodeStream& serializer) const
{
  serializer << nodeName << nodeValue << nodeDescription;
  serializer.StdContainerStreamer(otherChildNodesList);
  CDPNode::FillNodeChildren(serializer); //Always call direct base class implementation
}

void CDPNode::FlushValueChanges(uint64_t timestamp)

Flushes node value changes if any have been accumulated to be published if samplig time has been reached. The argument timestamp refers to current time. If 0 is passed in flush will be forced.

[override virtual] CDPNodePermissionFlags CDPNode::GetEffectivePermissionFlags(const std::shared_ptr<IAuthSession> &session) const

[protected] CDPNodeModeFlags &CDPNode::GetMutableNodeFlags()

Returns a non const reference to internal flags member.

Is used by inheriting classes to assign desired initial value to flags.

See also CDPNode::AddNodeModeFlags and CDPNode::ClearNodeModeFlags.

ICDPNode *CDPNode::GetNodeAbsorbedBy() const

[override virtual] unsigned int CDPNode::GetNodeID() const

Reimplemented from ICDPNode::GetNodeID().

Returns nodes unique ID in current application.

Node IDs from 0 to 255 are reserved, where 0 indicates a system and rest are allocated for applications.

[override virtual] CDPNodeModeFlags CDPNode::GetNodeModeFlags() const

Reimplemented from ICDPNode::GetNodeModeFlags().

Returns current nodes runtime characteristics flags.

Node flags should be usually set in inheriting classes constructor. Node may exhibit undesired behavior when flags are not set correctly.

See also CDPNode::GetMutableNodeFlags, CDPNode::AddNodeModeFlags, and CDPNode::ClearNodeModeFlags.

[override virtual] const std::string CDPNode::GetNodeName() const

Reimplemented from ICDPNode::GetNodeName().

Returns node's unique name in parent.

Must be overridden by inheriting class to return node's name. Base implementation returns empty string.

[override virtual] CDPNodeType CDPNode::GetNodeType() const

Reimplemented from ICDPNode::GetNodeType().

Returns node's base type CDP::StudioAPI::eCDP_NODE.

Node type is considered the closest CDP base class. For all classes inheriting CDPNode CDP::StudioAPI::eCDP_NODE is the closest base class type.

[override virtual] std::string CDPNode::GetNodeTypeName() const

Reimplemented from ICDPNode::GetNodeTypeName().

Returns node's class name "CDPNode".

Must be overridden to return inheriting class name. For CDPNode based classes class name is also used as model name.

[override virtual] CDPValueType CDPNode::GetNodeValueType() const

Reimplemented from ICDPNode::GetNodeValueType().

Returns node's value type.

Must be overridden when inheriting class is a value node. Base implementation returns CDP::StudioAPI::eUNDEFINED.

[override virtual] INodePermissions *CDPNode::GetPermissionHandler() const

Reimplemented from ICDPNode::GetPermissionHandler().

Returns permissions handler of the node.

If permissions are note supported for this node returns nullptr

[override virtual] CDPVariantValue CDPNode::GetVariantValue() const

Reimplemented from ICDPNode::GetVariantValue().

Returns variant value representing node's current value.

Must be overridden for value nodes to return node's value. For non value type nodes the CDPValueType of the variant value will be CDP::StudioAPI::eUNDEFINED.

bool CDPNode::HasValueSubscription() const

Returns true if there is a valuesubscription to this node, false if not.

When no value subscription is present, there is no need to call NotifyValueChange().

[override virtual] bool CDPNode::IsNodeLocal() const

Reimplemented from ICDPNode::IsNodeLocal().

Returns true if node is present in current application.

Nodes of other application in system are not considered local nodes, but are represented in the tree as non-local nodes.

void CDPNode::NotifyInvalidatedStructure() const

Notifies StudioAPI that subtree of child nodes has changed.

When node's children change during runtime the implementation must call this function after the change is completed. Applies to all changes that happen after configuration phase on startup. Changes can be additions, removals or renames of sub-nodes in the tree.

void CDPNode::NotifyValueChange(T oldValue, T newValue) const

Notify that node's value has changed by providing oldValue and newValue of template type T.

Must be called in value node's implementation immediately before the value is set to value member to guarantee causality of change for chained changes.

Allowed template types are:

bool,char,unsigned char,short,unsigned short,int,unsigned int,float,double,int64_t,uint64_t,std::string,std::string&,const CDPVariantValue&

[override virtual] bool CDPNode::RemoveChild(const std::string &name)

void CDPNode::SetNodeAbsorbedBy(const ICDPNode *absorber)

Set the node to be absorbed.

Sometimes logical structure of inheritance needs to differ from actual implementation, in case of using composition instead of inheritance in implementation the composited node can be absorbed to achieve this.

When following composition over inheritance paradigm the implementation structure of nodes may not be what is logically reasonable to expose. When using SetNodeAbsorbedBy() on a composited node all its child nodes will appear as children of compositing node (except Name node) when it is exposed in CDPNode::FillNodeChildren and wrapped in CDP::StudioAPI::AbsorbedChild.

See also CDP::StudioAPI::AbsorbedChild.

void CDPNode::SetNodeReparented(bool reparented)

Set the node to be reparented.

Sometimes logical structure of ownership needs to differer from actual implementation, in that case nodes can be reparented to achieve this.

For example CDPNode does not aggregate CDPProperties, this is done by CDPBaseObject, but it is useful to expose CDPProperties as CDPNode based classe's child nodes. This is one case where reparenting node from aggregating CDPBaseObject is used. As a result the reparented node is not exposed by the real parent and must be exposed from new parent in CDPNode::FillNodeChildren wrapping the node in CDP::StudioAPI::AdoptedChild.

In such a case care must be taken with naming of the reparented node, keeping it unique in the real parent and keeping reparented node's full path correct. The name becomes "reparentingNodeName.reparentedNodeName" if the new parent node is a child of the aggregator (the real parent of the reparented node).

See also CDP::StudioAPI::AdoptedChild.

[override virtual] void CDPNode::SetVariantValue(const CDP::StudioAPI::CDPVariantValue &value)

Sets variant value of node.

Must be overridden for value nodes to set node's value. For non value type nodes this call is ignored.

uint64_t CDPNode::UpdateNodeTimestamp(uint64_t timestamp)

Set current timestamp to override system default timestamp for node value changes Returns previous timestamp for restoring the default.