API Documentation

System Design

The System Design API lets you interact with the PolySync System Design File (SDF). This API allows for standard create, read, update, and destroy (CRUD) interactions with PolySync entity Configurations.

The PolySync SDF Configurator allows you to configure a PolySync Runtime, and the SDF API allows you to access data stored within the SDF.

The SDF defines the runtimes, hosts, and nodes that create a PolySync system. It also contains all the Configuration parameters for each of the SDF entities.

Usage #include <PolySyncSystem.hpp>

Functions

polysync::system::resetSchema ( … )

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | const polysync::Node & | node | Node reference used to determine file path to system design file. |

Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_CONFIG - Retrieval failed due to a SQL error
    • DTC_IOERR - Retrieval failed due to a SQL error

polysync::system::readDtcDescription ( … )

This will pull the description string for a given ps_dtc value from the system design file.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | ps_dtc | dtc | Value used to pull description string from the system design file. |

Returns
  • std::string - System description for a given diagnostic trouble code
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_CONFIG - Retrieval failed due to a SQL error

polysync::system::readParameterDescription ( … )

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | unsigned long | parameterId | ID value used to find a parameter entry in the system design file. |

Returns
  • std::string - Description for a parameter, matching the given ID, in the system design file
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_CONFIG - Retrieval failed due to a SQL error

polysync::system::createParameterDescription ( … )

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in ||| | in | ps_parameter_value_kind | | | in | std::string || | in | ps_node_ref||

Returns
  • bool - True on successful copy to system design file, false on failure
Exceptions
  • none

Configuration

The abstract interface for system configuration elements.

The default behavior is the same for all subclasses already implemented, i.e. SensorConfiguration, RuntimeConfiguration, etc.

Configuration::Configuration ( )

The default constructor. Subclass implementations that use this constructor will attempt to retrieve data from the default SDF path.

Configuration::Configuration ( … )

The constructor taking polysync::Node. The node reference is used to determine the runtime path for the system design file (SDF).

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | const polysync::Node & | node | Node reference used to determine SDF path. |

virtual Configuration::~Configuration ( ) = default

The default empty destructor.

virtual Configuration::create ( … ) = 0

This will add a new configuration entry to the SDF. The configuration’s ID member will be set during it’s creation, and does not need to be set in the argument.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | uint | autoFill | Optional argument. Default value = 1. Default will populate with all child entities existing in the configuration. |

virtual Configuration::read ( … ) = 0

This will read from an existing SDF configuration in the SDF.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | ulong | id | Unique SDF ID for configuration to gather data from. | | in | uint | autoFill | Optional argument. Default value = 1. Default will populate with all child entities existing in the configuration. |

virtual Configuration::update ( … ) = 0

This will update the existing SDF configuration to match this object.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | uint | autoFill | Optional argument. Default value = 1. Default will populate with all child entities existing in the configuration. |

virtual Configuration::destroy ( ) = 0

This function will remove this configuration from the SDF.

virtual Configuration::getId ( ) const = 0

This function will return this configuration’s unique system design file ID.

Returns
  • ulong - SDF configuration ID

virtual Configuration::getName ( ) const = 0

This function will return this configuration’s system design file name.

Returns
  • std::string - string name from the SDF

virtual Configuration::getSiblingIds ( ) const = 0

This will get a list of sibling configurations with a matching parent.

Returns
  • std::vector< ulong > - List of configuration IDs under same parent

virtual Configuration::getSiblingCount ( ) const = 0

This will get the number of sibling configurations with matching parent configurations.

Returns
  • ulong - Number of configurations with the same parent

virtual Configuration::getParameterListId ( ) const = 0

This will get the SDF ID for this configuration’s parameter list.

Returns
  • ulong - ID value for corresponding parameter list data in SDF

virtual Configuration::setId ( ) = 0

This will set the SDF ID for this configuration.

virtual Configuration::setName ( ) = 0

