Koppeln eines Satzes mit der DeviceInformationPairing.Custom-Eigenschaft

Verwenden Sie die Windows.Devices.Enumeration-APIs , um Geräte als Satz zu koppeln.

Windows unterstützt das Koppeln einer Sammlung von Geräten als Gruppe. Die Plattform unterstützt zwei Typen von Set.

• Automatisch ermittelter Satz. Dies geschieht, wenn ein Protokoll (z. B. Bluetooth LE) automatisch andere Endpunkte erkennt, die zum Satz gehören, während ein primärer Endpunkt gekoppelt wird. Während ein Benutzer beispielsweise den rechten Ohrhörer über Bluetooth LE analysiert, kann der Protokollstapel den linken Ohrhörer ermitteln; sodass beide als Satz kombiniert werden können.
• Expliziter Satz. Diese sind nützlich, wenn ein Gerät über mehrere Protokolle ermittelt wird. Beispielsweise werden IPP-Drucker (Internet Printing Protocol) in der Regel über drei Protokolle ermittelt: IPP, WSD und eSCL. Wenn mehrere Endpunkte für dasselbe Gerät erkannt werden, können sie explizit als Satz gekoppelt werden.

Codebeispiel für einen automatisch erkannten Satz (Bluetooth-Stil)

In diesem Codebeispiel wird die automatisch erkannte Kopplung im Bluetooth-Stil mithilfe eines benutzerdefinierten Kopplungsobjekts implementiert. Wie bei einer typischen Implementierung der benutzerdefinierten Kopplung ist ein Pairing-Anfragen-Handler erforderlich, um die Kopplungszeremonie zu verwalten. In diesem Fall implementiert das Codebeispiel nur die nur bestätigen Pairing-Zeremonie. Der neue und interessante Teil ist das Hinzufügen eines Handlers für ein angefordertes Paarungsset-Mitglied.

Mit dem Set-Member-Handler kann die Plattform versuchen, das übergebene Gerät als Teil eines Sets zu koppeln. Ohne diesen Handler wird der Protokollstapel nicht versuchen, die Mitglieder einer Paarungsgruppe aufzulisten. Das Bluetooth-Protokoll ermittelt festgelegte Member als Teil der Kopplung, sodass der Sethandler irgendwann nach dem Zurückgeben des Zeremonienhandlers aufgerufen wird. In diesem Ablauf kann der Set-Handler in der Regel erwarten, dass er einmal nach der Durchführung der Zeremonie mit einer festen Liste von Set-Mitgliedern aufgerufen wird. Das bedeutet, dass das Protokoll alle Endpunkte erkennt, die es während der Kopplung erreichen kann, und später keine weiteren mehr ermittelt.

In diesem Codebeispiel werden alle ermittelten Set-Member synchron mit derselben BtSetPairing-Routine gekoppelt, die zum Koppeln des primären Geräts/Endpunkts verwendet wird. Das parallele Koppeln wird ebenfalls unterstützt und kann für Ihr Szenario effizienter sein. Der Einfachheit halber wird dies jedoch nicht im Codebeispiel gezeigt. Da wir auch die Setmember mit einem Sethandler koppeln, können sie potenziell rekursiv mehr Satzmember erzeugen, die gekoppelt werden sollen. In der Regel sieht der Sethandler für die ermittelten Satzmember wahrscheinlich nur die Ermittlung abgeschlossen , wobei der Satzmembervektor leer ist.

Codebeispiel in C++/WinRT

void PairingTests::BtSetPairing(DeviceInformation device)
{
    DevicePairingKinds ceremonies = DevicePairingKinds::ConfirmOnly;
    auto customPairing = device.Pairing().Custom();
    event_revoker ceremonyEventToken = customPairing.PairingRequested(
        { this, &PairingTests::PairingRequestedHandler });
    event_revoker setEventToken = customPairing.PairingSetMembersRequested(
        { this, &PairingTests::PairingSetMembersRequestedHandler });

    DevicePairingResult result = customPairing.PairAsync(ceremonies).get();

    if (DevicePairingResultStatus::Paired == result.Status()) // Pairing worked.
    else // Handle pairing failure.
}

