Associazione di un set alla proprietà DeviceInformationPairing.Custom

Note

Alcune informazioni sono relative a un prodotto non definitivo, che potrebbe subire modifiche sostanziali prima del rilascio sul mercato. Microsoft non fornisce alcuna garanzia, espressa o implicita, in relazione alle informazioni fornite qui.

Usare le API Windows.Devices.Enumeration per associare i dispositivi come gruppo.

Windows supporta l'associazione di una raccolta di dispositivi come set. La piattaforma supporta due tipi di set.

  • Set individuato automaticamente. Ciò si verifica quando un protocollo ,ad esempio Bluetooth LE, individua automaticamente altri endpoint che appartengono al set durante l'associazione di un endpoint primario. Ad esempio, mentre un utente sta parando l'auricolare destro su Bluetooth LE, lo stack di protocolli potrebbe individuare l'auricolare sinistro; in modo che entrambi possano essere associati insieme come un set.
  • Set esplicito. Questi sono utili quando un dispositivo viene individuato su più di un protocollo. Ad esempio, le stampanti IPP (Internet Printing Protocol) vengono in genere individuate su tre protocolli: IPP, WSD ed eSCL. Quando vengono individuati più endpoint per lo stesso dispositivo, possono essere associati in modo esplicito come set.

Esempio di codice per un set individuato automaticamente (stile Bluetooth)

Questo esempio di codice implementa l'associazione di set individuati automaticamente (in stile Bluetooth) usando un oggetto di associazione personalizzato. Come per un'implementazione tipica dell'associazione personalizzata, è necessario un gestore di associazione richiesto per gestire la cerimonia di associazione. In questo caso, l'esempio di codice implementa solo la procedura di associazione solo conferma. La parte nuova e interessante consiste nell'aggiunta di un gestore pairing-set-member-requested.

Il gestore set-member-consente alla piattaforma di tentare di associare il dispositivo passato come set. Senza tale gestore, lo stack di protocolli non tenterà di enumerare i membri di un set di associazione. Il protocollo Bluetooth individua i membri dell’insieme durante la finalizzazione dell’abbinamento, quindi l’handler dell’insieme viene chiamato qualche tempo dopo che l’handler della procedura di associazione ha restituito il controllo. In questo flusso, in genere il gestore dell’insieme viene chiamato una sola volta dopo aver gestito la cerimonia con un elenco fisso di membri dell’insieme; ciò significa che il protocollo scopre tutti gli endpoint che riesce a rilevare durante l’abbinamento e che non ne scoprirà altri in seguito.

Questo esempio di codice associa in modo sincrono tutti i membri del set individuato con la stessa routine BtSetPairing usata per associare il dispositivo o l'endpoint primario. Anche l'associazione in parallelo è supportata e potrebbe essere più efficiente per lo scenario in uso. Ma per semplicità, questo non è illustrato nell'esempio di codice. Poiché stiamo associando anche gli elementi dell'insieme a un gestore dell'insieme, questi possono potenzialmente produrre ricorsivamente altri elementi dell'insieme da associare. Ma in genere il gestore dell'insieme per i membri dell'insieme individuati probabilmente vedrà solo discovery completed, con il vettore dei membri dell'insieme vuoto.

Note

Questo esempio di codice è senza il contesto di uno scenario o di un'app più grande; ma un'app dovrebbe probabilmente tenere traccia dei dispositivi associati e dei risultati dell'associazione. Per consentire all'app di capire se l'intera operazione di associazione del set è riuscita o meno.

Note

Queste API sono in genere asincrone. Le operazioni di associazione hanno thread di lavoro propri e i gestori vengono chiamati su thread diversi. Il codice non deve bloccarsi così spesso come in questo esempio di codice.

Esempio di codice 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);
    }
}

Esempio di codice per un set esplicito (tipo IPP)