This will set this configuration’s system design file name.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | std::string | name | string name for this configuration. |

virtual Configuration::setParameterListId ( ) = 0

This wills set the parameter list in the system design file for this configuration.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | ulong | parameterListId | SDF ID to parameter list entry for this configuration. |

Configuration::getNodeReference ( ) const

The accessor to a PolySync node pointer.

Returns

Configuration::setNodeReference ( )

The mutator for a PolySync node pointer. If the value is set for this configuration, CRUD operations will use this node to determine the path to the SDF file.

Parameters

| in/out | type | name | description | |:—:|:—:|—| | in | ps_node_ref | nodeReference | Pointer to PolySync node. |

SensorDescriptor

This contains SDF information about a specific sensor device.

SensorDescriptor::SensorDescriptor ( )

The empty constructor initializes private data.

SensorDescriptor::SensorDescriptor ( … )

The copy constructor for the C type.

Parameters
in/out type name description
in ps_sdf_sensor_descriptor cDescriptor C struct to copy.

SensorDescriptor::SensorDescriptor ( )

The copy constructor.

Parameters
in/out type name description
in SensorDescriptor descriptor Object to copy.

virtual SensorDescriptor::~SensorDescriptor ( )

The destructor.

SensorDescriptor::setSensorType ( )

The mutator for private member data.

Parameters
in/out type name description
in ps_sensor_kind sensorKind Sensor kind value, i.e. PSYNC_SENSOR_KIND_UNKNOWN.

SensorDescriptor::setName ( )

The mutator for private member data.

Parameters
in/out type name description
in std::string name String name for sensor.

SensorDescriptor::setDescription ( )

Parameters
in/out type name description
in SensorDescriptor descriptor Object to copy.

SensorDescriptor::getSensorType ( ) const

The accessor for the private data member.

Returns

SensorDescriptor::getName ( ) const

The accessor for the private data member.

Returns
  • std::string

SensorDescriptor::getDescription ( ) const

The accessor for the private data member.

Returns
  • std::string

SensorDescriptor::getSensorDescriptor ( )

The accessor for the private data member.

Returns

ParameterValue

The C++ wrapper for ps_parameter_value.

The private data contains a value and a type.

Possible types: - PARAMETER_VALUE_UNKNOWN - PARAMETER_VALUE_ULONGLONG - PARAMETER_VALUE_LONGLONG - PARAMETER_VALUE_DOUBLE - PARAMETER_VALUE_STRING

ParameterValue::ParameterValue ( )

The constructor. This allocates private data, setting ps_parameter_value_kind to PARAMETER_VALUE_UNKNOWN.

ParameterValue::ParameterValue ( … )

The copy constructor taking ps_parameter_value.

Parameters
in/out type name description
in ps_parameter_value cValue PolySync C struct to copy.

virtual ParameterValue::~ParameterValue ( )

The destructor. This deallocates private data resources.

ParameterValue::getValue ( )

This will get the value from the underlying union in string form.

Returns
  • std::string - String representation of parameter value

ParameterValue::setValue ( )

This will set the value according to the implicit type of the object.

Parameters
in/out type name description
in std::string value std::string - converted to correct type.

ParameterValue::getType ( ) const

This will get the data type for the parameter value that is stored in the underlying union.

Returns

ParameterValue::copyStruct ( … )

Parameters
in/out type name description
in const ps_parameter_value & cValue C struct to copy.

ParameterValue::getParameterValue ( ) const

The access to private data.

Returns
  • const ps_parameter_value &

ParameterConfiguration

This will implement the configuration interface.

See link for override member function information.

ParameterConfiguration::ParameterConfiguration ( )

The empty constructor. See configuration.

ParameterConfiguration::ParameterConfiguration ( … )

The constructor. This uses the polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to determine file path to system design file.
Exceptions
  • none

ParameterConfiguration::ParameterConfiguration ( … )

