NetworkOperatorTetheringSessionAccessPointConfiguration 类

定义

包含用于配置 Wi-Fi 网络热点的所有每会话配置字段,以及相关的帮助程序方法。

NetworkOperatorTetheringSessionAccessPointConfiguration 包含与其持久对应 NetworkOperatorTetheringAccessPointConfiguration 相同的字段和帮助程序方法,并添加多个内容。 但是 NetworkOperatorTetheringSessionAccessPointConfiguration 中的所有可配置属性都被视为每个会话,包括所有共享属性。

NetworkOperatorTetheringSessionAccessPointConfiguration 主要与 StartTetheringAsync 结合使用,以指定每个会话的共享配置。 这样做不会清除或更改现有的永久性配置。 调用不带参数的 StartTetheringAsync 始终使用通过 ConfigureAccessPointAsync 预配置的持久性配置。

public ref class NetworkOperatorTetheringSessionAccessPointConfiguration sealed
/// [Windows.Foundation.Metadata.Activatable(1114112, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 1114112)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class NetworkOperatorTetheringSessionAccessPointConfiguration final
[Windows.Foundation.Metadata.Activatable(1114112, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 1114112)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class NetworkOperatorTetheringSessionAccessPointConfiguration
function NetworkOperatorTetheringSessionAccessPointConfiguration()
Public NotInheritable Class NetworkOperatorTetheringSessionAccessPointConfiguration
继承
Object Platform::Object IInspectable NetworkOperatorTetheringSessionAccessPointConfiguration
属性

Windows 要求

设备系列
Windows 11, version 24H2 (在 10.0.26100.0 中引入)
API contract
Windows.Foundation.UniversalApiContract (在 v19.0 中引入)
应用功能
wiFiControl

示例

Windows.Networking.NetworkOperators 命名空间中的网络连接 API 提供了一组全面的功能,使你能够以编程方式配置和控制网络共享 (,即) 与其他设备共享设备的 Internet 连接。 下面的代码示例演示如何使用每个会话的系绳配置。

使用每会话网络共享配置,可以暂时替代永久性网络共享热点配置,而无需永久更改它。 这在需要临时设置时特别有用。 例如,当使用移动热点将 HMD 连接到电脑时,但当你希望通过临时 Wi-Fi 网络连接设备来尽可能无缝地连接设备时,而不向用户透露配置详细信息,并且不更改用户的当前移动热点配置。

此外,若要实现与电脑的低延迟和低抖动连接,可能需要使用 6 GHz 连接。 如果用户的电脑通过 5 GHz Wi-Fi 连接连接到 Internet,则无法在 6 GHz 频带上启动移动热点。 因此,有一个每会话参数 PerformancePriority,它告诉驱动程序如何在网络热点和工作站连接之间确定性能的优先级。 Default 常量告知驱动程序优先于其他所有站点连接。 另一方面, TetheringOverStation 告知驱动程序优先处理网络热点的性能,从而允许驱动程序根据需要将工作站连接降级到 2.4 GHz。 这一切都是为用户提供尽可能多的无缝体验,而无需他们亲自更改热点配置和工作站连接。

下面的代码示例展示了:

  • API 支持验证。 应用必须测试运行它的操作系统是否支持每个会话的共享配置。 为此,请使用 ApiInformation.IsApiContractPresent 方法。
  • 获取网络共享管理器。 代码示例的本地定义的 GetTetheringManagerForCurrentConnection 方法标识正在使用的 Internet 连接配置文件,并检索与该配置文件对应的网络管理器。 网络管理器稍后用于检索主要接入点配置,并启动实际的网络共享会话。
  • 设置会话配置。 可以从现有主配置派生网络会话配置,也可以从头开始设置一个。 然后,可以设置或修改各种参数,例如 SSID、通行短语、带区、身份验证种类和性能优先级。
  • 启动网络共享会话。 会话配置可以传递给 StartTetheringAsync 方法以启动网络共享会话。 此方法还通过 TetheringOperationStatus 枚举提供广泛的反馈,提供对操作结果的细致理解。
using System;
using System.Threading.Tasks;
using Windows.Foundation.Metadata;
using Windows.Networking.NetworkOperators;
using Windows.Networking.Connectivity;

namespace TetheringApiDemoApp
{
  static class TetheringApiDemoClass
  {
    // Sample desired per-session access point configuration values.
    private const string DesiredSsid = "DemoSsid";

    private const string DesiredPassphrase = "DemoPassphrase";

    private const TetheringWiFiBand DesiredBand =
      TetheringWiFiBand.SixGigahertz;

    private const TetheringWiFiAuthenticationKind DesiredAuthenticationKind =
      TetheringWiFiAuthenticationKind.Wpa3;

    private const TetheringWiFiPerformancePriority DesiredPerformancePriority =
      TetheringWiFiPerformancePriority.TetheringOverStation;

    public static void VerifyPerSessionTetheringApiSupport()
    {
      if (!ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 17))
      {
        throw new InvalidOperationException(
          "This OS doesn't support per-session tethering configurations.");
      }
    }

    public static NetworkOperatorTetheringManager GetTetheringManagerForCurrentConnection()
    {
      // Get the connection profile associated with the internet connection currently used by the local machine.
      ConnectionProfile currentConnectionProfile = NetworkInformation.GetInternetConnectionProfile();

      if (currentConnectionProfile == null)
      {
        throw new InvalidOperationException("Machine isn't connected to the internet.");
      }

      TetheringCapability tetheringCapability =
        NetworkOperatorTetheringManager.GetTetheringCapabilityFromConnectionProfile(currentConnectionProfile);

      if (tetheringCapability != TetheringCapability.Enabled)
      {
        throw new InvalidOperationException(
          $"Tethering is disabled on this machine. Reason code: {tetheringCapability}.");
      }

      return NetworkOperatorTetheringManager.CreateFromConnectionProfile(currentConnectionProfile);
    }

    public static async Task<NetworkOperatorTetheringSessionAccessPointConfiguration>
      SetUpSessionConfigurationAsync(NetworkOperatorTetheringManager tetheringManager)
    {
      NetworkOperatorTetheringSessionAccessPointConfiguration sessionConfiguration =
         new NetworkOperatorTetheringSessionAccessPointConfiguration();

      sessionConfiguration.Ssid = DesiredSsid;
      sessionConfiguration.Passphrase = DesiredPassphrase;

      if (await sessionConfiguration.IsBandSupportedAsync(DesiredBand))
      {
        sessionConfiguration.Band = DesiredBand;
      }
      else
      {
        throw new InvalidOperationException("Desired band isn't supported.");
      }

      if (await sessionConfiguration.IsAuthenticationKindSupportedAsync(DesiredAuthenticationKind))
      {
        sessionConfiguration.AuthenticationKind = DesiredAuthenticationKind;
      }
      else
      {
        throw new InvalidOperationException("Desired authentication kind isn't supported.");
      }

      sessionConfiguration.PerformancePriority = DesiredPerformancePriority;

      return sessionConfiguration;
    }

    public static async Task StartTetheringSessionAsync(
      NetworkOperatorTetheringManager tetheringManager,
      NetworkOperatorTetheringSessionAccessPointConfiguration sessionConfiguration)
    {
      TetheringOperationStatus operationResult =
        await tetheringManager.StartTetheringAsync(sessionConfiguration);

      if (operationResult.Status == TetheringOperationStatus.Success)
      {
        Console.WriteLine("Tethering started successfully.");
      }
      else if (operationResult.Status == TetheringOperationStatus.AlreadyOn)
      {
        // Custom error message for AlreadyOn status.
        Console.WriteLine("Tethering is already on.");
      }
      else if (operationResult.Status == TetheringOperationStatus.RadioRestriction)
      {
        // Custom error message for RadioRestriction status.
        Console.WriteLine(
          "Can't start tethering at 6 GHz due to radio restrictions (2x2 + dual radio).");
      }
      else if (operationResult.Status == TetheringOperationStatus.BandInterference)
      {
        // Custom error message for BandInterference status.
        Console.WriteLine(
          "Can't start tethering at 6 GHz because a 5 GHz connection interferes.");
      }
      else
      {
        // Generic error message for all other statuses.
        Console.WriteLine(
          $"Failed to start tethering: {operationResult.AdditionalErrorMessage}.");
      }
    }

    public static async Task Main()
    {
      try
      {
        VerifyPerSessionTetheringApiSupport();

        NetworkOperatorTetheringManager tetheringManager = GetTetheringManagerForCurrentConnection();

        NetworkOperatorTetheringSessionAccessPointConfiguration sessionConfiguration =
          await SetUpSessionConfigurationAsync(tetheringManager);

        await StartTetheringSessionAsync(tetheringManager, sessionConfiguration);
      }
      catch (InvalidOperationException ex)
      {
        Console.WriteLine($"Failed to initialize tethering configuration: {ex.Message}.");
      }
      catch (Exception ex)
      {
        Console.WriteLine($"Unexpected error: {ex.Message}.");
      }
    }
  }
}