void PairingTests::PairingRequestedHandler(DeviceInformationCustomPairing const&,
    DevicePairingRequestedEventArgs const& args)
{
    switch (args.PairingKind())
    {
    case DevicePairingKinds::ConfirmOnly:
        args.Accept();
        break;
    default:
        // This code example doesn't implement other ceremonies.
        // The handler wouldn't be called for ceremonies that the app didn't register.
    }
}

void PairingTests::PairingSetMembersRequestedHandler(DeviceInformationCustomPairing
    const&, DevicePairingSetMembersRequestedEventArgs const& args)
{
    switch (args.Status())
    {
    case DevicePairingAddPairingSetMemberStatus::SetDiscoveryCompletedByProtocol:
        // This is the expected result if we started set pairing 
        // a Bluetooth device. Note: there still might be no set members.
        break;
    case DevicePairingAddPairingSetMemberStatus::SetDiscoveryPartiallyCompletedByProtocol:
        // The protocol enumerated some but not all set members.
        break;
    case DevicePairingAddPairingSetMemberStatus::SetDiscoveryNotAttemptedByProtocol:
        // Not expected for Bluetooth.
        // This constant implies that the protocol likely doesn't support set-pairing.
    default:
        // The other constants aren't expected in an auto-discovered Bluetooth set scenario.
        // Error handling can go here.
    }

    for (auto setMember : args.PairingSetMembers())
    {
        BtSetPairing(setMember);
    }
}

Codebeispiel für einen expliziten Satz (IPP-Style)

In diesem Codebeispiel wird die explizite Satzkopplung mithilfe eines benutzerdefinierten Kopplungsobjekts implementiert. Wie bei einer typischen Implementierung der benutzerdefinierten Kopplung ist ein Pairing-Anfragen-Handler erforderlich, um die Kopplungszeremonie zu verwalten. In diesem Fall implementiert das Codebeispiel nur die nur bestätigen Pairing-Zeremonie. Wie im Beispielcode für Bluetooth besteht der neue und interessante Teil darin, einen Handler für Kopplungs-Set-Mitgliedsanforderung hinzuzufügen. Der Handler für Satzmitglieder ermöglicht es der Plattform, Geräte als Gruppe zu koppeln.

Im Vergleich zum Set-Kopplungsszenario im Bluetooth-Stil fügt dieses Codebeispiel dem Satz explizit Geräte hinzu. Und der Sethandler impliziert etwas anderes für die Protokolle im Zusammenhang mit der Kopplung von IPP-Druckern. Es bedeutet, dass Clients die Geräteermittlung über die verschiedenen Protokolle verarbeiten, und der PnP-Zustand und die Druckwarteschlangen, die als Ergebnis der Kopplung aller set-Member erstellt wurden, sollten synchronisiert werden.

Um die Implementierung des Codebeispiels einfach zu halten, wird davon ausgegangen, dass zuvor ein Vektor von Satzelementendpunkten erkannt und zusammen mit dem primären Gerät als Parameter übergeben wurde. In einem typischen IPP-Szenario werden Endpunkte beispielsweise in beliebiger Reihenfolge ermittelt. So könnte das primäre Gerät beispielsweise über WSD entdeckt worden sein; und dann würde der Vektor Geräte enthalten, die Endpunkte darstellen, die über IPP ermittelt wurden, und eSCL. Aber jede Kombination ist möglich und gültig. Es fügt Set-Elemente dem benutzerdefinierten Kopplungsobjekt des primären Geräts im Hauptthread der App hinzu und ruft dann PairAsync auf.

Bei dieser Implementierung wird das primäre Mengenmitglied gleichzeitig mit den anderen Mengenmitgliedern gekoppelt. Die Set-Mitglieder werden nacheinander synchron im Handler gekoppelt. Aber auch hier können sie parallel kombiniert werden, um eine bessere Effizienz zu erzielen.

