Service Devices In Karabo

Karabo comes with a selection of service devices, which in principle may be interacted with through their public interface, although this is normally not necessary if appropriate clients, such as the GUI are used.

C++ Service Devices

namespace karabo::devices

Namespace for package core

Typedefs

using karabo::devices::BeginTemporarySessionHandler = typedef std::function<void(const BeginTemporarySessionResult&)>
using karabo::devices::ExpirationHandler = typedef std::function<void(const ExpiredTemporarySessionInfo&)>

Handler for expired temporary session events.

using karabo::devices::EminentExpirationHandler = typedef std::function<void(const EminentExpirationInfo&)>

Handler for “temporary session about to expire” events.

using karabo::devices::AsyncHandler = typedef std::function<void()>
using karabo::devices::InfluxResponseHandler = typedef std::function<void(const karabo::net::HttpResponse&)>

Enums

enum RejectionType

Values:

TOO_MANY_ELEMENTS = 0
VALUE_STRING_SIZE
PROPERTY_WRITE_RATE
SCHEMA_WRITE_RATE
FAR_AHEAD_TIME

Functions

template <class T>
void addToSetOrCreate(Hash &h, const std::string &key, const T &object)

Helper function used below: Add object to set<T> at key’s position in h - if no such key exists, create one

static void trim_vector_elements(std::vector<std::string> &v)

Variables

constexpr karabo::util::Schema::AccessLevel MAX_LOGIN_ACCESS_LEVEL = karabo::util::Schema::AccessLevel::ADMIN
constexpr karabo::util::Schema::AccessLevel MAX_TEMPORARY_SESSION_ACCESS_LEVEL = karabo::util::Schema::AccessLevel::ADMIN
constexpr unsigned int CHECK_TEMPSESSION_EXPIRATION_INTERVAL_SECS = 5U
const unsigned int defVectorMaxSize = 100
struct BeginTemporarySessionResult

Inherits from karabo::net::OneTimeTokenAuthorizeResult

class DataLogger
#include <DataLogger.hh>

A DataLogger device is assigned devices in the distributed system and logs their slow control data.

DataLoggers are managed by the karabo::devices::DataLoggerManager.

Each is able to log any number of devices. This list can be specified at instantiation, but can also dynamically changed by the slots slotTagDeviceToBeDiscontinued and slotAddDevicesToBeLogged. When the logger is ready to log data, its state changes from INIT to NORMAL.

Inherits from karabo::core::Device<>

Subclassed by karabo::devices::FileDataLogger, karabo::devices::InfluxDataLogger

Protected Functions

void initializeLoggerSpecific()

Do some actions here that may require asynchronous logic … and, finally, startConnection() should be called This function may be overridden by derived classes but at the end the ‘startConnection’ function should be called as a last step of initialization

bool removeFrom(const std::string &str, const std::string &vectorProp)

Helper to remove an element from a vector<string> element - needs protection by m_perDeviceDataMutex. Note that if the same element is in the vector more than once, only the first one is removed.

Return
whether could be removed
Parameters
  • str: the element to remove
  • vectorProp: the key of the vector<string> element

bool appendTo(const std::string &str, const std::string &vectorProp)

Helper to add an element to a vector<string> element - needs protection by m_perDeviceDataMutex. Note that if the same element is already in, it will not be added again.

Return
whether it was added (i.e. false if ‘str’ was already in the vectorProperty
Parameters
  • str: the element to add
  • vectorProp: the key of the vector<string> element

void preDestruction()

Override preDestruction from Device class

Private Functions

void slotTagDeviceToBeDiscontinued(const std::string &reason, const std::string &deviceId)

FIXME: Update text This tags a device to be discontinued, three cases have to be distinguished

(a) Regular shut-down of the device (wasValidUpToNow = true, reason = ‘D’) (b) Silent death of the device (wasValidUpToNow = true, reason = ‘D’) (c) Start-up of this (DataLogger) device whilst the device was alive (wasValidUpToNow = false, reason = ‘L’)

This slot will be called by the DataLoggerManager

void handleConfigConnected(const DeviceData::Pointer &data, const std::shared_ptr<std::atomic<unsigned int>> &counter)

Helper for connecting to both signalChanged and signalStateChanged.

void updateTableAndFlush(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)

Flush data in file hierarchy or to the database tables

Parameters
  • aReplyPtr: if pointer to an AsyncReply that (if non-empty) has to be called without argument when done

virtual void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr) = 0

“Flush” data accumulated in the internal cache to the external storage (file, database,…)

bool allowLock() const

This device may not be locked

Return
false

class DataLoggerManager
#include <DataLoggerManager.hh>

The DataLoggerManager manages device loggers in the distributed system.

In the Karabo distributed system two types of data archiving exist:

  • run associated archival of scientific data through the DAQ system
  • constant device state and slow control logging using the data logger services

This device manages the data loggers used in the second logging scenario. It is the central configuration point to set via its expected parameters the

  • flushInterval: at which loggers flush their data to disk
  • maximumFileSize: of log files after which a new log file chunk is created
  • directory: the directory into which loggers should write their data
  • serverList: a list of device servers which each runs one logger. Each device in the distributed system is assigned to one logger. They are added to the loggers on these servers in a round robin fashion, allowing for load balancing. Assignment is made permanent in a loggermap.xml file that is regularly written to disk. This allows to distribute the servers in the serverList to be distributed among several hosts and still have fixed places for reading the data back.

Inherits from karabo::core::Device<>

Private Functions

std::pair<bool, std::string> checkSummary()

Assemble summary from m_checkStatus and clear for next use. The boolean returned tells whether the status requires operator attention.

void printLoggerData() const

Print internal cash of logger status. Needs to be protected by m_strand.

void forceDeviceToBeLogged(const std::string &deviceId)

If deviceId’s logging status is fishy, re-add to its logger. Needs to be protected by m_strand.

Parameters
  • deviceId: the fishy device

void slotGetLoggerMap()

Request the current mapping of loggers to servers. The reply contains a Hash where the the logger id is the key and the server id the value.

std::string loggerServerId(const std::string &deviceId, bool addIfNotYetInMap)

Get id of server that should run logger for given device that should be logged

Return
the server id - can be empty if addIfNotYetInMap == false
Parameters
  • deviceId: the device that should be logged
  • addIfNotYetInMap: whether to create a server/logger relation in the logger map in case it does not yet exist for deviceId

std::string serverIdToLoggerId(const std::string &serverId) const

Get id of DataLogger running on server with id ‘serverId’

std::string loggerIdToServerId(const std::string &loggerId) const

Get id of server that should run logger with id ‘loggerId’

bool allowLock() const

This device may not be locked

Return
false

void evaluateBlockedOnStrand(const karabo::util::Hash &oldList, const karabo::util::Hash &newList)

Evaluate old and new configuration in order to possibly start/stop archiving for some devices/device classes.

Parameters
  • oldList: old configuration for blocked devices/classes
  • newList: new configuration for blocked devices/classes

std::vector<karabo::util::Hash> makeLoggersTable()

create a vector of hashes that can be loaded in a table from the Hash with the mapping device -> logger

Private Members

karabo::util::Hash m_checkStatus

1st level keys: entries in m_serverList, 2nd level: “state”, “backlog”, “beingAdded” and “devices”

std::unordered_map<std::string, std::set<std::string>> m_knownClasses

Keep track of all important stuff during check.

karabo::net::Strand::Pointer m_strand

to be accessed on the strand

const std::string m_blockListFile

Hash with ‘deviceIds’ and ‘classIds’ entries.

class DataLogReader
#include <DataLogReader.hh>

DataLogReader devices read archived information from the Karabo data loggers.

DataLogReader devices read archived information from the Karabo data loggers. They are managed by karabo::devices::DataLoggerManager devices. Calls to them should usually not happen directly, but rather through a karabo::core::DeviceClient and it’s karabo::core::DeviceClient::getPropertyHistory and karabo::core::DeviceClient::getConfigurationFromPast methods.

