void MyComponent::Activate()
{
  CDPComponent::Activate();
  OSAPIThread::Start(CDPTHREAD_PRIORITY_NORMAL,ShortName());
}

void MyComponent::Suspend()
{
  CDPComponent::Suspend();
  OSAPIThread::Stop();
  OSAPIThread::Delete();
}

void MyComponent::ProcessRunning()
{
  myEvent.Set();
}

...

void MyComponent::Main()
{
  while(!Stopped())
  {
    myEvent.Wait(); // synchronize.
    myEvent.Reset();
    ...
  }
}

if (DebugLevel(DEBUGLEVEL_EXTENDED))
  CDPMessage("%s: Entering state:  %s\n", Name(), state->name);

if (DebugLevelForComponent(m_pParent, DEBUGLEVEL_EXTENDED))
  CDPMessage("%s: New value: %f\n", Name(), GetDouble());

Member Function Documentation

CDPComponent::CDPComponent()

Constructs a CDPComponent. Initializes all member variables to safe default values.

[virtual] CDPComponent::~CDPComponent()

Destructs the instance.

[override virtual] void CDPComponent::Activate()

Reimplemented from CDPBaseObject::Activate().

Activates the component, starts message processing and periodic process execution.

Subcomponents must be activated individually.

All components listed in Application configuration with attribute Activate="1" in component configuration will be started automatically.

Connects all subcomponents connections and remote component connections.

Activate the object so it can receive messages and do processing. When this function is called, the member mutex of the CDPComponent (if this is not a CDPComponent: then the member mutex of the object owner) has already been locked.

This function may be called from another thread, typically the main thread or the Application process thread, or from the correct CDPEngine scheduler.

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

[virtual] void CDPComponent::AddToSyncInList(CDPPropertyBase *pProperty)

Adds a Property to the list of objects to periodically sync in.

See also SyncIn() and AddToSyncInOnceList().

[virtual] void CDPComponent::AddToSyncInList(CDPBaseObject *pObject)

Adds an object to the list of objects to sync in.

See also SyncIn().

[virtual] void CDPComponent::AddToSyncInOnceList(CDPPropertyBase *pProperty)

Syncs in a Property just once.

See also SyncIn() and AddToSyncInList().

[virtual] void CDPComponent::AddToSyncOutList(CDPPropertyBase *pProperty)

Adds a Property to the list of objects to periodically sync out.

See also SyncOut() and AddToSyncOutOnceList().

[virtual] void CDPComponent::AddToSyncOutList(CDPBaseObject *pObject)

Adds an object to the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::AddToSyncOutOnceList(CDPPropertyBase *pProperty)

Syncs out a Property just once.

See also SyncOut() and AddToSyncOutList().

void CDPComponent::ClearConfigurationFault(CDPNode *node)

Marks node configuration failures no longer active

Node should clear the fault via this method after configuration error fixed or error condition not active any more.

See also ReportConfigurationFault.

[static] CDPComponent *CDPComponent::ComponentPointer(const char *name)

Find the pointer to the CDPComponent object identified by name. Static method.

This method is preferred due to performance increase compared to CDPObject::Pointer() when it is known that the object is derived CDPComponent.

Example:

CDPComponent* pComponent = ComponentPointer("Component.Subcomp");
if (pComponent)
  pComponent->AddSubcomponent(mySubComponent);  // Adds a subcomponent to pComponent

name: The full name of the object.

Returns: Pointer to the CDPComponent-derived object identified by name.

[override virtual] void CDPComponent::Configure(const char *xml)

Reimplemented from CDPObject::Configure().

Configures the Component. Will be called automatically when starting a CDP application.

Opens file if src="filename" specified. Finds and opens file named "Components<component full name>.xml" if xml==0.

[virtual] void CDPComponent::ConnectRemoteObject(const char *connectionName, const char *remoteObject)

Connect an already registered connection to a remote object (remoteObject).

A CDPConnector and connectionName (local name) must have been registered with RegisterRemoteObject() before using this method.

connectionName Local name of connection/object earlier registered with RegisterRemoteObject()

remoteObject Full or relative name of the object to connect to.

[virtual] void CDPComponent::ConnectRemoteObject(CDPConnector *connector, const char *remoteObject)

Connect a connector to a remote object. Normally, the other version of ConnectRemoteObject() is used by components.

connector The connector to use. Will be connected to remoteObject.

remoteObject Full or relative name of the object to connect to.

[virtual] void CDPComponent::Create(const char *fullName)

