DeviceClient

class DeviceClient : public std::enable_shared_from_this<DeviceClient>

@brief This class can be used to (remotely) control devices of the distributed system Synchronous calls (i.e. get()) are in fact asynchronous under the hood

The Karabo DeviceClient provides a high-level interface for common calls to (remote) devices in the distributed system. In principle functionality implemented in the DeviceClient can be fully implemented in the Device using low level SignalSlotable calls alone, but device developers are discouraged from this approach, especially if synchronous behavior is acceptable or even desired.

In the context of a Device the DeviceClient is available using the Device::remote() function; it then shares the SignalSlotable instance of the device, e.g. there is no instantiation overhead.

Types

Name	Description
InputChannelHandlers	Container of handlers for InputChannel, to be passed to bool registerChannelMonitor(const std::string& channelName, const InputChannelHandlers& handlers, const karabo::data::Hash& inputChannelCfg = karabo::data::Hash()); See documentation of that method for meaning of various handlers.

Type Aliases

Name	Description
SignalChangedMap	keys are instance IDs, values are a sets of properties that changed
InstanceUsage	Map of devices that we are connected to with timer stating their age since last access.

Variables

Name	Description
m_runtimeSystemDescription	server + type host version status deviceClasses + classes + + description SCHEMA configuration HASH description SCHEMA configuration HASH device + type host version status classId serverId + fullSchema => SCHEMA configuration => HASH activeSchema + => SCHEMA
m_devicesChangesHandler	Handler for all monitored devices configuration updates during last interval.
m_signalsChangedTimer	defines whether aging is running or not
m_loggerMapMutex	map of collected signalChanged

Functions

