Skip to content

GuiServerDevice

class GuiServerDevice : public karabo::core::Device

@brief 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. Conversely, it handles requests by clients and passes them on to devices in the distributed system.

Variables

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

Functions

Name Description
initUsersActionsLog @brief Initializes the user actions log.
logUserAction @brief Adds an entry with a given text to the user actions log.
loggerMapConnectedHandler Wrapping requestNoWait
postReconfigure Called if configuration changed from outside.
startDeviceInstantiation Starts the deadline timer which throttles device instantiation.
startNetworkMonitor Starts the deadline timer which triggers network stats collection
startMonitorConnectionQueues Starts the deadline timer which monitors connection queues currentSuspects : Hash with pending message counts - keys are bad client addresses
collectNetworkStats Perform network stats collection
deferredDisconnect writes a message to the specified channel with the given priority channel : message : prio : Deferred disconnect handler.
safeAllClientsWrite writes message to all channels connected to the gui-server device message : prio :
sendLoginErrorAndDisconnect @brief Sends a login error message to the client currently connected and closes the connection after a time interval elapses.
onError an error specified by ErrorCode e occurred on the given channel.
violatesReadOnly validate the incoming type and info hash if a readOnly command is requested to be executed type : info : Return : bool whether the request violates read-only restrictions
isProjectLoadingReplyType @brief Checks whether a given reply type requested by a GUI Client is for a request involved in the Load Project operation.
violatesClientConfiguration validates the client configuration currently only validating the type versus the client version.
onGuiInfo an info further specified by hash occurred on a connection to a GUI client.
onConnect connects a client on to the GUI server on channel.
registerConnect @brief Creates an internal ChannelData structure mapped to the TCP Channel in charge of the connection between the GUI Client and the GUI Server.
onWaitForLogin @brief Handler for login messages expected to be sent by a GUI Client right after it establishes a TCP connection to the GUI Server.
onLogin @brief Handles a login request of a user on a GUI client.
onTokenAuthorizeResult @brief Handles the result of the authorize one-time token operation performed as part of a GUI client login on behalf of an authenticated user.
onSessionExpiration @brief Handles a session expired event communicated by an internal instance of GuiServerSessionManager.
onEndSessionNotice @brief Handles a "session about to expire" event.
onTemporarySessionExpiration @brief Handles a temporary session expired event communicated by an internal instance of GuiServerSessionManager.
onEndTemporarySessionNotice @brief Handles a "temporary session about to expire" event.
onRead handles incoming data in the Hash info from channel.
setTimeout 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(instanceKey) is one instance of the classes in "ignoreTimeoutClasses".
forwardReconfigureReply Callback helper for onReconfigure success : whether call succeeded channel : who requested the call input : will be copied to the key input of the reply message
forwardHashReply Callback helper for generic actions called by the gui server.
onRequestGeneric Request a generic action internally.
onReconfigure 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 channel : to potentially send "reconfigureReply" info :
onBeginTemporarySession @brief Handles a message of type "beginTemporarySession" by starting a temporary session on top of the current user-authenticated session (if there's one).
onBeginSessionResult @brief Handles the result of an "login" request sent by a connected client.
onBeginTemporarySessionResult @brief Handles the result of an "beginTemporarySession" request sent by a connected client.
onEndTemporarySession @brief Handles a message of type "endTemporarySession" by ending the current temporary session (if there's one).
forwardExecuteReply Callback helper for onExecute success : whether call succeeded channel : who requested the call input : will be copied to the key input of the reply message
onExecute Calls a command slot on a specified device.
onInitDevice Enqueues a future device instantiation.
initSingleDevice Instructs the server at serverId to try initializing the device at deviceId as given in info.
initReply is the callback for the onInitDevice method.
onGetDeviceConfiguration requests the current device configuration for deviceId specified in info and sends it back in a hash message on channel.
onKillServer instructs the server specified by serverId in info to shutdown.
onKillDevice instructs the device specified by deviceId in info to shutdown.
onStartMonitoringDevice 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.
onStopMonitoringDevice De-registers the client connected by channel from the device specified by deviceId in info.
onGetClassSchema requests a class schema for the classId on the server specified by serverId in info.
onGetDeviceSchema requests a device schema for the device specified by deviceId in info.
onGetPropertyHistory requests the history for a property on deviceId in the time range t0 and t1 as specified in info.
propertyHistory Callback for onGetPropertyHistory.
onGetConfigurationFromPast Request configuration for a device at point in time time as specified in info.
configurationFromPast Success callback for onGetDeviceConfiguration
configurationFromPastError Failure callback for onGetDeviceConfiguration
getDataReaderId Helper for history retrieval functions deviceId : of the device whose history is searched for Return : id of DataLogReader device to ask for history
onSubscribeNetwork registers the client connected on channel to a pipe-lined processing channel identified by channelName in info in case subscribe is true.
onSubscribeLogs Kept to reply back that log subscription not supported anymore after 2.16.X channel : info :
onSetLogPriority sets the Log priority on a server.
forwardSetLogReply Callback helper for onSetLogPriority success : whether call succeeded channel : who requested the call input : will be copied to the key input of the reply message
onRequestNetwork Receives a message from the GUI client that it processed network data from an output channel with name channelName in the info Hash.
onNetworkData 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.
sendSystemTopology sends the current system topology to the client connected on channel.
instanceNewHandler sends the current system topology to the client connected on channel.
instanceChangeHandler Handles events related to instances: new instance, instance updated, instance gone. @Note: Its signature matches karabo::core::InstanceChangeThrottler::InstanceChangeHandler).
devicesChangedHandler Acts upon incoming configuration updates from one or more devices.
slotGetClientSessions @brief Retrieve information about the current client sessions of the GUI server.
slotProjectUpdate Called from projectManagers to notify about updated Projects info: : the info hash containing the information about the updated projects instanceId: : the instance id of the project manager device
slotDumpToLog Slot to dump complete debug info to log file Same info as received from 'slotDumpDebugInfo' with empty input Hash
slotNotify Slot to send a notification message to all clients connected - replies empty Hash 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
slotBroadcast 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. 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.
requestScene Slot to provide scene info : Hash with key "name" that provides string identifying which scene
getDebugInfo Helper for 'slotDumpToLog' and 'slotDumpDebugInfo'
slotDisconnectClient Slot to force disconnection of client.
typeAndInstanceFromTopology Returns the instance type and instance id from a topology entry topologyEntry: : a Hash of the topology format type: : string which will afterwards contain type instanceId: : string which will be filled with the instance id
allowLock This device may not be locked Return : false
registerPotentialProjectManager Checks if an instance at instanceId is a ProjectManager.
getKnownProjectManagers Return a list of project services known to this GUI server Return :
checkProjectManagerId Check if a given project manager identified by id is known in the distributed system channel : to forward a failure message to if not deviceId : of the project manager device type : of the request Return : true if the project manager id exists in the distributed system
getChannelAddress Utility for getting a "name" from client connections.
skipExecutionTimeout 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
recalculateTimingOutDevices 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

Variable Details

m_errorDetailsDelim

static const std::string m_errorDetailsDelim

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

Function Details

allowLock

bool allowLock() const

This device may not be locked

Return : false

checkProjectManagerId

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

channel : to forward a failure message to if not

deviceId : of the project manager device

type : of the request

Return : true if the project manager id exists in the distributed system

collectNetworkStats

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

Perform network stats collection

configurationFromPast

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

Success callback for onGetDeviceConfiguration

configurationFromPastError

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

Failure callback for onGetDeviceConfiguration

deferredDisconnect

void deferredDisconnect(WeakChannelPointer channel)

writes a message to the specified channel with the given priority

channel :

message :

prio : Deferred disconnect handler.

devicesChangedHandler

void devicesChangedHandler(const karabo::data::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.

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.

forwardExecuteReply

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

Callback helper for onExecute

success : whether call succeeded

channel : who requested the call

input : will be copied to the key input of the reply message

forwardHashReply

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

Callback helper for generic actions called by the gui server.

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

forwardReconfigureReply

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

Callback helper for onReconfigure

success : whether call succeeded

channel : who requested the call

input : will be copied to the key input of the reply message

forwardSetLogReply

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

Callback helper for onSetLogPriority

success : whether call succeeded

channel : who requested the call

input : will be copied to the key input of the reply message

getChannelAddress

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

Utility for getting a "name" from client connections.

getDataReaderId

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

Helper for history retrieval functions

deviceId : of the device whose history is searched for

Return : id of DataLogReader device to ask for history

getDebugInfo

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

Helper for 'slotDumpToLog' and 'slotDumpDebugInfo'

getKnownProjectManagers

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

Return a list of project services known to this GUI server

Return :

initReply

void initReply(WeakChannelPointer channel, const std::string& givenDeviceId, const karabo::data::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.

channel :

givenDeviceId :

givenConfig :

success :

message :

initSingleDevice

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

error :

initUsersActionsLog

void initUsersActionsLog()

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

instanceChangeHandler

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

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

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

instanceNewHandler

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

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

channel :

isProjectLoadingReplyType

bool isProjectLoadingReplyType(const std::string& replyType)

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

replyType : the string that specifies the reply type.

Return : bool is the reply type involved in the Load Project operation?

logUserAction

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

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

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)

loggerMapConnectedHandler

void loggerMapConnectedHandler()

Wrapping requestNoWait

onBeginSessionResult

void onBeginSessionResult(const WeakChannelPointer& channel, const std::string& clientId, const karabo::util::Version& clientVersion, const bool isLoginOverLogin, const karabo::devices::BeginSessionResult& result)

@brief Handles the result of an "login" request sent by a connected client.

channel : the TCP channel connecting to the client that requested the session

clientId : an identification of the GUI Client that originated the login request

clientVersion : the version of the GUI client logging in.

isLoginOverLogin : is the token being authorized in the context of a login over an existing user session (true) or of a login that is starting a completely new user session?

result : the result of the begin session operation that will be communicated back to the client.

Note

a login over an existing user session has the potentially "desired side-effect" of just "refreshing" an existing user session, by updating its start time. This is useful when the maximum retention time for a token session is about to expire - the user can be instructed to refresh his/her login to keep going on the same GUI Client connection. This is the primary reason for the GUI Server not caring if the login over login corresponds to a user change or not.

onBeginTemporarySession

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

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

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 successfully authorized for the temporary session to be started.

onBeginTemporarySessionResult

void onBeginTemporarySessionResult(WeakChannelPointer channel, karabo::data::Schema::AccessLevel levelBeforeTemporarySession, const BeginSessionResult& result)

@brief Handles the result of an "beginTemporarySession" request sent by a connected client.

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.

onConnect

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.

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

channel :

onEndSessionNotice

void onEndSessionNotice(const EminentExpirationInfo& info)

@brief Handles a "session about to expire" event.

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

info : data about the session about to expire.

onEndTemporarySession

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

@brief 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".

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.

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

onEndTemporarySessionNotice

void onEndTemporarySessionNotice(const EminentExpirationInfo& info)

@brief 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".

info : data about the temporary session about to expire.

onError

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.

e :

channel :

onExecute

void onExecute(WeakChannelPointer channel, const karabo::data::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

channel :

info :

onGetClassSchema

void onGetClassSchema(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onGetConfigurationFromPast

void onGetConfigurationFromPast(WeakChannelPointer channel, const karabo::data::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.

onGetDeviceConfiguration

void onGetDeviceConfiguration(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onGetDeviceSchema

void onGetDeviceSchema(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onGetPropertyHistory

void onGetPropertyHistory(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onGuiInfo

void onGuiInfo(const karabo::data::Hash& hash)

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

hash :

onInitDevice

void onInitDevice(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onKillDevice

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

instructs the device specified by deviceId in info to shutdown.

info :

onKillServer

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

instructs the server specified by serverId in info to shutdown.

info :

onLogin

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

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

channel : the TCP channel between the GUI client and the GUI server

info : Hash with information needed to validate the login request.

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.

onNetworkData

void onNetworkData(const std::string& channelName, const karabo::data::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.

channelName: : name of the InputChannel that provides these data

data: : the data coming from channelName

meta: : corresponding meta data

onRead

void onRead(const karabo::net::ErrorCode& e, WeakChannelPointer channel, karabo::data::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:

``` embed:rst:leading-asterisk

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

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

channel :

info :

readOnly :

onReconfigure

void onReconfigure(WeakChannelPointer channel, const karabo::data::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

channel : to potentially send "reconfigureReply"

info :

onRequestGeneric

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

Request a generic action internally.

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

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

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

onRequestNetwork

void onRequestNetwork(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onSessionExpiration

void onSessionExpiration(const ExpiredSessionInfo& info)

@brief Handles a session expired event communicated by an internal instance of GuiServerSessionManager.

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

info : data about the expired session.

onSetLogPriority

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

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

channel :

info :

onStartMonitoringDevice

void onStartMonitoringDevice(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onStopMonitoringDevice

void onStopMonitoringDevice(WeakChannelPointer channel, const karabo::data::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.

channel :

info :

onSubscribeLogs

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

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

channel :

info :

onSubscribeNetwork

void onSubscribeNetwork(WeakChannelPointer channel, const karabo::data::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 further 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.

channel :

info :

onTemporarySessionExpiration

void onTemporarySessionExpiration(const ExpiredSessionInfo& info)

@brief Handles a temporary session expired event communicated by an internal instance of GuiServerSessionManager.

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

info : data about the expired temporary session.

onTokenAuthorizeResult

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

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

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.

isLoginOverLogin : is the token being authorized in the context of a login over an existing user session (true) or of a login that is starting a completely new user session?

authResult : the result of the one-time token authorization operation to be handled.

Note

a login over an existing user session has the potentially "desired side-effect" of just "refreshing" an existing user session, by updating its start time. This is useful when the maximum retention time for a token session is about to expire - the user can be instructed to refresh his/her login to keep going on the same GUI Client session. This is the primary reason for the GUI Server not caring if the login over login corresponds to a user change or not.

onWaitForLogin

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

@brief 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::data::Hash&)

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.

postReconfigure

virtual void postReconfigure()

Called if configuration changed from outside.

propertyHistory

void propertyHistory(WeakChannelPointer channel, bool success, const std::string& deviceId, const std::string& property, const std::vector<karabo::data::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.

channel :

success : whether the request succeeded

deviceId :

property :

data :

recalculateTimingOutDevices

void recalculateTimingOutDevices(const karabo::data::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

registerConnect

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

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

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

registerPotentialProjectManager

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

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

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

requestScene

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

Slot to provide scene

info : Hash with key "name" that provides string identifying which scene

safeAllClientsWrite

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

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

message :

prio :

sendLoginErrorAndDisconnect

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

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

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.

sendSystemTopology

void sendSystemTopology(WeakChannelPointer channel)

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

channel :

setTimeout

void setTimeout(karabo::xms::SignalSlotable::Requestor& requestor, const karabo::data::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(instanceKey) is one instance of the classes in "ignoreTimeoutClasses".

skipExecutionTimeout

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

slotBroadcast

void slotBroadcast(const karabo::data::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.

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.

slotDisconnectClient

void slotDisconnectClient(const std::string& client)

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

client : string to identify client, as can be received via slotDumpDebugInfo(Hash("clients", 0))

slotDumpToLog

void slotDumpToLog()

Slot to dump complete debug info to log file

Same info as received from 'slotDumpDebugInfo' with empty input Hash

slotGetClientSessions

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

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

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.

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

slotNotify

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

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

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

slotProjectUpdate

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

Called from projectManagers to notify about updated Projects

info: : the info hash containing the information about the updated projects

instanceId: : the instance id of the project manager device

startDeviceInstantiation

void startDeviceInstantiation()

Starts the deadline timer which throttles device instantiation.

startMonitorConnectionQueues

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

Starts the deadline timer which monitors connection queues

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

startNetworkMonitor

void startNetworkMonitor()

Starts the deadline timer which triggers network stats collection

typeAndInstanceFromTopology

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

Returns the instance type and instance id from a topology entry

topologyEntry: : a Hash of the topology format

type: : string which will afterwards contain type

instanceId: : string which will be filled with the instance id

violatesClientConfiguration

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

validates the client configuration

currently only validating the type versus the client version.

type :

channel :

Return : bool whether the request violates client validation

violatesReadOnly

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

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

type :

info :

Return : bool whether the request violates read-only restrictions