Create component instance with members (signals, alarms, parameters..).

[override virtual protected] void CDPComponent::CreateModel()

Reimplemented from CDPBaseObject::CreateModel().

Creates a model instance for this class and fills model data.

This is a model method. The changes initiated will affect all components of this type.

Overridden method must always call base implementation.

[override virtual protected] void CDPComponent::CreateXMLConfigurationFilename(std::string &src, const std::string shortName = "", const char *parentName = NULL)

Reimplemented from CDPObject::CreateXMLConfigurationFilename().

Creates .xml configuration file name from component name. Resolves the application component path for application owned components. If shortName is empty, Name() will be used internally. If shortName is specified, shortName and parentName (may be nullptr) are combined and used.

void CDPComponent::DecreaseDebugLevel()

Decrease DebugLevel

[override virtual] void CDPComponent::Destroy()

Reimplemented from CDPBaseObject::Destroy().

Removes references to this component in other objects. Destroy this and all members. This method should reverse what what was done in Create(). Calls CDPObject::Destroy().

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

Reimplemented from CDPNode::FillNodeChildren().

CDPConnector *CDPComponent::FindSubcomponentConnector(const char *subcomponent)

Returns connector to subcomponent if found.

void CDPComponent::FlushValues(uint64_t timestamp)

[virtual] int CDPComponent::GetDebugLevel()

CDPComponent::GetDebugLevel Returns the debug level of the component

double CDPComponent::GetFrequency() const

Returns the component sampling frequency for this instance.

OSAPIMutex &CDPComponent::GetMemberAccessMutex()

Returns the reference to the member access mutex so it can be used with OSAPIMutexLocker. Take care when using this, as improper usage may cause race conditions.

See also LockMemberAccess() and ReleaseMemberAccess().

[override virtual] CDP::StudioAPI::CDPNodeType CDPComponent::GetNodeType() const

Reimplemented from ICDPNode::GetNodeType().

double CDPComponent::GetOperatorPeriod() const

Returns the Operator sampling period for this instance.

Usually equal to CDPComponent's GetPeriod(), but may return other value in overridden function.

[protected] XMLElementEx *CDPComponent::GetOrCreateSubComponentElement()

double CDPComponent::GetPeriod() const

Returns the component sampling period for this instance.

std::string CDPComponent::GetPriorityName() const

CDPProcess *CDPComponent::GetProcess() const

[override virtual] std::string CDPComponent::GetProperty(std::string propertyName)

Reimplemented from CDPBaseObject::GetProperty().

Get property value from property storage. Will call CDPObject and return value for property if propertyName is not found. Specially handled properties are: "Status", "StatusNumber" and "XMLConfigurationFilename".

See also SetProperty() and CDPObject::GetPropertyObject().

std::string CDPComponent::GetSchedulingGroupName() const

int CDPComponent::GetStateNumber(const char *state)

Gets numeric state identifier, first state == 1, returns 0 if not found.

int CDPComponent::GetStateNumber()

Get numeric state identifier of current state.

std::string CDPComponent::GetStateString(int stateNumber)

Get string state identifier for numeric state identifier. First state == 1.

[virtual] std::list<std::string> CDPComponent::GetSubcomponentNames()

CDPComponent::GetSubcomponentNames() This function walks through all subcomponents directly owned by this component and fills up a string list containing the full names of said subcomponents

int CDPComponent::GetSyncInId()

int CDPComponent::GetSyncOutId()

[override virtual] XMLElementEx *CDPComponent::GetXMLElement()

Reimplemented from CDPObject::GetXMLElement().

Get the XMLElement pointing to <Component>

[override virtual] const XMLParser &CDPComponent::GetXMLParser() const

Reimplemented from CDPObject::GetXMLParser().

[override virtual] XMLParser &CDPComponent::GetXMLParser()

Reimplemented from CDPObject::GetXMLParser().

[virtual protected] bool CDPComponent::HandleXMLElement(XMLElementEx *pEx)

Handles creation of objects that have an XML configuration in component configuration file. Handle XMLElement <Name...>

Return true for each element that should not be handled by CDP (properties are generated for unhandled elements)

Example code for handling:

bool MyComponent::HandleXMLElement( XMLElementEx* pEx)
  {
    std::string strElementName=pEx->GetName();

    if(strElementName=="MyElement")
    {
      if(pEx->GetParent()==nullptr)
      {
        // set XML element
        m_pXMLElement = pEx;
        //call base to configure base component stuff such as name etc:
        CDPObject::Configure(pEx);
        return true;  // If true is returned, all child elements are skipped.
      }
    }
    return CDPComponent::HandleXMLElement(pEx); // call baseclass
  }

