CDPObject Class

Base class for all addressable objects in CDP. More...

Header: #include <CDPSystem/Base/CDPObject.h>
Inherits: CDPBaseObject,
Inherited By:

CDPAlarm, CDPComponent, CDPParameter, CDPPort, and CDPSignal

Public Functions

CDPObject()
~CDPObject() override
virtual void ActivateIfWaitingForActivate()
void AddProperty_DontSaveDontGenerateEvent(const char *pName, const std::string &strName)
void AddToBaseObjectList(CDPBaseObject *pObj)
virtual void Configure(const char *xml)
virtual void Configure(XMLElementEx *pObjectElement)
virtual void Create(const char *shortName, CDPComponent *pParent)
virtual void CreateXMLConfigurationFilename(std::string &src, const std::string shortName = "", const char *parentName = NULL)
CDPProperty<std::string> &Description()
virtual void DontSaveXML()
CDPBaseObject *GetBaseObject(const char *name)
CDPComponent *GetCDPComponent()
virtual XMLPrimitive *GetObjectXMLLocation()
CDPComponent *GetParent() const
virtual const char *GetType()
virtual XMLElementEx *GetXMLElement()
virtual const XMLParser &GetXMLParser() const
virtual XMLParser &GetXMLParser()
bool IsInitialized()
virtual bool IsWaitingForActivate() const
const char *Name() const override
int ParentHandle() const
std::string ParentName() const
void PropertyClearXMLPointer(CDPPropertyBase *pBase)
void RemoveFromBaseObjectList(CDPBaseObject *pObj)
void SaveNonDefaultProperties()
void SendNotify(MessageRequestHandle *message) const
virtual void XMLParserCallback(XMLPrimitive *pPrim) override

Reimplemented Public Functions

virtual void Activate() override
virtual void ConfigureModel() override
virtual void Create(const char *shortName, CDPBaseObject *pParent)
virtual void Destroy() override
virtual void FillNodeChildren(CDP::StudioAPI::NodeStream &stream) const override
virtual std::string GetNodeLongName() const override
virtual CDP::StudioAPI::CDPNodeType GetNodeType() const override
virtual std::string GetNodeTypeName() const override
virtual std::string GetProperty(std::string propertyName) override
virtual int ReceiveMessage(void *message) override
virtual void SetProperty(std::string propertyName, std::string propertyValue) override
virtual const char *ShortName() const override
virtual void Suspend() override

Static Public Members

CDPObject *GetParentCDPObject(const char *name)
CDPObject *Pointer(const char *name)
std::string ResolveRelativeName(std::string &relativeName, CDPObject *owner, const char *componentName = 0)
std::string ResolveRelativeName(std::string &relativeName, const std::string &ownerName, const char *componentName = 0)
char *ResolveRelativeName(char *relativeName, CDPObject *owner, const char *componentName = 0)
CDPObject *Root()

Protected Functions

void ClearPropertyXMLPointers()
virtual void GetComponentXML(XMLParser &parser, const char *xml)
int MessageConfirm(void *messageAck) override
int MessageTimeout(void *messageAck) override
void ReceiveEvent(Event *ev) override
void RemotePropertyChanged(unsigned int remoteHandle, std::string propertyName, std::string propertyValue) override
virtual void SetPropertyHandler(CDPPropertyBase *pProp)
virtual bool ValidatePropertyHandler(CDP::StudioAPI::CDPVariantValue &newValue, CDPPropertyBase *property)

Reimplemented Protected Functions

virtual void CreateModel() override

Protected Variables

CDPProperty<double> activateWait
CDPProperty<std::string> m_description
char *m_fullName
BaseObjectList m_listBaseObjects
CDPProperty<std::string> m_name
XMLElementEx *m_pXMLElement
CDPProperty<std::string> m_propAlias
char *m_shortName
std::string xmlConfigurationFilename

Static Protected Members

OSAPIMutex ObjectMapLock
ObjectMap s_mapObjects
CDPObject *s_pObjectRoot

