Emparejar un conjunto con la propiedad personalizada de DeviceInformationPairing

Usa la API Windows.Devices.Enumeration para emparejar dispositivos como un conjunto.

Windows admite el emparejamiento de una colección de dispositivos como un conjunto. La plataforma admite dos tipos de conjuntos.

• Conjunto detectado automáticamente. Esto sucede cuando un protocolo (como Bluetooth LE) detecta automáticamente otros puntos de conexión que pertenecen al conjunto al emparejar un punto de conexión principal. Por ejemplo, mientras un usuario analiza el oído derecho a través de Bluetooth LE, la pila de protocolos podría detectar el oído izquierdo; para que ambos se puedan emparejar como un conjunto.
• Conjunto explícito. Son útiles cuando se detecta un dispositivo en más de un protocolo. Por ejemplo, las impresoras del Protocolo de impresión en Internet (IPP) normalmente se detectan en tres protocolos: IPP, WSD y eSCL. Cuando se detectan varios puntos de conexión para el mismo dispositivo, se pueden emparejar explícitamente como un conjunto.

Ejemplo de código para un conjunto detectado automáticamente (estilo Bluetooth)

Este ejemplo de código implementa el emparejamiento de conjuntos detectados automáticamente (estilo Bluetooth) mediante un objeto de emparejamiento personalizado. Al igual que con una implementación típica del emparejamiento personalizado, se requiere un controlador de solicitud de emparejamiento para gestionar la ceremonia de emparejamiento. En este caso, el ejemplo de código implementa únicamente la ceremonia de emparejamiento solo de confirmación. La nueva e interesante parte es agregar un controlador pairing-set-member-requested.

El manejador de miembros del conjunto permite a la plataforma intentar emparejar el dispositivo proporcionado como un conjunto. Sin ese controlador, la pila de protocolos no intentará enumerar los miembros de un conjunto de emparejamiento. El protocolo Bluetooth detecta los miembros del conjunto como parte de la finalización del emparejamiento, por lo que el manejador del conjunto se llama en algún momento después de que su manejador de ceremonia vuelva. En este flujo, normalmente se espera que el manejador de conjuntos sea llamado una vez después de gestionar la ceremonia con una lista fija de miembros del conjunto; lo que significa que el protocolo detecta todos los puntos de conexión que puede durante el emparejamiento y no descubrirá más después.

Este ejemplo de código empareja de forma sincrónica todos los miembros del conjunto detectados con la misma rutina BtSetPairing que se usa para emparejar el dispositivo o punto de conexión principal. También se admite el emparejamiento en paralelo y puede ser más eficaz para su escenario. Pero por motivos de simplicidad, eso no se muestra en el ejemplo de código. Dado que también estamos emparejando los miembros del conjunto con un manejador de conjuntos, estos pueden potencialmente producir de forma recursiva más miembros del conjunto para emparejar. Pero normalmente, el manejador de conjuntos para los miembros del conjunto detectado verá probablemente la detección completada con el vector de miembros del conjunto vacío.

Ejemplo de código en 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);
    }
}

Ejemplo de código para un conjunto explícito (estilo IPP)

En este ejemplo de código se implementa el emparejamiento de conjuntos explícitos mediante un objeto de emparejamiento personalizado. Al igual que con una implementación típica del emparejamiento personalizado, se requiere un controlador de solicitud de emparejamiento para gestionar la ceremonia de emparejamiento. En este caso, el ejemplo de código implementa únicamente la ceremonia de emparejamiento solo de confirmación. Al igual que con el ejemplo de código Bluetooth, la nueva e interesante parte es agregar un controlador para pairing-set-member-requested. El controlador de miembros del conjunto permite a la plataforma intentar emparejar dispositivos como un conjunto.

En comparación con el escenario de emparejamiento de conjuntos de estilo Bluetooth, este ejemplo de código agrega explícitamente dispositivos al conjunto. Y el gestor de conjuntos sugiere algo un poco diferente para los protocolos relacionados con la conexión de impresoras IPP. Implica que los clientes gestionan la detección de dispositivos en los distintos protocolos y se deben sincronizar el estado PnP y las colas de impresión creadas como resultado del emparejamiento de todos los miembros del conjunto.

Para simplificar la implementación del ejemplo de código, se supone que se descubrió un vector de puntos de conexión de miembros del conjunto de antemano y se pasó como un parámetro junto con el dispositivo principal. Por ejemplo, en un escenario típico de IPP, los puntos de conexión se detectan en orden arbitrario. Por lo tanto, el dispositivo principal podría haberse descubierto a través de WSD por ejemplo; y, a continuación, el vector contendrá dispositivos que representan los puntos de conexión detectados a través de IPP y eSCL. Pero cualquier combinación es posible y válida. Agrega miembros establecidos al objeto de emparejamiento personalizado del dispositivo principal en el subproceso principal de la aplicación y, a continuación, llama a PairAsync.

Con esta implementación, el miembro primario del conjunto se emparejará simultáneamente con los miembros del conjunto. Los miembros del conjunto se emparejan uno por uno de forma sincrónica en el controlador. Pero de nuevo, se pueden emparejar en paralelo para mejorar la eficacia.