void CDPComponent::IncreaseDebugLevel()

Increase DebugLevel

[virtual protected] void CDPComponent::InitOperators()

Will loop through m_operators and call Init() on the operators.

This function is called in end of Configure() and when fs has changed.

bool CDPComponent::IsInConfigure()

Return true if component is inside Configure() (use IsInitialized() if you want to find out if Configure() has been run at least once).

[virtual] bool CDPComponent::IsState(const char *pS)

Compares the input state string with the current state and returns true if equal.

[virtual] void CDPComponent::LockMemberAccess()

Should be called before modifying (writing/deleting) objects. It is called by CDPEngine before Transitions, Processes, Messages

See also ReleaseMemberAccess().

[virtual] int CDPComponent::MessageEventNotify(void *messageEventUpdate)

Called by event subscriber to notify subscribed objects that new simple events have arrived.

[virtual] int CDPComponent::MessageExtendedEventNotify(void *messageExtendedEventUpdate)

Called by event subscriber to notify subscribed objects that new extended events have arrived.

bool CDPComponent::NeedsSync()

[static] CDPConnector *CDPComponent::Parent(std::string fullName)

Returns pointer to parent Component connector for childs fullName. Finds the pointer to CDPConnector to the parent (owner) of object 'fullName'.

std::string CDPComponent::ParentName() const

Returns parent name.

[virtual] CDP::CDPCOMPONENT_PRIORITY_e CDPComponent::Priority() const

Returns the current priority value.

Returned value is one of the scheduling priority enums in CDP::CDPCOMPONENT_PRIORITY_e.

unsigned int CDPComponent::Process()

Runs the state machine.

This method is called periodically from the CDPEngine. It takes care of the following tasks:

• Updates the status by or'ing the status of all alarms and all subcomponents.
• Runs all state transition handlers out of the current state and changes state if a handler returns true.
• Calls the process function for the current state.
• Calculates process timer and process period.

Returns Status()

[virtual protected] void CDPComponent::ProcessNull()

Process method for the default initial state of the component. May be overridden.

[virtual protected] void CDPComponent::ProcessSubSchedulables()

Process all items which have been added as sub item to current component.

Runs item's Process(). If item needs syncing, SyncIn() is called before item's Process() and SyncOut() is called after.

See also UpdateScheduler().

[virtual] void CDPComponent::QueryStatesMulti(unsigned int requestFromHandle, unsigned int stateNumberToStartFrom)

Sends a message containing many (all, if there is room) state machine state-strings.

[override virtual] int CDPComponent::ReceiveMessage(void *message)

Reimplemented from CDPBaseObject::ReceiveMessage().

Handles incoming messages.

[virtual] void CDPComponent::RegisterAlarm(CDPAlarm &alarm)

Adds an alarm to the component.

[virtual] void CDPComponent::RegisterRemoteObject(CDPConnector *componentConnector, const char *connectionName, const char *remoteObject = 0)

Registers connection to a remote object. componentConnector must always be specified. Either connectionName or remoteObject must be specified, or both of them. If only componentConnector and connectionName are specified, ConnectRemoteObject(connectionName, remoteObject) must be called later.

ConnectRemoteObject() may be used later to connect/change the connection.

componentConnector The connector to use. Will be connected to connectionName and/or remoteObject.

connectionName Local name to use for the connection/object.

remoteObject Full or relative name of the object to connect to.

Assumes that LockMemberAccess() has been called

See also CDPComponent::ConnectRemoteObject().

[virtual] void CDPComponent::RegisterStateProcess(const char *state, CDPCOMPONENT_STATEPROCESS stateProcess, const char *description = 0)

Registers a state machine state.

[virtual] void CDPComponent::RegisterStateTransitionHandler(const char *fromState, const char *toState, CDPCOMPONENT_STATETRANSITIONHANDLER transitionHandler, const char *description = 0)

Registers a state transition handler.

From state and to state must be registered prior to registering the transition.

[virtual] void CDPComponent::RegisterSubcomponent(const char *subcomponent, CDPConnector *subcomponentConnector = 0)

Registers connection to a member subcomponent.

subcomponent Short or full name of subcomponent. Connector will be created using this name if name is specified.

subcomponentConnector Reference to CDPConnector for subcomponent. A connector will be created if a pointer is not specified.

Assumes that LockMemberAccess() is called