Questo esempio di codice implementa l'associazione esplicita di set usando un oggetto di associazione personalizzato. Come per un'implementazione tipica dell'associazione personalizzata, è necessario un gestore di associazione richiesto per gestire la cerimonia di associazione. In questo caso, l'esempio di codice implementa solo la procedura di associazione confirm only. Come per l'esempio di codice Bluetooth, la parte nuova e interessante consiste nell'aggiungere un gestore pairing-set-member-requested. Il gestore dei membri del set consente alla piattaforma di tentare di associare i dispositivi come set.

Rispetto allo scenario di associazione di set in stile Bluetooth, questo esempio di codice aggiunge in modo esplicito i dispositivi al set. E il gestore set implica qualcosa di leggermente diverso per i protocolli correlati all'associazione di stampanti IPP. Implica che i client gestiscono l'individuazione dei dispositivi sui vari protocolli e che lo stato PnP e le code di stampa create come risultato dell'associazione di tutti i membri del set devono essere sincronizzati.

Per mantenere semplice l'implementazione dell'esempio di codice, si presuppone che un vettore di endpoint membro impostati sia stato individuato in anticipo e passato come parametro insieme al dispositivo primario. Ad esempio, in uno scenario IPP tipico, gli endpoint vengono individuati in ordine arbitrario. Quindi il dispositivo primario potrebbe essere stato scoperto su WSD per esempio; e quindi il vettore conterrà dispositivi che rappresentano gli endpoint individuati tramite IPP e eSCL. Ma qualsiasi combinazione è possibile e valida. Aggiunge membri impostati all'oggetto di associazione personalizzato del dispositivo primario nel thread principale dell'app e quindi chiama PairAsync.

Note

In pratica, è possibile aggiungere membri a un oggetto di associazione personalizzato in qualsiasi momento in qualsiasi thread. Le operazioni eseguite tramite un protocollo possono richiedere molto tempo o potrebbero persino bloccarsi finché non scade il timeout, quindi può essere utile sovrapporle. Valutare la possibilità di sfruttare il parallelismo dell'API per aggiungere e associare dispositivi contemporaneamente. Questo è possibile anche mentre si stanno ancora enumerando i dispositivi tramite connessione cablata. I vantaggi di abbinarli come insieme continuano generalmente a valere.

Con questa implementazione, il membro del set primario verrà associato simultaneamente ai membri del set. I membri del set vengono associati uno alla volta in modo sincrono nel gestore. Ma anche in questo caso, possono essere abbinati in parallelo per migliorare l'efficienza.

Gli oggetti nodo del dispositivo in PnP vengono spesso creati in seguito all'associazione. Nel caso di IPP, i nodi del dispositivo vengono sempre creati per ogni endpoint dopo l'associazione. Questa API per l'associazione dei set sincronizza implicitamente la creazione dei nodi di dispositivo tra gli endpoint del set. Nel flusso di questo esempio di codice, tutti i nodi del dispositivo verranno sincronizzati perché tutti i membri del set vengono aggiunti prima dell'avvio dell'associazione. Per altri dettagli su come questa API sincronizza i nodi del dispositivo in PnP, vedere la sezione Commenti generali in questo argomento.

Note

Questo esempio di codice è senza il contesto di uno scenario o di un'app più grande; ma un'app dovrebbe probabilmente tenere traccia dei dispositivi associati e dei risultati dell'associazione. Per consentire all'app di capire se l'intera operazione di associazione del set è riuscita o meno.

Esempio di codice 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);
    }
}

Commento generale

Associazione di set individuata automaticamente (in stile Bluetooth)

Questa API è necessaria per consentire l'associazione di un gruppo in stile Bluetooth, in cui i membri del gruppo vengono individuati dal protocollo dopo l'associazione dell'endpoint primario. Un semplice esempio potrebbe essere un set di auricolari wireless. Quando l'abbinamento del primo auricolare viene finalizzato, il dispositivo informa il PC che c'è un secondo dispositivo da associare come parte del set. L'API di associazione personalizzata è estesa per consentire alle app di gestire le operazioni sugli insiemi tramite il nuovo gestore add set member status.