注解

网络共享是一项允许 Windows 设备充当移动热点的功能:通过 Wi-Fi 或蓝牙提供与其他设备的 Internet 连接。 可以在 Wi-Fi 网络热点上配置四个持久性字段:网络 SSID、网络密码、网络无线频带 (例如 2.4 GHz、5 GHz、6 GHz) ,以及网络身份验证算法 (WPA2、WPA3) 。 设置后,所有这些字段在网络会话之间保留;表示值存储在非易失性存储中。

但也可以使用完全按会话配置来启动网络会话。 每个会话的共享配置不会在网络共享会话之间保留,也不会更改当前的持久配置。 每会话字段是 性能优先级

因此, NetworkOperatorTetheringSessionAccessPointConfiguration 的目的是在通过 StartTetheringAsync 启动网络会话时指定每个会话的共享配置。 此仅按会话类的其他成员通常是用户当前无法通过 Windows 设置配置的值。

构造函数

NetworkOperatorTetheringSessionAccessPointConfiguration()

创建 NetworkOperatorTetheringSessionAccessPointConfiguration 的实例。

属性

AuthenticationKind

获取或设置要用于 Wi-Fi 网络连接的身份验证类型。 类似于 NetworkOperatorTetheringAccessPointConfiguration.AuthenticationKind