The copy constructor.

Parameters
in/out type name description
in const ParameterConfiguration & objectToCopy Existing object to copy from.
Exceptions
  • none

ParameterConfiguration::ParameterConfiguration ( … )

The C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_parameter_value & cStructToCopy Existing object to copy from.
Exceptions
  • none

virtual ParameterConfiguration::~ParameterConfiguration ( )

The destructor.

ParameterConfiguration::createNewParameterDescription ( … )

This will create a new parameter description entry in the system design file.

Parameters
in/out type name description
in unsigned long newDescriptionId ID value. Must be greater than PSYNC_PARAMETER_ID_MAX.
in std::string newDescription String description for system design file entry.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_CONFIG - Retrieval failed due to a SQL error
    • DTC_USAGE - Must call setParameterValue prior to creation

ParameterConfiguration::getParameterValue ( ) const

The accessor to private data.

// Get parameter value from existing @ref ParameterConfiguration object.
auto myParameterValue = myParameterConfiguration.getValue();

// Print the data as a string.
std::cout << myParameterValue.getValue() << std::endl;
Returns
  • ParameterValue

ParameterConfiguration::getMin ( ) const

The accessor to private data. This represents the maximum value allowed in the system design file. Not all ParameterConfiguration objects have a minimum.

if( myParameterValue.getMin().getType() == PARAMETER_VALUE_UNKNOWN )
{
    // Minimum value not supported for this parameter configuration
}
Returns
  • ParameterValue - See example above to determine if minimum value is supported for this ParameterConfiguration entry in the system design file

ParameterConfiguration::getMax ( ) const

The accessor to private data. This represents the maximum value allowed in the system design file. Not all ParameterConfiguration objects have a maximum.

if( myParameterValue.getMax().getType() == PARAMETER_VALUE_UNKNOWN )
{
    // Maximum value not supported for this parameter configuration
}
Returns
  • ParameterValue - See example above to determine if minimum value is supported for this ParameterConfiguration entry in the system design file

ParameterConfiguration::getStep ( ) const

The accessor to private data. This represents the incremental ( + or - ) step value allowed for this configuration. Not all ParameterConfiguration objects have a step increment.

if( myParameterValue.getStep().getType() == PARAMETER_VALUE_UNKNOWN )
{
    // Step increment not supported for this parameter configuration
}
Returns
  • ParameterValue - See example above to determine if step increment is supported for this ParameterConfiguration entry in the system design file

ParameterConfiguration::getDescription ( ) const

The accessor to private data. This will get the string description for this parameter from the system design file.

Returns
  • std::string

ParameterConfiguration::getFlags ( ) const

The accessor to private data. This will perform a bitwise comparison for potential flags set for this parameter configuration, e.g. PSYNC_PARAMETER_FLAG_READONLY.

Returns
  • unsigned short - Use bitwise comparison to determine which flags are set

ParameterConfiguration::getParameterDescriptionId ( ) const

The accessor to private data. This represents a foreign key pointing to the associated description for this parameter configuration. Descriptions are stored in a different table in the system design file. This value ties a specific parameter configuration to a specific description.

Returns
  • unsigned long - Foreign key linking this parameter configuration to a description in the system design file

ParameterConfiguration::setParameterValue ( … )

The mutator to private data.

Changes will not exist in the system design file until a user calls create or update for this configuration.

Parameters
in/out type name description
in const ParameterValue & value Object containing value for setting in the system design file.

ParameterConfiguration::setMin ( … )

The mutator to private data. Changes will not exist in the system design file until a user calls create or update for this configuration.

Parameters
in/out type name description
in const ParameterValue & value Object containing value for setting in the system design file.

ParameterConfiguration::setMax ( … )

Mutator to private data. Changes will not exist in the system design file until a user calls create or update for this configuration.

Parameters
in/out type name description
in const ParameterValue & value Object containing value for setting in the system design file.

