GenericPropertyPtr< InterfaceType > Class Template Reference

Defines a set of metadata that describes the values held by a Property object stored under the key equal to the property's name. More...

Detailed Description

template<typename InterfaceType>
class GenericPropertyPtr< InterfaceType >

Defines a set of metadata that describes the values held by a Property object stored under the key equal to the property's name.

A property can be added to a Property object or a Property object class. Once added to either, the Property is frozen and can no longer be changed. Adding a Property to a Property object allows for its corresponding value to be get/set. Similarly, when a Property object is created using a Property object class to which a Property was added, corresponding values can be get/set.

When retrieving a Property from a Property object, the returned Property is bound to the Property object. Property metadata fields can reference another Property/Value of the bound Property object. Most Property fields can contain an EvalValue that is evaluated once the corresponding Property field's getter is called. For more information on using EvalValues and binding Properties, see the below section "EvalValue fields and Property binding".

Below we define the types of fields available and highlight some special property types, and what fields are expected for a specific type of property.

Generally, the mandatory fields of a Property are Name, Value type, and Default value.

Property metadata fields

A Property can define the following fields:

• Name: The name of the property. Within a Property object or Property object class, no two properties can have the same name. A Property value is linked to a Property via its name.
• Value type: The type of the corresponding Property value stored in a Property object. The Default value must also be of the same type.
• Default value: The default value of the Property. If no Property value is set on the Property object, the value getter will return the default value.
• Description: A short string description of the property.
• Item type: If the property is a list or dictionary type, the Item type field specifies the types of values stored in the container.
• Key type: If the property is a dictionary type, the Key type specifies the key type of the dictionary.
• Unit: The Property's unit. Eg. second, meter, volt.
• Min value: The minimum value of the Property's corresponding value. The property must be numeric for this field to be valid.
• Max value: The maximum value of the Property's corresponding value. The property must be numeric for this field to be valid.
• Suggested values: A list of suggested values for the property. The list allows a user to see what values are expected for the Property. Those values, however, are not enforced.
• Selection values: A list or dictionary of selection values. If the Selection values field is configured, the value of the Property must be an integer that is used to index into the list/dictionary of selection values.
• Referenced property: Reference to another property on the Property object. When the Referenced property field is set, all getter/setter methods except for those referencing the name and the Referenced property fields will be invoked on the referenced property instead. This field is usually an EvalValue object, pointing to a different property depending on the Property object's current state.
• Is referenced: If true, the property is referenced by another. Properties with the Is referenced field set to true are visible only through the property referencing them and will not be included in the list of visible properties available on the Property object.
• Validator: Validator object that contains an EvalValue expression that checks whether or not the value is valid. See the "Validation and Coercion" section below. See the Validator documentation for more information.
• Coercer: Coercer object that contains an EvalValue expression that coerces any written Property value to the specified boundaries. See the Coercer documentation for more information.
• Read-only: Property values of Properties with Read-only set to true cannot be changed. This can be circumvented by using a protected write available through the PropertyObjectProtected interface.
• Callable info: Available only for function- and procedure-type properties. Contains information about the parameter and return types of the function/procedure stored as the Property value.
• On property value write: Event triggered when the corresponding Property value is written to. Contains a reference to the Property object and allows for overriding the written value.
• On property value read: Event triggered when the corresponding Property value is read. Contains a reference to the Property object and allows for overriding the read value.

EvalValue fields and Property binding

Properties that are retrieved from a Property object are bound to that Property object. This allows for a Property metadata field to access other Properties and their corresponding values of the Property object. Most fields of a Property can be configured with an EvalValue. The EvalValue is evaluated when the property field is retrieved, allowing for its evaluated value to change depending on the state of the Property object.

In an EvalValue expression, other Property object Properties can be referenced with the "%" symbol, while their Property values can be referenced with "$". For example, setting the Visible field to be: EvalValue(If($showProp == 1)) results in the property being visible only if the Property value of "showProp" is set to 1.

Selection properties

Selection properties are those that have the Selection values field configured with either a list, or dictionary, and its Value type must be Integer. The values of the list/dictionary match the Item type of the property, while the keys of the dictionary must be integers. (matching the Value type).