Macros

Detailed Description

Base class for all addressable objects in CDP.

The CDPObject is the base class for all addressable objects in CDP. It registers with the CDP subsystem, which makes it possible to send messages to and retrieve information from the object. The CDPObject has message-handler functions, which can be invoked by using a CDPConnector to send messages to the object. All CDPObjects that are not CDPComponents have a parent object that they reside in.

Features

  • Human readable name, specified in Create(). Joined with the parent name, this name uniquely defines the object within a system and is used to address the object. Joined names are separated by '.'
  • Configured from configuration file.
  • Capability to send, receive and reply to messages.
  • Description string for each instance for documentation purposes.
  • Registers with CDP subsystem to facilitate object distribution.
  • Has a parent CDPComponent.

CDPObjects are typically created as CDPComponent child objects in the parent component configuration file. Alarms, signals and parameters are examples of CDPComponent members.

Message handling

Messages are registered in CreateModel like this (the CodeGenerator does this automatically for CDPComponent messages):

Messages with defined binary identifiers and handlers

RegisterMessage(CM_OPEN,"Open","Open the valve.",(CDPOBJECT_MESSAGEHANDLER)&ClassName::MessageOpen, "ParamName");

Messages with defined binary identifiers and no handler

RegisterMessage(CM_OPEN,"Open","Open the valve.", NULL, "ParamName");

This message must be handled in an override of ReceiveMessage(...).

TextMessages

RegisterMessage(CM_TEXTCOMMAND,"Open","Open the valve.",(CDPOBJECT_MESSAGEHANDLER)&ClassName::MessageOpen, "ParamName");

This will make messages with command=CM_TEXTCOMMAND and textCommand=Open to be forwarded to the message handler function MessageOpen(void* Message).

Properties

CDPProperties are available through the virtual function GetProperty(), and can be set through SetProperty().

Supported Properties (in addition to base properties)

AliasCDPObject Alias name
ActivateCDPObject Activate time in seconds (after Application::Start()) (0 = Suspend object)
DescriptionCDPObject description test
ActivateWaitSee Activate.

Supported Messages

CM_TEXTCOMMANDCall a registered MessageHandler (MessageTextCommand). SetProperty and GetProperty are such MessageHandlers.
CM_REQUESTHANDLERequest a MessageNotify (CM_NOTIFY) from the object
CM_ACTIVATECall Activate()
CM_SUSPENDCall Suspend()
CM_CONFIGURE(re) Configure object
CM_DESTROYDestroy the object
CM_SETALIAS(MessageTextString) Set the CDPObject Alias name
CM_MESSAGE_ACKMessage acknowledge received. Command sent from Messenger to Origin object of successful message, sent as a MessageACK message
CM_MESSAGE_NACKMessage acknowledge timed out. Command sent from Messenger to Origin object of unsuccessful message, sent as a MessageACK message
MESSAGE_COMMAND(message)Matching message commands will be called if found.

Member Function Documentation

CDPObject::CDPObject()

Default constructor. Resets all member variables to safe initial values. Overload to set custom members.

CDPObject::~CDPObject()

Default destructor.

[override virtual] void CDPObject::Activate()

Reimplemented from CDPBaseObject::Activate().

Activates message processing and process state machine for the object. Activates 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.

[virtual] void CDPObject::ActivateIfWaitingForActivate()

Called to automatically activate components/objects after Configure(). Activate() is called if: activateWait==1.0, or Time elapsed since Application::Start() is greater than activateWait (value of Activate in xml).

See also CDPEngine::RemoveActivateWait.

void CDPObject::AddProperty_DontSaveDontGenerateEvent(const char *pName, const std::string &strName)

Adds a property to the property database if it does not exist. SaveOnChange and LogEventOnChange is set to false if the property is found.

void CDPObject::AddToBaseObjectList(CDPBaseObject *pObj)

Adds pObj to m_listBaseObjects. Do not call this for CDPObject derived classes.

[protected] void CDPObject::ClearPropertyXMLPointers()

