CDPNode Class

(CDP::StudioAPI::CDPNode)

The CDPNode is base class for all classes exposed through StudioAPI. More...

Public Functions

CDPNode()
~CDPNode() override
void AddNodeModeFlags(const CDPNodeModeFlags &flags)
void ClearNodeModeFlags(CDPNodeModeFlags flags = ~( CDPNodeModeFlags() ))
virtual void FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const override
bool HasValueSubscription() const
void NotifyInvalidatedStructure()
void NotifyValueChange(T oldValue, T newValue) const
void SetNodeAbsorbed(bool absorbed)
void SetNodeReparented(bool reparented)
virtual void SetVariantValue(const CDP::StudioAPI::CDPVariantValue &value) override
void UpdateNodeTimestamp(uint64_t timestamp)

Reimplemented Public Functions

virtual unsigned int GetNodeID() const override
virtual CDPNodeModeFlags GetNodeModeFlags() const override
virtual const std::string GetNodeName() const override
virtual CDPNodeType GetNodeType() const override
virtual std::string GetNodeTypeName() const override
virtual CDPValueType GetNodeValueType() const override
virtual CDPVariantValue GetVariantValue() const override
virtual bool IsNodeLocal() const override

Protected Functions

CDPNodeModeFlags &GetMutableNodeFlags()

Detailed Description

The CDPNode is base class for all classes exposed through StudioAPI.

An CDPNode is class that implements base node for CDP structure.

Each class inheriting CDPNode should also provide a model file (<class name>.xml).

Each class that is intended to be used in configuration time by users should expose itself trough library model declaration file (<library name>.xml).

Instances of CDPNode are not automatically aggregated in any other CDP class so all instances need to be created in code and also exposed in parents FillNodeChildren() function.

Each node has:

  • node id - Unique id in running application
  • name - Each node must have unique name inside its parent
  • type - Type of closest CDP base class
  • type name - Name of the inheriting class itself also called model name
  • value type - Type of value when node represents a value
  • value - Value when node represents a value
  • mode flags - Flags defining capabilities

Member Function Documentation

CDPNode::CDPNode()

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.

CDPNode::~CDPNode()

Destructs an CDPNode.

void CDPNode::AddNodeModeFlags(const CDPNodeModeFlags &flags)

Add flags to current node instance.

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

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

Clear flags from current node instance.

Clears all flags when called without argument.

[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
}

[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.

[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] 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()

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&

void CDPNode::SetNodeAbsorbed(bool absorbed)

Set the node to be absorbed.

Sometimes logical structure of inheritance needs to differer 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 SetNodeAbsorbed() 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.

void CDPNode::UpdateNodeTimestamp(uint64_t timestamp)

© CDP Technologies AS - All rights reserved