CDPConnector myConnector;                 // autogenerated in MyComponent header file
...
myConnector.Create("myConnector",this);   // auto-generated in MyComponent::Create() method
...
myConnector.ConnectTo("MyApp.MyCDPComponent.MyCDPObject"); // ConnectTo() should be called to tell which remote object the connector should connect to, can e.g. be done in Configure() or later. Not needed if the connector is already configured with correct remote name.
...

void MyComponent::ProcessStart()
{
  if (myConnector.Connected() && startWanted && !started)
    myConnector.SendMessage("Start");
}

void MyComponent::ProcessNull()
{
  if(myConnector.Connected() && myConnector.RemoteState("Online"))
    requestedState = "Online";
}

if (pumpConnector.Connected())
  pumpConnector.SendMessage("Start");

if (pumpConnector.Connected() && pumpConnector.RemoteState("Stopped"))
  pumpConnector.SendMessage("Start","AdditionalInformation");

int MyComponent::MessageStart(void* message)
{
  MessageTextCommandWithParameterReceive* msg = static_cast<MessageTextCommandWithParameterReceive*>(message);
  std::string strParameter(msg->parameters);
  CDPMessage("%s: Received Start Message with parameter %s\n",Name(),strParameter.c_str());
  return 1;
}

void MyComponent::ProcessNull()
{
  static bool sent = false;
  if(pump.Connected())
  {
    pump.SendMessage("Start");
    sent = true;
  }
}

int MyComponent::MessageTimedOut(void* messageAck)
{
  MessageACK* pMack = static_cast<MessageACK*>(messageAck);
  unsigned int handle = pMack->originalMessage.Destination();
  CDPMessage("%s: Got Timeout for message to Handle : 0x%08x, sendStatus=%i\n",Name(),handle,pMack->sendStatus);
  return 1;
}

int MyComponent::MessageConfirm(void* messageAck)
{
  MessageACK* pMack = static_cast<MessageACK*>(messageAck);
  unsigned int handle = pMack->originalMessage.Destination();
  CDPMessage("%s: Got Confirmation for message to Handle : 0x%08x, sendStatus=%i\n",Name(),handle,pMack->sendStatus);
  return 1;
}

void PumpController::ProcessNull()
{
  if (pump.Connected() && !modelRequested)
  {
    pump.SubscribeToEventNotifications(this); // Set up subscription so RemotePropertyChanged is called when property is received

    bool success = false;
    std::string model = pump.GetProperty("Model",success);
    if(success)
      RemotePropertyChanged(pump.RemoteHandle(),"Model",model); // locally found property will not cause callback to be called, so we invoke it manually.

    modelRequested = true;
  }
}

void PumpController::RemotePropertyChanged(unsigned int remoteHandle, std::string propertyName, std::string propertyValue)
{
  if(remoteHandle==pump.RemoteHandle() && propertyName=="Model")
  {
    // Print out the model:
    CDPMessage("%s: pump has model %s\n", Name(), propertyValue.c_str());
    // Tell the connector we are no longer interested in eventNotifications:
    RunInComponentThread([=]{pump.UnsubscribeFromEventNotifications(this);});
  }
}

Member Function Documentation

CDPConnector::CDPConnector()

Constructs a CDPConnector

CDPConnector::CDPConnector(const char *remoteName)

Constructs a CDPConnector and connects to remoteName.

CDPConnector::~CDPConnector()

Releases connection and destroys the instance.

std::string CDPConnector::ClosestParentCDPObjectName() const

Returns closest parent CDPComponent/CDPObject of RemoteName()

If not Connected(), empty string is returned. If Connected(), RemoteName() will be returned if the full remote name does not contain any CDPNode(s) at the end of the name. If there are any CDPNode(s) at the end of the name, the closest parent CDPComponent/CDPObject name will be returned.

If e.g. the remote name is 'App.CDPComponent.CDPObject', 'App.CDPComponent.CDPObject' will be returned.

If e.g. the remote name is 'App.CDPComponent', 'App.CDPComponent' will be returned.