Name	Description
DeviceClient	Constructor which establishes an own connection to the communication system.
DeviceClient	Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer) signalSlotable : An instance of the SignalSlotable lass implicitInit : If true (default for backward compatibility - but NOT recommended!), the constructor will implicitly try to trigger a call to initialize() via the event loop. Since this can fail silently, it is strongly recommended to use implicitInit = false and call the initialize() method right after the constructor. serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported.
DeviceClient	Constructor aimed at cases where a specific DataLoggerManagerId is required.
DeviceClient	Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer) and aimed at cases where a specific DataLoggerManagerId is required.
initialize	Second constructor.
getInstanceId	InstanceId of underlying communication object (i.e. SignalSlotable)
setInternalTimeout	Sets the internal timeout for any request/response like communications internalTimeout : The default timeout in ms
getInternalTimeout	Retrieves the currently set internal timeout Return : default timeout in ms
setAgeing	Set ageing on or off (on by default) Return :
setDeviceMonitorInterval	Set interval to wait between subsequent (for the same instance) calls to handlers registered via registerDeviceMonitor.
exists	Allows asking whether an instance is online in the current distributed system boolean : indicating whether existing and hostname if exists Return :
enableInstanceTracking	Enables tracking of new and departing device instances The handlers registered with registerInstance[New
getSystemInformation	Returns the full information about the current (runtime) distributed system Return : a Hash containing the full system description
getSystemTopology	Returns only the topology of the current system (no instance configurations or descriptions) Return : Hash containing the topology of the runtime system
getServers	Retrieves all servers currently existing in the distributed system Return : array of server ids
getClasses	Retrieves all device classes (plugins) available on a given device server deviceServer : device server id Return : array of device classes
getDevices	Retrieves all devices (instances) available on a given device server deviceServer : device server id Return : array of device instanceIds
getDevices	Retrieves all devices in the distributed system.
getDeviceSchema	Retrieves the full Schema (parameter description) of the given instance; instanceId : Device's instance ID Return : full Schema
getDeviceSchemaNoWait	Retrieves the full Schema (parameter description) of the given instance The call is non-blocking, if no Schema is currently available the return will be empty.
getActiveSchema	Retrieves the currently active Schema (filtered by allowed states and allowed roles) of the given instance instanceId : Device's instance ID Return : active Schema
getClassSchema	Retrieves a schema from static context of a loaded Device class plug-in.
getClassSchemaNoWait	Retrieves a schema from static context of a loaded Device class plug-in.
getProperties	Retrieve the properties of a device at deviceId.
getClassProperties	Retrieve the properties of a class loaded on a server serverId : server to request information from classId : of the class Return : vector containing the property paths of the class
getCurrentlyExecutableCommands	Retrieve a list of commands that may be currently executed on a device in the distributed system.
getCurrentlySettableProperties	Retrieve a list of properties that may be currently altered on a device in the distributed system.
loadConfigurationFromFile	Load a device configuration from a file filename : Return : a Hash containing the configuration
instantiate	Attempt to instantiate a device of the specified class, on a remote server with a given initial configuration serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available classId : of the device to be instantiate configuration : Hash which contains the initial device configuration. It must have one out of the two following forms: option 1: - key "classId" pointing to a string, option 2: - no classId specified: class id to be instantiated is taken from classId parameter option 3 (for backward compatibility - not recommended): - a single key (e.g. "myClassId") representing the classId - the value for this key is a Hash with all the non-default properties timeoutInSeconds : by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been instantiated. Return : (ok, reply) pair where ok is true if no exception occurred and reply is the answer received from server
instantiate	Instantiate a device on a remote server serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available configuration : Hash which contains the initial device configuration. The 'classId' attribute must be present. timeoutInSeconds : by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been instantiated. Return :
formatConfigToInstantiate	Utility method that takes care of adding classId to configuration of device to be instantiated by instantiate and instantiateNoWait.
instantiateNoWait	Instantiate a device on a remote server.
instantiateNoWait	Instantiate a device on a remote server.
killDevice	Kill a device in the distributed system and wait until it is actually dead deviceId : of the device to kill timeoutInSeconds : timeoutInSeconds by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been killed. Return :
killDeviceNoWait	Kill a device in the distributed system and return immediately deviceId : of the device to kill Return :
killServer	Kill a device server in the distributed system and all its associated devices.
killServerNoWait	Kill a device server in the distributed system and all its associated devices.
get	Return the configuration Hash of an instance.
get	Return the configuration Hash of an instance.
getConfigurationNoWait	Return the cached configuration if it is still valid, otherwise query an updated version but return an empty Hash.
hasAttribute	Check if an attribute exists for a property on a given instance instanceId : to check on key : path to the property to check if it has a given attribute attribute : to check for keySep : path separator Return : a boolean indicating if the attribute is present
get	Return a property from a remote instance.
get	Return a property from a remote instance.
getAs	Return a property from a remote instance casted to the template type.
getAsAny	Return a property from a remote instance as a std::any value. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query. instanceId : to retrieve the property from key : identifying the property keySep : path separator Return : the current property value on the remote device as std::any type
cacheLoggerMap	Toggles caching of the DataLogger map on (true) and off (false).
getFromPast	Returns the history of a device property for a given period of time deviceId : of the device holding the property key : path to the property on the device from : karabo::data::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from to : karabo::data::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now maxNumData : maximum number of data points to retrieve, starting from the start of the interval Return : a vector of Hashes holding the property's history. Each entry consists of a Hash with a key "v" holding the value of the appropriate type. For each entry "v" Karabo train and timestamp attributes are set which can be retrieved using the karabo::data::Timestamp::fromHashAttributes method.
getPropertyHistory	Returns the history of a device property for a given period of time deviceId : of the device holding the property key : path to the property on the device from : karabo::data::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from to : karabo::data::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now maxNumData : maximum number of data points to retrieve, starting from the start of the interval Return : a vector of Hashes holding the property's history. Each entry consists of a Hash with a key "v" holding the value of the appropriate type. For each entry "v" Karabo train and timestamp attributes are set which can be retrieved using the karabo::data::Timestamp::fromHashAttributes method.
getDataLogReader	Returns instanceId of data log reader for data of given device.
getConfigurationFromPast	Returns the device configuration and corresponding schema for a given point in time.
listConfigurationFromName	Returns the configurations saved for a device under names that contain a given name part.
getConfigurationFromName	Returns the configuration and schema saved for a device under a given name.
getLastConfiguration	Returns the most recently saved configuration for a device that has a given priority.
saveConfigurationFromName	Saves a collection of current device configurations (and the corresponding schemas) in the configuration database under a common name, user, priority and description.
registerInstanceChangeMonitor	Register a throttled callback handler to be triggered when a new device instance appears, updates its instance info record or goes away in the distributed system.
flushThrottledInstanceChanges	Flushes, asap, the throttled instance changes that are waiting to be dispatched.
registerInstanceNewMonitor	Register a callback handler to be triggered if a new instance appears in the distributed system.
registerInstanceUpdatedMonitor	Register a callback handler to be triggered if an instance receives a state update from the distributed system callBackFunction : which will receive the instanceInfo Hash
registerInstanceGoneMonitor	Register a callback handler to be triggered if an instance disappears from the distributed system callBackFunction : receiving the instanceId and instanceInfo Hash
registerSchemaUpdatedMonitor	Register a callback handler to be triggered if an instance receives a schema update from the distributed system callBackFunction : receiving the instanceId and updated Schema !!! note Currently, registering only a schema update monitor with an instance of a DeviceClient is not enough to have the registered call-back activated. A workaround for this is to also register a property monitor with the same instance of DeviceClient that has been used to register the schema update monitor. Example: DeviceClient dc = std::shared_ptr(new DeviceClient()); dc->registerSchemaUpdateMonitor(fnSchemaUpdateHandler); dc->registerPropertyMonitor("deviceId", "property_to_monitor", fnCallback);
registerClassSchemaMonitor	Register a callback handler to be triggered if a new class appears on a device server callBackFunction : receiving the server id, class id and new class Schema
registerPropertyMonitor	Register a callback function to be triggered when a given property on a device in the distributed system updates instanceId : of the device to be monitored key : path to the property to be monitored callbackFunction : handling the update notification. It receives the device id, path, value and timestamp of the updated property Return : true if the operation was successful
registerPropertyMonitor	Register a callback function to be triggered when a given property on a device in the distributed system updates.
unregisterPropertyMonitor	Unregister a property monitor instanceId : to unregister the monitor from key : path to the property to unregister from.
registerDeviceMonitor	Register a callback function to be triggered when a a device in the distributed system updates.
registerDeviceForMonitoring	Registers a device to have its configurations changes monitored.
registerDevicesMonitor	Registers a handler for configuration changes for any of the monitored devices.
unregisterDeviceFromMonitoring	Unregisters a device from configuration changes monitoring.
registerDeviceMonitor	Register a callback function to be triggered when a a device in the distributed system updates.
unregisterDeviceMonitor	Unregister a device monitor.
registerChannelMonitor	Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).
registerChannelMonitor	Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).
registerChannelMonitor	Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).
unregisterChannelMonitor	Unregister monitoring of output channel instanceId : of the device having the output channel channel : is name of the output channel Return : false if channel was not registered
unregisterChannelMonitor	Unregister monitoring of output channel channelName : identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output) Return : false if channel was not registered
set	Set a remote property in the distributed system instanceId : of the device to set the property on key : path to the property to set value : to set timeoutInSeconds : maximum timeout until set operation fails, set to -1 to wait forever keySep : path separator
setNoWait	Set a remote property in the distributed system as a fire-and-forget operation.
set	Bulk-set remote properties in the distributed system instanceId : of the device to set the property on values : a Hash containing the to be set value in a path structure indicating which properties to set timeoutInSeconds : maximum timeout until set operation fails, set to -1 to wait forever
setNoWait	Bulk-set remote properties in the distributed system as a fire-and-forget operation.
executeNoWait	Executes a function on a device (an exposed via its Schema) and immediately returns (fire & forget) deviceId : The deviceId command : Name of the command
execute	@brief Executes a function on a device synchronously (waits until the function finished) Args : Variadic template for the slot args (no arg is a particular case). deviceId : The devideId command : The command timeoutInSeconds : Timeout
execute1	@brief Synchronously executes a slot that returns a single element response.
execute2	@brief Synchronously executes a slot that returns a two element tuple as a response.
execute3	@brief Synchronously executes a slot that returns a three element tuple as a response.
execute4	@brief Synchronously executes a slot that returns a four element tuple as a response.
getOutputChannelSchema	Request the data schema for an output channel as a Hash containing relevant information deviceId : outputChannelName : Return : a Hash containing the output channel's data schema
getOutputChannelNames	Get the list of all output channel names of the remote device.
lock	Request locking of device at deviceId.
prepareTopologyEntry	Prepare a topology entry for the runtime system description path : the path created with prepareTopologyPath using instanceId and instanceInfo instanceInfo : The instanceInfo Hash received from the broadcast
mortalize	Unmark deviceId from staying connected all the time without ageing.
eraseFromRuntimeSystemDescription	returns true if path could be removed
getSectionFromRuntimeDescription	Get section (e.g. "device") from runtime description. Returns empty Hash if section does not exist.
findInstanceSafe	Find full path of 'instanceId' in m_runtimeSystemDescription, empty if path does not exist.
findInstance	As findInstanceSafe, but to be called under protection of m_runtimeSystemDescriptionMutex.
doSendSignalsChanged	Actually process data in 'signalChangedMap' - try/catch should be outside.
connectNeeded	Marks 'instanceId' as used.
initServiceDeviceIds	@brief Internal helper method to initialize the service device ids members of the DeviceClient instance.
findAndEraseDevicesAsGone	Helper for _slotInstanceGone for servers Finds all devices that belong to given server, removes them from m_runtimeSystemDescription and returns pairs of their deviceIds and instanceInfo.
treatInstanceAsGone	Helper for _slotInstanceGone Does all needed action - despite of removal from m_runtimeSystemDescription - and despite of special treatment of devices on the server if instance is a server