Los objetos de nodo de dispositivo en PnP a menudo se crean como resultado del emparejamiento. En el caso de IPP, los nodos de dispositivo siempre se crean para cada extremo una vez emparejados. Esta API de emparejamiento de conjuntos sincroniza implícitamente la creación de nodos de dispositivo entre los puntos de conexión del conjunto. En el flujo de este ejemplo de código, todos los nodos de dispositivo se sincronizarán porque todos los miembros establecidos se agregan antes de que se inicie el emparejamiento. Para obtener más información sobre cómo esta API sincroniza los nodos de dispositivo en PnP, consulte la sección Comentarios generales de este tema.

Ejemplo de código en 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);
    }
}

Comentarios generales

Emparejamiento de dispositivos detectados automáticamente (estilo Bluetooth)

Esta API es necesaria para lograr el emparejamiento de conjuntos estilo Bluetooth donde el protocolo descubre a los miembros del conjunto después de que se empareje el punto final principal. Un ejemplo sencillo podría ser un conjunto de auriculares inalámbricos. A medida que se finaliza el emparejamiento del primer auricular, el dispositivo informa al PC de que hay un segundo dispositivo para emparejar como parte del conjunto. La API de emparejamiento personalizado se extiende para permitir que las aplicaciones controlen las operaciones de conjuntos mediante el nuevo controlador de estado de miembro de conjunto añadido.

Emparejamiento explícito (estilo IPP)

Del mismo modo, también puede usar esta API para emparejar cualquier grupo de dispositivos de punto de conexión de asociación (AEP) como un conjunto. Con un objeto de emparejamiento personalizado, la aplicación puede agregar otros puntos de conexión al emparejamiento establecido en cualquier momento en cualquier subproceso. Esto es así por diseño porque la detección y el emparejamiento de dispositivos a través de una red pueden tardar mucho tiempo en cada dispositivo, por lo que no queremos serializar estas operaciones cuando podamos evitarlo.

Es especialmente útil emparejar conjuntos al detectar dispositivos en muchos protocolos en los que las pilas de protocolos y dispositivos no se coordinan fácilmente. Por ejemplo, es probable que Windows detecte una impresora de red moderna con tres protocolos de red diferentes, cada uno de los cuales genera puntos de conexión de asociación. En ese caso, la agrupación de los tres puntos de conexión en un conjunto es muy útil por un par de razones: evita el redescubrimiento innecesario a través de la red y crea una única cola de impresión simplificada.

Incluso si una impresora de red no está emparejada como un conjunto, el spooler de impresión sigue intentando crear una sola cola de impresión por usuario, independientemente de si se puede emparejar a través de varios protocolos. Si una impresora se empareja inicialmente a través de un protocolo, el sistema operativo (SO) intentará volver a detectarla en los demás protocolos admitidos y asociar a todos ellos para evitar colas de impresión duplicadas. Normalmente, el sistema operativo puede hacerlo de forma rápida y correcta y generar una cola de impresión simplificada.

Sin embargo, si la aplicación ya ha descubierto todos los puntos de conexión de la impresora, este paso de redescubrimiento es desperdiciado. Y peor, puede agregar retrasos largos antes de que la impresora esté lista para usarse. Además, si los protocolos están demasiado desincronizados o retrasados, es posible que el spooler tenga que crear colas de impresión adicionales para la misma impresora, lo que resulta confuso para los usuarios finales.

Emparejar todos los puntos de conexión a la vez como un conjunto evita un redescubrimiento que podría ser lento. Garantiza que el estado PnP está sincronizado y genera colas de impresión optimizadas óptimas.

Sincronización de nodos de dispositivo

Cuando los dispositivos se emparejan como un conjunto con esta API, el estado de dispositivo PnP resultante se sincroniza convenientemente. La API no restringe cuando una aplicación puede agregar un miembro establecido; pero hay límites en los que la plataforma puede sincronizar los nodos de dispositivo. La sincronización de los nodos del dispositivo se bloquea hasta que su emparejamiento se haya finalizado en todos los puntos de conexión del conjunto. Después, todos los nodos de dispositivo para todos los puntos de conexión se crean a la vez. Puede agregar más miembros adicionales al conjunto después de ese punto, y aunque no se bloquea la creación de nodos de dispositivo posteriores, estos se crean de inmediato.

• La creación del nodo de dispositivo se sincroniza cuando:
  • Los miembros del conjunto se añaden antes de que comience el emparejamiento.
  • Los miembros del conjunto se agregan mientras al menos uno de ellos no se haya finalizado.
• La creación del nodo de dispositivo no está sincronizada:
  • Cualquier momento después de que se hayan finalizado todos los miembros del conjunto agregados.

Como cuestión práctica, la API no permite que una aplicación controle cuándo se completa la finalización de la ceremonia para influir en este comportamiento sobre cómo se sincronizan los nodos de dispositivo. La aproximación más cercana sería cuando la aplicación elige completar la ceremonia. Un emparejamiento no se puede finalizar hasta que el controlador de ceremonias de la aplicación devuelva el control; así que esa es la última oportunidad de la aplicación para influir en el momento en que se finalizan todos los miembros del conjunto.