Inherits from karabo::core::Device<>

Subclassed by karabo::devices::FileLogReader, karabo::devices::InfluxLogReader

Protected Functions

void slotGetPropertyHistory(const std::string &deviceId, const std::string &property, const karabo::util::Hash &params)

Use this slot to get the history of a given property The slot replies a vector of Hashes where each entry consists of a Hash with a key “v” holding the value of the property at timepoint signified in “v“‘s attributes using a format compatible with karabo::util::Timestamp::fromHashAttributes

Parameters
  • deviceId: for which to get the history for
  • property: path to the property for which to get the history from
  • params: Hash containing optional limitations for the query:
    • from: iso8601 timestamp indicating the start of the interval to get history from
    • to: iso8601 timestamp indicating the end of the interval to get history from
    • maxNumData: maximum number of data points to retrieve starting from start

void slotGetConfigurationFromPast(const std::string &deviceId, const std::string &timepoint)

Request the configuration Hash and schema of a device at a given point at time. Depending on the device status and on the availability of logged data, the configuration and schema returned will be:

  1. If the device was online and logging data at the given timepoint, the configuration and the schema will be the ones that were active at the timepoint;
  2. If the device was offline at the given timepoint, but there is data logged for it before the timepoint, the last active configuration and schema before that timepoint will be returned;
  3. If the device was offline at the given timepoint and there’s no data logged before the timepoint, an empty configuration and an empty schema will be returned.

The slot replies with a tuple of 4 values. The first two are the Hash and Schema objects containing the configuration Hash and the corresponding device schema for timepoint. The third is a boolean whose true value indicates the device was online and actively logging data at the timepoint. The fourth value is the string form of the timepoint for the configuration returned and will be the latest timestamp among the timestamps of the properties in the configuration returned.

Parameters
  • deviceId: of the device to get the configuration from
  • timepoint: in iso8601 format for which to get the information

An important note: if no configuration is found for the device at the timepoint (or before the timepoint), the third value in the reply will be false and the fourth will be the string form of the Epoch (01/01/1970 at 00:00:00).

void onOk()

helper functions to handle state transition in derived classes: onOk: sets the State to ON

const string onException(const std::string &message)

helper functions to handle state transition in derived classes: onException: sets the State to ERROR, logs the exception trace to status and to the Karabo Logs

Return
the exception trace
Parameters
  • message: a string to be prepended to the trace

struct DeviceData

Inherits from std::enable_shared_from_this< DeviceData >

Subclassed by karabo::devices::FileDeviceData, karabo::devices::InfluxDeviceData

Public Functions

virtual void handleChanged(const karabo::util::Hash &config, const std::string &user) = 0

Called when configuration updates arrive for logging

Parameters
  • config: a Hash with the updates and their timestamps
  • the: user responsible for this update - if any

virtual void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp) = 0

Called when a Schema update arrive for logging

Parameters
  • schema: - the new one
  • stamp: - the timestamp to be assigned for that update

void getPathsForConfiguration(const karabo::util::Hash &configuration, const karabo::util::Schema &schema, std::vector<std::string> &paths) const

Retrieves the paths of the leaf nodes in a given configuration. The paths are returned in ascending order of their corresponding nodes timestamps.

Note
karabo::devices::DataLogReader depends on the configuration items being properly sorted in time to retrieve configuration changes.
Parameters
  • configuration: A configuration with the nodes corresponding to the paths.
  • schema: The schema for the configuration hash.
  • paths: The paths of the leaf nodes in the configuration, sorted by nodes timestamps.

class FileDataLogger

Inherits from karabo::devices::DataLogger

Private Functions

void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)

“Flush” data accumulated in the internal cache to the external storage (file, database,…)

struct FileDeviceData

Inherits from karabo::devices::DeviceData

Public Functions

void handleChanged(const karabo::util::Hash &config, const std::string &user)

Called when configuration updates arrive for logging

Parameters
  • config: a Hash with the updates and their timestamps
  • the: user responsible for this update - if any

bool updatePropsToIndex()

Helper function to update data.m_idxprops, returns whether data.m_idxprops changed.

void ensureFileClosed()

Helper to ensure archive file is closed. Must only be called from functions posted on ‘data.m_strand’.

std::pair<bool, size_t> ensureFileOpen()

Helper to ensure archive file (m_configStream) is open. Must only be called from functions posted on ‘data.m_strand’.

Return
pair of * whether it is a new file (in contrast to a re-opened existing one)
  • current file position, size_t(-1) tells that file could not be opened (permissions?)

void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp)

Called when a Schema update arrive for logging

Parameters
  • schema: - the new one
  • stamp: - the timestamp to be assigned for that update

struct FileLoggerIndex
#include <FileLogReader.hh>

A compound for representing indexes in text file logged data.

class FileLogReader
#include <FileLogReader.hh>

A reader for data logs stored in text files by the class karabo::devices::FileDataLogger.

Inherits from karabo::devices::DataLogReader

Private Functions

void readToHash(karabo::util::Hash &hashOut, const std::string &path, const karabo::util::Timestamp &timestamp, const std::string &type, const std::string &value) const

Internal helper: Place ‘value’ interpreted as ‘type’ (and with given ‘timestamp’) into ‘hashOut’ at ‘path’.

std::pair<bool, FileLoggerIndex> findLoggerIndexTimepoint(const std::string &deviceId, const std::string &timepoint)

Retrieves, from the logger index, the event of type “device became online” that is closest, but not after a given timepoint. The retrieved logger index event can be used as a starting point for sweeping the device log for the last known given configuration at that timepoint.

Return
a pair whose ‘first’ is a boolean that indicates whether configuration was active at the timepoint (true) or whether it is a configuration from the most recent activation of the device prior to the timepoint because the device was not active logging at the timepoint. The pair’s ‘second’ value is the logger index of the given device that is the closest “device became online” event that is not after the given timepoint.
Parameters
  • deviceId: the device whose logger index event should be retrieved.
  • timepoint: the timepoint that will be used as the reference to find the logger index event.

FileLoggerIndex findNearestLoggerIndex(const std::string &deviceId, const karabo::util::Epochstamp &timepoint, const bool before)

Find logger closest index from archive_index.txt file that is before/after (according to ‘before’) ‘timepoint’. If there is none before (after) but that is asked for, take the one just after (before).

size_t findPositionOfEpochstamp(std::ifstream &f, double stamp, size_t left, size_t right, bool preferBefore)

Find index of that MetaData::Record in ‘f’ (between indices ‘left’ and ‘right’) that matches the Epochstamp ‘stamp’. In case no exact match (within 1 ms) is found, ‘preferBefore’ decides whether the index with a smaller or larger time stamp is returned.

void extractTailOfArchiveIndex(const std::string &tail, FileLoggerIndex &entry) const

Helper to extract DataLoggerIndex values out of the tail of a line in archive_index.txt. The tail is everything after event, timestampAsIso8061 and timestampAsDouble. The entry has to be partly filled (m_event and m_epoch) and partly serves as output (m_train, m_position, m_user and m_fileindex). Works for lines written to archive_index.txt by >= 1.5

class GuiServerDevice
#include <GuiServerDevice.hh>

The GuiServerDevice mediates between GUI clients and the distributed system.

The GuiServerDevice acts as a mediator between the distributed system and GUI clients, which connect to it through (tcp) channels. The device centrally manages updates from the distributed system and pushes them to the clients. Conversly, it handles requests by clients and passes them on to devices in the distributed system.

Inherits from karabo::core::Device<>

Private Functions

void initUsersActionsLog()

Initializes the user actions log.

The log contains entries describing the writing actions the GUI Server performed upon request of a user. It is separated from the remaining device server logs.

void logUserAction(const WeakChannelPointer &channel, const std::string &entryText)

Adds an entry with a given text to the user actions log.

Parameters
  • channel: The TCP Channel connecting the GUI Server to the GUI Client that originated the action execution request.
  • entryText: A description of the action (and possibly its parameters)