Type Alias Details

InstanceUsage

typedef std::map<std::string, int> InstanceUsage

Map of devices that we are connected to with timer stating their age since last access. Before C++14 not an unordered_map since we want to erase while looping over it

SignalChangedMap

typedef std::map<std::string, std::set<std::string>> SignalChangedMap

keys are instance IDs, values are a sets of properties that changed

Variable Details

m_devicesChangesHandler

DevicesChangedHandler m_devicesChangesHandler

Handler for all monitored devices configuration updates during last interval.

m_loggerMapMutex

std::mutex m_loggerMapMutex

map of collected signalChanged

m_runtimeSystemDescription

karabo::data::Hash m_runtimeSystemDescription

server + type host version status deviceClasses + classes + + description SCHEMA configuration HASH description SCHEMA configuration HASH

device + type host version status classId serverId + fullSchema => SCHEMA configuration => HASH activeSchema + => SCHEMA

m_signalsChangedTimer

boost::asio::steady_timer m_signalsChangedTimer

defines whether aging is running or not

Function Details

DeviceClient

explicit DeviceClient(const std::string& instanceId = std::string(), bool implicitInit = true, const karabo::data::Hash& serviceDeviceIds = karabo::data::Hash())

Constructor which establishes an own connection to the communication system. This constructor is intended for stand-alone C++ device clients. Once we care about authentication, this has to be added here.

instanceId : The id with which the client should participate in the system. If not unique or invalid, constructor will throw an exception. If empty (i.e. default), an id will be generated from host name and process id.

implicitInit : If true (default for backward compatibility - but NOT recommended!), the constructor will implicitly try to trigger a call to initialize() via the event loop. Since this can fail silently, it is strongly recommended to use implicitInit = false and call the initialize() method right after the constructor.

serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported.

explicit DeviceClient(const std::shared_ptr<karabo::xms::SignalSlotable>& signalSlotable, bool implicitInit = true, const karabo::data::Hash& serviceDeviceIds = karabo::data::Hash())

Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer)

signalSlotable : An instance of the SignalSlotable lass

implicitInit : If true (default for backward compatibility - but NOT recommended!), the constructor will implicitly try to trigger a call to initialize() via the event loop. Since this can fail silently, it is strongly recommended to use implicitInit = false and call the initialize() method right after the constructor.

serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported.

DeviceClient(const std::string& instanceId, const karabo::data::Hash& serviceDeviceIds)

Constructor aimed at cases where a specific DataLoggerManagerId is required. Requires an explicit call to DeviceClient::initialize() after the construction takes place.

instanceId : The id with which the client should participate in the system. If not unique or invalid, constructor will throw an exception. If empty, an id will be generated from host name and process id.

serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported.

DeviceClient(const std::shared_ptr<karabo::xms::SignalSlotable>& signalSlotable, const karabo::data::Hash& serviceDeviceIds)

Constructor using instantiated signalSlotable object (shared communication - take care that the signalSlotable is kept alive since the DeviceClient will only keep a weak pointer) and aimed at cases where a specific DataLoggerManagerId is required. Requires an explicit call to DeviceClient::initialize() after the construction takes place.

signalSlotable : An instance of the SignalSlotable lass

serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported.

cacheLoggerMap

bool cacheLoggerMap(bool toggle)

Toggles caching of the DataLogger map on (true) and off (false). If set to true the logger map is always kept up to date, which speeds up repeated calls to DeviceClient::getProperyHistory.

toggle :

Return : true if operation was successful

connectNeeded

bool connectNeeded(const std::string& instanceId)

Marks 'instanceId' as used. Returns true if explicit "connect" call should still be done for it.

doSendSignalsChanged

void doSendSignalsChanged(const SignalChangedMap& signalChangedMap)

Actually process data in 'signalChangedMap' - try/catch should be outside.

enableInstanceTracking

void enableInstanceTracking()

Enables tracking of new and departing device instances

The handlers registered with registerInstance[New|Gone|Updated]Monitor will be called accordingly. If the handler for instanceNew is registered before calling this method, it will be called for each device currently in the system.

NOTE: Use wisely! There is a performance cost to tracking all devices since it means subscribing to the heartbeats of all servers and devices in the system.

eraseFromRuntimeSystemDescription

bool eraseFromRuntimeSystemDescription(const std::string& path)

returns true if path could be removed

execute

template <typename... Args> void execute(const std::string& deviceId, const std::string& command, int timeoutInSeconds = 3, const Args&... slotArgs)

@brief Executes a function on a device synchronously (waits until the function finished)

Args : Variadic template for the slot args (no arg is a particular case).

deviceId : The devideId

command : The command

timeoutInSeconds : Timeout

execute1

template <typename R1, typename... Args> R1 execute1(const std::string& deviceId, const std::string& slotName, int timeoutInSeconds = 3, const Args&... slotArgs)

@brief Synchronously executes a slot that returns a single element response.

R1 : Type of the response.

Args : Variadic template for the slot arguments.

deviceId : Id of the device whose slot should be executed.

slotName : Name of the slot to execute.

timeoutInSeconds : Timeout for the slot execution.

slotArgs : Slot arguments.

Return : A value of R1 type

execute2

template <typename R1, typename R2, typename... Args> std::tuple<R1, R2> execute2(const std::string& deviceId, const std::string& slotName, int timeoutInSeconds = 3, const Args&... slotArgs)