ParameterConfiguration::setStep ( … )

The mutator to private data.

Changes will not exist in the system design file until a user calls create or update for this configuration.

Parameters
in/out type name description
in const ParameterValue & value Object containing value for setting in the system design file.

ParameterConfiguration::setDescription ( … )

The mutator to private data.

Changes will not exist in the system design file until a user calls create or update for this configuration.

Parameters
in/out type name description
in std::string description String description for this configuration.

ParameterConfiguration::setFlags ( … )

The mutator to private data.

Changes will not exist in the system design file until the user calls create or update for this configuration.

Parameters
in/out type name description
in unsigned short flags Bits to set. For example, PSYNC_PARAMETER_FLAG_READONLY.

ParameterConfiguration::setParameterDescriptionId ( … )

The mutator to private data.

Changes will not exist in the system design file until the user calls create or update for this configuration.

Parameters
in/out type name description
in unsigned long descriptionId Foreign key linking to a description in the system design file.

static ParameterConfiguration::copyValue ( … )

The copy method for C type.

Parameters
in/out type name description
in const ps_parameter_value & in Struct to copy.
out ps_parameter_value & out Struct receiving copied data.

IOConfiguration

This class implements the Configuration interface. Please see link for override member function information.

IOConfiguration::IOConfiguration ( )

This is an empty constructor.

The function uses a default PolySync system design file path for CRUD operations.

IOConfiguration::IOConfiguration ( … )

The constructor.

This function uses a polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to determine file path to system design file.

IOConfiguration::IOConfiguration ( … )

This is a copy constructor.

Parameters
in/out type name description
in const IOConfiguration & objectToCopy Existing object to copy from.

IOConfiguration::IOConfiguration ( … )

A C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_io_configuration & cStructToCopy Existing object to copy from.

virtual IOConfiguration::~IOConfiguration ( )

A destructor.

IOConfiguration::getParameterConfigurations ( ) const

An accessor to private data.

This will return a list of parameter configurations from the system design file for this configuration.

Returns
  • std::vector< ParameterConfiguration >

IOConfiguration::getSensorConfigurationId ( ) const

An accessor to private data.

This will return the primary key in the system design file for the parent SensorConfiguration.

Returns
  • unsigned long - Parent key in system design file

IOConfiguration::setSensorConfigurationId ( … )

A mutator to private data.

This will set the primary system design file key for the parent SensorConfiguration.

Parameters
in/out type name description
in unsigned long id Primary key value in system design file.
Returns
  • unsigned long - Parent key in system design file

SensorConfiguration

This will implement the Configuration interface.

Please see link for override member function information.

SensorConfiguration::SensorConfiguration ( )

An empty constructor.

This uses a default PolySync system design file path for CRUD operations.

SensorConfiguration::SensorConfiguration ( … )

A constructor.

This function uses a polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to
determine file path to system design file.

SensorConfiguration::SensorConfiguration ( … )

A copy constructor.

Parameters
in/out type name description
in const SensorConfiguration & objectToCopy
An existing object to copy from.

SensorConfiguration::SensorConfiguration ( … )

A C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_sensor_configuration & cStructToCopy Existing object to copy from.

virtual SensorConfiguration::~SensorConfiguration ( )

A destructor.

SensorConfiguration::getParameterConfigurations ( ) const

An accessor to private data.

This function returns a list of parameter configurations from the system design file for this configuration.

Returns
  • std::vector< ParameterConfiguration >

SensorConfiguration::getIoConfigurations ( ) const

This will get a list of IOConfiguration objects associated with this SensorConfiguration.

Returns
  • std::vector< IOConfiguration >

SensorConfiguration::getNodeId ( ) const

An accessor to private data.

This will return the primary key in the system design file for the parent NodeConfiguration.

Returns
  • unsigned long

SensorConfiguration::getSensorTypeId ( ) const

An accessor to private data.