[virtual] void CDPComponent::ReleaseMemberAccess()

Must be called after modifying (writing/deleting) objects. It is called by CDPEngine after Transitions, Processes, Messages.

See also LockMemberAccess().

[virtual] void CDPComponent::RemoveAlarm(CDPAlarm &alarm)

Remove alarm must be called before deleting the alarm.

Assumes that LockMemberAccess() has been called

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

[virtual] bool CDPComponent::RemoveFromSyncInList(CDPPropertyBase *pProperty)

Removes an object from the list of objects to sync in.

See also SyncIn().

[virtual] void CDPComponent::RemoveFromSyncInList(CDPBaseObject *pObject)

Removes an object from the list of objects to sync in.

See also SyncIn().

[virtual] bool CDPComponent::RemoveFromSyncOutList(CDPPropertyBase *pProperty)

Removes an object from the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::RemoveFromSyncOutList(CDPBaseObject *pObject)

Removes an object from the list of objects to sync out.

See also SyncOut().

[virtual] void CDPComponent::RemoveParameter(CDPParameter &param)

Remove parameter must be called before deleting the parameter.

Assumes that LockMemberAccess() has been called

void CDPComponent::RemoveRemoteObject(const char *connectionName)

Removes remote object connection. Assumes that LockMemberAccess() has been called.

void CDPComponent::RemoveRemoteObject(CDPConnector *connector)

Removes remote object connection. Assumes that LockMemberAccess() has been called.

void CDPComponent::RemoveStatus(unsigned int nodeId)

void CDPComponent::ReportConfigurationFault(CDPNode *node, const std::string &error)

Inform component about node configuration failure

Any node of the component can report about its configuration or failure via this method. As a result "ConfigurationFaults" alarm is triggered, with Text containing the number and a list of errors reported.

See also ClearConfigurationFault.

[virtual] void CDPComponent::RunInComponentThread(std::function<void() > command, double delayInSeconds = 0.0)

Queues the command and runs it in Component thread Process loop in delayInSeconds but not sooner than next Component cycle.

This is an alternative to using GetMemberAccessMutex() when modifying CDP objects from another thread, and can also be used to simplify handling timed code.

Example usage, where the transmission alarm will be set after the (current) state-machine has been run:

RunInComponentThread([&] () { m_transmissionAlarm->Set(); });

Another example, where the function 'MyComponent::OpenFirstValve' is executed after a 2 second delay:

void MyComponent::OpenFirstValve()
{
  Valve1On = true;
}

void MyComponent::TransitionStoppedToRunning()
{
  if(Start==true)
  {
    RunInComponentThread(std::bind(&MyComponent::OpenFirstValve, this), 2.0);
    return true;
  }
  else
    return false;
}

[virtual] void CDPComponent::RunInProcess(std::function<void() > command)

Queues the command wakes Process and runs command in Process context.

[virtual] void CDPComponent::SaveXML()

Saves component configuration. Take care, as this function blocks. This function can not be called from a process-function as it locks the member access mutex.

See also WriteXMLFileDelayed().

void CDPComponent::SetConfiguring(bool bIsInConfigure)

Called by CDP before and after Configure() is called

[virtual] void CDPComponent::SetFrequency(double frequency)

Set a new update frequency

[virtual] void CDPComponent::SetPriority(CDP::CDPCOMPONENT_PRIORITY_e priority)

Sets the priority to one of the scheduling priority enums in CDP::CDPCOMPONENT_PRIORITY_e.

[override virtual] void CDPComponent::SetProperty(std::string propertyName, std::string propertyValue)

Reimplemented from CDPBaseObject::SetProperty().

Set a property of the object. Called by MessageSetProperty after property name and value has been figured out.

See also GetProperty() and CDPObject::GetPropertyObject().

[override virtual] void CDPComponent::SetPropertyHandler(CDPPropertyBase *pProp)

Reimplemented from CDPObject::SetPropertyHandler().

This handler is called when a property changes.

void CDPComponent::SetXMLConfigurationFilename(const std::string &fileName)

Sets the component configuration file name.

void CDPComponent::SetXMLParser(XMLParser &parser)

Copies parser content to the Component's XMLParser.

[virtual protected] bool CDPComponent::ShouldBeSubScheduled(CDPSchedulable *item) const

Returns true if item should be subscheduled under this CDPComponent.

Depending on item priority, fs and scheduling group, true is returned if all the fields match.

bool CDPComponent::SignalRoutingOK()

Returns /c true if the Routing of all signals is OK.