@brief Synchronously executes a slot that returns a two element tuple as a response.

Note

a tuple, instead of a pair, is used as the return value for uniformity with the other executeN methods.

R1 : Type of first element of the resulting pair.

R2 : Type of second element of the resulting pair.

Args : Variadic template for the slot arguments.

deviceId : Id of the device whose slot should be executed.

slotName : Name of the slot to execute.

timeoutInSeconds : Timeout for the slot execution.

slotArgs : Slot arguments.

Return : std::tuple with the results of the slot execution.

execute3

template <typename R1, typename R2, typename R3, typename... Args> std::tuple<R1, R2, R3> execute3(const std::string& deviceId, const std::string& slotName, int timeoutInSeconds = 3, const Args&... slotArgs)

@brief Synchronously executes a slot that returns a three element tuple as a response.

R1 : Type of first element of the resulting tuple.

R2 : Type of second element of the resulting tuple.

R3 : Type of third element of the resulting tuple.

Args : Variadic template for the slot arguments.

deviceId : Id of the device whose slot should be executed.

slotName : Name of the slot to execute.

timeoutInSeconds : Timeout for the slot execution.

slotArgs : Slot arguments.

Return : std::tuple Tuple with the results of the slot execution.

execute4

template <typename R1, typename R2, typename R3, typename R4, typename... Args> std::tuple<R1, R2, R3, R4> execute4(const std::string& deviceId, const std::string& slotName, int timeoutInSeconds = 3, const Args&... slotArgs)

@brief Synchronously executes a slot that returns a four element tuple as a response.

R1 : Type of first element of the resulting tuple.

R2 : Type of second element of the resulting tuple.

R3 : Type of third element of the resulting tuple.

R4 : Type of fourth element of the resulting tuple.

Args : Variadic template for the slot arguments.

deviceId : Id of the device whose slot should be executed.

slotName : Name of the slot to execute.

timeoutInSeconds : Timeout for the slot execution.

slotArgs : Slot arguments.

Return : std::tuple Tuple with the results of the slot execution.

executeNoWait

void executeNoWait(const std::string& deviceId, const std::string& command)

Executes a function on a device (an exposed via its Schema) and immediately returns (fire & forget)

deviceId : The deviceId

command : Name of the command

exists

std::pair<bool, std::string> exists(const std::string& instanceId)

Allows asking whether an instance is online in the current distributed system

boolean : indicating whether existing and hostname if exists

Return :

findAndEraseDevicesAsGone

std::vector<std::pair<std::string, karabo::data::Hash>> findAndEraseDevicesAsGone( const std::string& serverId)

Helper for _slotInstanceGone for servers

Finds all devices that belong to given server, removes them from m_runtimeSystemDescription and returns pairs of their deviceIds and instanceInfo. Requires protection of m_runtimeSystemDescriptionMutex.

findInstance

std::string findInstance(const std::string& instanceId) const

As findInstanceSafe, but to be called under protection of m_runtimeSystemDescriptionMutex.

findInstanceSafe

std::string findInstanceSafe(const std::string& instanceId) const

Find full path of 'instanceId' in m_runtimeSystemDescription, empty if path does not exist.

flushThrottledInstanceChanges

void flushThrottledInstanceChanges()

Flushes, asap, the throttled instance changes that are waiting to be dispatched.

formatConfigToInstantiate

karabo::data::Hash formatConfigToInstantiate(const std::string& classId, const karabo::data::Hash& configuration)

Utility method that takes care of adding classId to configuration of device to be instantiated by instantiate and instantiateNoWait. If configuration does not have 'classId' key, this is added, with the value of classId parameter. Otherwise the configuration 'classId' value is used. In the latter case, if the value of classId parameter mismatches the one of 'classId' attribute of configuration a warning is thrown.

classId : of the device to be instantiated.

configuration : of the device to be instantiated.

Return : configuration ready to be sent to device server

get

karabo::data::Hash get(const std::string& instanceId)

Return the configuration Hash of an instance. The configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : for which to return the configuration of

Return : a Hash holding the instance configuration

void get(const std::string& instanceId, karabo::data::Hash& hash)

Return the configuration Hash of an instance. The configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : for which to return the configuration of

hash : reference to write configuration into

template <class T> T get(const std::string& instanceId, const std::string& key, const char keySep = data::Hash::k_defaultSep)

Return a property from a remote instance. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : to retrieve the property from

key : identifying the property

keySep : path separator

Return : the current property value on the remote device @raise TypeException if the templated type does not match the property type.

template <class T> void get(const std::string& instanceId, const std::string& key, T& value, const char keySep = data::Hash::k_defaultSep)

Return a property from a remote instance. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : to retrieve the property from

key : identifying the property

value : reference to write the property value to

keySep : path separator @raise TypeException if the templated type does not match the property type.

getActiveSchema

karabo::data::Schema getActiveSchema(const std::string& instanceId)

Retrieves the currently active Schema (filtered by allowed states and allowed roles) of the given instance

instanceId : Device's instance ID

Return : active Schema

getAs

template <class T> T getAs(const std::string& instanceId, const std::string& key, const char keySep = data::Hash::k_defaultSep)

Return a property from a remote instance casted to the template type. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : to retrieve the property from

key : identifying the property

keySep : path separator

Return : the current property value on the remote device @raise TypeException if the property cannot be casted to the template type

getAsAny

std::any getAsAny(const std::string& instanceId, const std::string& key, const char keySep = data::Hash::k_defaultSep)

Return a property from a remote instance as a std::any value. The instance configuration is internally cached, so it does not necessarily result in a query to the distributed system if the device configuration has not changed since the last query.

instanceId : to retrieve the property from

key : identifying the property

keySep : path separator

Return : the current property value on the remote device as std::any type

getClassProperties

std::vector<std::string> getClassProperties(const std::string& serverId, const std::string& classId)

Retrieve the properties of a class loaded on a server

serverId : server to request information from

classId : of the class

Return : vector containing the property paths of the class

getClassSchema

karabo::data::Schema getClassSchema(const std::string& serverId, const std::string& classId)

Retrieves a schema from static context of a loaded Device class plug-in. This schema represents a description of parameters possible to configure for instantiation. I.e. returns in fact a description of the constructor arguments to that device class.

serverId : instanceId of a deviceServer

classId : name of loaded class on the deviceServer (classId)

Return : Schema describing parameters available at instantiation time

getClassSchemaNoWait