Clears all the XML pointers in all properties in the property database.

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

Configures object from .xml configuration. Configure object instance from .xml description. Opens .xml file if src=".. is specified. If errors are detected, a disk alarm is set and this object (and owner component) becomes invalid.

[virtual] void CDPObject::Configure(XMLElementEx *pObjectElement)

Configures object instance from .xml description. Generates disk alarm and suspends the object if an error is encountered.

[override virtual] void CDPObject::ConfigureModel()

Reimplemented from CDPBaseObject::ConfigureModel().

Configures the model (set default values, read configuration)

[virtual] void CDPObject::Create(const char *shortName, CDPBaseObject *pParent)

Reimplemented from CDPBaseObject::Create().

Creates an object and connect it to the CDP system infrastructure. Note that shortName should be limited to CDPOBJECT_MAX_SHORTNAME_LENGTH

[virtual] void CDPObject::Create(const char *shortName, CDPComponent *pParent)

Create an object and connect it to the CDP system infrastructure. Note that shortName should be limited to CDPOBJECT_MAX_SHORTNAME_LENGTH

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

Reimplemented from CDPBaseObject::CreateModel().

Creates a model instance and registers messages to the object.

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

Creates .xml configuration file name from component name.

CDPProperty<std::string> &CDPObject::Description()

Returns textual description of this instance as specified by the Description attribute.

[override virtual] void CDPObject::Destroy()

Reimplemented from CDPBaseObject::Destroy().

Destroys the object and removes the object from CDP engine and model storage.

This method should reverse what whas done in Create().

Do pre-destructor stuff, like removing references to this object from lists in other objects.

It must be possible to call Destroy() several times without causing harm.

[virtual] void CDPObject::DontSaveXML()

Permanently prevent this object from being saved to XML. m_pXMLElement is unlinked from XMLParser, and the XMLParser will delete the element when destroyed.

[override virtual] void CDPObject::FillNodeChildren(CDP::StudioAPI::NodeStream &stream) const

Reimplemented from CDPNode::FillNodeChildren().

CDPBaseObject *CDPObject::GetBaseObject(const char *name)

CDPComponent *CDPObject::GetCDPComponent()

Returns pointer to the CDPComponent of this object. If this object is actually a CDPComponent then it is simply cast, otherwise parent CDPComponent is returned.

[virtual protected] void CDPObject::GetComponentXML(XMLParser &parser, const char *xml)

Reads .xml file from src="" attribute found in xml into parser. If parser contains elements, this function will just call parser.CallCallback() and return. If parser contains no elements, the XMLConfigurationName will be created, and then the src file (if found) will be read into the parser. Upon error, the object will be suspended and a disk alarm will be set.

[override virtual] std::string CDPObject::GetNodeLongName() const

Reimplemented from ICDPNode::GetNodeLongName().

Returns the full name of the object, f.i. "MyApp.MyComp.MyObject".

See also ShortName().

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

Reimplemented from ICDPNode::GetNodeType().

Returns CDP::StudioAPI::eCDP_OBJECT_NODE

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

Reimplemented from ICDPNode::GetNodeTypeName().

Returns "CDPObject"

[virtual] XMLPrimitive *CDPObject::GetObjectXMLLocation()

Returns a pointer to the XMLPrimitive for this object. For a component, the pointer to the <Component> element is returned, for an Alarm, a pointer to the <Alarm> element is returned, etc. May return nullptr if it can not determine object location.

CDPComponent *CDPObject::GetParent() const

Returns this CDPObject's parent pointer. The parent pointer is set to the parent CDPComponent (or derived) for CDPObject types after Create().

Note: For CDPComponent and derived classes the parent pointer is always set to 0.

[static] CDPObject *CDPObject::GetParentCDPObject(const char *name)

Returns the pointer to nearest CDPObject identified by name. Static method.

Example:

To check if a CDPObject* is also a CDPComponent*, use dynamic_cast