void loggerMapConnectedHandler()

Wrapping requestNoWait

void postReconfigure()

Called if configuration changed from outside.

void startDeviceInstantiation()

Starts the deadline timer which throttles device instantiation.

void startNetworkMonitor()

Starts the deadline timer which triggers network stats collection

void startMonitorConnectionQueues(const karabo::util::Hash &currentSuspects)

Starts the deadline timer which monitors connection queues

Parameters
  • currentSuspects: Hash with pending message counts - keys are bad client addresses

void collectNetworkStats(const boost::system::error_code &error)

Perform network stats collection

void deferredDisconnect(WeakChannelPointer channel)

writes a message to the specified channel with the given priority

Parameters
  • channel:
  • message:
  • prio: Deferred disconnect handler.

void safeAllClientsWrite(const karabo::util::Hash &message, int prio = LOSSLESS)

writes message to all channels connected to the gui-server device

Parameters
  • message:
  • prio:

void sendLoginErrorAndDisconnect(const karabo::net::Channel::Pointer &channel, const std::string &userId, const std::string &cliVersion, const std::string &errorMsg)

Sends a login error message to the client currently connected and closes the connection after a time interval elapses.

Parameters
  • channel: the channel the client to be notified and disconnected is connected.
  • userId: the id of the user whose login attempt failed.
  • cliVersion: the version of the GUI client attempting to login.
  • errorMsg: the error message to be sent to the client.

void onError(const karabo::net::ErrorCode &e, WeakChannelPointer channel)

an error specified by ErrorCode e occurred on the given channel. After an error the GUI-server will attempt to disconnect this channel.

Parameters
  • e:
  • channel:

bool violatesReadOnly(const std::string &type, const karabo::util::Hash &info)

validate the incoming type and info hash if a readOnly command is requested to be executed

Return
bool whether the request violates read-only restrictions
Parameters
  • type:
  • info:

bool isProjectLoadingReplyType(const std::string &replyType)

Checks whether a given reply type requested by a GUI Client is for a request involved in the Load Project operation.

Return
bool is the reply type involved in the Load Project operation?
Parameters
  • replyType: the string that specifies the reply type.

bool violatesClientConfiguration(const std::string &type, WeakChannelPointer channel)

validates the client configuration

currently only validating the type versus the client version.

Return
bool whether the request violates client validation
Parameters
  • type:
  • channel:

void onGuiError(const karabo::util::Hash &hash)

an error further specified by hash occurred on a connection to a GUI client. The GUI-server will attempt to forward the error to the debug channel of the GUI client.

Parameters
  • hash:

void onConnect(const karabo::net::ErrorCode &e, karabo::net::Channel::Pointer channel)

connects a client on to the GUI server on channel. The channel is registered with two priority handlers: remove oldest and loss-less. The onRead and onError handlers are registered to handle incoming data and faults on the channel. Both upon successful completion and exceptions in the process the acceptor socket of the GUI-server is re-registered so that new client connections may be established.

Parameters
  • e: holds an error code if any error occurs when calling this slot
  • channel:

void registerConnect(const karabo::util::Version &version, const karabo::net::Channel::Pointer &channel, const std::string &userId = "", const std::string &oneTimeToken = "")

Creates an internal ChannelData structure mapped to the TCP Channel in charge of the connection between the GUI Client and the GUI Server. Also updates the number of connected clients property of the GUI Server.

Called after a successful user authorization based on a one-time token (when the GUI Server requires user authentication).

For GUI Servers that don’t require user authentication / authorization, it’s called right after the message of “type” “login” is received by the server and the client’s version is verified as one being supported by the server. The client’s version verification is also performed by a GUI Server that requires authentication (right before the token validation).

Note
The access level is not being saved in the internal ChannelData structure because all the access level enforcement is currently client side only. If any enforcement is required on the server side, the access level information must be stored in ChannelData and updated whenever the user downgrades his/her access level on the GUI client.
Parameters
  • version: the version of the connected GUI client
  • channel: the TCP channel for the connection being registered
  • userId: the ID of the user logged in the connected GUI Client
  • oneTimeToken: the one-time token resulting from the user authentication previously triggered by GUI client - the token is used by the GUI Server to validate the authentication and to authorize the user (send the user’s login access level back to the GUI Client).

void onWaitForLogin(const karabo::net::ErrorCode &e, const karabo::net::Channel::Pointer &channel, karabo::util::Hash &info)

Handler for login messages expected to be sent by a GUI Client right after it establishes a TCP connection to the GUI Server.

Keeps discarding and logging warnings for any message whose “type” is not “login”. When such an unexpected message is received, the GUI server binds this handler again to the TCP channel.

When a message of “type” of “login” is received, its handling is delegated to onLogin(const karabo::net::ErrorCode&, const karabo::net::Channel::Pointer&, karabo::util::Hash&)

Parameters
  • e: holds an error code if the eventloop cancels this task or the channel is closed
  • channel: the TCP channel for the recently established connection with a GUI client
  • info: a Hash containing the message “type” and, for “login” messages, some info related to the login process, like the version of the connected GUI client and some user related info, like the userID or the oneTimeToken the GUI Client received upon successfully authenticating the user logging in.

void onLogin(const karabo::net::Channel::Pointer &channel, const karabo::util::Hash &info)

Handles a login request of a user on a GUI client. If the login credentials are valid, the current system topology is sent to the client.

Note
for clients >= 2.20 a login message with no OneTimeToken is interpreted by an authenticated GUI Server as a request for a read-only session. The GUI Server will respond to such messages with Access Level OBSERVER and the read-only flag set to true. For login messages with OneTimeToken the read-only flag will be always set to false and the Access Level will be the one returned by the Karabo Authentication Server.
Parameters
  • channel: the TCP channel between the GUI client and the GUI server
  • info: Hash with information needed to validate the login request.

void onTokenAuthorizeResult(const WeakChannelPointer &channel, const std::string &userId, const karabo::util::Version &cliVersion, const std::string &oneTimeToken, const karabo::net::OneTimeTokenAuthorizeResult &authResult)

Handles the result of the authorize one-time token operation performed as part of a GUI client login on behalf of an authenticated user.

Parameters
  • channel: the communication channel established with the GUI client logging in.
  • userId: the ID of the user on whose behalf the login is being made.
  • cliVersion: the version of the GUI client logging in.
  • oneTimeToken: the one-time token sent by the GUI client logging in.
  • authResult: the result of the one-time token authorization operation to be handled.

void onTemporarySessionExpiration(const ExpiredTemporarySessionInfo &info)

Handles a temporary session expired event communicated by the internal instance of the GuiServerTemporarySessionManager.

The expiration is handled by sending a message of type “onTemporarySessionExpired” to the client associated with the expired token. The message carries a Hash with paths “expiredToken” and “expirationTime”.

Parameters
  • info: data about the expired temporary session.

void onEndTemporarySessionNotice(const EminentExpirationInfo &info)

Handles a “temporary session about to expire” event.

The eminent temporary session end is handled by sending a message of type “onEndTemporarySessionNotice” to the client associated with the about to expire token. The message carries a Hash with paths “toExpireToken” and “secondsToExpiration”.

Parameters
  • info: data about the temporary session about to expire.

void onRead(const karabo::net::ErrorCode &e, WeakChannelPointer channel, karabo::util::Hash &info, const bool readOnly)

handles incoming data in the Hash info from channel. The further actions are determined by the contents of the type property in info. Valid types and there mapping to methods are given in the following table:

onRead allowed types
type resulting method call
reconfigure onReconfigure
execute onExecute
getDeviceConfiguration onGetDeviceConfiguration
getDeviceSchema onGetDeviceSchema
getClassSchema onGetClassSchema
initDevice onInitDevice
killServer onKillServer
killDevice onKillDevice
startMonitoringDevice onStartMonitoringDevice
stopMonitoringDevice onStopMonitoringDevice
getPropertyHistory onGetPropertyHistory
getConfigurationFromPast onGetConfigurationFromPast
subscribeNetwork onSubscribeNetwork
requestNetwork onRequestNetwork
error onGuiError
acknowledgeAlarm onAcknowledgeAlarm
requestAlarms onRequestAlarms
updateAttributes onUpdateAttributes
projectUpdateAttribute onProjectUpdateAttribute
projectBeginUserSession onProjectBeginUserSession
projectEndUserSession onProjectEndUserSession
projectSaveItems onProjectSaveItems
projectLoadItems onProjectLoadItems
projectListProjectManagers onProjectListProjectManagers
projectListItems onProjectListItems
projectListProjectsWithDevice onProjectListProjectsWithDevice
projectListDomains onProjectListDomains
requestGeneric onRequestGeneric
subscribeLogs <no action anymore>
setLogPriority onSetLogPriority
beginTemporarySession onBeginTemporarySession
endTemporarySession onEndTemporarySession

Both upon successful completion of the request or in case of an exception the onRead function is bound to the channel again, maintaining the connection of the client to the gui-server.

Parameters
  • e: holds an error code if the eventloop cancel this task or the channel is closed
  • channel:
  • info:
  • readOnly:

void setTimeout(karabo::xms::SignalSlotable::Requestor &requestor, const karabo::util::Hash &input, const std::string &instanceKey)

Sets the appropriate timeout to a Requestor

If input has a “timeout” key, set the maximum value of that and the gui server timeout on the requestor, except if input.get<std::string>(instanceKey) is one instance of the classes in “ignoreTimeoutClasses”.

void forwardReconfigureReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)

Callback helper for onReconfigure

Parameters
  • success: whether call succeeded
  • channel: who requested the call
  • input: will be copied to the key input of the reply message

void forwardHashReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &info, const karabo::util::Hash &reply)

Callback helper for generic actions called by the gui server.

Parameters
  • success: whether call succeeded
  • channel: who requested the call
  • info: the input info Hash
  • reply: the reply from the remote device or an empty Hash on failure

void onRequestGeneric(WeakChannelPointer channel, const karabo::util::Hash &info)

Request a generic action internally. Generic interface to call slots that take a single Hash as argument and reply with a single Hash.

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain the slot information.
    • type: requestGeneric
    • instanceId: the instanceId to be called
    • slot: the slot name of the instance
    • empty: if this property is provided, the input Hash is not bounced back
    • replyType (optional): the value of the key type in the reply to the client
    • timeout (optional) [s]: account for the slot call a specified timeout in seconds!
    • args: The Hash containing the parameters for the slot call

The forwardHashReply method is used to relay information to the gui client.

Returns:

In the default case, the return Hash is composed as follows::

  • success: boolean to indicate if the generic request was successful
  • reason: information on the error if not succesful otherwise empty
  • type: if specified in the input Hash, the replyType is used otherwise requestGeneric
  • request: the full input Hash information, including args
  • reply: The reply Hash of the instanceId

.. note: If the info Hash from the client provides an empty property, an empty Hash is sent back to the client instead of the input Hash.

void onReconfigure(WeakChannelPointer channel, const karabo::util::Hash &info)

Calls the Device::onReconfigure slot on the device specified in info.

The info should have the following entries:

  • string at deviceId defines the target device
  • Hash at configuration is the configuration update to apply
  • bool at reply: if given and true, success or failure will be reported back to channel by a message of type reconfigureReply that contains
    • input: the Hash given here as info
    • success: bool whether reconfiguration succeeded
    • failureReason: string with failure reason
  • optional int at timeout: if a reply should be reported back, defines seconds of timeout. In case timeout is missing, timeout errors will report success as true but provides a failureReason mentioning the timeout

Parameters
  • channel: to potentially send “reconfigureReply”
  • info:

void onBeginTemporarySession(WeakChannelPointer channel, const karabo::util::Hash &info)

Handles a message of type “beginTemporarySession” by starting a temporary session on top of the current user-authenticated session (if there’s one). The session begining is an asynchronous operation whose completion (either successful or not) will be handled by the onBeginTemporarySessionResult method.

Parameters
  • channel: the TCP channel connecting to the client that requested the begining of the temporary session.
  • info: a Hash which is supposed to contain an “temporarySessionToken” whose value is a one-time token that must be successfuly authorized for the temporary session to be started.

void onBeginTemporarySessionResult(WeakChannelPointer channel, karabo::util::Schema::AccessLevel levelBeforeTemporarySession, const BeginTemporarySessionResult &result)

Handles the result of an “beginTemporarySession” request sent by a connected client.

Parameters
  • channel: the TCP channel connecting to the client that requested the temporary session that will be used to send a message of type “onBeginTemporarySession” with the begin operation results back to the client.
  • levelBeforeTemporarySession: sent by the client as part of the begin temporary session request to be sent back when the temporary session ends.
  • result: the results of the begin temporary session operation that will be sent back to the client.

void onEndTemporarySession(WeakChannelPointer channel, const karabo::util::Hash &info)

Handles a message of type “endTemporarySession” by ending the current temporary session (if there’s one). The end of the session is performed synchronously (there’s no I/O involved) and its results are transmitted back to the client through a message of type “onEndTemporarySession”.

Note
the hash with the results of the ending operation sent back to the requesting client has the fields “success”, “reason” and “temporarySessionToken” (an echo of the token provided in the request).
Parameters
  • channel: the TCP channel connecting to the client that requested the end of the temporary session. Will be used to send the response back to the client.
  • info: a Hash which is supposed to contain an “temporarySessionToken” whose value is a one-time token that must match the one associated to the temporary session being terminated.

void forwardExecuteReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)

Callback helper for onExecute

Parameters
  • success: whether call succeeded
  • channel: who requested the call
  • input: will be copied to the key input of the reply message

void onExecute(WeakChannelPointer channel, const karabo::util::Hash &info)

Calls a command slot on a specified device.

The info should have the following entries:

  • string at deviceId defines the target device
  • string at command is the slot to call
  • bool at reply: if given and true, success or failure will be reported back to channel by a message of type executeReply that contains
    • input: the Hash given here as info
    • success: bool whether execution succeeded
    • failureReason: string with failure reason
  • optional int at timeout: if a reply should be reported back, defines seconds of timeout. In case timeout is missing, timeout errors will report success as true but provides a failureReason mentioning the timeout
    Parameters
    • channel:
    • info:

void onInitDevice(WeakChannelPointer channel, const karabo::util::Hash &info)

Enqueues a future device instantiation. The relevant information will be stored in m_pendingDeviceInstantiations and initSingleDevice will take care of the actual instantiation when it is called by the instantiation timer.

Parameters
  • channel:
  • info:

void initSingleDevice(const boost::system::error_code &error)

Instructs the server at serverId to try initializing the device at deviceId as given in info. The reply from the device server is registered to the initReply callback.

NOTE: This should only be called by m_deviceInitTimer

Parameters
  • error:

void initReply(WeakChannelPointer channel, const std::string &givenDeviceId, const karabo::util::Hash &givenConfig, bool success, const std::string &message, bool isFailureHandler)

is the callback for the onInitDevice method. It is called upon reply from the device server handling the initialization request. The reply is passed to the calling channel in form of a hash message with type=initReply, deviceId, success and message fields.

Parameters
  • channel:
  • givenDeviceId:
  • givenConfig:
  • success:
  • message:

void onGetDeviceConfiguration(WeakChannelPointer channel, const karabo::util::Hash &info)

requests the current device configuration for deviceId specified in info and sends it back in a hash message on channel. The message contains the following fields: type=deviceConfiguration, deviceId and configuration. The configuration is retrieved using the device client interface.

Parameters
  • channel:
  • info:

void onKillServer(WeakChannelPointer channel, const karabo::util::Hash &info)

instructs the server specified by serverId in info to shutdown.

Parameters
  • info:

void onKillDevice(WeakChannelPointer channel, const karabo::util::Hash &info)

instructs the device specified by deviceId in info to shutdown.

Parameters
  • info:

void onStartMonitoringDevice(WeakChannelPointer channel, const karabo::util::Hash &info)

Registers a monitor on the device specified by deviceId in info Upon changes of device properties they will be forwarded to channel from a handler for changes in configurations of monitored devices that is kept internally by the gui-server.

Only one channel per client is maintained for passing monitoring information and only one monitor is registered by the gui-server for any number of clients monitoring deviceId.

After successful registration the current device configuration is returned by calling onGetDeviceConfiguration for channel.

Parameters
  • channel:
  • info:

void onStopMonitoringDevice(WeakChannelPointer channel, const karabo::util::Hash &info)

De-registers the client connected by channel from the device specified by deviceId in info. If this is the last channel monitoring deviceId the device is removed from the set of devices monitored by the device-client.

Parameters
  • channel:
  • info:

void onGetClassSchema(WeakChannelPointer channel, const karabo::util::Hash &info)

requests a class schema for the classId on the server specified by serverId in info. This is done through the device client. A hash reply is sent out over channel containing type=classSchema, serverId, classId and schema.

Parameters
  • channel:
  • info:

void onGetDeviceSchema(WeakChannelPointer channel, const karabo::util::Hash &info)

requests a device schema for the device specified by deviceId in info. This is done through the device client. A hash reply is sent out over channel containing type=deviceSchema, deviceId, and schema.

Parameters
  • channel:
  • info:

void onGetPropertyHistory(WeakChannelPointer channel, const karabo::util::Hash &info)

requests the history for a property on deviceId in the time range t0 and t1 as specified in info. Additional the maximum number of data points may be specified in maxNumData. The request is asynchronously sent to the device logger logging information for deviceId. The reply from the logger is then forwarded to the client on channel using the propertyHistory history callback.

Parameters
  • channel:
  • info:

void propertyHistory(WeakChannelPointer channel, bool success, const std::string &deviceId, const std::string &property, const std::vector<karabo::util::Hash> &data)

Callback for onGetPropertyHistory. It forwards the history reply in data for the property on deviceId to the client connected on channel. The hash reply is of the format type=propertyHistory, deviceId, property, success, data and failureReason which states the failure reason if any.

Parameters
  • channel:
  • success: whether the request succeeded
  • deviceId:
  • property:
  • data:

void onGetConfigurationFromPast(WeakChannelPointer channel, const karabo::util::Hash &info)

Request configuration for a device at point in time time as specified in info. The info hash can as well have a preview boolean which is send back to the client. The request is asynchronously sent to the device logger logging information for deviceId. The reply from the logger is then forwarded to the client on channel using the configurationFromPast history callback in case of success or configurationFromPastError for failures.

void configurationFromPast(WeakChannelPointer channel, const std::string &deviceId, const std::string &time, const bool &preview, const karabo::util::Hash &config, const karabo::util::Schema&, const bool configAtTimepoint, const std::string &configTimepoint)

Success callback for onGetDeviceConfiguration

void configurationFromPastError(WeakChannelPointer channel, const std::string &deviceId, const std::string &time)

Failure callback for onGetDeviceConfiguration

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

Helper for history retrieval functions

Return
id of DataLogReader device to ask for history
Parameters
  • deviceId: of the device whose history is searched for

void onSubscribeNetwork(WeakChannelPointer channel, const karabo::util::Hash &info)

registers the client connected on channel to a pipe-lined processing channel identified by channelName in info in case subscribe is true. In case the pipe-lined processing channel is already connected to the gui-server no futher action is taken. Otherwise, a new connection is opened, set to copy and dropping behaviour in case the gui-server is busy, and with a maximum update frequency as defined by the delayOnInput property of the gui server. Network data from the pipe-lined processing connection is handled by the onNetworkData callback.

In this way only one connection to a given pipe-lined processing channel is maintained, even if multiple gui-clients listen to it. The gui-server thus acts as a kind of hub for pipe-lined processing onto gui-clients.

If subscribe is set to false, the connection is removed from the list of registered connections, but is kept open.

Parameters
  • channel:
  • info:

void onSubscribeLogs(WeakChannelPointer channel, const karabo::util::Hash &info)

Kept to reply back that log subscription not supported anymore after 2.16.X

Parameters
  • channel:
  • info:

void onSetLogPriority(WeakChannelPointer channel, const karabo::util::Hash &info)

sets the Log priority on a server. The info hash should contain a priority string and a instanceId string.

Parameters
  • channel:
  • info:

void forwardSetLogReply(bool success, WeakChannelPointer channel, const karabo::util::Hash &input)

Callback helper for onSetLogPriority

Parameters
  • success: whether call succeeded
  • channel: who requested the call
  • input: will be copied to the key input of the reply message

void onRequestNetwork(WeakChannelPointer channel, const karabo::util::Hash &info)

Receives a message from the GUI client that it processed network data from an output channel with name channelName in the info Hash.

Parameters
  • channel:
  • info:

void onNetworkData(const std::string &channelName, const karabo::util::Hash &data, const karabo::xms::InputChannel::MetaData &meta)

handles data from the pipe-lined processing channels the gui-server is subscribed to and forwards it to the relevant client channels, which have connected via onSubscribeNetwork. The incoming data is forwarded to all channels connected to this pipe-lined processing channel using the following hash message format: type=networkData, name is the channel name and data holding the data.

Parameters
  • channelName: name of the InputChannel that provides these data
  • data: the data coming from channelName
  • meta: corresponding meta data

void sendSystemTopology(WeakChannelPointer channel)

sends the current system topology to the client connected on channel. The hash reply contains type=systemTopology and the systemTopology.

Parameters
  • channel:

void instanceNewHandler(const karabo::util::Hash &topologyEntry)

sends the current system topology to the client connected on channel. The hash reply contains type=systemVersion and the systemVersion.

Parameters
  • channel:

void instanceChangeHandler(const karabo::util::Hash &instChangeData)

Handles events related to instances: new instance, instance updated, instance gone.

: Its signature matches karabo::core::InstanceChangeThrottler::InstanceChangeHandler).

void devicesChangedHandler(const karabo::util::Hash &what)

Acts upon incoming configuration updates from one or more devices. It is called back by a monitor registered on the device client. The reconfiguration contained in the what hash is forwarded to any channels connected to the monitor by onStartMonitoringDevice.

The message type of the hash sent out is type=”deviceConfigurations”. The hash has a second first level key, named “configurations”, whose value is a hash with the deviceIds as keys and the configuration changes for the corresponding deviceId as values.

Parameters
  • what: A hash containing all the configuration changes that happened to one or more monitored devices since the last update. Each node under the key “configurations” has the ‘deviceId’ as key and the changed configurations as a value of type Hash.

void slotGetClientSessions(const karabo::util::Hash &options)

Retrieve information about the current client sessions of the GUI server.

The reply is a hash with a single key, “clientSessions”, whose value is a vector of hashes with one hash per existing client connection. The hash for each connection has the following keys: 

. "clientVersion": string with the version of the connected
  client;

. "sessionStartTime": UTC timestamp of session start time as
  an ISO8601 string;

. "sessionToken": one-time token for the client session.
  Will be empty if the GUI Server is not in authenticated
  mode;

. "temporarySessionStartTime": UTC timestamps of temporary
  session start time as an ISO8601 string. If there's no
  active temporary session on top of the client session, an
  empty string is returned;

. "temporarySessionToken": one-time token for the temporary
  session (an empty string if there's no active temporary
  session).
Parameters
  • options: Hash with a single key “onlyWithTempSession” and a boolean value that when “true” makes the slot include only client sessions with active temporary sessions in the reply.

void slotProjectUpdate(const karabo::util::Hash &info, const std::string &instanceId)

Called from projectManagers to notify about updated Projects

Parameters
  • info: the info hash containing the information about the updated projects
  • instanceId: the instance id of the project manager device