karabo::data::Schema getClassSchemaNoWait(const std::string& serverId, const std::string& classId)

Retrieves a schema from static context of a loaded Device class plug-in. This schema represents a description of parameters possible to configure for instantiation. This function can be used to pre-cache a schema for later usage. It returns an empty schema.

serverId : instanceId of a deviceServer

classId : name of loaded class on the deviceServer (classId)

Return : an empty schem

getClasses

std::vector<std::string> getClasses(const std::string& deviceServer)

Retrieves all device classes (plugins) available on a given device server

deviceServer : device server id

Return : array of device classes

getConfigurationFromName

karabo::data::Hash getConfigurationFromName(const std::string& deviceId, const std::string& name)

Returns the configuration and schema saved for a device under a given name.

deviceId : of the device whose named configuration and schema should be returned.

name : of the device configuration and schema to be returned.

Return : a hash with the operation execution status and the device configuration and schema in case of success. For the operation execution status, the returned hash has the keys "success" with a boolean value that indicates whether the the operation was successful and a key "reason" with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key "config" whose value will be a hash with the keys "name", "timepoint", "description", "priority", "user", "config" and "schema" when a device configuration with the given name is found or an empty hash in case of failure or when no device configuration with the given name exists.

getConfigurationFromPast

std::pair<karabo::data::Hash, karabo::data::Schema> getConfigurationFromPast(const std::string& deviceId, const std::string& timepoint)

Returns the device configuration and corresponding schema for a given point in time. Information for the nearest matching logged time is returned.

deviceId : of the device to return the configuration for

timepoint : to return information for. Should be an iso8601 formatted string.

Return : a pair of the configuration Hash and corresponding device Schema

getConfigurationNoWait

karabo::data::Hash getConfigurationNoWait(const std::string& deviceId)

Return the cached configuration if it is still valid, otherwise query an updated version but return an empty Hash.

deviceId : for which to return the configuration of

Return : a Hash holding the instance configuration

getCurrentlyExecutableCommands

std::vector<std::string> getCurrentlyExecutableCommands(const std::string& instanceId)

Retrieve a list of commands that may be currently executed on a device in the distributed system. Available commands are determined by device state and access rights.

instanceId : of the device to ask for available commands

Return : a vector containing the slot names of the commands that can be executed

getCurrentlySettableProperties

std::vector<std::string> getCurrentlySettableProperties(const std::string& instanceId)

Retrieve a list of properties that may be currently altered on a device in the distributed system. Available properties are determined by device state and access rights.

instanceId : of the device to ask for settable properties

Return : a vector containing the slot names of the properties that can be altered.

getDataLogReader

std::string getDataLogReader(const std::string& deviceId)

Returns instanceId of data log reader for data of given device. Could be empty.

deviceId :

Return :

getDeviceSchema

karabo::data::Schema getDeviceSchema(const std::string& instanceId)

Retrieves the full Schema (parameter description) of the given instance;

instanceId : Device's instance ID

Return : full Schema

getDeviceSchemaNoWait

karabo::data::Schema getDeviceSchemaNoWait(const std::string& instanceId)

Retrieves the full Schema (parameter description) of the given instance The call is non-blocking, if no Schema is currently available the return will be empty. However, the schema request will be sent and should lead to later arrival of a schema.

instanceId : Device's instance ID

Return : full Schema

getDevices

std::vector<std::string> getDevices(const std::string& deviceServer)

Retrieves all devices (instances) available on a given device server

deviceServer : device server id

Return : array of device instanceIds

std::vector<std::string> getDevices()

Retrieves all devices in the distributed system.

Return : array of device instanceIds

getFromPast

std::vector<karabo::data::Hash> getFromPast(const std::string& deviceId, const std::string& key, const std::string& from, std::string to = "", int maxNumData = 0)

Returns the history of a device property for a given period of time

deviceId : of the device holding the property

key : path to the property on the device

from : karabo::data::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from

to : karabo::data::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now

maxNumData : maximum number of data points to retrieve, starting from the start of the interval

Return : a vector of Hashes holding the property's history. Each entry consists of a Hash with a key "v" holding the value of the appropriate type. For each entry "v" Karabo train and timestamp attributes are set which can be retrieved using the karabo::data::Timestamp::fromHashAttributes method.

getInstanceId

const std::string& getInstanceId()

InstanceId of underlying communication object (i.e. SignalSlotable)

getInternalTimeout

int getInternalTimeout() const

Retrieves the currently set internal timeout

Return : default timeout in ms

getLastConfiguration

karabo::data::Hash getLastConfiguration(const std::string& deviceId, int priority = 1)

Returns the most recently saved configuration for a device that has a given priority.

deviceId : of the device whose named configuration and schema should be returned.

priority : of the device configuration and schema to be returned.

Return : a hash with the operation execution status and the device configuration and schema in case of success. For the operation execution status, the returned hash has the keys "success" with a boolean value that indicates whether the the operation was successful and a key "reason" with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key "config" whose value will be a hash with the keys "name", "timepoint", "description", "priority", "user", "config" and "schema" when a device configuration with the given priority is found or an empty hash in case of failure or when no device configuration with the given priority exists.

getOutputChannelNames

std::vector<std::string> getOutputChannelNames(const std::string& deviceId)

Get the list of all output channel names of the remote device.

deviceId :

Return : vector containing output channel names

getOutputChannelSchema

karabo::data::Hash getOutputChannelSchema(const std::string& deviceId, const std::string& outputChannelName)

Request the data schema for an output channel as a Hash containing relevant information

deviceId :

outputChannelName :

Return : a Hash containing the output channel's data schema

getProperties

std::vector<std::string> getProperties(const std::string& deviceId)

Retrieve the properties of a device at deviceId.

deviceId : of the device to request information from

Return : a vector containing the property paths of the device

getPropertyHistory

std::vector<karabo::data::Hash> getPropertyHistory(const std::string& deviceId, const std::string& key, const std::string& from, std::string to = "", int maxNumData = 0)

Returns the history of a device property for a given period of time

deviceId : of the device holding the property

key : path to the property on the device

from : karabo::data::Epochstamp in Iso8601 format signifying the start of the time interval to get the history from

to : karabo::data::Epochstamp in Iso8601 format signifying the end of the time interval to get the history from. If left empty default to now

maxNumData : maximum number of data points to retrieve, starting from the start of the interval

