NetworkOperatorTetheringSessionAccessPointConfiguration Klasse

Referenz

Definition

Namespace:: Windows.Networking.NetworkOperators

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Bearbeiten

Enthält alle Konfigurationsfelder pro Sitzung, die zum Konfigurieren des Wi-Fi Tethering-Hotspots verwendet werden, sowie relevante Hilfsmethoden.

NetworkOperatorTetheringSessionAccessPointConfiguration enthält die gleichen Felder und Hilfsmethoden wie seine persistente Entsprechung NetworkOperatorTetheringAccessPointConfiguration , mit mehreren Ergänzungen. Alle konfigurierbaren Eigenschaften von NetworkOperatorTetheringSessionAccessPointConfiguration werden jedoch pro Sitzung behandelt, einschließlich aller freigegebenen Eigenschaften.

NetworkOperatorTetheringSessionAccessPointConfiguration wird hauptsächlich in Kombination mit StartTetheringAsync verwendet, um die Tetheringkonfiguration pro Sitzung anzugeben. Dadurch wird die vorhandene persistente Konfiguration nicht gelöscht oder geändert. Beim Aufrufen von StartTetheringAsync ohne Parameter wird immer die persistente Konfiguration verwendet, die über ConfigureAccessPointAsync vorkonfiguriert ist.

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

Vererbung: Object Platform::Object IInspectable NetworkOperatorTetheringSessionAccessPointConfiguration

Attribute: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 11, version 24H2 (eingeführt in 10.0.26100.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v19.0)
App-Funktionen	wiFiControl

Beispiele

Die Tethering-API im Windows.Networking.NetworkOperators-Namespace bietet einen umfassenden Satz von Funktionen, mit denen Sie das Tethering programmgesteuert konfigurieren und steuern können (d. h. die Gemeinsame nutzung der Internetverbindung eines Geräts mit anderen Geräten). Im folgenden Codebeispiel wird die Verwendung von Tetheringkonfigurationen pro Sitzung veranschaulicht.

Mit den Tetheringkonfigurationen pro Sitzung können Sie die Konfiguration des persistenten Tethering-Hotspots vorübergehend außer Kraft setzen, ohne sie dauerhaft zu ändern. Dies ist besonders nützlich, wenn eine temporäre Einstellung erforderlich ist. Beispielsweise, wenn Sie ein HMD mithilfe eines mobilen Hotspots mit einem PC verbinden, aber wenn Sie die Dinge so nahtlos wie möglich gestalten möchten, indem Sie das Gerät über ein temporäres Wi-Fi Netzwerk verbinden, ohne dem Benutzer die Konfigurationsdetails preiszugeben, und ohne die aktuelle Konfiguration des mobilen Hotspots des Benutzers zu ändern.

Darüber hinaus können Sie eine 6-GHz-Verbindung verwenden, um eine geringe Latenz und eine geringe Jitterverbindung mit dem PC zu erreichen. Wenn der PC des Benutzers über eine 5-GHz-Wi-Fi-Verbindung mit dem Internet verbunden ist, kann der mobile Hotspot nicht im 6-GHz-Band gestartet werden. Es gibt also einen Sitzungsparameter, PerformancePriority, der dem Treiber mitteilt, wie die Leistung zwischen dem Tethering-Hotspot und der Stationsverbindung priorisiert werden soll. Die Standardkonstante weist den Treiber an, die Stationsverbindung über alles andere zu priorisieren. Auf der anderen Seite weist TetheringOverStation den Treiber an, die Leistung des Tethering-Hotspots zu priorisieren, sodass der Treiber die Stationsverbindung bei Bedarf auf 2,4 GHz herabstufen kann. Dies ist alles, um dem Benutzer ein möglichst nahtloses Erlebnis zu bieten, ohne dass er die Hotspotkonfiguration und die Stationsverbindung persönlich ändern muss.

Im folgenden Codebeispiel wird folgendes veranschaulicht:

Überprüfung der API-Unterstützung. Es ist wichtig, dass Ihre App testet, ob das Betriebssystem, unter dem sie ausgeführt wird, Tetheringkonfigurationen pro Sitzung unterstützt. Verwenden Sie dazu die ApiInformation.IsApiContractPresent-Methode .
Abrufen des Tethering-Managers. Die lokal definierte GetTetheringManagerForCurrentConnection-Methode des Codebeispiels identifiziert das verwendete Internetverbindungsprofil und ruft einen Tethering-Manager ab, der diesem Profil entspricht. Der Tethering-Manager wird später verwendet, um die Konfiguration des primären Zugriffspunkts abzurufen und die eigentliche Tetheringsitzung zu starten.
Einrichten der Sitzungskonfiguration. Sie können eine Tetheringsitzungskonfiguration von der vorhandenen primären Konfiguration ableiten oder eine von Grund auf neu einrichten. Anschließend können Sie verschiedene Parameter festlegen oder ändern, z. B. SSID, Passphrase, Band, Authentifizierungsart und Leistungspriorität.
Starten der Tetheringsitzung. Die Sitzungskonfiguration kann an die StartTetheringAsync-Methode übergeben werden, um die Tetheringsitzung zu initiieren. Diese Methode bietet auch umfassendes Feedback über die TetheringOperationStatus-Enumeration und bietet ein differenziertes Verständnis des Vorgangsergebnisses.

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}.");
      }
    }
  }
}