CDPComponent* pComponent = dynamic_cast<CDPComponent*>(GetParentCDPObject("Component.Subcomp.MyNode.MyProperty"));
if (pComponent)
  pComponent->AddSubcomponent(mySubComponent);  // Adds mySubComponent to CDPComponent named "Subcomp"

This function will temporarily lock the ObjectMap and find the object requested.

Returns a pointer to the nearest CDPObject derived parent in scope identified by 'name', or nullptr if not found.

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

Reimplemented from CDPBaseObject::GetProperty().

Handles ShortName, Name, FullName and Model specifically in addition to calling base.

[virtual] const char *CDPObject::GetType()

Returns object type as a const char*, overloaded by extended classes

[virtual] XMLElementEx *CDPObject::GetXMLElement()

Gets the XML Element for this object (may be NULL for a CDPComponent)

[virtual] const XMLParser &CDPObject::GetXMLParser() const

Returns the const XML parser of the owner component

[virtual] XMLParser &CDPObject::GetXMLParser()

Returns the XML parser of the owner component

bool CDPObject::IsInitialized()

Returns true if Configure() has been run at least once.

[virtual] bool CDPObject::IsWaitingForActivate() const

Checks if an object is waiting to be activated.

Returns true if waiting to be activated:

[protected] int CDPObject::MessageConfirm(void *messageAck)

Acknowledge function, called to acknowledge that a destination has received a message when the message was sent with retryenabled.

[protected] int CDPObject::MessageTimeout(void *messageAck)

Message timed out function, called to notify that a message acknowledge has timed out. This means that we don't know if the message was delivered, but we know that we did NOT receive an acknowledge for the message within the timeout.

const char *CDPObject::Name() const

Returns the full name of the object, f.i. "MyApp.MyComp.MyObject".

See also ShortName().

int CDPObject::ParentHandle() const

Returns this CDPObject's parent (CDPComponent-) handle.

Note: When called from a CDPComponent, ParentHandle() will always return 0.

std::string CDPObject::ParentName() const

Returns the name of the parent object

[static] CDPObject *CDPObject::Pointer(const char *name)

Returns the pointer to the object identified by name. Static method.

Example:

To check if a CDPObject* is also a CDPComponent*, use dynamic_cast

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

This function will temporarily lock the ObjectMap and find the object requested.

Returns a pointer to the CDPObject-derived object identified by 'name', or nullptr if not found.

void CDPObject::PropertyClearXMLPointer(CDPPropertyBase *pBase)

Callback-handler to clear the XMLOwner for all properties

[protected] void CDPObject::ReceiveEvent(Event *ev)

Called when events are received, or when an event receiver has subscribed to simple event notifictaions.

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

Reimplemented from CDPBaseObject::ReceiveMessage().

Processes incoming message. Routes registered messages to registered message handlers. Returns 1 if message was processed, 0 if message was not handled.

[protected] void CDPObject::RemotePropertyChanged(unsigned int remoteHandle, std::string propertyName, std::string propertyValue)

Callback used by CDPComponent::Message(Extended)EventNotify() to notify that an event has occurred in an object that this objects has subscribed to.

void CDPObject::RemoveFromBaseObjectList(CDPBaseObject *pObj)

Removes pObj from m_listBaseObjects. Call this in Destroy() when you have called AddToBaseObjectList.

[static] std::string CDPObject::ResolveRelativeName(std::string &relativeName, CDPObject *owner, const char *componentName = 0)

[static] std::string CDPObject::ResolveRelativeName(std::string &relativeName, const std::string &ownerName, const char *componentName = 0)

Resolves relativeName into a full name, returning an std::string. '.' at relativeName start jumps down one level. Examples: Assuming This is a child of Application: '.Item' resolves to 'Application.This.Item' '..Item' resolves to 'Application.Item', and so on.

Also resolves relative to a component name if relative name starts with '$' and componentName specified.

Both the return-value and the first parameter relativeName will contain the resolved name.

[static] char *CDPObject::ResolveRelativeName(char *relativeName, CDPObject *owner, const char *componentName = 0)