void slotDumpToLog()

Slot to dump complete debug info to log file

Same info as received from ‘slotDumpDebugInfo’ with empty input Hash

void slotNotify(const karabo::util::Hash &info)

Slot to send a notification message to all clients connected - replies empty Hash

Parameters
  • info: a Hash with following keys
    • ”message”: a string containing the notification type
    • ”contentType”: a string defining the type of notification as the GUI client understands it
      • ”banner” means message will go to the GUI banner. Therefore it will be stored in the “bannerMessage” property of the GuiServerDevice and sent to any client that connects.
      • other types will likely just be shown in a pop-up window of the client

void slotBroadcast(const karabo::util::Hash &info)

Slot to send a Hash to the GUI clients connected - replies empty Hash

WARNING: No checks are performed on this slot. This slot can possibly disconnect all clients. Do not use it unless you understand the risks.

Parameters
  • info: a Hash with at least the following keys.
    • ”message”: a Hash that will be sent to the client(s). It should contain a “type” string.
    • ”clientAddress”: a string containing the GUI client address as coded in the slotDumpDebugInfo results. If the value for this key is an empty string, all clients will be notified.

void requestScene(const karabo::util::Hash &info)

Slot to provide scene

Parameters
  • info: Hash with key “name” that provides string identifying which scene

karabo::util::Hash getDebugInfo(const karabo::util::Hash &info)

Helper for ‘slotDumpToLog’ and ‘slotDumpDebugInfo’

void slotDisconnectClient(const std::string &client)

Slot to force disconnection of client. Reply is whether specified client found.

Parameters
  • client: string to identify client, as can be received via slotDumpDebugInfo(Hash(“clients”, 0))

void updateNewInstanceAttributes(const std::string &deviceId)

Called from instanceNewHandler to handle schema attribute updates which were received at initialization time. The slotUpdateSchemaAttributes slot is invoked if any updates are pending.

Parameters
  • deviceId: the instance id of the new device

void slotAlarmSignalsUpdate(const std::string &alarmServiceId, const std::string &type, const karabo::util::Hash &updateRows)

A slot called by alarm service devices if they want to notify of an alarm update updateType is a string of any of the following: init, update, delete, acknowledgeable, deviceKilled, refuseAcknowledgement

Parameters
  • alarmServiceId: the instance id of the service device
  • type: the type of the update: can be alarmUpdate, alarmInit
  • updateRows: the rows which should be updated. This is a Hash of Hashes, were the unique row indices, as managed by the alarm service are keys, and the values are Hashes of the form updateType->entry

entry is a Hash with the following entries:

timeOfFirstOccurrence -> string: timestamp of first occurrence of alarm trainOfFirstOccurrence -> unsigned long long: train id of first occurrence of alarm timeOfOccurrence -> string: timestamp of most resent occurrence of alarm trainOfOccurrence -> unsigned long long: train id of most resent occurrence of alarm needsAcknowledging -> bool: does the alarm require acknowledging acknowledgeable -> bool: can the alarm be acknowledged deviceId -> string: deviceId of device that raised the alarm property -> string: property the alarm refers to id -> the unique row id

it send the following Hash to the client (lossless)

Hash h(“type”, type, “instanceId”, alarmServiceId, “rows”, updateRows);

void onAcknowledgeAlarm(WeakChannelPointer channel, const karabo::util::Hash &info)

Called if the client wants to acknowledge an alarm, by sending a message of type “acknowledgeAlarm”

Parameters
  • channel: the channel the client is connected to
  • info: the message from the client. Should contain the unique row ids of the alarms to acknowledge. It is a Hash of Hashes of the same form as described for slotAlarmSignalsUpdate, where the keys give the unique row indices

void onRequestAlarms(WeakChannelPointer channel, const karabo::util::Hash &info, const bool replyToAllClients = false)

Called if a client sends a message of type “requestAlarms”

Parameters
  • channel: the channel the calling client is connected to
  • info: message passed from the client. It is a Hash that needs to contain a string field “alarmInstanceId”, which either contains a specifiy alarm service’s instance id, or an empty string. In the latter case a request for current alarms is forwarded to all known alarm services, otherwise to the specific one. Replies from the alarm services trigger calling “onRequestedAlarmsReply” asynchroniously.
  • replyToAllClients: If true, reply to all clients instead of only the requesting client.

void onRequestedAlarmsReply(WeakChannelPointer channel, const karabo::util::Hash &reply, const bool replyToAllClients)

Callback executed upon reply from an alarm service to “onRequestAlarms”. instanceId -> string: instance id of the replying alarm service alarms -> Nested Hash of form given in “slotAlarmSignalsUpdate”

Parameters
  • channel: the client channel the request came from, bound by “onRequestAlarms”
  • reply: reply from the alarm service, expected to contain fields
  • replyToAllClients: If true, reply to all clients

It sends out a Hash of form: Hash h(“type”, “alarmInit”, “instanceId”, reply.get<std::string>(“instanceId”), “rows”, reply.get<Hash>(“alarms”));

void onUpdateAttributes(WeakChannelPointer channel, const karabo::util::Hash &info)

Executed when the gui requests an update to schema attributes via the updateAttributes signal.

Parameters
  • channel: gui channel that requested the update
  • info: updated attributes, expected to be of form Hash(“instanceId”, str, “updates”, vector<Hash>) where each entry in updates is of the form Hash(“path”, str, “attribute”, str, “value”, valueType)

void onRequestedAttributeUpdate(WeakChannelPointer channel, const karabo::util::Hash &reply)

Callback for onUpdateAttributes

Parameters
  • channel: gui channel that requested the update
  • reply: reply from the device that performed the attribute update. Is of form Hash(“success” bool, “instanceId”, str, “updatedSchema”, Schema, “requestedUpdate”, vector<Hash>) where success indicates a successful update, instanceId the device that performed the update updatedSchema the new valid schema, regardless of success or not, and requestedUpdates the original update request, as received through onUpdateAttributes

void typeAndInstanceFromTopology(const karabo::util::Hash &topologyEntry, std::string &type, std::string &instanceId)

Returns the instance type and instance id from a topology entry

Parameters
  • topologyEntry: a Hash of the topology format
  • type: string which will afterwards contain type
  • instanceId: string which will be filled with the instance id

bool allowLock() const

This device may not be locked

Return
false

void registerPotentialProjectManager(const karabo::util::Hash &topologyEntry)

Checks if an instance at instanceId is a ProjectManager. If so, register it to the list of known project services

Parameters
  • topologyEntry: the topology Hash, from which the class of instanceId will be deduced

std::vector<std::string> getKnownProjectManagers() const

Return a list of project services known to this GUI server

Return

void onProjectBeginUserSession(WeakChannelPointer channel, const karabo::util::Hash &info)

Initialize a configuration database session for a user. The token should continue to be passed to subsequent database interactions to identify this session.

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectEndUserSession(WeakChannelPointer channel, const karabo::util::Hash &info)

End a configuration database session for a user.

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectSaveItems(WeakChannelPointer channel, const karabo::util::Hash &info)

Save items to the project database

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user - identifies the session
    • items: a vector of Hashes where each Hash is of the form:
      • xml: xml of the item
      • uuid: uuid of the item
      • overwrite: Boolean indicating behavior in case of revision conflict
      • domain: to write this item to. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectLoadItems(WeakChannelPointer channel, const karabo::util::Hash &info)

Load items from project database

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user - identifies the session
    • items: a vector of Hashes where each Hash is of the form:
      • uuid: uuid of the item
      • revision (optional): revision to load. If not given the newest revision will be returned
      • domain: to load this item from. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectListProjectManagers(WeakChannelPointer channel, const karabo::util::Hash &info)

Request the list of project manager devices known to the GUI server Will write to the calling channel a Hash where “type” = projectListProjectManagers and “reply” is a vector of strings containing the project manager device ids. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

Parameters
  • channel: from which the request originates
  • info: is given for compatability with all other calls but not further evaluated.