This will return a ps_sensor_kind value for the sensor represented by this configuration.

Returns

SensorConfiguration::setNodeId ( … )

A mutator to private data.

This will set the value for the parent NodeConfiguration primary key in the system design file.

Parameters
in/out type name description
in unsigned long parentId Primary key value to node configuration.

SensorConfiguration::setSensorTypeId ( … )

A mutator to private data.

This will set the value sensor type represented by this configuration. For example PSYNC_SENSOR_KIND_UNKNOWN.

Parameters
in/out type name description
in ps_sensor_kind sensorTypeId PolySync sensor type value.

NodeConfiguration

This function will implement a Configuration interface.

Please see link for override member function information.

NodeConfiguration::NodeConfiguration ( )

An empty constructor.

This function will use a default PolySync system design file path for CRUD operations.

NodeConfiguration::NodeConfiguration ( … )

A constructor.

This will use a polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to
determine file path to system design file.

NodeConfiguration::NodeConfiguration ( … )

A copy constructor.

Parameters
in/out type name description
in const NodeConfiguration & objectToCopy
Existing object to copy from.

NodeConfiguration::NodeConfiguration ( … )

A C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_node_configuration & cStructToCopy Existing object to copy from.

virtual NodeConfiguration::~NodeConfiguration ( )

A destructor.

NodeConfiguration::getParameterConfigurations ( ) const

An accessor to private data.

This function will return a list of parameter configurations from the system design file for this configuration.

Returns
  • std::vector< ParameterConfiguration >

NodeConfiguration::getSensorConfigurations ( ) const

This will get a list of SensorConfiguration objects associated with this NodeConfiguration.

Returns
  • std::vector< SensorConfiguration >

NodeConfiguration::isEnabled ( ) const

An accessor to private data.

This will return the primary key in the system design file for the parent NodeConfiguration.

Returns
  • bool - True if host is enabled, meaning that it is active on the PolySync runtime

NodeConfiguration::getHostId ( ) const

An accessor to private data. This will return the primary key in the system design file for the parent HostConfiguration.

Returns
  • unsigned long

NodeConfiguration::setEnabled ( … )

A mutator to private data.

This function will turn on this node configuration in the PolySync context.

Parameters
in/out type name description
in bool enabled Boolean == true to enable.
Returns
  • void

NodeConfiguration::setHostId ( … )

A mutator to private data.

This will set the value for the parent HostConfiguration primary key in the system design file.

Parameters
in/out type name description
in unsigned long hostId Primary key value to host configuration.
Returns
  • void

HostConfiguration

This will implement a configuration interface.

Please see link for override member function information.

HostConfiguration::HostConfiguration ( )

An empty constructor.

This uses a default PolySync system design file path for CRUD operations.

HostConfiguration::HostConfiguration ( … )

A constructor. This function will use a polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to
determine file path to system design file.

HostConfiguration::HostConfiguration ( … )

A copy constructor.

Parameters
in/out type name description
in const HostConfiguration & objectToCopy
Existing object to copy from.

HostConfiguration::HostConfiguration ( … )

A C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_host_configuration & cStructToCopy Existing object to copy from.

virtual HostConfiguration::~HostConfiguration ( )

A destructor.

HostConfiguration::readByInterface ( … )

This function will populate the HostConfiguration object from a given IP address (Linux).

Parameters
in/out type name description
in std::string interfaceAddress IP address (Linux) string where host is located.
in unsigned int autoFill Default value == 1. The default recursively populates child node configurations values.
Returns
  • void
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_CONFIG - Retrieval failed due to a SQL error

HostConfiguration::getParameterConfigurations ( ) const

An accessor to private data.

This will return a list of parameter configurations from the system design file for this configuration.

Returns
  • std::vector< ParameterConfiguration >

HostConfiguration::getNodeConfigurations ( ) const

This function will get a list of NodeConfiguration objects associated with the HostConfiguration.