[virtual] const char *CDPComponent::State()

Returns current state machine state.

[override virtual] unsigned int CDPComponent::Status() const

Reimplemented from CDPBaseObject::Status().

Returns status of the component.

See also CDPAlarm#Alarm Status Defines.

[virtual] bool CDPComponent::SubscribeToEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)

Adds pReceiver to list of objects that will receive a call of their RemotePropertyChanged() function when events from object with handle eventFilter are received. If eventFilter == 0xffffffff, all incoming events from connector will be sent to pReceiver.

[override virtual] void CDPComponent::Suspend()

Reimplemented from CDPBaseObject::Suspend().

Suspends the component, stops message processing and periodic process execution.

Stop the periodic calling of Process() and message processing for CDPObject derived types. The member mutex of the Component or owner object has already been locked when this function is called. This function will be called from the correct CDPEngine scheduler during runtime, or from the main task on shutdown.

[virtual] void CDPComponent::SyncIn(int syncInId = 0, int syncOutId = 0, void *pMessage = nullptr)

SyncIn synchronously clocks signals value from signal external side to signal internal side. CDPComponent will clock all its signals with SyncGroupId==0.

[virtual] void CDPComponent::SyncOut(int syncOutId = 0, int syncInId = 0, void *pMessage = nullptr)

SyncOut synchronously clocks signals value from signal internal side to signal external side. CDPComponent will clock all its signals with SyncGroupId==0.

bool CDPComponent::TimedOut(int usSinceLastTimedOut, int dither)

Called by engine process scheduler to keep track of process periodic interval. Used by the scheduler to determine if it's time to run Process() again.

usSinceLastTimedOut: Microseconds since last run of Process(). dither: Correction for sync error in scheduler process.

Returns true if it is time to call Process() now.

[virtual] bool CDPComponent::UnsubscribeFromEventCallback(CDPConnector &connector, IEventReceiver *pReceiver, unsigned int eventFilter = EVENT_PROPERTY_CHANGE)

Remove pReceiver from list of objects receiving a callback for incoming events from connector with specified filter. Specify eventFilter EVENT_MASK_ALL to remove for all events to this receiver, or another mask to remove only some events.

[protected] void CDPComponent::UpdateFrequency()

Updates Frequency calculations based on fs member.

Update the frequency (from fs) of which the scheduler is to call the Process() method for this component instance.

[protected] void CDPComponent::UpdateScheduler(CDPSchedulable *item)

Adds item to Component scheduling context

Depending on item priority, fs and scheduling group the item is added as sub item to current component if all the fields match or into current Process.

[virtual protected] void CDPComponent::UpdateSchedulerLists()

Will loop through CDPSchedulables and possibly move them between subSchedulables and CDPEngine's scheduler, because this CDPComponet's fs has changed.

void CDPComponent::UpdateStatus(unsigned int nodeId, unsigned int nodeStatus)

void CDPComponent::UpdateTimestamp(uint64_t timestamp)

[override virtual] bool CDPComponent::ValidatePropertyHandler(CDP::StudioAPI::CDPVariantValue &newValue, CDPPropertyBase *property)

Reimplemented from CDPObject::ValidatePropertyHandler().

Called when a property changes. Return true to allow setting newValue to property.

[virtual] void CDPComponent::WriteXMLFileDelayed()

Will trigger the Application worker thread to save the component configuration.

std::string &CDPComponent::XMLConfigurationFilename()

Returns component configuration file name.

[override virtual protected] void CDPComponent::XMLParserCallback(XMLPrimitive *pPrim)

Reimplemented from CDPObject::XMLParserCallback().

After a successful file parse, all elements in the XML tree is sent to this function.

XMLParser callback. Called for each element (<SomeElement/>) in the component configuration file in the order they are defined.

This function is only invoked after a successful parsing of the component configuration file. Example code for handling:

void MyComponent::XMLParserCallback(XMLPrimitive* pPrim)
{
  CDPComponent::XMLParserCallback(pPrim);

  if(pPrim->GetType()==e_XMLElement)
  {
    // We now know we have an XMLElementEx pointer:
    XMLElementEx* pEx = static_cast<XMLElementEx*>(pPrim);
    // Get the name of the element <Signal ... ></Signal>
    std::string strElementName = pEx->GetName(); // should return 'Signal' for a Signal.
    if(strElementName=="Signal" && pEx->GetAttributeValue("Name")=="TestSignal" )
    {
      // treat the <Signal Name="TestSignal" .... /> element further.
    }
  }
}