Resolves relativeName to a full name, returning a char ptr.

Note: relativeName will be updated with the resolved name, and must be able to hold the full name. Array size for relativeName should be CDPOBJECT_MAX_FULLNAME_LENGTH.

Examples: Assuming This is a child of Application: '.Item' resolves to 'Application.This.Item' '..Item' resolves to 'Application.Item', and so on.

Also resolves relative to a component name if relative name starts with '$' and componentName specified.

Both the return-value and the first parameter relativeName will contain the resolved name.

[static] CDPObject *CDPObject::Root()

Returns the root node (pointer to the application object).

void CDPObject::SaveNonDefaultProperties()

Saves all properties that have non-default values.

void CDPObject::SendNotify(MessageRequestHandle *message) const

Sends a CM_NOTIFY message back to the origin of message.

The notify message is used to notify the existence of an object. The requesting object uses the notify reply to determine the existence and handle of an object.

Uses the origin of message as destination for notify message.

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

Reimplemented from CDPBaseObject::SetProperty().

Handles Activate, ActivateWait and Handle specifically, and calls CDPBaseObject::SetProperty for all other properties.

[virtual protected] void CDPObject::SetPropertyHandler(CDPPropertyBase *pProp)

Callback-handler for properties that need special handling after they are set. Typically used when a change in a property requires other actions to be performed. When treating multiple properties in one callback, the property pointer pProp should be used to compare with the property in question:

if(pProp==&myProperty) { ... }

.

[override virtual] const char *CDPObject::ShortName() const

Reimplemented from CDPBaseObject::ShortName().

Returns the "short" name of the object, f.i. "MyObject"

See also Name().

[override virtual] void CDPObject::Suspend()

Reimplemented from CDPBaseObject::Suspend().

Suspends the object. Message processing and state machine is stopped. Stop the periodic calling of Process() (if this is a CDPComponent) and also stop 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 protected] bool CDPObject::ValidatePropertyHandler(CDP::StudioAPI::CDPVariantValue &newValue, CDPPropertyBase *property)

Callback-handler to restrict property values to certain values.

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

Callback that is called from the XMLParser for each XMLPrimitive in a successfully parsed configuration file.

Member Variable Documentation

OSAPIMutex CDPObject::ObjectMapLock

This variable holds mutex to handle exclusive access to object map.

CDPProperty<double> CDPObject::activateWait

This variable holds activate time for object relative to application startup.

CDPProperty<std::string> CDPObject::m_description

This variable holds human readable description of this component instance.

char *CDPObject::m_fullName

This variable holds the object full name.

BaseObjectList CDPObject::m_listBaseObjects

This variable holds a list of all base-objects in this object. It is here to get access to all CDPBaseObjects that this class owns. The Objects can be timers, Filters, Operators etc.

CDPProperty<std::string> CDPObject::m_name

This variable holds property holder for name.

XMLElementEx *CDPObject::m_pXMLElement

This variable holds a pointer to this object XML element.

CDPProperty<std::string> CDPObject::m_propAlias

This variable holds alternative global name.

char *CDPObject::m_shortName

This variable holds the object name relative to it's parent.

ObjectMap CDPObject::s_mapObjects

This variable holds a map relating the object name to the object handle. Use Handle(string) to look up in this map.

CDPObject *CDPObject::s_pObjectRoot

This variable holds pointer to the application's root object. Use Root() to access this pointer.

std::string CDPObject::xmlConfigurationFilename

This variable holds a string holding the name of the configuration file for this object.

Macro Documentation

CDPOBJECT_MAX_FULLNAME_LENGTH

The maximum full name length of an object , 256 characters including null-terminator

See also CDPOBJECT_MAX_SHORTNAME_LENGTH.

CDPOBJECT_MAX_SHORTNAME_LENGTH

The maximum short name length of an object , 32 characters including null-terminator

See also CDPOBJECT_MAX_FULLNAME_LENGTH.

© CDP Technologies AS - All rights reserved