DeviceInformationPairing.Custom プロパティを使用してセットをペアリングする

[アーティクル]
04/08/2024

Note

一部の情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

デバイスをセットとしてペアリングするには、Windows.Devices.Enumeration API を使用します。

Windows では、デバイスのコレクションをセットとしてペアリングすることができます。プラットフォームでは、次の 2 種類のセットがサポートされています。

自動検出セット。これは、プライマリエンドポイントのペアリング中に、セットに属する他のエンドポイントがプロトコル (Bluetooth LE など) によって自動的に検出された場合に発生します。たとえば、ユーザーが Bluetooth LE 経由で右側のイヤホンをペアリングしているときに、プロトコルスタックで左側のイヤホンが検出されることがあります。この場合、両方をセットとして一緒にペアリングできます。
明示的セット。これらは、デバイスが複数のプロトコルで検出される場合に便利です。たとえば、インターネット印刷プロトコル (IPP) プリンターは、通常、IPP、WSD、eSCL の 3 つのプロトコルで検出されます。同じデバイスから複数のエンドポイントが検出される場合は、それらを明示的にまとめてセットとしてペアリングできます。

自動検出セットのコード例 (Bluetooth スタイル)

このコード例では、カスタムペアリングオブジェクトを使用して、自動検出 (Bluetooth スタイル) セットのペアリングを実装します。カスタムペアリングの一般的な実装と同様に、ペアリング手続きを処理するためにペアリング要求ハンドラーが必要です。このコード例では、確認のみのペアリング手続きだけを実装しています。注目すべき違いは、ペアリングセットメンバー要求ハンドラーを追加している点です。

セットメンバーハンドラーがあると、プラットフォームは、渡されたデバイスをセットとしてペアリングしようと試みます。このハンドラーがない場合、プロトコルスタックは、ペアリングセットのメンバーの列挙を試行しません。 Bluetooth プロトコルは、ペアリングの最終処理の一部としてセットメンバーを検出します。したがって、セットハンドラーは手続きハンドラーが戻った後に呼び出されます。このフローでは、セットハンドラーは一般に、固定リストのセットメンバーで手続きが処理された後、1 回だけ呼び出されることが想定されます。つまり、プロトコルは、ペアリング中に検出できるエンドポイントをすべて検出し、後から追加で検出することはありません。

このコード例では、検出されたすべてのセットメンバーを、プライマリデバイス/エンドポイントのペアリングに使用されるのと同じ BtSetPairing ルーチンによって同期的にペアリングします。メンバーを並列でペアリングすることもサポートされ、それによってシナリオの効率が向上する可能性があります。ただしこれは、簡潔にするためにコード例には示されていません。セットメンバーのペアリングはセットハンドラーでも行われるため、ペアリングする追加のセットメンバーが再帰的に生成される可能性があります。ただし、通常、検出されたセットメンバーに対して呼び出されるセットハンドラーで通知されるのは、セットメンバーのベクターが空の検出完了のみであることがほとんどです。

Note

このコード例では、大規模なシナリオやアプリのコンテキストは考慮されていません。実際のアプリでは、多くの場合、ペアリングしようとしているデバイスとペアリングの結果を追跡する必要があります。これは、セットペアリングの操作全体が成功したかどうかをアプリで把握するためです。

Note

これらの API は一般的に非同期です。ペアリング操作には独自のワーカースレッドがあり、ハンドラーは別のスレッドで呼び出されます。実際のコードでは、このコード例ほど頻繁にブロックする必要はありません。

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

明示的セットのコード例 (IPP スタイル)

このコード例では、カスタムペアリングオブジェクトを使用して、明示的セットのペアリングを実装します。カスタムペアリングの一般的な実装と同様に、ペアリング手続きを処理するためにペアリング要求ハンドラーが必要です。このコード例では、確認のみのペアリング手続きだけを実装しています。 Bluetooth のコード例と同じく、注目すべき違いは、ペアリングセットメンバー要求ハンドラーを追加している点です。セットメンバーハンドラーがあると、プラットフォームは、デバイスをセットとしてペアリングしようと試みます。

