feat(gap): add ConnectionPriority to ConnectionParams

[acouvreur]

This replaces #422. It divides that work into a base contract and one PR for each platform that can use it.

What this adds

ConnectionPriority, and a Priority field in ConnectionParams. No backend reads the field yet. The behavior does not change.

Why a priority is necessary

Not all platforms accept explicit connection parameters. There are three groups.

Group	Mechanism
Exact	The Nordic SoftDevice, with sd_ble_gap_conn_param_update. HCI can also do this, but the code does not exist yet.
Presets only	Windows. BluetoothLEPreferredConnectionParameters has no public constructor. It has only three static presets, and only on Windows 11 build 22000 or later.
No mechanism	BlueZ has no D-Bus property for this. In CoreBluetooth, setDesiredConnectionLatency is a method of CBPeripheralManager, thus a central cannot use it. Web Bluetooth has no such function.

A priority is a request that the second group can use. Android and CoreBluetooth divide the same range into three parts.

Why the names are not Low, Medium and High

There are two problems with these names.

The vendors do not agree on the direction. Apple .low and Android CONNECTION_PRIORITY_HIGH have the same meaning.

Result	Apple	Windows	Android
Fast, high power	.low	ThroughputOptimized	CONNECTION_PRIORITY_HIGH
Between the two	.medium	Balanced	CONNECTION_PRIORITY_BALANCED
Slow, low power	.high	PowerOptimized	CONNECTION_PRIORITY_LOW_POWER

Thus many users will read ConnectionLatencyHigh in the opposite sense. Names that show the trade-off do not have this problem.

The Bluetooth Core Specification uses the term connection latency for a different parameter. It is the number of connection events that the peripheral can skip. Windows uses the same name for it, in BluetoothLEPreferredConnectionParameters.ConnectionLatency, with values from 0x0000 to 0x01F3. This is the object that the Windows PR uses. If we keep the term free, there is no conflict when we add that field.

References:

• https://learn.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothlepreferredconnectionparameters
• https://developer.apple.com/documentation/corebluetooth/cbperipheralmanagerconnectionlatency
• https://developer.android.com/reference/android/bluetooth/BluetoothGatt#requestConnectionPriority(int)

How to use the two together

A platform that accepts only presets uses Priority and ignores the explicit fields. A platform that sets the parameters in the controller uses the explicit fields. Set both fields to make a request that operates on all platforms.

The zero value does not change the connection. This agrees with the other fields in ConnectionParams.

The PRs on top of this one

• Windows, which sends Priority to the three WinRT presets
• Nordic SoftDevice, which changes Priority into explicit parameters

One item stays open after these two PRs. Five backends return nil from RequestConnectionParams but do nothing. A subsequent PR can report the support level of each device.

[acouvreur]

The full set of PRs:

• feat(gap): add ConnectionPriority to ConnectionParams #472, this PR. The ConnectionPriority contract. The behavior does not change.
• feat(windows): use ConnectionPriority for preferred connection parameters #473. Windows, which sends Priority to the three WinRT presets.
• feat(softdevice): use ConnectionPriority, and add PeripheralLatency #474. Nordic SoftDevice, and the PeripheralLatency field that the table needs.

#473 and #474 are independent of each other. Both are on top of this PR, thus GitHub changes their target to dev when this PR merges. I can also put the three PRs into one commit if you prefer this.