If e.g. the remote name is 'App.CDPComponent.CDPNode1.CDPNode2', 'App.CDPComponent' will be returned.

See also CDPConnector::RemoteName().

[virtual] void CDPConnector::Configure(XMLElementEx *pEx)

Runs Configure() for m_object and m_description. pEx must point to a xml Connector-line.

void CDPConnector::ConnectTo(const char *remoteName)

Connects to an object identified by remoteName, which is the full name of the object (local or remote) to connect to. Connection is not instant, so the user must call Connected() before attempting any operations on the connector.

bool CDPConnector::Connected() const

Gets connection status

Use Connected() to check if remote object is connected.

Returns true if communication link is valid and state and handle information is updated (see note). Returns false if communication link is not valid; i.e. the specified object is not available on the network.

[virtual] void CDPConnector::Create(const char *connectorName, CDPComponent *pOwnerComponent)

Initializes the instance. Creates CDPProperties and saves pOwnerComponent for later use.

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

Reimplemented from CDPNode::FillNodeChildren().

Writes m_object (routing to object), m_connected and m_description to serializer stream.

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

Reimplemented from ICDPNode::GetNodeName().

Returns the local name given to the connector.

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

Reimplemented from ICDPNode::GetNodeTypeName().

Returns a "CDPConnector".

std::string CDPConnector::GetProperty(const char *propertyName, bool &bSuccess)

Reads property from remote object.

If the property value is not available locally yet, the value will be requested, and (if SubscribeToEventNotifications has been called) then the owner component RemotePropertyChanged() will be called when the value arrives.

Callback-registration is done by calling SubscribeToEventNotifications( objectToReceiveNotify ) , and the callback will invoke the RemotePropertyChanged() function in objectToReceiveNotify when the property is retrieved.

Example code:

if(connector->Connected())
{
  connector->SubscribeToEventNotifications(this);

  bool success = false;
  std::string name = connector->GetProperty("Name",success);
  if(success)
    RemotePropertyChanged(connector->RemoteHandle(),"Name",name);
}

bool CDPConnector::GetPublishRoutingStatus() const

Gets the Connectors Object property routing publish behavior in RoutingsTable.

CDPComponent *CDPConnector::OwnerComponent() const

Returns raw pointer to owner component.

void CDPConnector::Preserve()

Tells the underlying CDPConnection to keep the connection even if this CDPConnector is destroyed or released.

bool CDPConnector::Preserved() const

Gets the preserved state of this connection

void CDPConnector::Release()

Releases connection without deleting connector.

unsigned int CDPConnector::RemoteHandle() const

Gets handle of remote component.

std::string CDPConnector::RemoteName() const

Returns full remote object name.

See also CDPConnector::ClosestParentCDPObjectName().

std::string CDPConnector::RemoteShortName() const

Returns connected component name. If not connected then returns empty string.

const char *CDPConnector::RemoteState() const

Gets state of remote component.

bool CDPConnector::RemoteState(const char *stateToCheck) const

Returns true if the component is in the specified state

unsigned int CDPConnector::RemoteStatus() const

Gets the most recently updated status of the remote object.

The status equals the or'ed statuses of the alarms and subcomponents. The Status bits are defined in CDPAlarm.

unsigned int CDPConnector::SendMessage(const MessagePacketHandle &message)

unsigned int CDPConnector::SendMessage(Message *msg, bool retryEnabled = true)

Sends custom message with or without retries.

This function is used to send messages already filled out by user code. Messages which is larger than the Message struct may be sent. Also remember that all values in the Message must be on network format. Use macros MESSAGE_FILL and similar to help filling the message correctly.

Note: Set the parameterSize member correctly. This must be set to the number of bytes following after the parameterSize member.

msg - Pointer to message to send. retryEnabled - Set to true to make the messenger ask for acknowledge and resend the message if not aknowledge has been received.

See also Messenger and MESSAGE_FILL.

unsigned int CDPConnector::SendMessage(const char *command, unsigned int origin = 0)

Sends CM_TEXTCOMMAND message with specified text command (no parameters).

command - Text command to send origin - Origin handle to put in message to send. If 0 or not specified, handle of CDPConnector's owner or Messenger will be used.