Bluetooth スタイルのセットペアリングシナリオと比較して、このコード例では、デバイスを明示的にセットに追加します。 Bluetooth と比べると、IPP プリンターのペアリングに関連するプロトコルでは、セットハンドラーが少し異なります。これは、クライアントがさまざまなプロトコル経由でデバイスの検出を処理しており、すべてのセットメンバーのペアリング結果として作成された PnP 状態と印刷キューを同期する必要があることを示しています。

コード例の実装をシンプルにするために、ここでは、セットメンバーエンドポイントのベクターが事前に検出されていて、プライマリデバイスと共にパラメーターとして渡されるものと想定しています。たとえば、一般的な IPP シナリオでは、エンドポイントは任意の順序で検出されます。したがって、たとえばプライマリデバイスは WSD 経由で検出され、ベクターには IPP や eSCL 経由で検出されたエンドポイントを表すデバイスが含まれることがあります。どのような組み合わせも可能であり、有効です。アプリのメインスレッドで、セットメンバーをプライマリデバイスのカスタムペアリングオブジェクトに追加し、PairAsync を呼び出します。

Note

実際には、セットメンバーのカスタムペアリングオブジェクトへの追加は、任意のタイミングかつ任意のスレッドで行われる可能性があります。プロトコル経由の操作は長い時間を要したり、タイムアウトするまでブロックされたりする場合があるため、オーバーラップで処理することが役立ちます。 API の並列処理を利用して、デバイスの追加とペアリングを同時に行うことを検討してください。これは、ネットワーク経由でデバイスを列挙している間でも可能です。デバイスをセットとしてペアリングする利点は、その場合も一般的に適用されます。

この実装では、プライマリセットメンバーはセットメンバーと同時にペアリングされます。セットメンバーは、ハンドラー内で一度に 1 つずつ同期的にペアリングされます。ただし、ここでも効率化のために並列でペアリングすることが可能です。

ペアリングの結果として、PnP のデバイスノードオブジェクトが作成されることがよくあります。 IPP の場合は、ペアリング後、エンドポイントごとに常にデバイスノードが作成されます。このセットペアリング API は、セット内のエンドポイント間でデバイスノードの作成を暗黙的に同期します。このコード例のフローでは、ペアリングの開始前にすべてのセットメンバーが追加されるため、すべてのデバイスノードが同期されることになります。この API によって PnP のデバイスノードがどのように同期されるかの詳細については、このトピックの「全般的な解説」セクションを参照してください。

Note

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) to
        // a Bluetooth device. Note: there still might be no set members.
        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 auto-discovered Bluetooth set scenario.
        // Error handling can go here.
    }

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

全般的な解説

自動検出 (Bluetooth スタイル) セットのペアリング

この API は Bluetooth スタイルのセットペアリングを実現するために必要です。このスタイルのセットペアリングでは、プライマリエンドポイントがペアリングされた後で、プロトコルによってセットメンバーが検出されます。単純な例として、ワイヤレスイヤホンのセットがあります。最初のイヤホンのペアリングが完了すると、デバイスは、セットの一部としてペアリングする 2 つ目のデバイスがあることを PC に通知します。カスタムペアリング API は、新しいセットメンバーステータスの追加ハンドラーを通じてアプリがセット操作を処理できるように拡張されています。

明示的 (IPP スタイル) セットのペアリング

同様に、この API を使用して、関連付けエンドポイント (AEP) デバイスのグループをセットとしてペアリングすることもできます。カスタムペアリングオブジェクトを使用すると、アプリはいつでも任意のスレッドでペアリングセットに他のエンドポイントを追加できます。このような仕様になっているのは、ネットワーク経由でのデバイスの検出とペアリングにはデバイスごとに長い時間がかかる可能性があり、その操作の連続実行を回避できる場合は回避した方が望ましいためです。