void onProjectListItems(WeakChannelPointer channel, const karabo::util::Hash &info)

Request a list of the items present in a domain. Optionally, an item type filter can be specified

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user - identifies the session
    • domain: domain to list items from
    • item_types: a vector of strings indicating the itemtypes to filter for. For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectListDomains(WeakChannelPointer channel, const karabo::util::Hash &info)

Request a list of the domains in the database.

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user - identifies the session For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void onProjectUpdateAttribute(WeakChannelPointer channel, const karabo::util::Hash &info)

Update item attributes in the project database

Parameters
  • channel: from which the request originates
  • info: is a Hash that should contain:
    • projectManager: project manager device to forward request to
    • token: token of the database user - identifies the session
    • items: a vector of Hashes where each Hash is of the form:
      • domain: to load this item from
      • uuid: uuid of the item
      • item_type: indicate type of item which attribute should be changed
      • attr_name: name of attribute which should be changed
      • attr_value: value of attribute which should be changed For the reply written to channel see the documentation of karabo.bound_devices.ProjectManager

void forwardReply(WeakChannelPointer channel, const std::string &replyType, const karabo::util::Hash &reply)

Forward a reply from a remote slot call to a requesting GUI channel.

Parameters
  • channel: to forward reply to
  • replyType: type of reply
  • reply: the reply to forward

bool checkProjectManagerId(WeakChannelPointer channel, const std::string &deviceId, const std::string &type, const std::string &reason)

Check if a given project manager identified by id is known in the distributed system

Return
true if the project manager id exists in the distributed system
Parameters
  • channel: to forward a failure message to if not
  • deviceId: of the project manager device
  • type: of the request

std::string getChannelAddress(const karabo::net::Channel::Pointer &channel) const

Utility for getting a “name” from client connections.

void tryToUpdateNewInstanceAttributes(const std::string &deviceId, const int callerMask)

Possibly update schema attributes on device

void onUpdateNewInstanceAttributesHandler(const std::string &deviceId, const karabo::util::Hash &response)

Response handler for updating schema attributes on device

bool skipExecutionTimeout(const std::string &deviceId)

Helper Function to identify whether a device belongs to the timeout violation list TODO: remove this once “fast slot reply policy” is enforced

returns true if a .timeout() should be skipped on execution requestor

void recalculateTimingOutDevices(const karabo::util::Hash &topologyEntry, const std::vector<std::string> &timingOutClasses, bool clearSet)

Helper Function to recalculate the list of timeout violating devices from the list of offending classes TODO: remove this once “fast slot reply policy” is enforced

Private Static Attributes

const std::string m_errorDetailsDelim

In reported failure reasons, this delimiter comes between short message and details like a trace.

class GuiServerTemporarySessionManager
#include <GuiServerTemporarySessionManager.hh>

Manages temporary sessions on top of user-authenticated GUI Sessions.

Takes care of authorizing one-time temporary session tokens to start temporary sessions and of communicating temporary sessions about to expire or already expired.

Inherits from std::enable_shared_from_this< GuiServerTemporarySessionManager >

Public Functions

GuiServerTemporarySessionManager(const std::string &topic, const std::string &authServerUrl, unsigned int temporarySessionDurationSeconds, unsigned int temporarySessionEndNoticeSeconds, EminentExpirationHandler onEminentExpiration, ExpirationHandler onExpiration)

Construct a new Gui Server Temporary Session Manager object.

Parameters
  • topic: the Karabo topic against which temporary session tokens will be authorized.
  • authServerUrl: the URL of the authentication server to use for authorizing one-time temporary session tokens.
  • temporarySessionDurationSeconds: the duration, in seconds, to be enforced for temporary sessions.
  • temporarySessionEndNoticeSeconds: the time in advance, in seconds, to communicate about an eminent end of temporary session event.
  • onEminentExpiration: handler for temporary sessions about to expire.
  • onExpiration: handler for expired temporary sessions.

void beginTemporarySession(const std::string &temporarySessionToken, const BeginTemporarySessionHandler &onBeginTemporarySession)

Assynchronously starts a new temporary session for a given one-time temporary session token.

Note
Calls the registered BeginTemporarySessionHandler with the results of the beginTemporarySession operation.
Parameters
  • temporarySessionToken: the one-time temporary session token to be authorized and bound to the started temporary session.
  • onBeginTemporarySession: handler for begin temporary session events (either successful or failed).

EndTemporarySessionResult endTemporarySession(const std::string &temporarySessionToken)

Synchronously terminates a temporary session referenced by a given temporary session token.

Return
a structure with the endTemporarySession operation results.
Note
an error due to a beginTemporarySession token not found isn’t necessarily an error from the GUI client point of view. In the unlikely scenario of an endTemporarySession request that reaches the GUI server while the expiration check that will detect the expiration of the same token is already running, the end temporary session request will “fail” with a “token not found” message. It is up to the GUI client to decide what to do in such cases - maybe keep track of an “over the wire” end temporary session request token and ignore any error related to it if an expiration notification is received for that token between the request dispatch and the arrival of its reponse.
Parameters
  • temporarySessionToken: the one-time temporary session token bound to the session to be terminated.

Private Functions

void checkTemporarySessionsExpirations(const boost::system::error_code &error)

Checks the currently active temporary sessions removing the expired ones after invoking the registered expiration handlers for each of them.

Parameters
  • error: an error code sent by boost::asio that if different from 0 indicates that the timer pulse that should invoke this check at some future point has been cancelled.

void onTokenAuthorizeResult(const std::string &temporarySessionToken, const BeginTemporarySessionHandler &onBeginTemporarySession, const karabo::net::OneTimeTokenAuthorizeResult &authResult)

Handles the result of a temporary session token authorization request, updating the internal state of the manager and communicating the outcome of the begin temporary session request to the external requestor.

Parameters
  • temporarySessionToken: the one-time temporary session token whose authorization was requested.
  • onBeginTemporarySession: handler for begin temporary session events (either successful or failed).
  • authResult: the result of the authorization of the temporary session token provided by the external caller of the begin temporary session operation.

void scheduleNextExpirationsCheck()

Schedules the next expiration check if there’s any esalation to be checked.

Note
this method must be called with the m_tempSessionsMutex locked.

class IndexBuilderService
#include <FileLogReader.hh>

A singleton class for building logger indices from logger files. It calls karabo-idxbuild with a list of command line arguments.

Inherits from std::enable_shared_from_this< IndexBuilderService >

Public Functions

void buildIndexFor(const std::string &commandLineArguments)

Build an index by calling karabo-idxbuild with the supplied command line arguments

Parameters
  • commandLineArguments:

Public Static Functions

static Pointer getInstance()

Return a pointer to a singleton instance of IndexBuilderService. If no instance exists one is created.

Return

Private Functions

bool allowLock() const

This device may not be locked

Return
false

class InfluxDataLogger

Inherits from karabo::devices::DataLogger

Public Functions

void preDestruction()

Override preDestruction from Device class

Protected Functions

void initializeLoggerSpecific()

Do some actions here that may require asynchronous logic … and, finally, startConnection() should be called This function may be overridden by derived classes but at the end the ‘startConnection’ function should be called as a last step of initialization

void flushImpl(const std::shared_ptr<SignalSlotable::AsyncReply> &aReplyPtr)

“Flush” data accumulated in the internal cache to the external storage (file, database,…)

struct InfluxDeviceData

Inherits from karabo::devices::DeviceData

Public Functions

void handleChanged(const karabo::util::Hash &config, const std::string &user)

Called when configuration updates arrive for logging

Parameters
  • config: a Hash with the updates and their timestamps
  • the: user responsible for this update - if any

void login(const karabo::util::Hash &configuration, const std::vector<std::string> &sortedPaths)

Helper to store logging start event

Parameters
  • configuration: full device configuration received when logging starts
  • sortedPaths: full paths of configuration, sorted by increasing timestamp

