Bagikan melalui

Memasangkan set dengan properti DeviceInformationPairing.Custom

  • Artikel

Catatan

Beberapa informasi berkaitan dengan produk yang telah dirilis sebelumnya, yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Gunakan API Windows.Devices.Enumeration untuk memasangkan perangkat sebagai set.

Windows mendukung pemasangan kumpulan perangkat sebagai satu set. Platform ini mendukung dua jenis set.

  • Set yang ditemukan secara otomatis. Ini terjadi ketika protokol (seperti Bluetooth LE) secara otomatis menemukan titik akhir lain yang termasuk dalam set saat memasangkan titik akhir utama. Misalnya, saat pengguna mengurai earbud kanan melalui Bluetooth LE, tumpukan protokol mungkin menemukan earbud kiri; sehingga keduanya dapat dipasangkan bersama-sama sebagai satu set.
  • Set eksplisit. Ini berguna ketika perangkat ditemukan melalui lebih dari satu protokol. Misalnya, printer Internet Printing Protocol (IPP) biasanya ditemukan melalui tiga protokol: IPP, WSD, dan eSCL. Ketika beberapa titik akhir untuk perangkat yang sama ditemukan, maka mereka dapat dipasangkan secara eksplisit bersama-sama sebagai satu set.

Contoh kode untuk set yang ditemukan secara otomatis (gaya Bluetooth)

Contoh kode ini mengimplementasikan pemasangan set yang ditemukan secara otomatis (gaya Bluetooth) menggunakan objek pemasangan kustom. Seperti halnya implementasi khas pasangan kustom, handler yang diminta pemasangan diperlukan untuk menangani upacara pemasangan. Dalam hal ini, contoh kode hanya mengimplementasikan upacara pemasangan konfirmasi saja . Bagian baru dan menarik adalah menambahkan handler yang diminta pairing-set-member.

Set-member-handler memungkinkan platform untuk mencoba memasangkan perangkat yang diteruskan sebagai set. Tanpa handler tersebut, tumpukan protokol tidak akan mencoba menghitung anggota set pemasangan. Protokol Bluetooth menemukan anggota yang ditetapkan sebagai bagian dari menyelesaikan pemasangan, sehingga handler set dipanggil beberapa saat setelah handler upacaranya kembali. Dalam alur ini, handler yang ditetapkan umumnya dapat mengharapkan untuk dipanggil sekali setelah menangani upacara dengan daftar tetap anggota yang ditetapkan; yang berarti bahwa protokol menemukan semua titik akhir yang dapat dilakukannya selama pemasangan, dan tidak akan menemukan lebih banyak nanti.

Contoh kode ini secara sinkron memasangkan semua anggota set yang ditemukan dengan rutinitas BtSetPairing yang sama yang digunakan untuk memasangkan perangkat/titik akhir utama. Memasangkannya secara paralel juga didukung, dan mungkin lebih efisien untuk skenario Anda. Tetapi untuk kesederhanaan, itu tidak ditampilkan dalam contoh kode. Karena kami juga memasangkan anggota yang ditetapkan dengan handler yang ditetapkan, mereka berpotensi menghasilkan lebih banyak anggota yang ditetapkan untuk dipasangkan. Tetapi biasanya, handler set untuk anggota set yang ditemukan mungkin hanya akan melihat penemuan selesai dengan vektor anggota yang ditetapkan kosong.

Catatan

Contoh kode ini tanpa konteks skenario atau aplikasi yang lebih besar; tetapi aplikasi mungkin perlu melacak perangkat apa yang dipasangkannya, dan hasil pemasangannya. Itu agar aplikasi dapat merasakan apakah seluruh operasi pemasangan set berhasil atau tidak.

Catatan

API ini umumnya asinkron. Operasi pemasangan memiliki utas pekerja mereka sendiri, dan handler dipanggil pada utas yang berbeda. Kode Anda tidak perlu memblokir sesering contoh kode ini.

Contoh kode di 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);
    }
}

Contoh kode untuk set eksplisit (gaya IPP)

