Solution Registry

From wiki.gpii
Jump to: navigation, search

Description

GPII Program Flow-small-solreg.png

The Solution Registry holds metadata about applications, access features, and assistive technologies (referred to as Solutions) that are configurable with the Cloud4all/GPII. Each application entry will have information about how to launch it, set settings, detect whether it's running, available to the user, etc. The solution registry is held in a database (or in case of development, local testing or deployment with no internet - in a flat file). Like all other documents in the Cloud4All reference implementation, the format is JSON.

The solution metadata is used by several components of the GPII;

  • The Matchmaker to know what needs and preferences are matched by solution.
  • The Lifecycle Handler to know how to start and stop the application and detect whether it's running, and similar information used by other lifecycle actions.
  • The Settings Handler for information about how to find and set the preferences
  • The Device Reporter via the Local Solution Registry to find out what solutions are installed on the system.
  • The Transformer for information about transformation between common terms and application specific settings

The solution registry is also where new implementers of GPII/C4A will add an entry (or several) for their solution.

Format of solution entry

WARNING: This section is outdated. Up-to-date information about the format of the solution registry is to be found in the Universal repository on GitHub.

Each application will have at least one solution entry. If it behaves and/or is handled differently in different operating systems, versions, etc., it might have more than one solution entry.

The solution entry is a JSON object with at least the following mandatory fields:

  • name (string): The name of the application/solution in a human readable format.
  • id (string): Should be a unique ID for the application. The general format used is eg. "com.microsoft.win7.magnifier"
  • contexts (object): Describes the context required for this solution to be applicable
  • lifecycleManager (object): Instructions for the lifecycleManager describing what should happen when a user logs in and logs out
  • settingsHandlers (array): An array of describing settings handlers used (and their settings) by this solution

Besides the above, you can optionally specify the following fields:

  • version (string): The version(s) of the application this solution entry is valid for. This should be in a format compatible with [semver]

Below each of the more complex entries (contexts, settingsHandlers and LifecycleManager) will be explained in more detail with examples.

Contexts

The contexts block describes the context required for the solution to run. Currently, only the OS can be checked against, but this will be expanded in later versions of the architecture. The format of a context object is the following:

<syntaxhighlight lang="javascript">

       "contexts": {
           "OS": [
               {
                   "id": "os-id",
                   "version": "semver compatible version requirement"
               },
               {
                   (...) 
               }
           ]
       },

</syntaxhighlight>

