| 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290 |
1×
1×
1×
1×
1×
1×
10×
10×
10×
8×
4×
4×
10×
10×
4×
6×
6×
6×
6×
6×
6×
10×
1×
9×
9×
9×
20×
20×
52×
52×
14×
9×
9×
1×
5×
5×
5×
5×
1×
5×
5×
1×
5×
5×
1×
5×
5×
5×
5×
1×
5×
5×
5×
4×
4×
5×
1×
11×
11×
11×
11×
1×
11×
11×
11×
23×
23×
11×
1×
| /*
* Built-in AT.
* Handles the registration and de-registration of the Windows built-in AT (magnifier, osk, and narrator).
*
* Copyright 2016 Raising the Floor - International
*
* Licensed under the New BSD license. You may not use this file except in
* compliance with this License.
*
* The research leading to these results has received funding from the European Union's
* Seventh Framework Programme (FP7/2007-2013)
* under grant agreement no. 289016.
*
* You may obtain a copy of the License at
* https://github.com/GPII/universal/blob/master/LICENSE.txt
*/
"use strict";
var fluid = require("universal");
var gpii = fluid.registerNamespace("gpii");
var child_process = require("child_process");
require("../registrySettingsHandler/src/RegistrySettingsHandler.js");
/*
* The method of (de)registering AT is described in https://msdn.microsoft.com/library/windows/desktop/bb879984.aspx:
*
* "An application notifies the Ease of Access Center by setting a temporary registry key and then injecting the Windows
* Logo key + U key combination into the input stream."
*
* "The application should create the temporary key at the following location.
* HKCU\Software\Microsoft\Windows NT\CurrentVersion\AccessibilityTemp
*
* The temporary key should have the same name as the registered application name, such as [magnifierpane, osk, or
* Narrator].
* The value of the key is a DWORD set to 0x0003 when it is starting, or 0x0002 when the application is exiting."
*
* Sending this key sequence is not necessary for GPII, as either the AT will do that itself when it starts, or GPII
* will execute utilman.exe which performs the necessary work.
*/
gpii.windows.registeredAT = fluid.freezeRecursive({
/**
* The registry key where the temporary values for enabling/disabling are kept.
*/
accessibilityTempKey: {
baseKey: "HKEY_CURRENT_USER",
path: "Software\\Microsoft\\Windows NT\\CurrentVersion\\AccessibilityTemp"
},
/**
* The registry key where the registered AT is defined.
*/
registeredATKey: {
baseKey: "HKEY_LOCAL_MACHINE",
path: "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Accessibility\\ATs"
},
/**
* The registry key where the settings to be transferred to the secure desktop are put.
*/
settingsTransfer: {
baseKey: "HKEY_CURRENT_USER",
path: "SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Accessibility\\ATConfig"
}
});
/**
* Enable or disable a registered AT application.
*
* While an application is enabled, Windows will automatically start and stop the application when the user switches
* desktops. Disabling will stop this from happening.
*
* @param {String} name The registered name of the application. This can be "magnifierpane", "osk", "Narrator", or
* some other 3rd party name.
* @param {Boolean} enable true to enable the application.
* @param {Object} options Options
* @param {Boolean} options.configOnly true to only (de)register the application and not to start or stop it.
* @param {String} options.startCommand Overrides the command used to start the AT application.
* @param {String} options.processName Overrides the executable to terminate when disabling.
* @param {String} options.utilman Overrides the command for utilman.exe
* @return {*}
*/
gpii.windows.enableRegisteredAT = function (name, enable, options) {
var defaultOptions = {
configOnly: false,
utilman: "%SystemRoot%\\System32\\utilman.exe"
};
options = fluid.extend(defaultOptions, options);
if (!options.configOnly) {
if (enable) {
gpii.windows.startRegisteredAT(name, options);
} else {
gpii.windows.stopRegisteredAT(name, options);
}
}
var promise = fluid.promise();
// The AT will have enabled itself when it starts, so only update the registry when disabling.
if (enable && !options.configOnly) {
promise.resolve();
} else {
// On Windows 7/8, if there's more than one action value in the registry then it will display the Ease of Access
// Centre. (This could be because when the first AT is loaded, it then invokes yet another instance of utilman,
// which will work on the next value pulling the rug from under the first instance).
// To work around this, wait until it has been cleared.
gpii.windows.whilePendingAT().then(function () {
var targetValue = enable ? gpii.windows.API_constants.enableAT : gpii.windows.API_constants.disableAT;
gpii.windows.writeRegistryKey(gpii.windows.registeredAT.accessibilityTempKey.baseKey,
gpii.windows.registeredAT.accessibilityTempKey.path, name, targetValue, "REG_DWORD");
// Invoke utilman to trigger the de-registration.
gpii.windows.nativeExec(options.utilman, null, function (error) {
Iif (error && error.code) {
promise.reject({
isError: true,
message: "Error starting utilman. " + options.utilman + " returned exit code: " + error.code,
error: error
});
} else {
promise.resolve();
}
});
});
}
return promise;
};
/**
* Waits while there are pending actions for utilman.
*
* An entry in the AccessibilityTemp key with a value of either enableAT or disableAT means there is an action
* for utilman. When utilman performs these actions, it will change the values to something else (so it doesn't repeat
* the work).
*
* This registry key is polled for these values, and the returned promise will resolve when there aren't any.
*
* @param [options] Options
* @param options.pollDelay How often to check for changes.
* @param options.timeout Milliseconds to timeout after.
* @return {promise} Returns a promise, resolving when there are no pending actions. The value is "timeout" on timeout.
*/
gpii.windows.whilePendingAT = function (options) {
var defaultOptions = {
pollDelay: 500,
timeout: 5000
};
options = fluid.extend(true, defaultOptions, options);
var checkActions = function () {
// Scan the AccessibilityTemp key for action values.
var values = gpii.windows.enumRegistryValues(gpii.windows.registeredAT.accessibilityTempKey.baseKey,
gpii.windows.registeredAT.accessibilityTempKey.path);
// Check for a value that's enableAT or disableAT
return !fluid.find(values, function (value, name) {
var data = fluid.get(values, [name, "data"]);
if ((data === gpii.windows.API_constants.enableAT) ||
(data === gpii.windows.API_constants.disableAT)) {
return true;
}
});
};
var waitOptions = {
pollDelay: options.pollDelay,
timeout: options.timeout,
dontReject: true
};
return gpii.windows.waitForCondition(checkActions, waitOptions);
};
/**
* Starts a registered AT application.
*
* @param {String} name The registered name of the application. This can be "magnifierpane", "osk", "Narrator", or
* some other 3rd party name.
* @param {Object} [options] Options
* @param {String} options.startCommand Overrides the command used to start the AT application.
* @param {Object} options.atInfo Overrides the AT information taken from the registry.
*/
gpii.windows.startRegisteredAT = function (name, options) {
var command;
Iif (options && options.startCommand) {
command = options.startCommand;
} else {
// StartExe + StartParams is the command to execute
var atInfo = gpii.windows.getATInformation(name, ["StartExe", "StartParams"]);
if (options && options.atInfo) {
atInfo = fluid.extend(atInfo, options.atInfo);
}
command = atInfo.StartExe;
if (atInfo.StartParams !== undefined) {
command += " " + atInfo.StartParams;
}
}
// Before executing the command, make sure utilman isn't already running.
gpii.windows.waitForProcessTermination("utilman.exe").then(function () {
gpii.windows.nativeExec(command);
});
};
/**
* Stops a registered AT application.
*
* @param {String} name The registered name of the application. This can be "magnifierpane", "osk", "Narrator", or
* some other 3rd party name.
* @param {Object} [options] Options
* @param {String} options.processName Overrides the executable name to terminate.
* @param {Object} options.atInfo Overrides the AT information taken from the registry.
* @return {Promise} A promise that will resolve when the application has closed.
*/
gpii.windows.stopRegisteredAT = function (name, options) {
var exeName;
var atInfo = gpii.windows.getATInformation(name, ["ATExe", "CopySettingsToLockedDesktop"]);
Iif (options && options.processName) {
exeName = options.processName;
} else {
if (options && options.atInfo) {
atInfo = fluid.extend(atInfo, options.atInfo);
}
exeName = atInfo.ATExe;
}
var promiseTogo = gpii.windows.killProcessByName(exeName);
// Remove the registry key that's used to transfer settings to the secure desktop, otherwise these settings
// will override any future settings. Really, the AT should do this when it closes, unfortunately it doesn't get
// closed cleanly so it is getting done here instead.GPII-2315.
if (atInfo.CopySettingsToLockedDesktop) {
var regPath = gpii.windows.registeredAT.settingsTransfer.path + "\\" + name;
gpii.windows.deleteRegistryKey(gpii.windows.registeredAT.settingsTransfer.baseKey, regPath);
}
return promiseTogo;
};
/**
* Execute a command, ensuring it uses the native System32 directory instead of the 32-bit version.
*
* When running as a 32-bit process on a 64-bit OS, in order make sure the native version is executed the 64-bit
* cmd.exe will be used to perform the invocation.
*
* @param {String} command The command to execute.
* @param {Object} [options] The options for child_process.exec.
* @param {function} [callback] Called when the process terminates.
* @return {Object} Returns what child_process.exec returns.
*/
gpii.windows.nativeExec = function (command, options, callback) {
var execOptions = fluid.extend({}, options);
Eif (gpii.windows.isWow64()) {
execOptions.shell = process.env.SYSTEMROOT + "\\Sysnative\\cmd.exe";
}
return child_process.exec(command, execOptions, callback);
};
/**
* Gets some pieces of information about a registered AT application.
*
* The values are documented in https://msdn.microsoft.com/library/windows/desktop/bb879984.aspx
*
* @param {String} name The registered name of the application. This can be "magnifierpane", "osk", "Narrator", or
* some other 3rd party name.
* @param {Array of String} values A list of the values required.
* @return An object containing the values from the registry.
*/
gpii.windows.getATInformation = function (name, values) {
var regPath = gpii.windows.registeredAT.registeredATKey.path + "\\" + name;
var togo = {};
for (var n = 0, len = values.length; n < len; n++) {
var value = gpii.windows.readRegistryKey(gpii.windows.registeredAT.registeredATKey.baseKey, regPath, values[n], "REG_SZ");
togo[values[n]] = value.value;
}
return togo;
};
fluid.defaults("gpii.windows.enableRegisteredAT", {
gradeNames: "fluid.function",
argumentMap: {
name: 0,
enable: 1
}
});
|