Geräteknotenobjekte in PnP werden häufig als Ergebnis der Kopplung erstellt. Bei IPP werden Geräteknoten nach der Kopplung immer für jeden Endpunkt erstellt. Diese Set-Zuordnungs-API synchronisiert implizit die Erstellung von Geräteknoten zwischen den Endpunkten im Set. Im Ablauf dieses Codebeispiels werden alle Geräteknoten synchronisiert, da alle Satzelemente vor dem Start der Kopplung hinzugefügt werden. Weitere Informationen dazu, wie diese API Geräteknoten in PnP synchronisiert, finden Sie im Abschnitt "Allgemeine Kommentare " in diesem Thema.

Codebeispiel in C++/WinRT

void PairingTests::IppSetPairing(DeviceInformation device,
    std::vector<DeviceInformation> const& setMemberDevices)
{
    DevicePairingKinds ceremonies = DevicePairingKinds::ConfirmOnly;
    auto customPairing = device.Pairing().Custom();
    event_revoker ceremonyEventToken = customPairing.PairingRequested({ this,
                     &PairingTests::PairingRequestedHandler });
    event_revoker setEventToken = customPairing.PairingSetMembersRequested({ this,
                  &PairingTests::PairingSetMembersRequestedHandler });

    if (setMemberDevices)
    {
        for (auto setDevice : setMemberDevices)
        {
            customPairing.AddPairingSetMember(setDevice);
        }
    }

    DevicePairingResult result = customPairing.PairAsync(ceremonies).get();

    if (DevicePairingResultStatus::Paired == result.Status()) // Pairing worked.
    else // Handle pairing failure.
}

void PairingTests::PairingRequestedHandler(DeviceInformationCustomPairing const&,
    DevicePairingRequestedEventArgs const& args)
{
    switch (args.PairingKind())
    {
    case DevicePairingKinds::ConfirmOnly:
        args.Accept();
        break;
    }
}

void PairingTests::PairingSetMembersRequestedHandler(DeviceInformationCustomPairing const&,
    DevicePairingSetMembersRequestedEventArgs args)
{
    switch (args.Status())
    {
    case DevicePairingAddPairingSetMemberStatus::AddedToSet:
        // This is the expected result of adding a set member(s)
        // by calling the AddPairingSetMember method.
        break;
    case DevicePairingAddPairingSetMemberStatus::CouldNotBeAddedToSet:
        // Means we failed to add set member(s).
        break;
    case DevicePairingAddPairingSetMemberStatus::SetDiscoveryNotAttemptedByProtocol:
    default:
        // The other constants aren't expected in an explicit set scenario.
        // Error handling can go here.
    }

    for (auto setMember : args.PairingSetMembers())
    {
        IppSetPairing(setMember, nullptr);
    }
}

Allgemeiner Kommentar

Automatisch entdeckte Kopplung im Bluetooth-Stil

Diese API ist erforderlich, um eine Bluetooth-ähnliche Set-Kopplung durchzuführen, bei der Satzmitglieder nach dem Koppeln des primären Endpunkts vom Protokoll entdeckt werden. Ein einfaches Beispiel könnte eine Reihe von drahtlosen Ohrhörer sein. Da die Kopplung des ersten Ohrhörers abgeschlossen ist, informiert das Gerät den PC, dass ein zweites Gerät als Teil des Satzes gekoppelt werden muss. Die benutzerdefinierte Kopplungs-API wird erweitert, um Apps die Behandlung von Setvorgängen über den neuen Add-Set-Memberstatushandler zu ermöglichen.

Explizite IPP-Satzpaarung

Ebenso können Sie diese API verwenden, um eine beliebige Gruppe von AEP-Geräten (Association Endpoint) als Gruppe zu koppeln. Mit einem benutzerdefinierten Kopplungsobjekt kann Ihre App dem Kopplungssatz jederzeit in einem beliebigen Thread weitere Endpunkte hinzufügen. Das ist entwurfsbedingt, da die Geräteermittlung und -kopplung über ein Netzwerk für jedes Gerät sehr lange dauern kann, sodass wir diese Vorgänge nicht serialisieren möchten, wenn wir sie vermeiden können.

