CDPPort Class
The CDPPort is used to gather related data into a single data object similar to a structure in programming languages. More...
Header: | #include <CDPSystem/Base/CDPPort.h> |
Inherits: | CDPObject |
Public Functions
CDPPort() | |
virtual | ~CDPPort() |
void | AddInput(const std::string &name, const std::string &localName, const std::string &remoteName) |
void | AddOutput(const std::string &name, const std::string &localName, const std::string &remoteName) |
void | AddValuedInput(const std::string &name, const std::string &valueType, const std::string &initialValue, const std::string &valueRouting) |
void | AddValuedOutput(const std::string &name, const std::string &valueType, const std::string &initialValue, const std::string &valueRouting) |
void | Connect(const std::string &routing) |
void | Disconnect() |
void | ForEachConnection(const std::function<void( IPortConnection & ) > &f) |
virtual bool | HasNamedValueChild(const std::string &name) |
bool | IsConnected() const |
bool | IsInput() const |
int | MessageNACK(void *messageNack) |
int | MessageReconnectValue(void *message) |
virtual int | MessageReverseProxyValue(void *message) |
void | Reconnect() |
void | RemoveInput(const std::string &name) |
void | RemoveOutput(const std::string &name) |
void | SetDataConsistency(bool dataConsistency) |
Reimplemented Public Functions
virtual void | Activate() override |
virtual void | Configure(XMLElementEx *xml) override |
virtual void | Create(const char *shortName, CDPComponent *parent) override |
virtual void | CreateModel() override |
virtual void | Destroy() override |
virtual void | FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const override |
virtual void | SetProperty(std::string propertyName, std::string propertyValue) override |
virtual void | Suspend() override |
- 37 public functions inherited from CDPObject
- 46 public functions inherited from CDPBaseObject
- 26 public functions inherited from CDP::StudioAPI::CDPNode
- 22 public functions inherited from CDP::StudioAPI::ICDPNode
Protected Functions
int | HandleReverseProxyValue(const std::string &api, const std::string &value) |
virtual bool | IsInputConnection(XMLElementEx *connection) |
virtual int | MessageConnectValueFailed(void *message) |
virtual int | MessageConnectValueOK(void *message) |
Reimplemented Protected Functions
virtual void | SetPropertyHandler(CDPPropertyBase *property) override |
- 13 protected functions inherited from CDPObject
- 1 protected function inherited from CDP::StudioAPI::CDPNode
Additional Inherited Members
- 6 static public members inherited from CDPObject
- 1 static public member inherited from CDPBaseObject
- 7 protected variables inherited from CDPObject
- 9 protected variables inherited from CDPBaseObject
- 1 static protected member inherited from CDPObject
Detailed Description
The CDPPort is used to gather related data into a single data object similar to a structure in programming languages.
Connecting two CDPPorts via a single routing creates a data bus, propagating the data in directions defined by the CDPPort Connections.
You can make CDPPort types in C++ code, or in Configure mode.
Below is an example of a simple Motor interface header in C++ code:
class MotorInterface : public CDPPort { public: void Create(const char* shortName, CDPComponent* parent) override; CDPProperty<double> SpeedSetpoint; CDPProperty<double> ActualSpeed; CDPProperty<bool> Start; CDPProperty<bool> Stop; CDPProperty<bool> IsRunning; };
Note: When creating CDPProperties for CDPPorts with the Add wizard it is recommended to set the RoutingType to Periodic on them to guarantee same cycle data delivery in application local port connections.
Note: The length of CDPProperty<string> with RoutingType Periodic is not limited but only values of 925 characters or less are guaranteed to pass through the routing system to remote applications.
Properties with Event RoutingType are not guaranteed to be delivered during the same cycle. Event-based CDPProperty<string> length is also not limited but only values of 925 characters or less are guaranteed to pass through the routing system to both local and remote application requesters.
You can easily add code like the above by right-clicking a library, selecting Add New... and then selecting CDP Port Model. The model members (such as SpeedSetpoint) can be added as attributes, changed, and removed in Configure mode.
When a CDPPort is Routed to a location that has the same interface, the CDPPort will automatically handle setting up the data Routings between each member. When all data-member Routings are connected, the CDPPort will show as Connected. If one or more Routings are not connected, then the CDPPort will not show as Connected.
A CDPPort has the following properties:
Name | Description |
---|---|
Routing | The name of the location to look for properties, or Connections with the data API name having routings or routed values with matching names. |
Connected | Is automatically set to true when the port itself including all the properties in it is connected, false if not. |
Input | Should be set to true when the port is on the input side of an object, or set to false to put the port on the output side of an object. |
DataConsistency | When set to true , values connected by this port are sent within the same data packet, meaning that a group of remote values always appears consistent. Otherwise when multiple values change, they may appear for a remote application in the wrong order or one change might be delayed a little. This option can only be enabled when the port only connects values with periodic routing (not event-based, see CDPPropertyBase::RouteMethod_e). |
CDPPorts can, but do not need to, connect to other CDPPorts. A CDPPort can for instance connect to a CDPComponent or CDPObject. As long as it can connect up all properties, the connection will succeed and the data will propagate as configured.
Configuration-only ports can be used to interface data in a component and make it available for instance to a PortMUX (that makes it possible to switch between data sets using an index).
CDPPorts created purely in configuration can contain connections that inform the port about what data to transport. These are called PushConnections, PullConnections and ValuedConnections.
PushConnections are used when data should be taken from the CDPPort and pushed into the target of the PushConnection. PullConnections are used to pull data from a data source into the CDPPort. ValuedConnections are used when the data must be held inside the CDPPort similar to code-based CDPPorts, in this case, the direction of data is defined by the Input property of the ValuedConnection.
Note: When using Ports with PushConnections, PullConnections or ValuedConnections; make sure the Input property on connections is set correctly in the subscribing port and in any intermediate port in chain with connections. Set the Input when the connection's data is input data in given port's location.
Note: Port should not contain multiple Connections for the same API data with Input set to false; duplicate sources for the same API data are not allowed. Duplicate API data sources in port chain result in connection errors in application output.
PushConnection and PullConnections have the following properties:
Name | Description |
---|---|
LocalName | The local name is a routing that refers to the value in the Ports location that the Port will transport. |
RemoteName | The remote name is optional. When set, it refers to the value object relative name to look for on the remote side. If RemoteName is empty, the Connection name itself is first assumed to refer to the data API, then the short name of the object that LocalName refers to. RemoteName can also be used to override the data API name or translate it mid port connection chain if LocalName is left empty. |
Connect | Internal Connectivity flags (clear Hide Internal Items filter in Studio to see the flag). Downstream flag can be cleared to prevent connection from being queried from routed port API-s. Upstream flag can be cleared to hide connection from this port API. Defaults to allow both Downstream and Upstream connections. |
Connected | Is automatically set to true when LocalName and RemoteName are connected, false if not. |
Input | If the CDPPort has Routing and connection's Input is true, the CDPPort wants to receive this value from the subscribed port. If not, the value is sent from this CDPPort to the subscribed CDPPort. |
The table above shows that the (Pull- or Push-)Connections can do name-translation between local and remote objects. For instance, if a CDPPort source object is called IsRunning, and in the destination, it should map to Running, make sure to specify LocalName .IsRunning and RemoteName .Running inside the correct Connection in the CDPPort. This will make the CDPPort connect the local IsRunning value to the remote Running value.
Note: CDPPort routed data will take the most efficient correct route to reach the destination. If there are intermediate CDPPorts that either do not use the data nor have Connections, then the data does not pass through these CDPPorts. Only the information needed to make the data traverse correctly passes through these intermediate CDPPorts.
ValuedConnections have the following properties:
Name | Description |
---|---|
Type | Defines Connections value type. |
Value | Holds the Connections value. |
Routing | Optional routing to route Connections value from some other value. |
Connected | Is automatically set to true when opposing API value exists on the other end of Port chain. |
Input | If the CDPPort has Routing and Input is true, the CDPPort wants to receive this value from the other port. If not, the value is sent from this CDPPort to the other CDPPort. |
Note: The length of ValuedConnection<string> is not limited but only values of 925 characters or less are guaranteed to pass through the routing system to remote applications.
For detailed CDPPort usage see Advanced: CDP Port and How to Use Multivariable Interfaces
Member Function Documentation
CDPPort::CDPPort()
Plain port constructor
[virtual]
CDPPort::~CDPPort()
Destructor
[override virtual]
void CDPPort::Activate()
Reimplemented from CDPBaseObject::Activate().
Establishes connection to remote object. Called automatically by parent component on startup.
void CDPPort::AddInput(const std::string &name, const std::string &localName, const std::string &remoteName)
Adds a input connection in addition to those specified in configuration.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
void CDPPort::AddOutput(const std::string &name, const std::string &localName, const std::string &remoteName)
Adds a output connection in addition to those specified in configuration.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
void CDPPort::AddValuedInput(const std::string &name, const std::string &valueType, const std::string &initialValue, const std::string &valueRouting)
Adds a input connection with embedded value (like ValuedConnection<T>) in addition to those specified in configuration.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
void CDPPort::AddValuedOutput(const std::string &name, const std::string &valueType, const std::string &initialValue, const std::string &valueRouting)
Adds a output connection with embedded value (like ValuedConnection<T>) in addition to those specified in configuration.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
[override virtual]
void CDPPort::Configure(XMLElementEx *xml)
Reimplemented from CDPObject::Configure().
void CDPPort::Connect(const std::string &routing)
Connects the port to specified remote node
[override virtual]
void CDPPort::Create(const char *shortName, CDPComponent *parent)
Reimplemented from CDPObject::Create().
[override virtual]
void CDPPort::CreateModel()
Reimplemented from CDPBaseObject::CreateModel().
[override virtual]
void CDPPort::Destroy()
Reimplemented from CDPBaseObject::Destroy().
void CDPPort::Disconnect()
Disconnects all inputs and outputs. Disconnect does not clear current Routing.
[override virtual]
void CDPPort::FillNodeChildren(CDP::StudioAPI::NodeStream &serializer) const
Reimplemented from CDPNode::FillNodeChildren().
void CDPPort::ForEachConnection(const std::function<void( IPortConnection & ) > &f)
Call argument f function for each Connection the CDPPort has.
[protected]
int CDPPort::HandleReverseProxyValue(const std::string &api, const std::string &value)
[virtual]
bool CDPPort::HasNamedValueChild(const std::string &name)
Returns true if given port has a value child with given name
bool CDPPort::IsConnected() const
Returns true
if all inputs and outputs were found and have been connected.
bool CDPPort::IsInput() const
Returns true
if port is an input.
[virtual protected]
bool CDPPort::IsInputConnection(XMLElementEx *connection)
Override to programmatically determine whether a Connection is input or output.
[virtual protected]
int CDPPort::MessageConnectValueFailed(void *message)
Received when connecting a output failed.
[virtual protected]
int CDPPort::MessageConnectValueOK(void *message)
Received when a output specified in message parameter string was successfully connected.
int CDPPort::MessageNACK(void *messageNack)
int CDPPort::MessageReconnectValue(void *message)
Received when Port needs to try reconnect on a API value.
[virtual]
int CDPPort::MessageReverseProxyValue(void *message)
void CDPPort::Reconnect()
Connects to node specified by Routing property.
void CDPPort::RemoveInput(const std::string &name)
Removes a input.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
void CDPPort::RemoveOutput(const std::string &name)
Removes a output.
If port was connected when this method was called, a reconnect sequence will be triggered. For bulk modifications first call Disconnect(), then do modifications and finally call Reconnect().
void CDPPort::SetDataConsistency(bool dataConsistency)
When set to true
, values connected by this port are sent within the same data packet, meaning that a group of remote values always appears consistent. Otherwise when multiple values change, they may appear for a remote application in wrong order or one change might be delayed a little. This option can only be enabled when the port only connects values with periodic routing (not event-based, see CDPPropertyBase::RouteMethod_e).
If port was connected when this method was called, a reconnect sequence will be triggered.
[override virtual]
void CDPPort::SetProperty(std::string propertyName, std::string propertyValue)
[override virtual protected]
void CDPPort::SetPropertyHandler(CDPPropertyBase *property)
Reimplemented from CDPObject::SetPropertyHandler().
[override virtual]
void CDPPort::Suspend()
Reimplemented from CDPBaseObject::Suspend().
Disconnects all inputs and outputs from remote object.
Get started with CDP Studio today
Let us help you take your great ideas and turn them into the products your customer will love.