gpii-universal/gpii/node_modules/processReporter/README.md

Cross platform, core components of the GPII personalization infrastructure.

# Process Reporter

An Infusion component that can be used to acquire information about the processes associated with a GPII solution. In
particular, it can determine the running status of a solution.

The Process Reporter uses the information stored in the `isRunning` block of a solutions registry entry to decide
whether a solution is running.  For example, the `isRunning` block for the Linux screen reader Orca (the solution entry
`org.gnome.orca`) is as follows:

## Process Reporter API

Given a solutions registry entry, the Process Reporter uses the information stored in the `isRunning` block to determine
whether a solution has been launched and is currently running.  For example, the `isRunning` block for the Orca screen
reader (the solution entry `org.gnome.orca`) is as follows:

```snippet
"isRunning": [
    {
        "type": "gpii.processReporter.find",
        "command": "orca"
    }
]
```

The Process Reporter's invoker `handleIsRunning(entry)` uses the `type` property and `commmand` properties, and returns
either:

- `true`, if there is a running process corresponding to the `orca` command,
- `false`, if there is no running process corresponding to the `orca` command.

## Special cases

If the solutions registry entry does not have an `isRunning` block, then its run-state is not defined, and
`handleIsRunning()` returns `undefined`.

Most solutions run-state is based on a corresponding entry in the underlying OS's process or tasklist table.  For
example, the Linux/GNOME solution `org.gnome.orca` is running if the `orca` screen reader process is running.
Similarly, on Windows, `org.nvda-project` is running if there is an `nvda` process in the tasklist.

Some solutions, however, are not strictly process-oriented.  An example is the GNOME Shell screen magnifier (solution
`org.gnome.desktop.a11y.magnifier`).  The magnifier is not a separate process, but is built into GNOME Shell.  The
magnifier is running if (1) the `gnome-shell` process is running and (2) the `org.gnome.desktop.a11y.applications
screen-magnifier-enabled` GSetting is `true`.

To handle such cases, the `isRunning` block contains an array of criteria to check.  If all criteria are met, then the
solution is running.  The Process Reporter loops through and evaluates all the criteria.  Continuing to use the GNOME
Shell magnifier as the example: the Linux/GNOME implementation provides for checking both the status of the gnome-shell
process and the magnfier GSetting:

```snippet
"isRunning": [
    {
        "type": "gpii.processReporter.find",
        "command": "gnome-shell"
    },
    {
        "type": "gpii.processReporter.checkSetting",
        "schema": "org.gnome.desktop.a11y.applications",
        "setting": "screen-magnifier-enabled",
        "value": true
    }
]
```

## Dependencies

[infusion](https://github.com/fluid-project/infusion) framework.