Associazione esplicita di insiemi (in stile IPP)

Allo stesso modo, puoi anche usare questa API per associare come insieme qualsiasi gruppo di dispositivi Association Endpoint (AEP). Con un oggetto di associazione personalizzato, l'app può aggiungere altri endpoint al set di associazione in qualsiasi momento in qualsiasi thread. Questo è per impostazione predefinita perché l'individuazione e l'associazione dei dispositivi in una rete possono richiedere molto tempo per ogni dispositivo, quindi non si vuole serializzare queste operazioni quando è possibile evitarlo.

È particolarmente utile associare i set quando si individuano dispositivi su molti protocolli in cui il protocollo e gli stack di dispositivi non sono facilmente coordinati. Ad esempio, una stampante di rete moderna verrà probabilmente individuata da Windows con tre protocolli di rete diversi, ognuno dei quali produce endpoint di associazione. In tal caso, associare tutti e tre gli endpoint come un unico insieme è molto utile per un paio di motivi: evita inutili nuove operazioni di rilevamento sulla rete e crea un'unica coda di stampa semplificata.

Anche se una stampante di rete non è raggruppata in un set, lo spooler di stampa tenta comunque di creare un'unica coda di stampa per utente, a prescindere dal fatto che possa essere associata tramite più protocolli. Se inizialmente una stampante viene abbinata su un protocollo, il sistema operativo tenterà di individuarlo sugli altri protocolli supportati e associarlo a tutti per evitare code di stampa duplicate. In genere, il sistema operativo può farlo rapidamente e correttamente e produrre una coda di stampa semplificata.

Tuttavia, se l'app ha già individuato tutti gli endpoint per la stampante, questo passaggio di nuova individuazione è sprecato. E peggio, può aggiungere lunghi ritardi prima che la stampante sia pronta per l'uso. Inoltre, se i protocolli sono troppo non sincronizzati o in ritardo, lo spooler potrebbe dover creare code di stampa aggiuntive per la stessa stampante, creando confusione tra gli utenti finali.

L'associazione di tutti gli endpoint contemporaneamente come set consente di evitare la scoperta potenzialmente lenta. Garantisce che lo stato PnP sia sincronizzato e che produca code di stampa semplificate e ottimali.

Sincronizzazione dei nodi del dispositivo

Quando i dispositivi vengono associati come set a questa API, lo stato del dispositivo PnP risultante viene facilmente sincronizzato. L'API non vincola quando un'app può aggiungere un membro impostato; ma esistono limiti su quando la piattaforma può sincronizzare i nodi del dispositivo. La sincronizzazione dei nodi del dispositivo si blocca fino a quando non viene completata l'associazione di tutti gli endpoint nel set. Successivamente, tutti i nodi del dispositivo per tutti gli endpoint vengono creati contemporaneamente. È possibile aggiungere altri membri al set dopo quel punto, ma l'eventuale successiva creazione di un nodo del dispositivo non viene bloccata e viene invece eseguita immediatamente.

  • La creazione del nodo del dispositivo viene sincronizzata quando:
    • I membri del set vengono aggiunti prima che inizi l'abbinamento.
    • I membri set vengono aggiunti mentre almeno uno dei membri del set non viene finalizzato.
  • La creazione del nodo del dispositivo non è sincronizzata:
    • In qualsiasi momento dopo che tutti i membri aggiunti al set sono stati finalizzati.

In pratica, l'API non consente a un'app di controllare quando viene completata la finalizzazione della cerimonia per influenzare questo comportamento sulla sincronizzazione dei nodi del dispositivo. L'approssimazione più vicina sarebbe quando l'app sceglie di completare la cerimonia. Un abbinamento non può essere completato finché il gestore della procedura dell'app non termina; quindi questa è l'ultima occasione per l'app di influire su quando tutti gli elementi dell'insieme vengono finalizzati.