The Property value of a selection property represents the index or key used to retrieve the Selection value from the list/dictionary. As such, the values written to the corresponding Property value are always integers, but the selected value can be of any type.

To obtain the selected value, we get the corresponding Property value, and use it as the index/key to obtain the value from our list/dictionary of selection values. Alternatively, the Property object provides a Selection property getter method that automaticlly performs the above steps.

Selection properties must have a default value.

Function/Procedure properties

Function properties have the Value type Function or Procedure. Functions are callable methods that have an optional return type, while procedures do not return anything. The property value of a Function/Procedure property is a callable object.

To determine the parameter count and types, as well as the return type, the Callable info field must be configured. Callable info contains a list of argument types that need to be passed as arguments when invoking the callable object. If the Property is a Function, the Callable info field also contains the type of the variable returned by the function.

Importantly, Function and Procedure type properties are currently not accessible through the OPC UA layer. Thus, they will not appear on connected-to devices.

Function and Procedure type properties cannot have a default value.

Reference properties

Reference properties have the Referenced property field configured. The Referenced property contains a pointer to another Property that is part of the same Property object. On such properties, all Property field getters except for the Name, Is referenced, Referenced property, Value type, Key type, and Item type return the metadata fields of the referenced Property. Similarly, the Property object value getters and setters get/set the value of the referenced property. The Referenced property field is configured with an EvalValue that most often switches between different properties depending on the value of another property. For example the EvalValue string "switch($switchProp, 0, %prop1, 1, %prop2)" reads the value of the property named "switchProp" and references the property named "prop1" if the value is 0. If the value is 1, it references "prop2" instead.

A Property can be referenced by only one Property within a Property object.

Reference properties can only have the Name and Referenced property fields configured. Their Value type is always undefined.

Object-type properties

Object type properties have the Value type Object. These kinds of properties allow for Properties to be grouped and represented in a hierarchy of nested Property objects. A value of an object-type Property can only be a base Property object. Objects such as Devices or Function blocks that are descendants of the Property object class cannot be set as the Property value. Object type properties can only have their Name, Description and Default value configured, where the Default value is mandatory.

Object properties, as all other Property types get frozen once added to a Property Object. The notable exception is that locally, the object (default value) is cloned and cached. When the Property value of the Object-type Property is read, the cloned object is returned instead of the default value. This cloned object is not frozen, allowing for the any Properties of the child Property Object to be modified. The same behaviour is applied when a Property Object is created from a Property Object Class - all Object-type properties of the class are cloned.

Notably, a object-type property cannot be replaced via set property value (unless using set protected property value), but calling clear property value will reset all of its properties to their default values. clear property value cannot be called of the object-type property is read-only.

Container-type properties

Container type properties have the Value type List or Dictionary and must be homogeneous - they can only have the keys and values of the same type. Their Key and Item types are configured to match that of the Property's Default value. Any new Property value must adhere to the original key and item type.

Containers cannot contain Object-type values, Container-type values (List, Dictionary), or Function-type values. Same applies for they Key type of dictionary objects. Importantly, Container-type properties cannot have empty default values as of now. If the default values are empty, the Key and Item type deduction will not work properly, evaluating the types to be undefined.

Container properties must have a default value.

Numerical properties

Numerical properties represent numbers. Their values can be either Integers or Floating point numbers, depending on the configured Value type. Numerical properties can have the Min and Max value fields configured to limit the range of values accepted.

Additionally, Numerical properties they can have a list of Suggested values, indicating the expected values for the Property. Note that the Property system does not enforce that a Property value matches a number in the list of Suggested values.

Numerical properties must have a default value.

Struct properties

Struct properties represent structures of pre-defined key-value pairs. A Structure property has Value type ctStruct. It stores the Structure type of the Struct given as the default value. New Struct values must have the same Struct type as the default.

Public Member Functions
daq::CoreType	getValueType () const
	Gets the Value type of the Property. Values written to the corresponding Property value must be of the same type. More...
daq::CoreType	getKeyType () const
	Gets the Key type of the Property. Configured only if the Value type is ctDict. If so, the key type of the dictionary Property values must match the Property's Key type. More...
daq::CoreType	getItemType () const
	Gets the Item type of the Property. Configured only if the Value type is ctDict or ctList. If so, the item types of the list/dictionary must match the Property's Item type. More...