Return : a vector of Hashes holding the property's history. Each entry consists of a Hash with a key "v" holding the value of the appropriate type. For each entry "v" Karabo train and timestamp attributes are set which can be retrieved using the karabo::data::Timestamp::fromHashAttributes method.

getSectionFromRuntimeDescription

data::Hash getSectionFromRuntimeDescription(const std::string& section) const

Get section (e.g. "device") from runtime description. Returns empty Hash if section does not exist.

getServers

std::vector<std::string> getServers()

Retrieves all servers currently existing in the distributed system

Return : array of server ids

getSystemInformation

karabo::data::Hash getSystemInformation()

Returns the full information about the current (runtime) distributed system

Return : a Hash containing the full system description

getSystemTopology

karabo::data::Hash getSystemTopology()

Returns only the topology of the current system (no instance configurations or descriptions)

Return : Hash containing the topology of the runtime system

hasAttribute

bool hasAttribute(const std::string& instanceId, const std::string& key, const std::string& attribute, const char keySep = data::Hash::k_defaultSep)

Check if an attribute exists for a property on a given instance

instanceId : to check on

key : path to the property to check if it has a given attribute

attribute : to check for

keySep : path separator

Return : a boolean indicating if the attribute is present

initServiceDeviceIds

void initServiceDeviceIds(const karabo::data::Hash& serviceDeviceIds)

@brief Internal helper method to initialize the service device ids members of the DeviceClient instance.

serviceDeviceIds : A hash with ids of core service devices; e.g, "dataLoggerManagerId" key and the value is the name of the DataLoggerManager the device client instance should use for data logging operations. Currently keys "dataLoggerManagerId" and "configurationManagerId" are supported. If a supported key is missing, the default ID for the service device type is used.

initialize

void initialize()

Second constructor. It is strongly recommended to use the constructors with implicitInit = false and explicitely call initialize() after the construction.

instantiate

std::pair<bool, std::string> instantiate(const std::string& serverInstanceId, const std::string& classId, const karabo::data::Hash& configuration = karabo::data::Hash(), int timeoutInSeconds = -1)

Attempt to instantiate a device of the specified class, on a remote server with a given initial configuration

serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available

classId : of the device to be instantiate

configuration : Hash which contains the initial device configuration. It must have one out of the two following forms: option 1: - key "classId" pointing to a string, option 2: - no classId specified: class id to be instantiated is taken from classId parameter option 3 (for backward compatibility - not recommended): - a single key (e.g. "myClassId") representing the classId - the value for this key is a Hash with all the non-default properties

timeoutInSeconds : by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been instantiated.

Return : (ok, reply) pair where ok is true if no exception occurred and reply is the answer received from server

std::pair<bool, std::string> instantiate(const std::string& serverInstanceId, const karabo::data::Hash& configuration, int timeoutInSeconds = -1)

Instantiate a device on a remote server

serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available

configuration : Hash which contains the initial device configuration. The 'classId' attribute must be present.

timeoutInSeconds : by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been instantiated.

Return :

instantiateNoWait

void instantiateNoWait(const std::string& serverInstanceId, const std::string& classId, const karabo::data::Hash& configuration = karabo::data::Hash())

Instantiate a device on a remote server. In contrast to DeviceClient::instantiate, this function returns immediately.

serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available

classId : of the device to be instantiate

configuration : Hash which contains the initial device configuration. It must have one out of the two following forms: option 1: - key "classId" pointing to a string, option 2: - no classId specified: class id to be instantiated is taken from classId parameter option 3 (for backward compatibility - not recommended): - a single key (e.g. "myClassId") representing the classId - the value for this key is a Hash with all the non-default properties

void instantiateNoWait(const std::string& serverInstanceId, const karabo::data::Hash& configuration)

Instantiate a device on a remote server. In contrast to DeviceClient::instantiate, this function returns immediately.

serverInstanceId : of the server to instantiate the device on. Needs to have the device plugin available

configuration : Hash which contains the initial device configuration. The 'classId' attribute must be present.

Return :

killDevice

std::pair<bool, std::string> killDevice(const std::string& deviceId, int timeoutInSeconds = -1)

Kill a device in the distributed system and wait until it is actually dead

deviceId : of the device to kill

timeoutInSeconds : timeoutInSeconds by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device hasn't been killed.

Return :

killDeviceNoWait

void killDeviceNoWait(const std::string& deviceId)

Kill a device in the distributed system and return immediately

deviceId : of the device to kill

Return :

killServer

std::pair<bool, std::string> killServer(const std::string& serverId, int timeoutInSeconds = -1)

Kill a device server in the distributed system and all its associated devices. Waits til the server is dead.

serverId : of the server to kill

timeoutInSeconds : timeoutInSeconds timeoutInSeconds by default set to -1, which means block indefinitely, if a positive value an Exception is thrown if the device server hasn't been killed.

Return :

killServerNoWait

void killServerNoWait(const std::string& serverId)

Kill a device server in the distributed system and all its associated devices. Returns immediately.

serverId : of the server to kill

Return :

listConfigurationFromName

karabo::data::Hash listConfigurationFromName(const std::string& deviceId, const std::string& namePart = "")

Returns the configurations saved for a device under names that contain a given name part.

deviceId : of the device whose named configuration(s) and schema(s) should be returned.

namePart : of the device configuration(s) and schema(s) to be returned. An empty namePart means returns all the named configuration(s) and schema(s)

Return : a hash with the operation execution status and the list of configuration(s) and schema(s) in case of success. For the operation execution status, the returned hash has the keys "success" with a boolean value that indicates whether the the operation was successful and a key "reason" with a string value that will contain the reason for failure or will be empty in the case of success. The returned hash will also have a key "configs" whose value will be a vector of hashes with data about the configs that match the name part. If no configuration is saved for the device under a name that contains the namePart, the "configs" vector will be empty. Each hash in the "configs" vector contains the keys "name", "timepoint".

loadConfigurationFromFile

karabo::data::Hash loadConfigurationFromFile(const std::string& filename)

Load a device configuration from a file

filename :

Return : a Hash containing the configuration

lock

karabo::core::Lock lock(const std::string& deviceId, bool recursive = false, int timeout = -1)

Request locking of device at deviceId. Throws a karabo::util::LockException in case the lock cannot be acquired in the given timeout

deviceId: : the device to be locked

recursive: : if true, recursive locks on this device are allowed

