Windows Registry Settings Handler

From wiki.gpii
Jump to: navigation, search

Description

The Windows Registry Settings Handler is one of several Settings Handlers available to the Cloud4All/GPII implementers when making their solution (application) compatible with the GPII. This one is used to read and write values to and from the Windows system registry.

This page describes how to use the Windows Registry Settings Handler. For more general information about how and where Settings Handlers are used, we refer to the Settings Handler Documentation.

Using the Windows Registry Settings Handler

Like all settings handlers, this one is used in the solution entries of the Solution Registry, describing how a particular solution configures the settings handler and what application settings are supported. As with all Settings Handlers, the Windows Registry Settings Handler is configured using four key-value pairs namely: type", "options", "capabilities and capabilitiesTransformations. They should contain the following data:

  • "type": This denotes the settings handler to be used and should always have the value "gpii.windows.registrySettingsHandler" when using this settings handler
  • "options": The options describes the registry path in which to get or set the values. This is done via two fields: "hKey" describing the handle under which to locate they keys, and "path" describing the exact path to the keys that should be set. Both of these fields are mandatory. If a solution modifies values in several different locations of the registry, one windows registry settings handler block should be declared for each location..
  • "capabilities": This array tells what ontology terms the solution matches. This block is not specific to the type of settings handler, and we refer to the Settings Handler Documentation for more information.
  • "capabilityTransformations": As always, this blocks describes how common terms (from the Common Terms Registry) translates into settings understandable by the application. After transformation, the windows registry handler expects the following format:
{
  "registry-keyname": {
       "value": "reference-to-common-term",
       "dataType": "type-of-registry-key-entry"
   },
  "registry-keyname2": {
       "value": "reference-to-other-common-term",
       "dataType": "type-of-registry-key-entry2"
   },
   (...)
}

"registry-keyname" should be the name of the key in the registry for which to set the value. "reference-to-common-term" should contain the common term which corresponds to the registry setting from the Common Terms Registry. Finally, the "type-of-registry-key-entry" should match the registry type of the key given in "registry-keyname" - for example "REG_DWORD". Often the settings of an application might not entirely match that of a Common Term (eg. one might specify font size in pixels and the other one in points), for this type of transformations the Transformer is used - more information can be found here.

For more information about Settings Handlers and the individual blocks described above, see this page. The capabilityTransformation block is simple in its most basic form, but get rather complicated due the transformations. Information on how transformations work and which are available can be found on the Transformer page

Examples

Below is an example of of the Windows Registry Settings Handler, where we are configuring the settings handler to handle the keys found in HKEY_CURRENT_USER\Software\Microsoft\screenMagnifier. The key magnification is explicitly declared as being a transformation of the common term "display.screenEnhancement.magnification". Note that the below is an example snippet from a longer solution declaration found in the Solution Registry.

In the example, the type shows that we are using the Windows Registry Settings Handler. In the options block it can be seen that the registry keys we want to modify can be found under the HKEY_CURRENT_USER handler and path "Software\Microsoft\screenMagnifier". Note that the the backslashes are escaped with a backslash - this is mandatory when using the Registry Settings Handler. The capabilities block declares that this solution covers the needs and preferences described by the nested ontology term "display.screenEnhancement.screenMagnification". The ".applications.com\\.microsoft\\.windows\\.magnifier.name" is temporary due to a bug in the system.

In the capabilitiesTransformations block, only one setting is described. Namely the registry key "Magnification", which has type REG_DWORD and corresponds to the common term "display.screenEnhancement.magnification" if scaled by 100. For more information about the available transformations, see the documentation on the Transformer.

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