Contoh kode ini mengimplementasikan pemasangan set eksplisit menggunakan objek pemasangan kustom. Seperti halnya implementasi khas pasangan kustom, handler yang diminta pemasangan diperlukan untuk menangani upacara pemasangan. Dalam hal ini, contoh kode hanya mengimplementasikan upacara pemasangan konfirmasi saja . Seperti contoh kode Bluetooth, bagian baru dan menarik adalah menambahkan handler yang diminta pairing-set-member. Penangan anggota yang ditetapkan memungkinkan platform untuk mencoba memasangkan perangkat sebagai satu set.

Dibandingkan dengan skenario pemasangan set gaya Bluetooth, contoh kode ini secara eksplisit menambahkan perangkat ke set. Dibandingkan dengan Bluetooth, handler set menyiratkan sesuatu yang sedikit berbeda dari protokol yang terkait dengan pemasangan printer IPP. Ini menyiratkan bahwa klien menangani penemuan perangkat melalui berbagai protokol, dan status PnP dan antrean cetak yang dibuat sebagai akibat dari memasangkan semua anggota yang ditetapkan harus disinkronkan.

Untuk menjaga implementasi contoh kode tetap sederhana, ia mengasumsikan bahwa vektor titik akhir anggota yang ditetapkan ditemukan sebelumnya, dan diteruskan sebagai parameter bersama dengan perangkat utama. Misalnya, dalam skenario IPP khas, titik akhir ditemukan dalam urutan arbitrer. Jadi perangkat utama dapat ditemukan melalui WSD misalnya; dan kemudian vektor akan berisi perangkat yang mewakili titik akhir yang ditemukan melalui IPP, dan eSCL. Tetapi kombinasi apa pun dimungkinkan dan valid. Ini menambahkan anggota yang diatur ke objek pemasangan kustom perangkat utama pada utas utama aplikasi, lalu memanggil PairAsync.

Catatan

Dalam praktiknya, atur anggota mungkin ditambahkan ke objek pemasangan kustom kapan saja pada utas apa pun. Operasi melalui protokol dapat memakan waktu lama, atau bahkan mungkin diblokir sampai waktu habis, sehingga tumpang tindih berguna. Pertimbangkan untuk memanfaatkan paralelisme API untuk menambahkan dan memasangkan perangkat secara bersamaan. Ini dimungkinkan bahkan saat Anda masih menghitung perangkat melalui kabel. Keuntungan memasangkannya sebagai set umumnya masih berlaku.

Dengan implementasi ini, anggota set utama akan dipasangkan bersamaan dengan anggota yang ditetapkan. Anggota yang ditetapkan dipasangkan satu per satu secara sinkron di handler. Tetapi sekali lagi, mereka dapat dipasangkan secara paralel untuk efisiensi yang lebih baik.

Objek simpul perangkat dalam PnP sering dibuat sebagai akibat dari pemasangan. Dalam kasus IPP, simpul perangkat selalu dibuat untuk setiap titik akhir setelah dipasangkan. API set-pairing ini secara implisit menyinkronkan pembuatan simpul perangkat antar titik akhir dalam set. Dalam alur contoh kode ini, semua simpul perangkat akan disinkronkan karena semua anggota yang ditetapkan ditambahkan sebelum pemasangan dimulai. Untuk detail selengkapnya tentang bagaimana API ini menyinkronkan simpul perangkat di PnP, lihat bagian Komentar umum dalam topik ini.

Catatan

Contoh kode ini tanpa konteks skenario atau aplikasi yang lebih besar; tetapi aplikasi mungkin perlu melacak perangkat apa yang dipasangkannya, dan hasil pemasangannya. Itu agar aplikasi dapat merasakan apakah seluruh operasi pemasangan set berhasil atau tidak.

Contoh kode di 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);
    }
}

Komentar umum

Pemasangan set (gaya Bluetooth) yang ditemukan secara otomatis

API ini diperlukan untuk menyelesaikan pemasangan set gaya Bluetooth di mana anggota yang ditetapkan ditemukan oleh protokol setelah titik akhir utama dipasangkan. Contoh sederhana mungkin merupakan sekumpulan earbud nirkabel. Saat pemasangan earbud pertama diselesaikan, perangkat menginformasikan PC bahwa ada perangkat kedua yang dipasangkan sebagai bagian dari set. API pemasangan kustom diperluas untuk memungkinkan aplikasi menangani operasi yang ditetapkan melalui penangan status anggota set baru.