unsigned int CDPConnector::SendMessage(const char *command, const char *parameter, unsigned int origin = 0)

Sends CM_TEXTCOMMAND message with specified text command and string parameter. Both command and parameter must be zero terminated strings.

command - Text command to send, must be zero terminated. parameter - Zero-terminated string parameter. origin - Origin handle to put in message to send. If 0 or not specified, handle of CDPConnector's owner or Messenger will be used.

unsigned int CDPConnector::SendMessage(unsigned int command, unsigned int origin = 0)

Sends binary message (without parameters).

command - Binary command to send, typically CM_ACTIVATE or similar. origin - Origin handle to put in message to send. If 0 or not specified, handle of CDPConnector's owner or Messenger will be used.

void CDPConnector::SendMessageNoRetry(Message *msg)

Sends message without retries (no acknowledgement requested from recipient). Same as SendMessage(Message*, false)

See also CDPConnector::SendMessage().

void CDPConnector::SetAckLocalMessages(bool ackLocal)

void CDPConnector::SetConnectionChangeCallback(const std::function<void( bool connected ) > &callback)

void CDPConnector::SetProperty(const char *propertyName, const char *propertyValue, int saveOnChange = -1)

Sends a message that sets destination object's CDPProperty named propertyName to propertyValue.

If an owner component is set, it will receive callbacks on message acks.

If optional argument saveOnChange is set to 1, changed CDPProperty value is saved to XML. If 0 then value is changed but change is not saved to XML. Therefore it is lost after restarting the application. Default is -1, then property's SaveOnChange setting is used to determine whether to save the value. Note that this argument will not update SaveOnChange setting, it just overrides it.

void CDPConnector::SetPublishRoutingStatus(bool publishRoutingStatus)

Sets the Connectors Object property routing publish behavior in RoutingsTable. By default CDPConnector publishes its routing in the CDP tables for tools to see.

[virtual] bool CDPConnector::SubscribeToEventNotifications(IEventReceiver *pReceiver, unsigned int eventFilter = 0xffffffff)

Adds pReceiver to the list of objects that will receive updates when events from object with handle handleEventSource are received ( typically after a call to CDPConnector::GetProperty() )

The pReceiver will then receive a message describing the event. If handleEventSource==0xffffffff, all events will be sent to pReceiver. Use eventFilter to mask out which events to subscribe to.

The eventFilter bits are defined like this:

#define EVENT_ALARMSET                  0x00000001    // The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" (The Unack flag was set if not already set)
#define EVENT_ALARMCLEAR                0x00000002    // The alarm's Set flag was cleared. The Unack state is unchanged.
#define EVENT_ALARMACK                  0x00000004    // The alarm changed state from "Unacknowledged" to "Acknowledged". The Set state is unchanged.
#define EVENT_PROPERTY_CHANGE           0x00000008    // Some property was changed.
#define EVENT_REPRISE                   0x00000040    // A repetition/update of an event that has been reported before. Courtesy of late subscribers.
#define EVENT_SOURCE_OBJECT_UNAVAILABLE 0x00000100    // The provider of the event has become unavailable (disconnected or similar)
#define EVENT_NODE_BOOT                 0x40000000    // The provider reports that the CDPEventNode just have booted.
#define EVENT_EXTENDED_INFO_AVAILABLE   0x80000000    // Indicates that this event also have sent extended event, and that the extended event info is available as extended event.

#define EVENT_MASK_ALL                  0xffffffff
#define EVENT_MASK_ALARM_EVENT          (EVENT_ALARMSET | EVENT_ALARMCLEAR | EVENT_ALARMACK)

See also UnsubscribeFromEventNotifications.

[virtual] bool CDPConnector::UnsubscribeFromEventNotifications(IEventReceiver *pReceiver, unsigned int eventFilter = 0xffffffff)

Removes pReceiver from list of objects that will receive updates when events from object with handle handleEventSource are received.

The pReceiver will then receive a message describing the event. Use eventFilter to mask out which events to unsubscribe to.

See also SubscribeToEventNotifications.