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 boost::function<void(const BeginTemporarySessionResult&)>
-
using
karabo::devices::ExpirationHandler = typedef boost::function<void(const ExpiredTemporarySessionInfo&)>
Handler for expired temporary session events.
-
using
karabo::devices::EminentExpirationHandler = typedef boost::function<void(const EminentExpirationInfo&)>
Handler for “temporary session about to expire” events.
-
using
karabo::devices::AsyncHandler = typedef boost::function<void()>
-
using
karabo::devices::InfluxResponseHandler = typedef boost::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 removevectorProp
: 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 addvectorProp
: 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
Helper for connecting to both signalChanged and signalStateChanged.
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
“Flush” data accumulated in the internal cache to the external storage (file, database,…)
-
bool
allowLock
() const This device may not be locked
- Return
- false
-
void
-
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 loggedaddIfNotYetInMap
: 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/classesnewList
: new configuration for blocked devices/classes
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.
-
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 ¶ms) 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 forproperty
: path to the property for which to get the history fromparams
: 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:
- 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;
- 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;
- 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 fromtimepoint
: 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
-
void
-
struct
DeviceData
Inherits from boost::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 timestampsthe
: 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 onestamp
: - 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.
-
virtual void
-
class
FileDataLogger
Inherits from karabo::devices::DataLogger
Private Functions
“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 timestampsthe
: 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
-
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 ×tamp, 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
-
void
-
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 ¤tSuspects) 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 slotchannel
:
-
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 clientchannel
: the TCP channel for the connection being registereduserId
: the ID of the user logged in the connected GUI ClientoneTimeToken
: 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 closedchannel
: the TCP channel for the recently established connection with a GUI clientinfo
: 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 serverinfo
: 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
fromchannel
. The further actions are determined by the contents of thetype
property ininfo
. Valid types and there mapping to methods are given in the following table:¶ 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 closedchannel
: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 succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 succeededchannel
: who requested the callinfo
: the input info Hashreply
: 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 originatesinfo
: 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 otherwiserequestGeneric
- 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 typereconfigureReply
that containsinput
: the Hash given here asinfo
success
: bool whether reconfiguration succeededfailureReason
: string with failure reason
- optional int at
timeout
: if a reply should be reported back, defines seconds of timeout. In casetimeout
is missing, timeout errors will reportsuccess
as true but provides afailureReason
mentioning the timeout
- Parameters
channel
: to potentially send “reconfigureReply”info
:
- string at
-
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 succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 typeexecuteReply
that containsinput
: the Hash given here asinfo
success
: bool whether execution succeededfailureReason
: string with failure reason
- optional int at
timeout
: if a reply should be reported back, defines seconds of timeout. In casetimeout
is missing, timeout errors will reportsuccess
as true but provides afailureReason
mentioning the timeout- Parameters
channel
:info
:
- string at
-
void
onInitDevice
(WeakChannelPointer channel, const karabo::util::Hash &info) Enqueues a future device instantiation. The relevant information will be stored in
m_pendingDeviceInstantiations
andinitSingleDevice
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 atdeviceId
as given ininfo
. The reply from the device server is registered to theinitReply
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 callingchannel
in form of a hash message withtype=initReply
,deviceId
,success
andmessage
fields.- Parameters
channel
:givenDeviceId
:givenConfig
:success
:message
:
-
void
onGetDeviceConfiguration
(WeakChannelPointer channel, const karabo::util::Hash &info) requests the current device configuration for
deviceId
specified ininfo
and sends it back in a hash message onchannel
. The message contains the following fields:type=deviceConfiguration
,deviceId
andconfiguration
. 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
ininfo
to shutdown.- Parameters
info
:
-
void
onKillDevice
(WeakChannelPointer channel, const karabo::util::Hash &info) instructs the device specified by
deviceId
ininfo
to shutdown.- Parameters
info
:
-
void
onStartMonitoringDevice
(WeakChannelPointer channel, const karabo::util::Hash &info) Registers a monitor on the device specified by
deviceId
ininfo
Upon changes of device properties they will be forwarded tochannel
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
forchannel
.- Parameters
channel
:info
:
-
void
onStopMonitoringDevice
(WeakChannelPointer channel, const karabo::util::Hash &info) De-registers the client connected by
channel
from the device specified bydeviceId
ininfo
. If this is the last channel monitoringdeviceId
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 byserverId
ininfo
. This is done through the device client. A hash reply is sent out overchannel
containingtype=classSchema
,serverId
,classId
andschema
.- Parameters
channel
:info
:
-
void
onGetDeviceSchema
(WeakChannelPointer channel, const karabo::util::Hash &info) requests a device schema for the device specified by
deviceId
ininfo
. This is done through the device client. A hash reply is sent out overchannel
containingtype=deviceSchema
,deviceId
, andschema
.- Parameters
channel
:info
:
-
void
onGetPropertyHistory
(WeakChannelPointer channel, const karabo::util::Hash &info) requests the history for a
property
ondeviceId
in the time ranget0
andt1
as specified ininfo
. Additional the maximum number of data points may be specified inmaxNumData
. The request is asynchronously sent to the device logger logging information fordeviceId
. The reply from the logger is then forwarded to the client onchannel
using thepropertyHistory
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 indata
for theproperty
ondeviceId
to the client connected onchannel
. The hash reply is of the formattype=propertyHistory
,deviceId
,property
,success
,data
andfailureReason
which states the failure reason if any.- Parameters
channel
:success
: whether the request succeededdeviceId
:property
:data
:
-
void
onGetConfigurationFromPast
(WeakChannelPointer channel, const karabo::util::Hash &info) Request configuration for a
device
at point in timetime
as specified ininfo
. Theinfo
hash can as well have apreview
boolean which is send back to the client. The request is asynchronously sent to the device logger logging information fordeviceId
. The reply from the logger is then forwarded to the client onchannel
using theconfigurationFromPast
history callback in case of success orconfigurationFromPastError
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 bychannelName
ininfo
in casesubscribe
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 thedelayOnInput
property of the gui server. Network data from the pipe-lined processing connection is handled by theonNetworkData
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 apriority
string and ainstanceId
string.- Parameters
channel
:info
:
-
void
forwardSetLogReply
(bool success, WeakChannelPointer channel, const karabo::util::Hash &input) Callback helper for
onSetLogPriority
- Parameters
success
: whether call succeededchannel
: who requested the callinput
: will be copied to the keyinput
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 anddata
holding the data.- Parameters
channelName
: name of the InputChannel that provides these datadata
: the data coming from channelNamemeta
: corresponding meta data
-
void
sendSystemTopology
(WeakChannelPointer channel) sends the current system topology to the client connected on
channel
. The hash reply containstype=systemTopology
and thesystemTopology
.- Parameters
channel
:
-
void
instanceNewHandler
(const karabo::util::Hash &topologyEntry) sends the current system topology to the client connected on
channel
. The hash reply containstype=systemVersion
and thesystemVersion
.- 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 byonStartMonitoringDevice
.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 projectsinstanceId
: 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 devicetype
: the type of the update: can be alarmUpdate, alarmInitupdateRows
: 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 toinfo
: 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 toinfo
: 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 fieldsreplyToAllClients
: 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 updateinfo
: 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 updatereply
: 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 formattype
: string which will afterwards contain typeinstanceId
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 originatesinfo
: 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 toreplyType
: type of replyreply
: 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 notdeviceId
: of the project manager devicetype
: 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.
-
void
-
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 boost::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 boost::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
-
void
-
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
“Flush” data accumulated in the internal cache to the external storage (file, database,…)
-
void
-
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 timestampsthe
: 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 startssortedPaths
: 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 onestamp
: - 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.
-
void
-
class
InfluxLogReader
Inherits from karabo::devices::DataLogReader
Private Functions
Triggers the retrieval of the number of data points for a given device property during a time interval.
- Parameters
context
:
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
:
Triggers the retrieval of the property values in an ongoing GetPropertyHistory process.
- Parameters
context
:
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
:
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
:
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
:
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.
-
void
-
struct
PropFileInfo
- #include <FileLogReader.hh>
A compound structure holding data on an logger archive file.
-
using