Band

获取或设置要用于 Wi-Fi 网络连接的频带。 类似于 NetworkOperatorTetheringAccessPointConfiguration.Band

Passphrase

获取或设置要用于 Wi-Fi 网络连接的网络通行短语。 类似于 NetworkOperatorTetheringAccessPointConfiguration.Passphrase

PerformancePriority

获取或设置当main Internet 连接也通过 Wi-Fi 时用于 Wi-Fi 网络连接的性能优先级值。 如果工作站连接位于干扰所请求的系绳频带的频带上,则 Wi-Fi 芯片集将尝试将连接的频带更改为不会干扰的另一个频带。

许多 Wi-Fi 芯片集都有一个限制,即如果main连接超过 5 GHz 频带,则无法将网络连接热点配置为使用 6 GHz 频带。 将网络连接 (TetheringOverStation) 的优先顺序将告知 Wi-Fi 芯片集尝试将main连接更改为 2.4 GHz 频带,以便不再干扰为网络共享热点请求的 6 GHz 频带。

如果无法通过指定不同的性能优先级值实现或不允许频带移,则调用 StartTetheringAsync 将失败,并显示相应的结果状态 (BandInterference) 。

Ssid

获取或设置要用于 Wi-Fi 网络连接的网络 SSID。 类似于 NetworkOperatorTetheringAccessPointConfiguration.Ssid

方法

IsAuthenticationKindSupported(TetheringWiFiAuthenticationKind)

获取一个值,该值指示 Wi-Fi 适配器是否允许使用特定身份验证类型配置网络连接热点。 类似于 NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupported

IsAuthenticationKindSupportedAsync(TetheringWiFiAuthenticationKind)

异步获取一个值,该值指示 Wi-Fi 适配器是否允许使用特定身份验证类型配置网络连接热点。 类似于 NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupportedAsync

IsBandSupported(TetheringWiFiBand)

获取一个值,该值指示 Wi-Fi 适配器是否允许使用特定频带配置网络热点。 类似于 NetworkOperatorTetheringAccessPointConfiguration.IsBandSupported

IsBandSupportedAsync(TetheringWiFiBand)

异步获取一个值,该值指示 Wi-Fi 适配器是否允许使用特定频带配置网络热点。 类似于 NetworkOperatorTetheringAccessPointConfiguration.IsBandSupportedAsync

适用于