feat(windows): honour Windows "metered connection" flag for downloading updates

[rc-swag]

This adds a helper unit which uses the windows API to obtain a ConnectionProfile. This profile provides information about the connection status and connectivity statistics. This includes the connection costs, roaming, restricted etc. It also can check to see if background networking activity has been restricted.

Using the recommened example this commit combines these to determine if a network is metered. It also provides access to the background network being restricted.

There is a call that IsBackgroundUpdateAllowed that will return true if a background update is allowed.

This is then use in the Update State Machine and also by update pop up.
UpdateStateMachine
Before downloading IsBackgroundUpdateAllowed is called

Update Pop Up
This uses the IsMetered call and adds a warning if to the user who is wanting to Install Now.
This message would be better as a banner in the Update Configuration tab, rather than a delphi tab. This is the most efficent place to add the message for now.

Fixes: #13566

Build-bot: release:windows

User Testing

Mark connection as metered

For this we need to use windows setting to set the test machines network to metered. Right click the network connection icon in the Windows System tray and select network & internet settings Selected the connected work and the change the toggle for Metered connection to On

Windows 11

Windwos 10

TEST_RESTARTREQ_METERED

Use a keyboard update to test.

1. Install Keyman version attached to his PR
2. Download and install this older version of euro_latin
3. Make sure you have change the connected network to metered as explanined above.
4. Run Keyman
5. Go into the Keyman Configuration and the Update Tab
6. Press the check for updates button.
7. It should find an update for Euro Latin.
8. Press install updates ovbserve the warning is shown.

TEST_RESTARTREQ_NOT_METERED

This is to make sure a metered warning message is not present on non-metered connection.

1. Install Keyman version attached to his PR
2. Download and install this older version of euro_latin
3. Run Keyman.
4. Make sure you have change the connected network to metered OFF
5. Go into the Keyman Configuration and the Update Tab
6. Press the check for updates button.
7. It should find an update for Euro Latin.
8. Press install updates observe the metered warning is not shown.

TEST_NO_RESTARTREQ_METERED

This is to make sure a metered warning message is present but no other messages.

1. Install Keyman version attached to his PR
2. Download and install this older version of euro_latin
3. Do not run Keyman, if it has run sign in and out again.
4. Make sure you have change the connected network to metered OFF
5. Go into the Keyman Configuration and the Update Tab
6. Press the check for updates button.
7. It should find an update for Euro Latin.
8. Press install updates observe the metered warning is not shown.

TEST_NO_READY_TO_INSTALL_NOT_METERED

This is to make sure a metered connection message is not shown when
we already have the download and are just in the WaitingRestart State.

1. Install Keyman version attached to his PR
2. Download and install this older version of euro_latin
3. Make sure you have change the connected network to metered OFF
4. Go into the Keyman Configuration and the Update Tab
5. Press the check for updates button.
6. It should find an update for Euro Latin.
7. Close Configuration and the Keyman Splash screen if open.
8. Change the connected network to metered ON
9. 3. Do not Run Keyman if Keyman has run you will need to sign out of the current windows session.
10. Start Keyman
11. A pop saying an update is ready observe the metered warning is not shown.

TEST_NO_BACKGROUND_UPDATE

1. Install Keyman version attached to his PR
2. Download and install this older version of sil_euro_latin.zip
3. Close Keyman an Keyman Configuration
4. Make sure you have change the connected network to metered as explanined above.
5. Open Regedit WinR type regedit
6. Go to the current user key update state found at (Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine).
7. If required set the update state back to usIdle
8. Delete last update check time. This needs to be done otherwise it will stay in usIdle for 7 days.
9. Open Windows Explorer at "C:\Users"yourusername"\AppData\Local\Keyman\UpdateCache" folder.
10. Delete any *.kmp and *.exe files.
11. Open a command prompt and go to where kmshell is installed e.g c:\Program Files (x86)\Keyman\Keyman Desktop
12. run kmshell.exe -c This will run the configuration
13. Go to the Window Explorer window that is looking at the UpdateCache folder press F5 to refresh the window. No *.kmp or *.exe should appear as we are on metetered connection.

TEST_BACKGROUND_UPDATE

This is a regresion test.