void handleSchemaUpdated(const karabo::util::Schema &schema, const karabo::util::Timestamp &stamp)

Called when a Schema update arrive for logging

Parameters
  • schema: - the new one
  • stamp: - the timestamp to be assigned for that update

unsigned int newPropLogRate(const std::string &propPath, karabo::util::Epochstamp currentStamp, std::size_t currentSize)

Calculates what the value of the property logging rate of the device will be when the logging of a value with a given size and a given timestamp is taken into account.

Return
The updated value of the property logging rate, in bytes/sec, taking the logging of the value into account.
Parameters
  • prop: The path of the property whose current logging rate will be evaluated.
  • currentStamp: The current property update timestamp.
  • currentSize: The size for the new data to be logged - this is used along with the other records in the current log rating window to calculate the new value for the property logging rate.

unsigned int newSchemaLogRate(std::size_t schemaSize)

Calculates what the value of the schema logging rate of the device will be when the logging of a schema with a given size is taken into account. As schemas currently don’t have associated time information, the current system time is used for all the timing references.

Return
The updated value of the schema logging rate, in bytes/sec, taking the logging of the schema into account.
Parameters
  • schemaSize: The size for the new schema to be logged - this is used along with the other records in the current log rating window to calculate the new value for the schema logging rate.

bool logNewSchema(const std::string &schemaDigest, const std::vector<char> &schemaArchive)

Logs a new schema into the corresponding device’s __SCHEMA measurement. It is assumed that the verification of the uniquiness of the device schema has already been verified based on its digest.

Return
true If the new schema has been successfuly submitted for logging.
Return
false If the logging of the new schema has not been submitted for logging. Currently, this happens if logging the new schema would be above the allowed schema logging rate threshold for a device.
Parameters
  • schemaDigest: The digest (assumed unique) of the new schema to be saved.
  • schemaArchive: The serialised schema to be saved

void logRejectedData(const std::vector<RejectedData> &rejects, unsigned long long ts)

Logs the given set of rejected data in the BAD__DATA measurement and to the Karabo log. To avoid spanning of the Karabo log, log is emmitted for each device only once in a period of 30 secs.

Parameters
  • rejects: The rejected data to be logged.
  • ts: An epoch with the precision expected in the InfluxDb.

void logRejectedDatum(const RejectedData &rejects)

Logs the given rejected data record in the BAD__DATA measurement and to the Karabo log. To avoid spanning of the Karabo log, log is emmitted for each device only once in a period of 30 secs.

Parameters
  • rejects: The rejected data to be logged.

struct LoggingRecord
#include <InfluxDataLogger.hh>

The size, in characters, and the epoch seconds of a device log entry saved to Influx.

Used for calculating the logging rates associated to a device.

class InfluxLogReader

Inherits from karabo::devices::DataLogReader

Private Functions

void asyncDataCountForProperty(const std::shared_ptr<PropertyHistoryContext> &context)

Triggers the retrieval of the number of data points for a given device property during a time interval.

Parameters
  • context:

void onDataCountForProperty(const karabo::net::HttpResponse &dataCountResp, const std::shared_ptr<PropertyHistoryContext> &ctxt)

Handles the retrieval of the number of data points for an ongoing GetPropertyHistory process. Responsible for invoking the appropriate async method for retrieving the property values depending on the number of data points received.

Parameters
  • dataCountResponse:
  • context:

void asyncGetPropertyValues(const std::shared_ptr<PropertyHistoryContext> &ctxt)

Triggers the retrieval of the property values in an ongoing GetPropertyHistory process.

Parameters
  • context:

void asyncGetPropertyValuesMean(const std::shared_ptr<PropertyHistoryContext> &ctxt)

Triggers the retrieval of the property values mean in an ongoing GetPropertyHistory process. This is used when the number of available data points for the property is larger than the maximum requested by the slot caller and all values are scalar numbers. The UINT64 properties are included in this despite being reinterpreted as INT64 on the backend and possibly returning incorrect data.

Parameters
  • context:

void asyncGetPropertyValuesSamples(const std::shared_ptr<PropertyHistoryContext> &ctxt)

Triggers the retrieval of the property values samples in an ongoing GetPropertyHistory process. This is used when the number of available data points for the property is larger than the maximum requested by the slot caller.

Parameters
  • context:

void onPropertyValues(const karabo::net::HttpResponse &valuesResp, const std::string &columnPrefixToRemove, const std::shared_ptr<PropertyHistoryContext> &ctxt)

Handles the retrieval of the values of a property in an ongoing GetPropertyHistory process. Responsible for transforming the json formatted values received from InfluxDbClient into a vector of hashes suitable to be returned to the slot caller. Also responsible for replying to the slot caller.

Parameters
  • valuesResp:
  • columnPrefixToRemove:
  • context:

void onMeanPropertyValues(const karabo::net::HttpResponse &valuesResp, const std::shared_ptr<PropertyHistoryContext> &ctxt)

Handles the retrieval of the values of a property in an ongoing GetPropertyHistory process. Responsible for transforming the json formatted values received from InfluxDbClient into a vector of hashes suitable to be returned to the slot caller. This function extends the functionality of onPropertyValues while keeping the property history protocol.

Also responsible for replying to the slot caller.

Parameters
  • valuesResp:
  • context:

std::string unescapeLoggedString(const std::string &loggedStr)

Unescapes a logged string. A logged string has its new lines mangled, then its double slashes escaped and then its double quotes escaped. This functions applies those transformations in the reverse order.

Return
The unescaped original string.
Parameters
  • loggedStr: The string as it has been escaped by the Influx Logger.

bool handleHttpResponseError(const karabo::net::HttpResponse &httpResponse, const karabo::xms::SignalSlotable::AsyncReply &asyncReply)

Handles a given Http response whenever it indicates an error.

In the InfluxDb client <-> server communication context, any response with a status code greater or equal to 300 is considered an error and will be handled by this method.

The error handling consists of sending the appropriate error reply to the caller of the InfluxLogReader slot affected by the error and of optionally disconnecting the InfluxDbClient used by the slot.

Return
true if the httpResponse indicated an error that has been handled. false if the httpResponse didn’t indicate an error.
Parameters
  • httpResponse: the response that potentially indicates an error.
  • asyncReply: the reply to be sent to the caller of the slot where the error happened.

karabo::util::Epochstamp toEpoch(unsigned long long timeFromInflux) const

Convert a time point from influx to karabo Epochstamp

karabo::util::Hash buildInfluxClientConfig(const std::string &dbUrlForSlot) const

Builds and returns the configuration Hash for instantiating an InfluxDbClient to be used in the execution of one of the slots supported by the reader.

Return
the configuration Hash for the InfluxDbClient.
Parameters
  • dbUrlForSlot: the URL to be used in the configuration - each slot can use a different database URL.

class PropertyTest
#include <PropertyTest.hh>

The PropertyTest device includes all types Karabo knows about in it’s expected parameter section. It is a test device to assure changes to the framework do not result in broken types.

Inherits from karabo::core::Device<>

Private Functions

void orderTest_slotStart()

The order test started with this slot works as follows:

  • ’stringProperty’ defines the ‘other’ PropertyTest device supposed to send messages to us
  • ’int32Property’ defines how many messages it should send
  • the number of messages and our own id are transferred to the other device
  • we connect our ‘slotCount’ to the other’s ‘signalCount’
  • we call the other’s ‘slotStartCount’ which will trigger sending messages to us, alternating between direct calls to our ‘slotCount’ and emitting ‘signalCount’ with count arguments starting from 0
  • we keep track of all counts received and their order (so do not run with billions of counts!)
  • end of messaging is signaled to us via a call with count = -1
  • we publish the number of received messages and those counts (well, up to 1000 only) that are not in order as “orderTest.receivedCounts” and “orderTest.nonConsecutiveCounts”, respectively.

struct PropFileInfo
#include <FileLogReader.hh>

A compound structure holding data on an logger archive file.

Python Service Devices