Hinweise

Tethering ist ein Feature, das es einem Windows-Gerät ermöglicht, als mobiler Hotspot zu fungieren: Internetverbindungen mit anderen Geräten über Wi-Fi oder Bluetooth. Vier persistente Felder können auf dem Wi-Fi Tethering-Hotspot konfiguriert werden: die Netzwerk-SSID, das Netzwerkkennwort, das Funkfrequenzband des Netzwerks (z. B. 2,4 GHz, 5 GHz, 6 GHz) und der Netzwerkauthentifizierungsalgorithmus (z. B. WPA2, WPA3). Nach dem Festlegen bleiben alle diese Felder zwischen Tetheringsitzungen erhalten. Dies bedeutet, dass die Werte in einem nicht flüchtigen Speicher gespeichert werden.

Sie können aber auch eine Tetheringsitzung starten, indem Sie eine konfiguration vollständig pro Sitzung verwenden. Eine Sitzungs-Tetheringkonfiguration wird zwischen Tetheringsitzungen nicht beibehalten, und die aktuelle persistente Konfiguration wird nicht geändert. Ein Feld pro Sitzung hat Leistungspriorität.

Der Zweck von NetworkOperatorTetheringSessionAccessPointConfiguration besteht daher darin, die Tetheringkonfiguration pro Sitzung anzugeben, wenn die Tetheringsitzung über StartTetheringAsync gestartet wird. Die zusätzlichen Member dieser rein sitzungsbezogenen Klasse sind in der Regel Werte, die von Benutzern derzeit nicht über die Windows-Einstellungen konfiguriert werden können.

Konstruktoren

NetworkOperatorTetheringSessionAccessPointConfiguration()

Erstellt eine instance von NetworkOperatorTetheringSessionAccessPointConfiguration.

Eigenschaften

AuthenticationKind	Ruft die Authentifizierungsart ab, die für die Wi-Fi Tetheringverbindung verwendet werden soll, oder legt diese fest. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.AuthenticationKind.
Band	Ruft das Frequenzband ab, das für die Wi-Fi Tetheringverbindung verwendet werden soll, oder legt dieses fest. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.Band.
Passphrase	Ruft die Netzwerkpassphrase ab, die für die Wi-Fi Tetheringverbindung verwendet werden soll, oder legt diese fest. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.Passphrase.
PerformancePriority	Ruft den Wert der Leistungspriorität ab, der für die Wi-Fi Tetheringverbindung verwendet werden soll, wenn die Standard Internetverbindung auch über WLAN erfolgt, oder legt diesen fest. Wenn sich die Stationsverbindung auf einem Frequenzband befindet, das das angeforderte Tetherfrequenzband beeinträchtigt, versucht der Wi-Fi Chipsatz, das Frequenzband der Verbindung in ein anderes zu ändern, das nicht beeinträchtigt wird. Viele Wi-Fi Chipsätze haben eine Einschränkung, bei der der Tethering-Hotspot nicht für die Verwendung eines 6-GHz-Band konfiguriert werden kann, wenn die Standard-Verbindung über ein 5-GHz-Band liegt. Beim Priorisieren der Tetheringverbindung (TetheringOverStation) wird der Wi-Fi Chipsatz aufgefordert, die Standard Verbindung auf ein 2,4-GHz-Band umzustellen, sodass keine Störungen mit dem angeforderten 6-GHz-Band für den Tethering-Hotspot mehr auftreten. Wenn die Frequenzbandverschiebung nicht möglich oder zulässig ist, indem ein anderer Wert für die Leistungspriorität angegeben wird, schlägt der Aufruf von StartTetheringAsync mit einem geeigneten Ergebnis status (BandInterference) fehl.
Ssid	Ruft die Netzwerk-SSID ab, die für die Wi-Fi Tetheringverbindung verwendet werden soll, oder legt diese fest. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.Ssid.

Methoden

IsAuthenticationKindSupported(TetheringWiFiAuthenticationKind)	Ruft einen Wert ab, der angibt, ob der Wi-Fi Adapter das Konfigurieren des Tethering-Hotspots mit einer bestimmten Authentifizierungsart zulässt. Ähnelt NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupported.
IsAuthenticationKindSupportedAsync(TetheringWiFiAuthenticationKind)	Ruft asynchron einen Wert ab, der angibt, ob der Wi-Fi Adapter das Konfigurieren des Tethering-Hotspots mit einer bestimmten Authentifizierungsart ermöglicht. Ähnelt NetworkOperatorTetheringAccessPointConfiguration.IsAuthenticationKindSupportedAsync.
IsBandSupported(TetheringWiFiBand)	Ruft einen Wert ab, der angibt, ob der Wi-Fi Adapter das Konfigurieren des Tethering-Hotspots mit einem bestimmten Frequenzband zulässt. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.IsBandSupported.
IsBandSupportedAsync(TetheringWiFiBand)	Ruft asynchron einen Wert ab, der angibt, ob der Wi-Fi Adapter das Konfigurieren des Tethering-Hotspots mit einem bestimmten Frequenzband ermöglicht. Ähnlich wie NetworkOperatorTetheringAccessPointConfiguration.IsBandSupportedAsync.

Gilt für:

Freigeben über