1. Install Keyman version attached to his PR
2. Download and install this older version of sil_euro_latin.zip
3. Close Keyman an Keyman Configuration
4. Make sure you have change the connected network metered to OFF as explanined above.
5. Open Regedit WinR type regedit
6. Go to the current user key update state found at (Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine).
7. If required set the update state back to usIdle
8. Delete last update check time. This needs to be done otherwise it will stay in usIdle for 7 days.
9. Open Windows Explorer at "C:\Users"yourusername"\AppData\Local\Keyman\UpdateCache" folder.
10. Delete any *.kmp and *.exe files.
11. Open a command prompt and go to where kmshell is installed e.g c:\Program Files (x86)\Keyman\Keyman Desktop
12. run kmshell.exe -c This will run the configuration
13. Go to the Window Explorer window that is looking at the UpdateCache folder press F5 to refresh the window. The sil_euro_latin.kmp should appear as we are not on a metered connection.

[keymanapp-test-bot]

User Test Results

Test specification and instructions

• ⬜ TEST_RESTARTREQ_METERED (OPEN)
• ⬜ TEST_RESTARTREQ_NOT_METERED (OPEN)
• ⬜ TEST_NO_RESTARTREQ_METERED (OPEN)
• ⬜ TEST_NO_READY_TO_INSTALL_NOT_METERED (OPEN)
• ✅ TEST_NO_BACKGROUND_UPDATE (PASSED) (notes)
• ✅ TEST_BACKGROUND_UPDATE (PASSED) (notes)

Results Template

# Test Results

* **TEST_RESTARTREQ_METERED (OPEN):** notes
* **TEST_RESTARTREQ_NOT_METERED (OPEN):** notes
* **TEST_NO_RESTARTREQ_METERED (OPEN):** notes
* **TEST_NO_READY_TO_INSTALL_NOT_METERED (OPEN):** notes

Test Artifacts

• Windows
  • Keyman for Windows
  • FirstVoices Keyboards for Windows
  • FirstVoices Keyboards for Windows (old PRs)
  • Keyman for Windows (old PRs)
  • Text Editor (ARM64)
  • Text Editor (x64)
  • Text Editor (x86)

[Meng-Heng]

Test Prerequisite

1. Windows 10 Bootcamp
2. Keyman version 19.0.248-alpha-test-16099
3. sil_euro_latin version 3.0.0

Test Results

• TEST_WARNING_MESSAGE (PASSED):

1. The metered connection is set to on
2. Launch Keyman
3. Go into the Keyman Configuration -> the Update Tab
4. Press the check for updates button.
5. Update for Eurolatin (SIL) appears
6. Press install updates
7. Confirm -- The pop-up window does have the metered warning.

• TEST_NO_WARNING_MESSAGE_PART1 (PASSED):

1. Launch Keyman
2. The metered connection is off
3. Go into the Keyman Configuration -> the Update Tab
4. Press the check for updates button
5. Update for Eurolatin (SIL) appears
6. Press install updates
7. Confirmed -- The pop-up window does not have the metered warning.

• TEST_NO_WARNING_MESSAGE_PART2 (PASSED):

1. Launch Keyman
2. The metered connection stays off
3. Go into the Keyman Configuration -> the Update Tab
4. Press the check for updates button.
5. Update for Eurolatin (SIL) appears
6. Exit Keyman Configuration and the Keyman Splash screen from the tray
7. Start Keyman
8. Confirmed -- The pop-up window saying an update and does not have the metered warning
   

Note

I did not get the exact message as in the test requirement (see the image right above this note)

• TEST_NO_BACKGROUND_UPDATE (PASSED):

1. Close Keyman and Keyman Configuration
2. The metered connection is set to on
3. Follow the instruction to delete last update check time in Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine
4. Open Windows Explorer at "C:\Users\havm\AppData\Local\Keyman\UpdateCache" folder
5. Delete *.kmp file
6. Open a command prompt and go to c:\Program Files (x86)\Keyman\Keyman Desktop
7. Run kmshell.exe -c
8. The Keyman Configuration, Update tab opens up
9. Confirm – In Window Explorer window that is looking at the UpdateCache folder press, there is no *.kmp or *.exe appear as we are on metered connection.

• TEST_BACKGROUND_UPDATE (PASSED):