"OS" means that this is a requirement to the Operating System context. This is an array that can hold one or more OS requirements. Each requirement block is an object that should contain two things: an ID (as reported by nodejs' os.platform()) and a version requirement written in a semver-compatible way.

Examples
  • Windows 7:

<syntaxhighlight lang="javascript">

       "contexts": {
           "OS": [
               {
                   "id": "win32",
                   "version": ">=5.0"
               }
           ]
       }

</syntaxhighlight>

  • Linux with kernel greater than 2.6.26 (eg. Fedora 16):

<syntaxhighlight lang="javascript">

       "contexts": {
           "OS": [
              {
                   "id": "linux",
                   "version": ">=2.6.26"
               }
           ]
       }

</syntaxhighlight>

Lifecycle Manager

The lifecycleManager section describes the process of setting up the solution and tearing it down again. This configurable process generally includes:

  • In the start of the users session:
    • Taking a snapshot of the device's current settings, so they can be restored later
    • Invoking the appropriate Settings Handler
    • Launching the solution
  • When user is done:
    • Stopping the solution
    • Restoring the previous settings (if required) once the user is finished

Each of these activities is accomplished by a Lifecycle Handler, which are functions that can be registered with the architecture and are responsible for performing a single, specific task of the configuration workflow.

The Lifecycle Manager block has the following format:

<syntaxhighlight lang="javascript">

       "lifecycleManager": {
           "start": [ 
               "setSettings", 
               {
                   "type": "lifecycle.action.function",
                   "arg1": "some argument1",
                   "arg2": true,
                   (...)
               }
           ],
           "stop": [ {
                   "type": "lifecycle.action.other-function",
                   "argA": { "a", "b" },
                   "argB": "other argument",
                   (...)
               },
               "restoreSettings", 
               {
                   "type": "lifecycle.action.other-function",
                   (...)
               }
           ]
       }

</syntaxhighlight>

The Lifecycle Manager instructions will always have the id lifecycleManager, which should be an object with two arrays in it: start and stop. The start array describes what should happen when the user session starts. and the stop array describes the instructions to be carried out on log out. The instructions in the array will be carried out in the given order. The start and stop arrays can contain an arbitrary number of objects referencing different Lifecycle Handlers. There are certain keywords that are recognized as being special actions. this is the strings "setSettings" and "restoreSettings". These can be put instead of an object in the start and stop arrays and will result in Settings Handler setting and restoring the application settings.

The object should have a type that refers to what Lifecycle Handler to execute, and then an arbitrary number of key-value pairs for arguments to the Lifecycle Handler. There is a range of lifecycle actions available - these are described in details with examples on the Lifecycle Handler page.

Below are some examples of Lifecycle Manager blocks - for details on the lifecycle actions objects, see: Lifecycle Handler

Examples

  • Windows 7 - built in magnifier using the environment variable SYSTEMROOT:

<syntaxhighlight lang="javascript">

       "lifecycleManager": {
           "start": [ 
               "setSettings", 
               {
                   "type": "gpii.launch.exec",
                   "command": "${{environment}.SystemRoot}\\System32\\Magnify.exe"
               }
           ],
           "stop": [ 
               {
                   "type": "gpii.launch.exec",
                   "command": "${{environment}.SystemRoot}\\System32\\taskkill.exe /f /im Magnify.exe"
               },
               "restoreSettings"
           ]
       }

</syntaxhighlight>

  • Gnome 3 (Linux) - built in onscreen magnifier

<syntaxhighlight lang="javascript">

       "lifecycleManager": {
           "start": [
               {
                   "type": "gpii.gsettings.setSingleKey",
                    "schemaId": "org.gnome.desktop.a11y.applications",
                    "key": "screen-magnifier-enabled",
                    "value": "true"
               }
           ],
           "stop": [
               {
                   "type": "gpii.gsettings.setSingleKey",
                    "schemaId": "org.gnome.desktop.a11y.applications",
                    "key": "screen-magnifier-enabled",
                    "value": "true"
               }
           ]
       }

</syntaxhighlight>

Settings Handlers

The Settings Handlers are a type of special type of Lifecycle Handler that are responsible for configuring the settings of an application, access feature, or assistive technology, and the details of this is declared in the settingsHandlers block. It should be an array of objects, where each object declares a Settings Handler and it's properties. The settings handlers will be called in the order they are declared in the array.

Below is the format of the settingsHandlers block shown:

<syntaxhighlight lang="javascript">

       "settingsHandlers": [
           {
               (.. settings handler 1 ..)
           }, {
               (.. settings handler 2 ..)
           }
       ],

</syntaxhighlight>

Depending on the solution, the setting handler declarations might be quite complex. Out of the box, the Cloud4all/GPII architecture ships with the following Settings Handlers:

  • XML files
  • JSON Files
  • Linux GSettings
  • Linux DBus
  • Windows Registry
  • Windows SystemParametersInfo

These are described along with examples on the Settings Handlers page. Below are some examples of settingsHandlers blocks. Dont worry if it looks complicated, a quick read of Settings Handler, and you should be equipped to writing your own settingsHandler blocks:

  • Windows 7 - built in magnifier (with only magnification setting declared, and being transformed (scaled by 100)):

<syntaxhighlight lang="javascript">

"settingsHandlers": [

           {
               "type": "gpii.windows.registrySettingsHandler",
               "options": {
                   "hKey": "HKEY_CURRENT_USER",
                   "path": "Software\\Microsoft\\ScreenMagnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.com\\.microsoft\\.windows\\.magnifier.name"
               ],
               "capabilitiesTransformations": {
                   "Magnification": {
                       "expander": {
                           "type": "gpii.transformer.scaleValue",
                           "inputPath": "display.screenEnhancement.magnification",
                           "outputPath": "value",
                           "factor": 100
                       },
                       "dataType": {
                           "expander": {
                               "type": "fluid.model.transform.literalValue",
                               "value": "REG_DWORD"
                           }
                       }
                   }
               }
           }
       ]

</syntaxhighlight>

  • Gnome Shell (Linux) - built in magnifier. Setting the settings: mag-factor, show-cross-hair, and a transformed mouse-tracking.

<syntaxhighlight lang="javascript">

       "settingsHandlers": [
           {
               "type": "gpii.gsettings.set",
               "options": {
                   "schema": "org.gnome.desktop.a11y.magnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" 
               ],
               "capabilitiesTransformations": {
                   "mag-factor": "display.screenEnhancement.magnification",
                   "show-cross-hairs": "display.screenEnhancement.showCrosshairs",
                   "mouse-tracking": {
                       "expander": {
                           "type": "fluid.model.transform.valueMapper",
                           "inputPath": "display.screenEnhancement.tracking",
                           "options": {
                               "mouse": {
                                   "outputValue": "centered"
                               }
                           }
                       }
                   }
               }
           }
       ],

</syntaxhighlight>

Full Examples of Solution Registry Entries

Now that we have gone through each of the individual parts of a solution declaration, let's see how a full solution looks when declared in the solution registry:

Windows Built-in Screen Magnifier

Below is a declaration of the Built In magnifier in Windows 7. Below are the highlights:

  • It has the descriptive name "Windows Built-in Screen Magnifier" and the unique ID "com.microsoft.windows.magnifier".
  • It requires the context of windows XP or 7 ("win32" with a version >= 5).
  • The "lifecycleManager" block says that when the user logs in the settings will be set by the settingsHandler ("setSettings"), and then a system call ("gpii.launch.exec") will be made to start the magnifier. On logging out, the application is killed by another system call ("gpii.launch.exec") and settings restored ("restoreSettings").
  • It uses the Windows Registry Settings Handler ("gpii.windows.registrySettingsHandler") and it sets the key HKEY_CURRENT_USER\\Software\\Microsoft\\ScreenMagnifier to the scaled value of a users preference (from the Common Terms Registry).

<syntaxhighlight lang="javascript"> {

       "name": "Windows Built-in Screen Magnifier",
       "id": "com.microsoft.windows.magnifier",
       "contexts": {
           "OS": [
               {
                   "id": "win32",
                   "version": ">=5.0"
               }
           ]
       },
       "lifecycleManager": {
           "start": [ 
               "setSettings", 
               {
                   "type": "gpii.launch.exec",
                   "command": "${{environment}.SystemRoot}\\System32\\Magnify.exe"
               }
           ],
           "stop": [ {
                   "type": "gpii.launch.exec",
                   "command": "${{environment}.SystemRoot}\\System32\\taskkill.exe /f /im Magnify.exe"
               },
               "restoreSettings"
           ]
       },
       "settingsHandlers": [
           {
               "type": "gpii.windows.registrySettingsHandler",
               "options": {
                   "hKey": "HKEY_CURRENT_USER",
                   "path": "Software\\Microsoft\\ScreenMagnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.com\\.microsoft\\.windows\\.magnifier.name"
               ],
               "capabilitiesTransformations": {
                   "Magnification": {
                       "expander": {
                           "type": "gpii.transformer.scaleValue",
                           "inputPath": "display.screenEnhancement.magnification",
                           "outputPath": "value",
                           "factor": 100
                       },
                       "dataType": {
                           "expander": {
                               "type": "fluid.model.transform.literalValue",
                               "value": "REG_DWORD"
                           }
                       }
                   }
               }
           }
       ]
   }

</syntaxhighlight>

Gnome Shell built-in magnifier

This example is a declaration of the Built In magnifier in Gnome ShellL (Linux). Below are the highlights:

  • It has the descriptive name "GNOME Shell Magnifier" and the unique ID "org.gnome.desktop.a11y.magnifier".
  • It requires the context of Linux with a kernel version of minimum 2.6.26
  • The "lifecycleManager" block says that when the user logs in the settings should be set ("setSettings") and then the GSettings Lifecycle Action will be called to start the magnifie. On logging out the magnifier is closed using the same lifecycle action and settings restored ("restoreSettings").
  • It uses the GSettings Settings Handler ("gpii.gsettings.set") sets three different settings in the application one of which is transformed.

<syntaxhighlight lang="javascript">

   {
       "name": "GNOME Shell Magnifier",
       "id": "org.gnome.desktop.a11y.magnifier",
       "contexts": {
           "OS": [
               {
                   "id": "linux",
                   "version": ">=2.6.26"
               }
           ]
       },
       "lifecycleManager": {
           "start": [
               "setSettings",
               {
                   "type": "gpii.gsettings.setSingleKey",
                    "schemaId": "org.gnome.desktop.a11y.applications",
                    "key": "screen-magnifier-enabled",
                    "value": "true"
               }
           ],
           "stop": [
               {
                   "type": "gpii.gsettings.setSingleKey",
                    "schemaId": "org.gnome.desktop.a11y.applications",
                    "key": "screen-magnifier-enabled",
                    "value": "true"
               },
               "restoreSettings"
           ]
       },
       "settingsHandlers": [
           {
               "type": "gpii.gsettings.set",
               "options": {
                   "schema": "org.gnome.desktop.a11y.magnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" 
               ],
               "capabilitiesTransformations": {
                   "mag-factor": "display.screenEnhancement.magnification",
                   "show-cross-hairs": "display.screenEnhancement.showCrosshairs",
                   "mouse-tracking": {
                       "expander": {
                           "type": "fluid.model.transform.valueMapper",
                           "inputPath": "display.screenEnhancement.tracking",
                           "options": {
                               "mouse": {
                                   "outputValue": "centered"
                               }
                           }
                       }
                   }
               }
           }
       ]

} </syntaxhighlight>


Wiki Categories