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...

Inheritance diagram for IProperty:

Collaboration diagram for IProperty:

Detailed Description

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
virtual ErrCode INTERFACE_FUNC	getValueType (CoreType *type)=0
	Gets the Value type of the Property. Values written to the corresponding Property value must be of the same type. More...

virtual ErrCode INTERFACE_FUNC	getKeyType (CoreType *type)=0
	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...

virtual ErrCode INTERFACE_FUNC	getItemType (CoreType *type)=0
	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...

virtual ErrCode INTERFACE_FUNC	getName (IString **name)=0
	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...

virtual ErrCode INTERFACE_FUNC	getDescription (IString **description)=0
	Gets the short string Description of the Property. More...

virtual ErrCode INTERFACE_FUNC	getUnit (IUnit **unit)=0
	Gets the Unit of the Property. More...

virtual ErrCode INTERFACE_FUNC	getMinValue (INumber **min)=0
	Gets the Minimum value of the Property. Available only if the Value type is `ctInt` or `ctFloat`. More...

virtual ErrCode INTERFACE_FUNC	getMaxValue (INumber **max)=0
	Gets the Maximum value of the Property. Available only if the Value type is `ctInt` or `ctFloat`. More...

virtual ErrCode INTERFACE_FUNC	getDefaultValue (IBaseObject **value)=0
	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...

virtual ErrCode INTERFACE_FUNC	getSuggestedValues (IList **values)=0
	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...

virtual ErrCode INTERFACE_FUNC	getVisible (Bool *visible)=0
	Used to determine whether the property is visible or not. More...

virtual ErrCode INTERFACE_FUNC	getReadOnly (Bool *readOnly)=0
	Used to determine whether the Property is a read-only property or not. More...

virtual ErrCode INTERFACE_FUNC	getSelectionValues (IBaseObject **values)=0
	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...

virtual ErrCode INTERFACE_FUNC	getReferencedProperty (IProperty **property)=0
	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...

virtual ErrCode INTERFACE_FUNC	getIsReferenced (Bool *isReferenced)=0
	Used to determine whether the Property is referenced by another property. More...

virtual ErrCode INTERFACE_FUNC	getValidator (IValidator **validator)=0
	Gets the validator of the Property. More...

virtual ErrCode INTERFACE_FUNC	getCoercer (ICoercer **coercer)=0
	Gets the coercer of the Property. More...

virtual ErrCode INTERFACE_FUNC	getCallableInfo (ICallableInfo **callable)=0
	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...

virtual ErrCode INTERFACE_FUNC	getStructType (IStructType **structType)=0
	Gets the Struct type object of the Property, if the Property is a Struct property. More...

virtual ErrCode INTERFACE_FUNC	getOnPropertyValueWrite (IEvent **event)=0
	Gets the event object that is triggered when a value is written to the corresponding Property value. More...

virtual ErrCode INTERFACE_FUNC	getOnPropertyValueRead (IEvent **event)=0
	Gets the event object that is triggered when the corresponding Property value is read. More...

virtual ErrCode INTERFACE_FUNC	getValue (IBaseObject **value)=0
	Gets the value of the Property. Available only if the Property is bound to a Property object. More...

virtual ErrCode INTERFACE_FUNC	setValue (IBaseObject *value)=0
	Sets the value of the Property. Available only if the Property is bound to a Property object. More...

Public Member Functions inherited from IBaseObject
virtual ErrCode INTERFACE_FUNC	borrowInterface (const IntfID &intfID, void **obj) const =0
	Returns another interface which is supported by the object without incrementing the reference count. More...

virtual ErrCode INTERFACE_FUNC	dispose ()=0
	Disposes all references held by the object. More...

virtual ErrCode INTERFACE_FUNC	getHashCode (SizeT *hashCode)=0
	Returns hash code of the object. More...

virtual ErrCode INTERFACE_FUNC	equals (IBaseObject other, Bool equal) const =0
	Compares object to another object for equality. More...

virtual ErrCode INTERFACE_FUNC	toString (CharPtr *str)=0
	Returns a string representation of the object. More...

Public Member Functions inherited from IUnknown
virtual ErrCode INTERFACE_FUNC	queryInterface (const IntfID &intfID, void **obj)=0
	Returns another interface which is supported by the object and increments the reference count. More...

virtual int INTERFACE_FUNC	addRef ()=0
	Increments the reference count for an interface on an object. More...

virtual int INTERFACE_FUNC	releaseRef ()=0
	Decrements the reference count for an interface on an object. More...

Member Function Documentation

◆ getCallableInfo()

virtual ErrCode INTERFACE_FUNC getCallableInfo ( ICallableInfo ** callable )

pure virtual

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

Parameters

[out] callable The Callable info object.

◆ getCoercer()

virtual ErrCode INTERFACE_FUNC getCoercer ( ICoercer ** coercer )

virtual ErrCode INTERFACE_FUNC getSelectionValues ( IBaseObject ** values )

pure virtual

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.

Parameters

[out] values The list/dictionary of possible selection values.

◆ getStructType()

virtual ErrCode INTERFACE_FUNC getStructType ( IStructType ** structType )

pure virtual

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

Parameters

[out] structType The Struct type of the Struct Property.

◆ getSuggestedValues()

virtual ErrCode INTERFACE_FUNC getSuggestedValues ( IList ** values )

pure virtual

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.

Parameters

[out] values The Suggested values of the Property.

◆ getUnit()

virtual ErrCode INTERFACE_FUNC getUnit ( IUnit ** unit )

pure virtual

Gets the Unit of the Property.

Parameters

[out] unit The Unit of the Property.

◆ getValidator()

virtual ErrCode INTERFACE_FUNC getValidator ( IValidator ** validator )

pure virtual

Gets the validator of the Property.

Parameters

[out] validator The validator.

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

◆ getValue()

virtual ErrCode INTERFACE_FUNC getValue ( IBaseObject ** value )

pure virtual

Gets 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.

◆ getValueType()

virtual ErrCode INTERFACE_FUNC getValueType ( CoreType * type )

pure virtual

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

Parameters

[out] type The value type.

◆ getVisible()

virtual ErrCode INTERFACE_FUNC getVisible ( Bool * visible )

pure virtual

Used to determine whether the property is visible or not.

Parameters

[out] visible True if the Property is visible; false otherwise.

◆ setValue()

virtual ErrCode INTERFACE_FUNC setValue ( IBaseObject * value )

pure virtual

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.

	openDAQ Open data acquisition platform

Detailed Description

Property metadata fields

EvalValue fields and Property binding

Selection properties

Function/Procedure properties

Reference properties

Object-type properties

Container-type properties

Numerical properties

Struct properties

Public Member Functions

Member Function Documentation

◆ getCallableInfo()

◆ getCoercer()

◆ getDefaultValue()

◆ getDescription()

◆ getIsReferenced()

◆ getItemType()

◆ getKeyType()

◆ getMaxValue()

◆ getMinValue()

◆ getName()

◆ getOnPropertyValueRead()

◆ getOnPropertyValueWrite()

◆ getReadOnly()

◆ getReferencedProperty()

◆ getSelectionValues()

◆ getStructType()

◆ getSuggestedValues()

◆ getUnit()

◆ getValidator()

◆ getValue()

◆ getValueType()

◆ getVisible()

◆ setValue()