1. Uninstall and reinstall Keyman
2. Launch Keyman and install the keyboard
3. Close Keyman and Keyman Configuration
4. The metered connection is set to off
5. Follow the instruction to delete last update check time in Computer\HKEY_CURRENT_USER\SOFTWARE\Keyman\Keyman Engine
6. Open Windows Explorer at "C:\Users\havm\AppData\Local\Keyman\UpdateCache" folder
7. The folder is empty
8. Open a command prompt and go to c:\Program Files (x86)\Keyman\Keyman Desktop
9. Run kmshell.exe -c This will run the configuration
10. Confirm – In the Window Explorer window that is looking at the UpdateCache folder, there is now a sil_euro_latin.kmp file as we are not on a metered connection.

[ermshiperete]

From devin.ai:

Contradictory dialog messages when IsMetered=True and HasKeymanRun=False in Update_ApplyNow

In UfrmMain.pas:831, when HasKeymanRun is False but IsMetered is True, the form is created with RestartRequired=False and ReadyToInstall=False (default). This causes FormCreate at Keyman.Configuration.UI.UfrmStartInstall.pas:72-73 to show S_Ready_To_Install ("An update to Keyman has been downloaded and is ready to install") while simultaneously displaying the metered warning S_Metered_Warning ("You're on a metered connection. Downloading now may incur data charges") at line 77. These messages directly contradict each other: one says the update has already been downloaded, while the other warns about downloading costs. Before this PR, this code path didn't exist — the old code only showed the dialog when HasKeymanRun was true, always passing RestartRequired=true, so S_Ready_To_Install was never displayed here.

[rc-swag]

@Meng-Heng We need to test some scenarios again after my changes thanks.

[mcdurdin]

This change looks really solid.

One thing: I am not that comfortable with the UI of the dialog -- the red background is not consistent with styling of the rest of the app and I think we should use a standard Warning icon instead. Happy for that to be a follow-up PR.

[mcdurdin]

Can we use the modern file naming scheme:

Keyman.Configuration.Util.NetworkConnection.pas?

[mcdurdin]

These would be better in a class, because otherwise they land in the global namespace in Delphi, which is very cluttered already.

type
  TUtilNetworkConnection = class // or TNetworkConnection?
    class function IsMetered: Boolean; static;
    class function IsBackgroundDataRestricted: Boolean; static;
    class function IsBackgroundUpdateBlocked: Boolean; static;
  end;

[mcdurdin]

Do we need to initialize COM before these functions are called? If so, we should call that out in the docs

[mcdurdin]

Suggested change

	if Profile <> nil then
	if Assigned(Profile) then

Normal Delphi pattern

[mcdurdin]

Can we report errors on Sentry please? (Silent swallowing of the error is okay)

[mcdurdin]

Ditto Sentry

[mcdurdin]

Suggested change

	EInstallScenario: TInstallCase;
	InstallCase: TInstallCase;

The prefix E is usually reserved for exceptions. And why not call it InstallCase to match the type name?

[rc-swag]

Long story I initally called it InstallScenario, but then I found following that unwritten enum rule of the small letter preffix it became
isRestartRequiredMetered etc. Which when reading through the code again got confused with the actual word "is" so I changed the name as "ic" avoided the confusion. It is a shame because Scenario sounds better.

[mcdurdin]

Suggested change

	// We are ready to install Metered warning not needed even if on Metered connection
	frmStartInstall := TfrmStartInstall.Create(nil, TInstallCase.icReadyToInstallNotMetered);
	// We are ready to install Metered warning not needed even if on Metered connection
	frmStartInstall := TfrmStartInstall.Create(nil, TInstallCase.icReadyToInstallNotMetered);

[mcdurdin]

I found this install case name confusing; is the following name accurate?

Suggested change

	icNoInstallMessageMetered
	icReadyToDownloadWarnMetered

I guess my confusion extends to the dialog box as well -- would it be possible for the dialog box to say something to clarify that a download is required, something like this?

The update has not yet been downloaded.
and
You're on a metered connection. Downloading now may incur data charges.

[Meng-Heng]

@Meng-Heng We need to test some scenarios again after my changes thanks.

Noted with thanks, @rc-swag. I'll test this tomorrow.