daq::StringPtr	getName () const
	Gets the Name of the Property. The names of Properties in a Property object must be unique. The name is used as the key to the corresponding Property value when getting/setting the value. More...
daq::StringPtr	getDescription () const
	Gets the short string Description of the Property. More...
daq::UnitPtr	getUnit () const
	Gets the Unit of the Property. More...
daq::NumberPtr	getMinValue () const
	Gets the Minimum value of the Property. Available only if the Value type is ctInt or ctFloat. More...
daq::NumberPtr	getMaxValue () const
	Gets the Maximum value of the Property. Available only if the Value type is ctInt or ctFloat. More...
daq::BaseObjectPtr	getDefaultValue () const
	Gets the Default value of the Property. The Default value must always be configured for a Property to be in a valid state. Exceptions are Function/Procedure and Reference properties. More...
daq::ListPtr< daq::IBaseObject >	getSuggestedValues () const
	Gets the list of Suggested values. Contains values that are the optimal settings for the corresponding Property value. These values, however, are not enforced when setting a new Property value. More...
daq::Bool	getVisible () const
	Used to determine whether the property is visible or not. More...
daq::Bool	getReadOnly () const
	Used to determine whether the Property is a read-only property or not. More...
daq::BaseObjectPtr	getSelectionValues () const
	Gets the list or dictionary of selection values. If the list/dictionary is not empty, the property is a Selection property, and must have the Value type ctInt. More...
daq::GenericPropertyPtr< daq::IProperty >	getReferencedProperty () const
	Gets the referenced property. If set, all getters except for the Name, Referenced property, and Is referenced getters will return the value of the Referenced property. More...
daq::Bool	getIsReferenced () const
	Used to determine whether the Property is referenced by another property. More...
daq::ValidatorPtr	getValidator () const
	Gets the validator of the Property. More...
daq::CoercerPtr	getCoercer () const
	Gets the coercer of the Property. More...
daq::CallableInfoPtr	getCallableInfo () const
	Gets the Callable information objects of the Property that specifies the argument and return types of the callable object stored as the Property value. More...
daq::StructTypePtr	getStructType () const
	Gets the Struct type object of the Property, if the Property is a Struct property. More...
daq::Event< daq::PropertyObjectPtr, daq::PropertyValueEventArgsPtr >	getOnPropertyValueWrite () const
	Gets the event object that is triggered when a value is written to the corresponding Property value. More...
daq::Event< daq::PropertyObjectPtr, daq::PropertyValueEventArgsPtr >	getOnPropertyValueRead () const
	Gets the event object that is triggered when the corresponding Property value is read. More...
daq::BaseObjectPtr	getValue () const
	Gets the value of the Property. Available only if the Property is bound to a Property object. More...
void	setValue (const daq::BaseObjectPtr &value) const
	Sets the value of the Property. Available only if the Property is bound to a Property object. More...

Member Function Documentation

getCallableInfo()

daq::CallableInfoPtr getCallableInfo ( ) const

inline

Gets the Callable information objects of the Property that specifies the argument and return types of the callable object stored as the Property value.

Returns

The Callable info object.

getCoercer()

daq::CoercerPtr getCoercer ( ) const

inline

Gets the coercer of the Property.

Returns

The coercer.

Used to coerce a value written to the corresponding Property value to the constraints specified by the coercer.

getDefaultValue()

daq::BaseObjectPtr getDefaultValue ( ) const

inline

Gets the Default value of the Property. The Default value must always be configured for a Property to be in a valid state. Exceptions are Function/Procedure and Reference properties.

Returns

The Default value of the Property.

getDescription()

daq::StringPtr getDescription ( ) const

inline

Gets the short string Description of the Property.

Returns

The Description of the Property.

getIsReferenced()

daq::Bool getIsReferenced ( ) const

inline

Used to determine whether the Property is referenced by another property.

Returns

True if the Property is referenced by another property; false otherwise.

getItemType()

daq::CoreType getItemType ( ) const

inline

Gets the Item type of the Property. Configured only if the Value type is ctDict or ctList. If so, the item types of the list/dictionary must match the Property's Item type.

Returns

The Item type of list/dictionary properties.

getKeyType()

daq::CoreType getKeyType ( ) const

inline