Es ist besonders nützlich, Geräte in Sätzen zu paaren, wenn sie über viele Protokolle hinweg entdeckt werden, bei denen die Protokoll- und Gerätearchitekturen nicht leicht koordiniert werden können. Beispielsweise wird ein moderner Netzwerkdrucker wahrscheinlich von Windows mit drei verschiedenen Netzwerkprotokollen ermittelt, von denen jeder Zuordnungsendpunkte erzeugt. In diesem Fall ist das Paaren aller drei Endpunkte als Satz aus einigen Gründen sehr nützlich: Es vermeidet unnötige Neuentdeckung über das Netzwerk und erstellt eine optimierte Druckwarteschlange.

Auch wenn ein Netzwerkdrucker nicht als Einheit gekoppelt ist, versucht der Druckspooler trotzdem, eine einzelne Druckwarteschlange pro Benutzer zu erstellen, unabhängig davon, ob sie über mehrere Protokolle gekoppelt werden kann. Wenn ein Drucker anfänglich über ein Protokoll gekoppelt ist, versucht das Betriebssystem (OS), es über die anderen unterstützten Protokolle wiederzuentdecken und alle protokolle zuzuordnen, um doppelte Druckwarteschlangen zu vermeiden. In der Regel kann das Betriebssystem dies schnell und erfolgreich ausführen und eine optimierte Druckwarteschlange erstellen.

Wenn die App jedoch bereits alle Endpunkte für den Drucker entdeckt hat, ist dieser Wiederentdeckungsschritt verschwendet. Und schlimmer noch, es kann lange Verzögerungen hinzufügen, bevor der Drucker einsatzbereit ist. Wenn Protokolle nicht synchron oder verzögert sind, muss der Spooler möglicherweise zusätzliche Druckwarteschlangen für denselben Drucker erstellen, was für Endbenutzer verwirrend ist.

Durch gleichzeitiges Koppeln aller Endpunkte als Satz wird eine potenziell langsame Wiederentdeckung vermieden. Dadurch wird sichergestellt, dass der PnP-Zustand synchronisiert wird und optimale optimierte Druckwarteschlangen erzeugt.

Geräteknotensynchronisierung

Wenn die Geräte als Satz mit dieser API gekoppelt werden, wird der resultierende PnP-Gerätestatus bequem synchronisiert. Die API schränkt nicht ein, wann eine App Set-Mitglieder hinzufügen kann, aber es gibt Beschränkungen, wann die Plattform Geräteknoten synchronisieren kann. Die Geräteknotensynchronisierung wird blockiert, bis alle Endpunkte im Satz ihre Kopplung abgeschlossen haben. Danach werden alle Geräteknoten für alle Endpunkte gleichzeitig erstellt. Sie können nach diesem Zeitpunkt der Menge weitere Mitglieder hinzufügen, aber die nachfolgende Erstellung von Geräteknoten wird nicht blockiert, sondern sofort durchgeführt.

• Die Geräteknotenerstellung wird synchronisiert, wenn:
  • Set-Member werden vor dem Start der Kopplung hinzugefügt.
  • Set-Mitglieder werden hinzugefügt, während mindestens eines der Set-Mitglieder nicht abgeschlossen ist.
• Die Geräteknotenerstellung wird nicht synchronisiert:
  • Jedes Mal, nachdem alle hinzugefügten Satzmitglieder abgeschlossen wurden.

Die API lässt es praktisch nicht zu, dass eine App steuern kann, wann die Zeremonie abgeschlossen ist, um dieses Verhalten auf die Synchronisierung von Geräteknoten zu beeinflussen. Die näherste Annäherung wäre, wenn sich die App entscheidet, die Zeremonie abzuschließen. Eine Paarung kann erst abgeschlossen werden, wenn der Zeremonienmanager der App zurückkehrt; das ist also die letzte Chance der App, zu beeinflussen, wann alle Elemente des Sets abgeschlossen sind.