Galaxy Communicator Documentation:

The Hub GUI Message Set

License / Documentation home / Help and feedback

The Hub accepts a -gui command line argument which specifies the host:port of a remote server which will replace the normal status messages. The host can be the string <listener>, which indicates that the Hub should set up a listener at the specified port for the server to contact (note that this is not the wisest thing in the world, because the server will miss some important initialization messages). This remote server can implement profiling and visualization functionality. Any programmer can implement such a server. In this document, we describe the message set this server must support.

We've implemented two servers which exemplify this functionality. The one we will describe here along with the message set is a trivial template for such servers. We've also provided with the Open Source Toolkit an extensive Java tool which implements this message set which visualizes the Hub activity.

Usage

These usage notes apply only to the sample server.

Command line

<GALAXY_ROOT>/contrib/MITRE/tools/bin/sample_hub_gui ...

Default port

4111

Command line arguments

The sample utility only accepts the standard server arguments.

Message set

These messages are all sent to the remote server by the Hub automatically. It is not possible to refer to the GUI server directly in a Hub program, but it is possible to use the Builtin function hub_gui_notify to relay a message to the GUI, if present.

provider_status is used to inform the GUI about new service providers (or changes in the status of an existing provider, e.g., when a provider connects/disconnects from the Hub). The contents of each provider frame at connection time is determined partially by the PROPERTIES: directives associated with the provider (technically, it's the service provider's properties themselves, but the client API won't have an opportunity to apply before this status message is sent). So you might specify a screen name for a provider as follows:
SERVICE_PROVIDER: Parser
PROPERTIES: :screen_name "My Parser"
If the server properties contain the :gui_invisible key, the GUI will not receive any status messages about the server.

  parameter type optional depends on description/constraints
IN: :provider_list list     Contains list of service provider frames. In each frame, the Hub GUI recognizes at least these keys:
  • :provider_id (string, required) is the provider ID of a service provider.
  • :init, if present, indicates that the provider is being declared rather than being referenced (if :init is absent and the value indicated by :provider_id is unknown, the frame will be ignored).
  • :hub_is_client, cooccurs with the :init key; if present, indicates that the provider is one that the Hub contacted, rather than one that contacted the Hub.
  • :connected (integer, required) is 0 if the provider is not connected to the Hub and 1 if it is.
  • :available (integer, optional) is 1 if the provider is available (i.e., currently being used). In most cases, this will be the case. You can use this key in the GUI that you write to, e.g., grey out servers which currently aren't on the active path.
  • :screen_name (string, required when the provider is first added to the GUI) is the name to be used for this provider in the GUI.
  • :icon (string, optional) is the full path to the icon (JPG or GIF) to be used for this provider in the GUI.
  • :menu_items (list, optional) is a list of string/frame pairs (each pair represented as a list) that correspond to menu items for the provider. When the menu item is selected via the GUI, the specified frame is sent to the Hub.

This message returns NULL.
 

add_menu_items can be used to added general menu items to the remote server, if is it really a GUI.
 
  parameter type optional depends on description/constraints
IN: :menu_items list     Contains a list of string/frame pairs (each pair represented as a list) that correspond to general menu items for the GUI (i.e., not tied to a specific service provider). When the menu item is selected via the GUI, the specified frame is sent to the Hub.

This message returns NULL.
 

new_service_type alerts the GUI to the introduction of a new provider of a given service type.
 
  parameter type optional depends on description/constraints
IN: :name string     Name of the new service type of the new provider.
  :port integer     Port on which the service provider is listening.

This message returns a frame.
 

message_event indicates to the GUI that a message was sent (either Hub to service provider or provider to Hub).
 
  parameter type optional depends on description/constraints
IN: :provider_id integer     The provider ID of a service provider
  :msg frame     The message being sent.
  :msg_type integer     The type of message sent
  :destination string     If equal to "server", the message is being sent from the Hub to a server. Otherwise, the message is being sent from a server to the Hub.

This message returns NULL.
 

session_status contains information about the current sessions in the system.
 
  parameter type optional depends on description/constraints
IN: :action integer     The ID of the action. Valid values are GAL_HUB_SESSION_SETTINGS (0), GAL_HUB_SESSION_CREATED (1), GAL_HUB_SESSION_DESTROYED (2), and GAL_HUB_SESSION_HISTORY (3).
  :session_id string     If the action is GAL_HUB_SESSION_CREATED or GAL_HUB_SESSION_DESTROYED, this is the ID of the session that was created or destroyed. Otherwise, this key is not needed.
  :settings frame     If the action is GAL_HUB_SESSION_SETTINGS, this frame includes information about the settings of all current sessions. Otherwise, this key is not needed.
  :history frame     If the action is GAL_HUB_SESSION_HISTORY, this frame includes historical information about sessions. Otherwise, this key is not needed.
  :debug integer yes   If present, this key indicates that this status information is being sent in response to a Hub debug command issued by the GUI. The status information is displayed in the GUI's debug window.

This message returns NULL.
 

session_lock_status contains information about session locks.
 
  parameter type optional depends on description/constraints
IN: :action integer     The ID of the action. Valid values are GAL_HUB_SESSION_LOCK_STATUS (0), GAL_HUB_SESSION_LOCK_SET (1), and GAL_HUB_SESSION_LOCK_RELEASED (2).
  :providers_sessions list     If the action is GAL_HUB_SESSION_LOCK_STATUS, this list of string/string pairs indicates which sessions can write to which service providers.
  :providers_sessions_readers list     If the action is GAL_HUB_SESSION_LOCK_STATUS, this list of string/string pairs indicates which service providers are reading from which sessions.
  :providers_sessions_writers list     If the action is GAL_HUB_SESSION_LOCK_STATUS, this list of string/string pairs indicates which service providers are writing to which sessions.
  :lock_type integer     If the action is GAL_HUB_SESSION_LOCK_SET or GAL_HUB_SESSION_LOCK_RELEASED, this is the type of lock that was set or released.
  :session_id string     If the action is GAL_HUB_SESSION_LOCK_SET or GAL_HUB_SESSION_LOCK_RELEASED, this is the session that was locked or unlocked.
  :debug integer yes   If present, this key indicates that this status information is being sent in response to a Hub debug command issued by the GUI. The status information is displayed in the GUI's debug window.

This message returns NULL.
 

session_alarm_status contains information about session alarms.
 
  parameter type optional depends on description/constraints
IN: :action integer     The ID of the action. Valid values are GAL_HUB_SESSION_ALARM_STATUS (0), GAL_HUB_SESSION_ALARM_ENABLED (1),  GAL_HUB_SESSION_ALARM_DISABLED (2), GAL_HUB_SESSION_ALARM_RESET (3), and GAL_HUB_SESSION_ALARM_EXPIRED (4).
  :alarm_key string     This is the alarm ID.
  :session_id string     If the action is GAL_HUB_SESSION_ALARM_STATUS, this is the id of the session that owns the alarm.
  :expiration_secs integer     If the action is GAL_HUB_SESSION_ALARM_STATUS or GAL_HUB_SESSION_ALARM_RESET, this is the number of seconds that the alarm is set to expire after.
  :remaining_secs integer     If the action is GAL_HUB_SESSION_ALARM_STATUS, this is the number of seconds remaining before the alarm expires.

This message returns NULL.
 

token_status contains information about tokens.
 
  parameter type optional depends on description/constraints
IN: :action integer     The ID of the action. Valid values are GAL_HUB_TOKEN_STATUS (0),  GAL_HUB_TOKEN_CREATED (1), and GAL_HUB_TOKEN_DESTROYED (2).
  :state frame     Information on the current tokens.
  :tidx string     If the action is GAL_HUB_TOKEN_CREATED or GAL_HUB_TOKEN_DESTROYED, this is the id of the token that was created or destroyed.
  :debug integer yes   If present, this key indicates that this status information is being sent in response to a Hub debug command issued by the GUI. The status information is displayed in the GUI's debug window.

This message returns NULL.
 

listener_status contains information about the Hub listener.
 
  parameter type optional depends on description/constraints
IN: :action integer     The ID of the action. Valid values are GAL_HUB_LISTENER_INITIALIZED (0) and GAL_HUB_LISTENER_INITIALIZATION_ERROR (1).
  :port integer     If the action is GAL_HUB_LISTENER_INITIALIZED, this is the port that the Hub listener is using.
  :reused integer     If the action is GAL_HUB_LISTENER_INITIALIZED, if this is 1, the Hub listener is reusing the specified port.

This message returns NULL.
 

message_queue_status contains information about the message queue.
 
  parameter type optional depends on description/constraints
IN: :action integer     The id of the action. The only valid value is GAL_HUB_MESSAGE_QUEUE_CONTENTS (0).
  :queue 32-bit integer array     Array of the token ids of the messages currently in the queue.

This message returns NULL.
 

hub_debug_prompt is invoked to cause the GUI to prompt the user for a Hub debug command. This message takes no input, and it postpones its reply. See Messages issued.
 

hub_debug_info is used to report miscellaneous Hub debug information to the GUI.
 
  parameter type optional depends on description/constraints
IN: :type string yes   A string that indicates what type of information is being provided.
  :frame frame yes   A frame containing debug information.
  :msg string yes   A text message containing debug information.

This message returns NULL.

Messages issued

When the GUI server receives a hub_debug_prompt message, it prompts the user for a Hub debug command. Once that command is specified, it is sent to the Hub via a hub_debug_cmd message:
 
{c hub_debug_cmd
    :debug_cmd <string form of debug command>
}
License / Documentation home / Help and feedback
Last updated August 13, 2002