Merged PR 21097: New Ge APIs

Steven White · Steven White · commit dd9f7fb0b00f · 2024-03-01T02:10:24.000Z
New Ge APIs
diff --git a/windows.networking.networkoperators/networkoperatortetheringmanager_starttetheringasync_1060696031.md b/windows.networking.networkoperators/networkoperatortetheringmanager_starttetheringasync_1060696031.md
@@ -12,18 +12,29 @@ public Windows.Foundation.IAsyncOperation<Windows.Networking.NetworkOperators.Ne
 
 ## -description
 
-Allows you to start a tethering session without having to pre-configure it via [ConfigureAccessPointAsync](./networkoperatortetheringmanager_configureaccesspointasync_1399951422.md). The configuration passed as a parameter is valid only for the current session, and will be lost once the session has ended.
+Starts the mobile hotspot using a specified per-session configuration.
+
+This overload allows you to start a tethering session without having to pre-configure it via [ConfigureAccessPointAsync](./networkoperatortetheringmanager_configureaccesspointasync_1399951422.md). The configuration passed as a parameter is valid only for the current session, and will be lost once the session has ended.
 
 Starting a new session via this overload of **StartTetheringAsync** also allows you to configure per-session-only parameters that can't be persistently set via **ConfigureAccessPointAsync**. Parameters that *can* be persisted are the network SSID, the network password, the network wireless frequency band, and the network authentication algorithm.
 
+We recommended that you first call [StopTetheringAsync](./networkoperatortetheringmanager_stoptetheringasync_1234797808.md) in order to ensure that the tethering hotspot is off.
+
 ## -parameters
 
 ### -param configuration
 
+A [NetworkOperatorTetheringSessionAccessPointConfiguration](./networkoperatortetheringsessionaccesspointconfiguration.md) object containing all the per-session fields necessary to configure the mobile hotspot. This configuration doesn't persist between sessions. 
+
 ## -returns
 
+An object containing a [TetheringOperationStatus](./tetheringoperationstatus.md) status code indicating whether the start operation was successful, or the reason of failure, as well as a detailed **HSTRING** containing an additional error message if applicable.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
+
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringmanager_starttetheringasync_388849923.md b/windows.networking.networkoperators/networkoperatortetheringmanager_starttetheringasync_388849923.md
@@ -13,6 +13,8 @@ public Windows.Foundation.IAsyncOperation<Windows.Networking.NetworkOperators.Ne
 ## -description
 Establishes the tethering network.
 
+We recommended that you first call [StopTetheringAsync](./networkoperatortetheringmanager_stoptetheringasync_1234797808.md) in order to ensure that the tethering hotspot is off.
+
 ## -returns
 The result of the tethering network operation.
 
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration.md
@@ -12,18 +12,37 @@ public sealed class NetworkOperatorTetheringSessionAccessPointConfiguration
 
 ## -description
 
-Represents a per-session tethering configuration.
+Contains all per-session configuration fields used to configure the Wi-Fi tethering hotspot, plus relevant helper methods.
 
-**NetworkOperatorTetheringSessionAccessPointConfiguration** contains the same fields and helper methods as [NetworkOperatorTetheringAccessPointConfiguration](./networkoperatortetheringaccesspointconfiguration.md) does, with several additions.
+**NetworkOperatorTetheringSessionAccessPointConfiguration** contains the same fields and helper methods as its persistent counterpart [NetworkOperatorTetheringAccessPointConfiguration](./networkoperatortetheringaccesspointconfiguration.md) does, with several additions. But all the configurable properties from **NetworkOperatorTetheringSessionAccessPointConfiguration** are treated as per-session, including all the shared properties.
+
+**NetworkOperatorTetheringSessionAccessPointConfiguration** is used primarily in combination with [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md) to specify the per-session tethering configuration. Doing so won't clear or alter the existing persistent configuration. Calling **StartTetheringAsync** with no parameters always uses the persistent configuration pre-configured via [ConfigureAccessPointAsync](./networkoperatortetheringmanager_configureaccesspointasync_1399951422.md).
 
 ## -remarks
 