timeout: : timeout during which we try to acquire the lock. Set to -1 to wait try indefinitely, 0 to only try once, otherwise give integer seconds to wait.

Return : a Lock object, holding the lock to deviceId.

mortalize

void mortalize(const std::string& deviceId)

Unmark deviceId from staying connected all the time without ageing.

Also clears a zombie (marked by negative age) from m_instanceUsage and thus locks m_instanceUsageMutex. That means, unlike immortalize(..) and isImortal(..), mortalize(..) must not be called under protection of m_instanceUsageMutex.

prepareTopologyEntry

karabo::data::Hash prepareTopologyEntry(const std::string& path, const karabo::data::Hash& instanceInfo) const

Prepare a topology entry for the runtime system description

path : the path created with prepareTopologyPath using instanceId and instanceInfo

instanceInfo : The instanceInfo Hash received from the broadcast

registerChannelMonitor

bool registerChannelMonitor(const std::string& channelName, const InputChannelHandlers& handlers, const karabo::data::Hash& inputChannelCfg = karabo::data::Hash())

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS). Internally, an InputChannel is created and configured using the cfg Hash and its connection status can be monitored via the 'statusTracker' of the handlers argument

channelName : identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)

handlers : container for various handlers (handlers can be empty function pointers): - dataHandler std::function to be called whenever data arrives - inputHandler std::function to be called whenever data arrives - eosHandler std::function called for EOS - statusTracker std::function called whenever the connection status of the underlying InputChannel changes

inputChannelCfg : configures via InputChanel::create(..) - use default except you know what your are doing. For the expert: "connectedOutputChannels" will be overwritten

Return : false if channel is already registered

bool registerChannelMonitor(const std::string& instanceId, const std::string& channel, const karabo::xms::SignalSlotable::DataHandler& dataHandler, const karabo::data::Hash& inputChannelCfg = karabo::data::Hash(), const karabo::xms::SignalSlotable::InputHandler& eosHandler = karabo::xms::SignalSlotable::InputHandler(), const karabo::xms::SignalSlotable::InputHandler& inputHandler = karabo::xms::SignalSlotable::InputHandler())

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).

DEPRECATED - use interface with 'InputChannelHandlers' argument!

instanceId : of the device having the output channel

channel : is name of the output channel

dataHandler : std::function<void (const karabo::data::Hash&, const MetaData&) to be called whenever data arrives

inputChannelCfg : configures via InputChanel::create(..) - use default except you know what your are doing for the expert: "connectedOutputChannels" will be overwritten

eosHandler : std::function called for EOS if given

inputHandler : std::function to be called whenever data arrives

Return : false if channel is already registered

bool registerChannelMonitor(const std::string& channelName, const karabo::xms::SignalSlotable::DataHandler& dataHandler, const karabo::data::Hash& inputChannelCfg = karabo::data::Hash(), const karabo::xms::SignalSlotable::InputHandler& eosHandler = karabo::xms::SignalSlotable::InputHandler(), const karabo::xms::SignalSlotable::InputHandler& inputHandler = karabo::xms::SignalSlotable::InputHandler())

Register handlers to be called whenever the defined output channel receives data or end-of-stream (EOS).

DEPRECATED - use interface with 'InputChannelHandlers' argument!

channelName : identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)

dataHandler : std::function<void (const karabo::data::Hash&, const MetaData&) to be called whenever data arrives

inputChannelCfg : configures via InputChanel::create(..) - use default except you know what your are doing for the expert: "connectedOutputChannels" will be overwritten

eosHandler : std::function called for EOS if given

inputHandler : std::function to be called whenever data arrives

Return : false if channel is already registered

registerClassSchemaMonitor

void registerClassSchemaMonitor(const ClassSchemaHandler& callBackFunction)

Register a callback handler to be triggered if a new class appears on a device server

callBackFunction : receiving the server id, class id and new class Schema

registerDeviceForMonitoring

void registerDeviceForMonitoring(const std::string& deviceId)

Registers a device to have its configurations changes monitored.

deviceId : of the device to be added to the set of monitored devices.

Note

In order to receive notifications about configuration changes for any of the monitored devices, one needs to register handlers by calling registerDeviceMonitor (updates one by one - even if updates are throttled) or with registerDevicesMonitor (bulk updates).

registerDeviceMonitor

void registerDeviceMonitor( const std::string& instanceId, const std::function<void(const std::string&, const karabo::data::Hash&)>& callbackFunction)

Register a callback function to be triggered when a a device in the distributed system updates.

instanceId : of the device to register to

callbackFunction : handling the update. It will receive the device instance id and the updated device configuration Hash

template <class UserDataType> void registerDeviceMonitor(const std::string& instanceId, const std::function<void(const std::string&, const karabo::data::Hash&, const std::any&)>& callbackFunction, const UserDataType& userData)

Register a callback function to be triggered when a a device in the distributed system updates. Additional user data may be passed to the callback

instanceId : of the device to register to

callbackFunction : handling the update. It will receive the device instance id and the updated device configuration Hash as well as std::any userData.

userData : to be passed to the callback as std::any

registerDevicesMonitor

void registerDevicesMonitor(const DevicesChangedHandler& devicesChangedHandler)

Registers a handler for configuration changes for any of the monitored devices.

Note

• To register a device to be monitored, a call to registerDeviceForMonitoring must be made. * Throttling of device updates must be enabled via a call to setDeviceMonitorInterval with an argument greater than 0.

devicesChangesHandler : callback function for configuration changes events for any monitored device.

registerInstanceChangeMonitor

void registerInstanceChangeMonitor(const InstanceChangeThrottler::InstanceChangeHandler& callBackFunction, unsigned int throttlerIntervalMs = 500u, unsigned int maxChangesPerCycle = 100u)

Register a throttled callback handler to be triggered when a new device instance appears, updates its instance info record or goes away in the distributed system. The throtter that dispatches the instance changes events to the handler uses a given interval between its running cycles.

callBackFunction : Function to be invoked with information about the instances changes events.

throttlerInterval : Interval, in milliseconds, between successive cycles of the throttle.

maxChangesPerCycle : Maximum number of instance changes to be dispatched per cycle of the throttler - upon reaching this limit the throttler immediately dispatches the changes, despite the elapsed time from the last cycle.

registerInstanceGoneMonitor

void registerInstanceGoneMonitor(const InstanceGoneHandler& callBackFunction)

Register a callback handler to be triggered if an instance disappears from the distributed system