Returns
  • std::vector< NodeConfiguration >

HostConfiguration::getInterfaceAddress ( ) const

An accessor to private data.

This will return an IP address (Linux) as a string.

Returns
  • std::string

HostConfiguration::getLicenseFile ( ) const

An accessor to private data.

This will return a system file path to PolySync license file.

Returns
  • std::string

HostConfiguration::getRnrBaseDirectory ( ) const

An accessor to private data.

This function will return a string file path to the directory containing PolySync log files.

Returns
  • std::string

HostConfiguration::getRuntimeConfigurationId ( ) const

An accessor to private data.

This function will return the primary key in the system design file for the parent RuntimeConfiguration.

Returns
  • unsigned long

HostConfiguration::isEnabled ( ) const

An accessor to private data.

This function will return the primary key in the system design file for the parent RuntimeConfiguration.

Returns
  • bool - True if host is enabled, meaning that it is active on the PolySync runtime

HostConfiguration::setEnabled ( … )

A mutator to private data.

This function will turn on this host configuration in the PolySync context.

Parameters
in/out type name description
in bool enabled Boolean == true to enable.
Returns
  • void

HostConfiguration::setRuntimeConfigurationId ( … )

This will set the primary key for a RuntimeConfiguration parent to associate with this host configuration.

Parameters
in/out type name description
in unsigned long parentId Primary key in system design file for parent configuration.
Returns
  • void

HostConfiguration::setInterfaceAddress ( … )

A mutator for private data.

This will set the interface address for this host configuration.

Parameters
in/out type name description
in std::string interfaceAddress IP address string (Linux).
Returns
  • void

HostConfiguration::setLicenseFile ( … )

A mutator to private data.

This will set the path to the PolySync license file.

Parameters
in/out type name description
in std::string filePath Path to PolySync license file.
Returns
  • void

HostConfiguration::setRnrBaseDirectory ( … )

A mutator to private data.

This will set the path to the PolySync log files.

Parameters
in/out type name description
in std::string filePath Path to PolySync log files.
Returns
  • void

RuntimeConfiguration

This will implement a Configuration interface.

Please see link for override member function information.

RuntimeConfiguration::RuntimeConfiguration ( )

An empty constructor.

This function uses a default PolySync system design file path for CRUD operations.

RuntimeConfiguration::RuntimeConfiguration ( … )

A constructor.

This function uses a polysync::Node reference system design file path for CRUD operations.

Parameters
in/out type name description
in const polysync::Node & node Node reference used to
determine file path to system design file.

RuntimeConfiguration::RuntimeConfiguration ( … )

A copy constructor.

Parameters
in/out type name description
in const RuntimeConfiguration & objectToCopy
Existing object to copy from.

RuntimeConfiguration::RuntimeConfiguration ( … )

A C type copy constructor.

Parameters
in/out type name description
in const ps_sdf_runtime_configuration & cStructToCopy Existing object to copy from.

virtual RuntimeConfiguration::~RuntimeConfiguration ( )

A destructor.

RuntimeConfiguration::getParameterConfigurations ( ) const

An accessor to private data.

This will return a list of parameter configurations from the system design file for this configuration.

Returns
  • std::vector< ParameterConfiguration >

RuntimeConfiguration::getHostConfigurations ( ) const

This will get a list of HostConfiguration objects associated with this RuntimeConfiguration.

Returns
  • std::vector< HostConfiguration >

RuntimeConfiguration::getDomainId ( ) const

An accessor to private data.

This will represent the domain identifier for this runtime.

Returns
  • unsigned long

RuntimeConfiguration::getApiVersion ( ) const

An accessor to private data.

This will return a string value with PolySync version information.

Returns
  • std::string

RuntimeConfiguration::setApiVersion ( … )

A mutator to private data.

This function will return a string value with PolySync version information.

Parameters
in/out type name description
in std::string version PolySync version string.
Returns
  • std::string