-The purpose of this class is to specify the per-session tethering configuration when starting the tethering session via [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md). The additional members of this per-session-only class are typically values that aren't currently configurable by users via Windows **Settings**.
+Tethering is a feature that allows a Windows device to function as a mobile hotspot: providing internet connections to other devices over Wi-Fi or Bluetooth. Four persistent fields can be configured on the Wi-Fi tethering hotspot: the network SSID, the network password, the network wireless frequency band (for example, 2.4 GHz, 5 GHz, 6 GHz), and the network authentication algorithm (for example, WPA2, WPA3). Once set, all of those fields persist between tethering sessions; meaning that the values are stored in non-volatile storage.
+
+But you can also start a tethering session using an entirely per-session configuration. A per-session tethering configuration doesn't persist between tethering sessions, and doesn't alter the current persistent configuration. A per-session field is *performance priority*.
+
+So the purpose of **NetworkOperatorTetheringSessionAccessPointConfiguration** is to specify the per-session tethering configuration when starting the tethering session via [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md). The additional members of this per-session-only class are typically values that aren't currently configurable by users via Windows **Settings**.
 
 ## -see-also
 
 ## -examples
 
+The tethering API in the **Windows.Networking.NetworkOperators** namespace provides a comprehensive set of functionalities that enable you to programmatically configure and control tethering (that is, sharing a device's internet connection with other devices). The code example below demonstrates the use of per-session tethering configurations.
+
+With the per-session tethering configurations, you can temporarily override the persistent tethering hotspot configuration without permanently altering it. That's particularly useful when a temporary setting is required. For example, when connecting an HMD to a PC by using mobile hotspot, but when you want to make things as seamless as possible by connecting the device via a temporary Wi-Fi network, without revealing the configuration details to the user, and without altering the user's current mobile hotspot configuration.
+
+Moreover, to achieve a low latency and low jitter connection to the PC, you might want to use a 6 GHz connection. If the user's PC is connected to the internet via a 5 GHz Wi-Fi connection, then the mobile hotspot can't be started on the 6 GHz band. So there's a per-session parameter, [PerformancePriority](./networkoperatortetheringsessionaccesspointconfiguration_performancepriority.md), that tells the driver how to prioritize performance between the tethering hotspot and the station connection. The [Default](./tetheringwifiperformancepriority.md) constant tells the driver to prioritize the station connection over everything else. On the other hand, [TetheringOverStation](./tetheringwifiperformancepriority.md) tells the driver to prioritize the performance of the tethering hotspot, thus allowing the driver to downgrade the station connection to 2.4 GHz if needed. This is all to offer the user as much of a seamless experience as possible, without requiring them to personally change the hotspot configuration and station connection.
+
+The code sample below showcases:
+
+* **API support verification**. It's important that your app tests whether the operating system it happens to be running on supports per-session tethering configurations. To do that, use the [ApiInformation.IsApiContractPresent](/uwp/api/windows.foundation.metadata.apiinformation.isapicontractpresent) method.
+* **Obtaining the tethering manager**. The code sample's locally-defined **GetTetheringManagerForCurrentConnection** method identifies the internet connection profile in use, and retrieves a tethering manager that corresponds to that profile. The tethering manager is later used to retrieve the primary access point configuration, and start the actual tethering session.
+* **Setting up the session configuration**. You can derive a tethering session configuration from the existing primary configuration, or set one up from scratch. You can then set or modify various parameters, like the SSID, passphrase, band, authentication kind, and performance priority.
+* **Starting the tethering session**. The session configuration can be passed to the [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md) method to initiate the tethering session. This method also provides extensive feedback through the [TetheringOperationStatus](./tetheringoperationstatus.md) enum, offering a nuanced understanding of the operation's result.
+
 ```csharp
 using System;
 using System.Threading.Tasks;
@@ -173,3 +192,6 @@ namespace TetheringApiDemoApp
   }
 }
 ```
+
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_authenticationkind.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_authenticationkind.md
@@ -12,12 +12,17 @@ public Windows.Networking.NetworkOperators.TetheringWiFiAuthenticationKind Authe
 
 ## -description
 
+Gets or sets the authentication kind to be used for the Wi-Fi tethering connection. Similar to [NetworkOperatorTetheringAccessPointConfiguration.AuthenticationKind](./networkoperatortetheringaccesspointconfiguration_authenticationkind.md).
+
 ## -property-value
 
+The enumeration value that describes the authentication kind to be used for the Wi-Fi tethering connection.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_band.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_band.md
@@ -12,12 +12,17 @@ public Windows.Networking.NetworkOperators.TetheringWiFiBand Band { get; set; }
 
 ## -description
 
+Gets or sets the frequency band to be used for the Wi-Fi tethering connection. Similar to [NetworkOperatorTetheringAccessPointConfiguration.Band](./networkoperatortetheringaccesspointconfiguration_band.md).
+
 ## -property-value
 
+The enumeration value that describes the frequency band to be used for the Wi-Fi tethering connection.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isauthenticationkindsupported_1988795581.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isauthenticationkindsupported_1988795581.md
@@ -12,16 +12,23 @@ public bool IsAuthenticationKindSupported (Windows.Networking.NetworkOperators.T
 
 ## -description
 
+Gets a value indicating whether the Wi-Fi adapter allows configuring the tethering hotspot with a specific authentication kind. Similar to [NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupported](./networkoperatortetheringaccesspointconfiguration_isauthenticationkindsupported_1988795581.md).
+
 ## -parameters
 
 ### -param authenticationKind
 
+Specifies the authentication kind to query for.
+
 ## -returns
 
+`true` if the authentication kind is supported; otherwise, `false`.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isauthenticationkindsupportedasync_453305428.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isauthenticationkindsupportedasync_453305428.md
@@ -12,16 +12,23 @@ public Windows.Foundation.IAsyncOperation<bool> IsAuthenticationKindSupportedAsy
 
 ## -description
 
+Asynchronously gets a value indicating whether the Wi-Fi adapter allows configuring the tethering hotspot with a specific authentication kind. Similar to [NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupportedAsync](./networkoperatortetheringaccesspointconfiguration_isauthenticationkindsupportedasync_453305428.md).
+
 ## -parameters
 
 ### -param authenticationKind
 
+Specifies the authentication kind to query for.
+
 ## -returns
 
+An asynchronous operation object which, when it completes, contains the value `true` if the authentication kind is supported; otherwise, `false`.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isbandsupported_675204954.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isbandsupported_675204954.md
@@ -12,16 +12,23 @@ public bool IsBandSupported (Windows.Networking.NetworkOperators.TetheringWiFiBa
 
 ## -description
 
+Gets a value indicating whether the Wi-Fi adapter allows configuring the tethering hotspot with a specific frequency band. Similar to [NetworkOperatorTetheringAccessPointConfiguration.IsBandSupported](./networkoperatortetheringaccesspointconfiguration_isbandsupported_675204954.md).
+
 ## -parameters
 
 ### -param band
 
+Specifies the frequency band to query for.
+
 ## -returns
 
+`true` if the frequency band is supported; otherwise, `false`.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isbandsupportedasync_854171434.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_isbandsupportedasync_854171434.md
@@ -12,16 +12,23 @@ public Windows.Foundation.IAsyncOperation<bool> IsBandSupportedAsync (Windows.Ne
 
 ## -description
 
+Asynchronously gets a value indicating whether the Wi-Fi adapter allows configuring the tethering hotspot with a specific frequency band. Similar to [NetworkOperatorTetheringAccessPointConfiguration.IsBandSupportedAsync](./networkoperatortetheringaccesspointconfiguration_isbandsupportedasync_854171434.md).
+
 ## -parameters
 
 ### -param band
 
+Specifies the frequency band to query for.
+
 ## -returns
 
+An asynchronous operation object which, when it completes, contains the value `true` if the frequency band is supported; otherwise, `false`.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_networkoperatortetheringsessionaccesspointconfiguration_1221375020.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_networkoperatortetheringsessionaccesspointconfiguration_1221375020.md
@@ -12,10 +12,13 @@ public NetworkOperatorTetheringSessionAccessPointConfiguration ();
 
 ## -description
 
+Creates an instance of the [NetworkOperatorTetheringSessionAccessPointConfiguration](./networkoperatortetheringsessionaccesspointconfiguration.md).
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_passphrase.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_passphrase.md
@@ -12,12 +12,17 @@ public string Passphrase { get; set; }
 
 ## -description
 
+Gets or sets the network passphrase to be used for the Wi-Fi tethering connection. Similar to [NetworkOperatorTetheringAccessPointConfiguration.Passphrase](./networkoperatortetheringaccesspointconfiguration_passphrase.md).
+
 ## -property-value
 
+An **HSTRING** value describing the network passphrase to be used for the Wi-Fi tethering connection.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_performancepriority.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_performancepriority.md
@@ -12,12 +12,21 @@ public Windows.Networking.NetworkOperators.TetheringWiFiPerformancePriority Perf
 
 ## -description
 
+Gets or sets the performance priority value to be used for the Wi-Fi tethering connection when the main internet connection is also over Wi-Fi. If the station connection is on a frequency band that interferes with the requested tethering frequency band, then the Wi-Fi chipset will attempt to change the connection's frequency band to another one that won't interfere.
+
+Many Wi-Fi chipsets have a limitation where if the main connection is over a 5 GHz band, then the tethering hotspot can't be configured to use a 6 GHz band. Prioritizing the tethering connection ([TetheringOverStation](./tetheringwifiperformancepriority.md)) will tell the Wi-Fi chipset to attempt to change the main connection over to a 2.4 GHz band, so that there'll no longer be interference with the requested 6 GHz band for the tethering hotspot.
+
+If the frequency band shift isn't possible or allowed by specifying a different performance priority value, then calling [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md) will fail with an appropriate result status (BandInterference).
+
 ## -property-value
 
+The enumeration value that specifies how the Wi-Fi chipset should prioritize performance between the tethering hotspot and the station connection.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_ssid.md b/windows.networking.networkoperators/networkoperatortetheringsessionaccesspointconfiguration_ssid.md
@@ -12,12 +12,17 @@ public string Ssid { get; set; }
 
 ## -description
 
+Gets or sets the network SSID to be used for the Wi-Fi tethering connection. Similar to [NetworkOperatorTetheringAccessPointConfiguration.Ssid](./networkoperatortetheringaccesspointconfiguration_ssid.md).
+
 ## -property-value
 
+An **HSTRING** value describing the network SSID to be used for the Wi-Fi tethering connection.
+
 ## -remarks
 
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
diff --git a/windows.networking.networkoperators/tetheringoperationstatus.md b/windows.networking.networkoperators/tetheringoperationstatus.md
@@ -42,13 +42,13 @@ The operation could not begin because Bluetooth or a required Bluetooth device i
 The operation did not complete because of limited network connectivity.
 
 ### -field AlreadyOn: 9
-The hotspot is already running.
+The hotspot is already on (already running). This status is returned only when calling [StartTetheringAsync](./networkoperatortetheringmanager_starttetheringasync_1060696031.md) with a specified per-session configuration.
 
 ### -field RadioRestriction: 10
-Can't start at 6 GHz due to radio restrictions (2x2 + dual radio).
+Can't start a mobile hotspot on the requested frequency band due to radio restrictions (for example, the 6 GHz band requires 2x2 antennae / dual radio).
 
 ### -field BandInterference: 11
-Can't start at 6 GHz because a 5 GHz connection interferes.
+Can't start a mobile hotspot on the requested frequency band due to the main connection frequency band interfering (for example, the 6 GHz band can't be configured for the mobile hotspot access point if the main station connection is over the 5 GHz band).
 
 ## -remarks
 
@@ -62,5 +62,6 @@ Can't start at 6 GHz because a 5 GHz connection interferes.
 ## -examples
 
 ## -see-also
+
 ## -capabilities
 cellularDeviceIdentity, cellularDeviceControl
diff --git a/windows.networking.networkoperators/tetheringwifiperformancepriority.md b/windows.networking.networkoperators/tetheringwifiperformancepriority.md
@@ -12,22 +12,29 @@ public enum TetheringWiFiPerformancePriority
 
 ## -description
 
-Defines constants that specify
+Defines constants that specify performance priority options for the Wi-Fi chipset to decide which connection performance to prioritize should the station connection band interfere with the tethering hotspot band.
 
 ## -enum-fields
 
 ### -field Default: 0
 
-Specifies
+Specifies the default behavior provided by the Wi-Fi chipset.
 
 ### -field TetheringOverStation: 1
 
-Specifies
+Specifies that the Wi-Fi chipset should prioritize the performance of the tethering hotspot over the performance of the station connection. This will allow the station connection frequency band to be changed to avoid any kind of interference.
+
+For example, the main connection is over a 5 GHz band, and so the tethering hotspot can't be configured to use a 6 GHz band. In that case, *TetheringOverStation* tells the Wi-Fi chipset to attempt to change the main connection over to a 2.4 GHz band, so there'll no longer be interference with the requested 6 GHz band for the tethering hotspot.
+
+A *BandInterference* status code is still possible when turning on the tethering hotspot if the Wi-Fi chipset can't change the station connection frequency. For example, the user's access point isn't broadcasting 2.4 GHz and 5GHz on the same SSID; some access point have different SSIDs for different frequencies: SSID-2.4G and SSID-5G. Due to hardware limitations, the only scenario where a band interference might occur and this performance priority can prevent it is when the device's station connection is over 5 GHz and the requested tethering hotspot is over 6 GHz.
 
 ## -remarks
 
+The performance priority can be set only as a per-session hotspot configuration field; meaning that it won't persist between tethering sessions. This field will be part only of the [NetworkOperatorTetheringSessionAccessPointConfiguration](./networkoperatortetheringsessionaccesspointconfiguration.md) class, which holds all configurable per-session values.
+
 ## -see-also
 
 ## -examples
 
-
+## -capabilities
+wiFiControl