Pemasangan set eksplisit (gaya IPP)

Demikian pula, Anda juga dapat menggunakan API ini untuk memasangkan sekelompok perangkat titik akhir asosiasi (AEP) apa pun sebagai satu set. Dengan objek pemasangan kustom, aplikasi Anda dapat menambahkan titik akhir lain ke pemasangan yang diatur kapan saja di utas apa pun. Itu secara desain karena penemuan dan pemasangan perangkat melalui jaringan dapat memakan waktu lama untuk setiap perangkat, jadi kami tidak ingin menserialisasikan operasi ini ketika kami dapat menghindarinya.

Sangat berguna untuk dipasangkan dalam set saat menemukan perangkat melalui banyak protokol di mana protokol dan tumpukan perangkat tidak mudah dikoordinasikan. Misalnya, printer jaringan modern kemungkinan akan ditemukan oleh Windows dengan tiga protokol jaringan yang berbeda, yang masing-masing menghasilkan titik akhir asosiasi. Dalam hal ini, memasangkan ketiga titik akhir sebagai satu set sangat berguna karena beberapa alasan: ini menghindari penemuan kembali yang boros melalui kawat, dan menciptakan satu antrean cetak yang disederhanakan.

Bahkan jika printer jaringan tidak dipasangkan sebagai set, penampung cetak masih mencoba membuat antrean cetak tunggal per pengguna terlepas dari apakah itu dapat dipasangkan melalui beberapa protokol. Jika printer awalnya dipasangkan melalui satu protokol, maka sistem operasi (OS) akan mencoba menemukannya kembali melalui protokol lain yang didukung, dan mengaitkannya atas semuanya untuk menghindari antrean cetak duplikat. Biasanya, OS dapat melakukannya dengan cepat dan berhasil dan menghasilkan satu antrean cetak yang disederhanakan.

Namun, jika aplikasi telah menemukan semua titik akhir untuk printer, maka langkah penemuan ulang ini sia-sia. Dan lebih buruk lagi, ia dapat menambahkan penundaan panjang sebelum printer siap digunakan. Selain itu, jika protokol terlalu tidak sinkron atau tertunda, maka penampung mungkin harus membuat antrean cetak tambahan untuk printer yang sama, yang membingungkan bagi pengguna akhir.

Memasangkan semua titik akhir sekaligus sebagai set menghindari penemuan kembali yang berpotensi lambat. Ini memastikan bahwa status PnP disinkronkan, dan menghasilkan antrean cetak yang disederhanakan secara optimal.

Sinkronisasi simpul perangkat

Ketika perangkat dipasangkan sebagai set dengan API ini, status perangkat PnP yang dihasilkan disinkronkan dengan nyaman. API tidak membatasi kapan aplikasi dapat menambahkan anggota yang ditetapkan; tetapi ada batasan kapan platform dapat menyinkronkan simpul perangkat. Sinkronisasi simpul perangkat memblokir hingga semua titik akhir dalam set menyelesaikan pemasangannya. Setelah itu, semua simpul perangkat untuk semua titik akhir dibuat sekaligus. Anda dapat menambahkan lebih banyak anggota yang diatur ke set setelah titik tersebut, tetapi tidak ada pembuatan simpul perangkat berikutnya yang diblokir, tetapi malah dibuat segera.

  • Pembuatan simpul perangkat disinkronkan ketika:
    • Atur anggota ditambahkan sebelum pemasangan dimulai.
    • Atur anggota ditambahkan sementara setidaknya salah satu anggota yang ditetapkan tidak diselesaikan.
  • Pembuatan simpul perangkat tidak disinkronkan:
    • Setiap kali setelah semua anggota set yang ditambahkan telah diselesaikan.

Sebagai masalah praktis, API tidak mengizinkan aplikasi untuk mengontrol kapan finalisasi upacara selesai untuk memengaruhi perilaku ini tentang bagaimana simpul perangkat disinkronkan. Perkiraan terdekat adalah ketika aplikasi memilih untuk menyelesaikan upacara. Pemasangan tidak dapat diselesaikan sampai handler upacara aplikasi kembali; jadi itulah kesempatan terakhir aplikasi untuk memengaruhi ketika semua anggota yang ditetapkan diselesaikan.