Gets the Key type of the Property. Configured only if the Value type is ctDict. If so, the key type of the dictionary Property values must match the Property's Key type.

Returns

The Key type of dictionary properties.

getMaxValue()

daq::NumberPtr getMaxValue ( ) const

inline

Gets the Maximum value of the Property. Available only if the Value type is ctInt or ctFloat.

Returns

The Maximum value of the Property.

getMinValue()

daq::NumberPtr getMinValue ( ) const

inline

Gets the Minimum value of the Property. Available only if the Value type is ctInt or ctFloat.

Returns

The Minimum value of the Property.

getName()

daq::StringPtr getName ( ) const

inline

Gets the Name of the Property. The names of Properties in a Property object must be unique. The name is used as the key to the corresponding Property value when getting/setting the value.

Returns

The Name of the Property.

getOnPropertyValueRead()

daq::Event<daq::PropertyObjectPtr, daq::PropertyValueEventArgsPtr> getOnPropertyValueRead ( ) const

inline

Gets the event object that is triggered when the corresponding Property value is read.

Returns

The On-read event.

The event arguments contain a reference to the property object, as well as a function allowing for the read value to be overridden.

getOnPropertyValueWrite()

daq::Event<daq::PropertyObjectPtr, daq::PropertyValueEventArgsPtr> getOnPropertyValueWrite ( ) const

inline

Gets the event object that is triggered when a value is written to the corresponding Property value.

Returns

The On-write event.

The event arguments contain a reference to the property object, as well as a function allowing for the written value to be overridden.

getReadOnly()

daq::Bool getReadOnly ( ) const

inline

Used to determine whether the Property is a read-only property or not.

Returns

True if the Property is a read-only property; false otherwise.

Read-only Property values can still be modified by using the PropertyObjectProtected interface methods.

getReferencedProperty()

daq::GenericPropertyPtr<daq::IProperty> getReferencedProperty ( ) const

inline

Gets the referenced property. If set, all getters except for the Name, Referenced property, and Is referenced getters will return the value of the Referenced property.

Returns

The referenced property.

If the Property is not bound to a Property object this call will not be able to return the Referenced property.

getSelectionValues()

daq::BaseObjectPtr getSelectionValues ( ) const

inline

Gets the list or dictionary of selection values. If the list/dictionary is not empty, the property is a Selection property, and must have the Value type ctInt.

Returns

The list/dictionary of possible selection values.

getStructType()

daq::StructTypePtr getStructType ( ) const

inline

Gets the Struct type object of the Property, if the Property is a Struct property.

Returns

The Struct type of the Struct Property.

getSuggestedValues()

daq::ListPtr<daq::IBaseObject> getSuggestedValues ( ) const

inline

Gets the list of Suggested values. Contains values that are the optimal settings for the corresponding Property value. These values, however, are not enforced when setting a new Property value.

Returns

The Suggested values of the Property.

getUnit()

daq::UnitPtr getUnit ( ) const

inline

Gets the Unit of the Property.

Returns

The Unit of the Property.

getValidator()

daq::ValidatorPtr getValidator ( ) const

inline

Gets the validator of the Property.

Returns

The validator.

Used to validate whether a value written to the corresponding Property value is valid or not.

getValue()

daq::BaseObjectPtr getValue ( ) const

inline

Gets the value of the Property. Available only if the Property is bound to a Property object.

Returns

The Property value.

OPENDAQ_ERR_NO_OWNER if the Property is not bound to a Property object.

The call is equivalent to calling getPropertyValue on the Property object and all the limitations and implications of that call still apply.

getValueType()

daq::CoreType getValueType ( ) const

inline

Gets the Value type of the Property. Values written to the corresponding Property value must be of the same type.

Returns

The value type.

getVisible()

daq::Bool getVisible ( ) const

inline

Used to determine whether the property is visible or not.

Returns

True if the Property is visible; false otherwise.

setValue()

void setValue ( const daq::BaseObjectPtr &  value ) const

inline

Sets the value of the Property. Available only if the Property is bound to a Property object.

Parameters

value

The Property value.

Returns

OPENDAQ_ERR_NO_OWNER if the Property is not bound to a Property object.

The call is equivalent to calling getPropertyValue on the Property object and all the limitations and implications of that call still apply.