callBackFunction : receiving the instanceId and instanceInfo Hash

registerInstanceNewMonitor

void registerInstanceNewMonitor(const InstanceNewHandler& callBackFunction)

Register a callback handler to be triggered if a new instance appears in the distributed system.

callBackFunction : which will receive the instanceInfo Hash

registerInstanceUpdatedMonitor

void registerInstanceUpdatedMonitor(const InstanceUpdatedHandler& callBackFunction)

Register a callback handler to be triggered if an instance receives a state update from the distributed system

callBackFunction : which will receive the instanceInfo Hash

registerPropertyMonitor

template <class ValueType> bool registerPropertyMonitor( const std::string& instanceId, const std::string& key, const std::function<void(const std::string& /*deviceId*/, const std::string& /*key*/, const ValueType& /*value*/, const karabo::data::Timestamp& /*timestamp*/)>& callbackFunction)

Register a callback function to be triggered when a given property on a device in the distributed system updates

instanceId : of the device to be monitored

key : path to the property to be monitored

callbackFunction : handling the update notification. It receives the device id, path, value and timestamp of the updated property

Return : true if the operation was successful

template <class ValueType, class UserDataType> bool registerPropertyMonitor( const std::string& instanceId, const std::string& key, const std::function<void(const std::string& /*deviceId*/, const std::string& /*key*/, const ValueType& /*value*/, const karabo::data::Timestamp& /*timestamp*/, const std::any& /*userData*/)>& callbackFunction, const UserDataType& userData)

Register a callback function to be triggered when a given property on a device in the distributed system updates. Additional user data may be passed to the callback

instanceId : of the device to be monitored

key : path to the property to be monitored

callbackFunction : handling the update notification. It receives the device id, path, value and timestamp of the updated property as well as std::any userData.

userData : to be passed to the callback as std::any

Return : true if the operation was successful

registerSchemaUpdatedMonitor

void registerSchemaUpdatedMonitor(const SchemaUpdatedHandler& callBackFunction)

Register a callback handler to be triggered if an instance receives a schema update from the distributed system

callBackFunction : receiving the instanceId and updated Schema

Note

Currently, registering only a schema update monitor with an instance of a DeviceClient is not enough to have the registered call-back activated. A workaround for this is to also register a property monitor with the same instance of DeviceClient that has been used to register the schema update monitor.

  Example:

  DeviceClient dc = std::shared_ptr<DeviceClient>(new DeviceClient());
  dc->registerSchemaUpdateMonitor(fnSchemaUpdateHandler);
  dc->registerPropertyMonitor("deviceId", "property_to_monitor", fnCallback);

saveConfigurationFromName

std::pair<bool, std::string> saveConfigurationFromName(const std::string& name, const std::vector<std::string>& deviceIds)

Saves a collection of current device configurations (and the corresponding schemas) in the configuration database under a common name, user, priority and description.

name : to be assigned to the saved collection of device configurations (with schemas).

deviceIds : the devices whose current configurations (and schemas) are to be saved.

Return : a pair with a success flag (true when the operation succeeds) in the first position and a reason failture description (empty in case of success) in the second position.

set

template <class T> void set(const std::string& instanceId, const std::string& key, const T& value, int timeoutInSeconds = -1, const char keySep = data::Hash::k_defaultSep)

Set a remote property in the distributed system

instanceId : of the device to set the property on

key : path to the property to set

value : to set

timeoutInSeconds : maximum timeout until set operation fails, set to -1 to wait forever

keySep : path separator

void set(const std::string& instanceId, const karabo::data::Hash& values, int timeoutInSeconds = -1)

Bulk-set remote properties in the distributed system

instanceId : of the device to set the property on

values : a Hash containing the to be set value in a path structure indicating which properties to set

timeoutInSeconds : maximum timeout until set operation fails, set to -1 to wait forever

setAgeing

void setAgeing(bool toggle)

Set ageing on or off (on by default)

Return :

setDeviceMonitorInterval

void setDeviceMonitorInterval(long int milliseconds)

Set interval to wait between subsequent (for the same instance) calls to handlers registered via registerDeviceMonitor. Changes received within that interval will be cached and, in case of several updates of the same property within the interval, only the most up-to-date value will be handled. If negative, switch off caching and call handler immediately.

setInternalTimeout

void setInternalTimeout(const unsigned int internalTimeout)

Sets the internal timeout for any request/response like communications

internalTimeout : The default timeout in ms

setNoWait

template <class T> void setNoWait(const std::string& instanceId, const std::string& key, const T& value, const char keySep = data::Hash::k_defaultSep)

Set a remote property in the distributed system as a fire-and-forget operation. Warning: there is no guarantee and indication if the set succeeded!

instanceId : of the device to set the property on

key : path to the property to set

value : to set

keySep : path separator

void setNoWait(const std::string& instanceId, const karabo::data::Hash& values)

Bulk-set remote properties in the distributed system as a fire-and-forget operation. Warning: there is no guarantee and indication if the set succeeded!

instanceId : of the device to set the property on

values : a Hash containing the to be set value in a path structure indicating which properties to set

treatInstanceAsGone

void treatInstanceAsGone(const std::string& instanceId, const karabo::data::Hash& instanceInfo)

Helper for _slotInstanceGone

Does all needed action - despite of removal from m_runtimeSystemDescription - and despite of special treatment of devices on the server if instance is a server

unregisterChannelMonitor

bool unregisterChannelMonitor(const std::string& instanceId, const std::string& channel)

Unregister monitoring of output channel

instanceId : of the device having the output channel

channel : is name of the output channel

Return : false if channel was not registered

bool unregisterChannelMonitor(const std::string& channelName)

Unregister monitoring of output channel

channelName : identifies the channel as a concatenation of the id of its devices, a colon (:) and the name of the output channel (e.g. A/COOL/DEVICE:output)

Return : false if channel was not registered

unregisterDeviceFromMonitoring

void unregisterDeviceFromMonitoring(const std::string& deviceId)

Unregisters a device from configuration changes monitoring.

deviceId : of the device to be removed from the set of monitored devices.

unregisterDeviceMonitor

void unregisterDeviceMonitor(const std::string& instanceId)

Unregister a device monitor.

instanceId : to unregister the monitor from

unregisterPropertyMonitor

void unregisterPropertyMonitor(const std::string& instanceId, const std::string& key)

Unregister a property monitor

instanceId : to unregister the monitor from

key : path to the property to unregister from.