プロトコルとデバイススタックを簡単には統合できない状況で、多数のプロトコルでデバイスを検出する場合は、セットでのペアリングが特に役立ちます。たとえば、最新のネットワークプリンターは、Windows によって 3 つの異なるネットワークプロトコルで検出され、それぞれが関連付けエンドポイントを生成する可能性があります。この場合、3 つのエンドポイントのすべてをセットとしてペアリングすると、ネットワーク経由で無駄な再検出が行われるのを回避でき、単一の合理化された印刷キューが作成されるため、非常に便利です。

ネットワークプリンターがセットとしてペアリングされない場合でも、印刷スプーラーは、プリンターが複数のプロトコルでペアリングできるかどうかにかかわらず、ユーザーごとに単一の印刷キューを作成しようとします。プリンターが最初に 1 つのプロトコルでペアリングされた場合、オペレーティングシステム (OS) は、印刷キューの重複を防ぐために、サポートされている他のプロトコルで再検出を試み、検出されたすべてのプロトコルで関連付けを行います。 OS は通常、これをすばやく正常に実行し、1 つの合理化された印刷キューを生成することができます。

ただし、アプリで既にプリンターのすべてのエンドポイントが検出されている場合、この再検出の手順は無駄になります。さらに悪いことに、これにより、プリンターの使用準備ができる前に長い遅延が発生することがあります。また、プロトコルが極端に同期されていないか遅延していると、スプーラーでは同じプリンター用に追加の印刷キューを作成することが必要になる場合があり、エンドユーザーの混乱を招きます。

すべてのエンドポイントをセットとして一度にペアリングすれば、時間がかかる可能性のある再検出を回避できます。これにより、PnP 状態が同期され、合理化された最適な印刷キューが生成されます。

デバイスノードの同期

この API を通じてデバイスがセットとしてペアリングされると、結果の PnP デバイス状態は適切に同期されます。 API では、アプリがいつセットメンバーを追加できるかに関する制約はありませんが、プラットフォームがいつデバイスノードを同期できるかについては制限があります。デバイスノードの同期は、セット内のすべてのエンドポイントのペアリングが完了するまでブロックされます。その後で、すべてのエンドポイントのすべてのデバイスノードが一度に作成されます。この時点以降もセットにセットメンバーを追加できますが、その場合は後続のデバイスノードの作成はブロックされず、すぐに作成されます。

次の状況では、デバイスノードの作成が同期されます。
- ペアリングの開始前にセットメンバーが追加されたとき。
- 少なくとも 1 つのセットメンバーの最終処理が完了していないうちにセットメンバーが追加されたとき。
次の状況では、デバイスノードの作成は同期されません。
- 追加されたすべてのセットメンバーの最終処理が完了した後。

実際問題として、この API では、デバイスノードの同期の動作に関与しようとしても、手続きの最終処理がいつ完了するかをアプリで制御することはできません。最も近いタイミングは、アプリが手続きを完了することにしたときです。ペアリングの処理はアプリの手続きハンドラーが戻るまで完了できないため、すべてのセットメンバーの最終処理が完了するタイミングにアプリから影響を与えるとしたら、そのときが最後の機会となります。

次の方法で共有

DeviceInformationPairing.Custom プロパティを使用してセットをペアリングする

自動検出セットのコード例 (Bluetooth スタイル)

C++/WinRT でのコードの例

明示的セットのコード例 (IPP スタイル)

C++/WinRT でのコードの例

全般的な解説

自動検出 (Bluetooth スタイル) セットのペアリング

明示的 (IPP スタイル) セットのペアリング

デバイスノードの同期

フィードバック

その他のリソース

次の方法で共有

DeviceInformationPairing.Custom プロパティを使用してセットをペアリングする

自動検出セットのコード例 (Bluetooth スタイル)

C++/WinRT でのコードの例

明示的セットのコード例 (IPP スタイル)

C++/WinRT でのコードの例

全般的な解説

自動検出 (Bluetooth スタイル) セットのペアリング

明示的 (IPP スタイル) セットのペアリング

デバイス ノードの同期

フィードバック

その他のリソース

デバイスノードの同期