struktur _BRB_L2CA_OPEN_CHANNEL (bthddi.h)

Artikel
03/08/2023

Struktur _BRB_L2CA_OPEN_CHANNEL menjelaskan saluran L2CAP untuk dibuka ke perangkat jarak jauh, atau respons dari driver profil yang menerima atau menolak permintaan koneksi L2CAP masuk yang dimulai oleh perangkat jarak jauh.

Sintaks

struct _BRB_L2CA_OPEN_CHANNEL {
  BRB_HEADER                     Hdr;
  L2CAP_CHANNEL_HANDLE           ChannelHandle;
  union {
    struct {
      USHORT Response;
      USHORT ResponseStatus;
    };
    USHORT Psm;
  };
  ULONG                          ChannelFlags;
  BTH_ADDR                       BtAddress;
  struct {
    ULONG                    Flags;
    L2CAP_CONFIG_VALUE_RANGE Mtu;
    L2CAP_CONFIG_VALUE_RANGE FlushTO;
    L2CAP_FLOWSPEC           Flow;
    USHORT                   LinkTO;
    ULONG                    NumExtraOptions;
    PL2CAP_CONFIG_OPTION     ExtraOptions;
    struct {
      UCHAR ServiceType;
      ULONG Latency;
    } LocalQos;
  } ConfigOut;
  struct {
    ULONG                    Flags;
    L2CAP_CONFIG_VALUE_RANGE Mtu;
    L2CAP_CONFIG_RANGE       FlushTO;
  } ConfigIn;
  ULONG                          CallbackFlags;
  PFNBTHPORT_INDICATION_CALLBACK Callback;
  PVOID                          CallbackContext;
  PVOID                          ReferenceObject;
  CHANNEL_CONFIG_RESULTS         OutResults;
  CHANNEL_CONFIG_RESULTS         InResults;
  UCHAR                          IncomingQueueDepth;
};

Anggota

Hdr

Struktur BRB_HEADER yang berisi informasi tentang BRB saat ini.

ChannelHandle

Menangani yang digunakan untuk mengidentifikasi koneksi setelah koneksi berhasil. Saat mengirim BRB_L2CA_OPEN_CHANNEL, ini akan diisi ketika BRB selesai. Saat mengirim BRB_L2CA_OPEN_CHANNEL_RESPONSE, ini harus diisi oleh server sebelum mengirim BRB. Nilai yang ditetapkan harus INDICATION_PARAMETERS::ConnectionHandle yang diteruskan selama IndicationRemoteConnect.

Response

Hanya digunakan dengan BRB_L2CA_OPEN_CHANNEL_RESPONSE. Salah satu nilai CONNECT_RSP_RESULT_Xxx digunakan.

Jika BRB kembali dengan status STATUS_REQUEST_NOT_ACCEPTED, maka Respons akan berisi respons negatif dari host jarak jauh.

ResponseStatus

Jika Respons sama dengan CONNECT_RSP_RESULT_PENDING, maka bidang ini valid. Salah satu nilai CONNECT_RSP_STATUS_XXX digunakan.

Psm

Protocol/Service Multiplexer (PSM) yang digunakan saluran untuk menyambungkan ke perangkat jarak jauh. Saat digunakan dengan permintaan BRB_L2CA_OPEN_CHANNEL , anggota ini ditetapkan sebagai bidang input. Saat digunakan dengan permintaan BRB_L2CA_OPEN_CHANNEL_RESPONSE , anggota ini digunakan sebagai bidang output.

ChannelFlags

Bendera yang menentukan persyaratan saluran yang akan dibuka. Nilai bendera yang valid tercantum dalam tabel berikut ini:

Bendera	Deskripsi
CF_LINK_AUTHENTICATED	Tautan harus diautentikasi.
CF_LINK_ENCRYPTED	Tautan harus dienkripsi. Mengatur bendera ini juga mengatur bendera CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Driver profil menunjukkan preferensinya bahwa pengguna tidak dimintai PIN.

BtAddress

Alamat Bluetooth perangkat yang koneksinya dimaksudkan.

ConfigOut

Substruktur yang berisi pengaturan parameter untuk BRB_L2CA_OPEN_CHANNEL BRB yang dikirim ke perangkat jarak jauh.

ConfigOut.Flags

Bendera yang menentukan persyaratan saluran yang akan dibuka. Nilai bendera yang valid tercantum dalam tabel berikut ini:

Bendera	Deskripsi
CF_LINK_AUTHENTICATED	Tautan harus diautentikasi.
CF_LINK_ENCRYPTED	Tautan harus dienkripsi. Mengatur bendera ini juga mengatur bendera CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Driver profil menunjukkan preferensinya bahwa pengguna tidak dimintai PIN.

ConfigOut.Mtu

Rentang unit transfer pesan (MTU) yang digunakan untuk menegosiasikan ukuran setengah saluran keluar.

ConfigOut.FlushTO

Rentang nilai yang mungkin digunakan untuk batas waktu flush untuk setengah saluran keluar.

ConfigOut.Flow

Disiapkan untuk penggunaan masa mendatang. Jangan gunakan.

ConfigOut.LinkTO

Batas waktu tautan Link Manager.

ConfigOut.NumExtraOptions

Jumlah item array yang terkandung dalam anggota ExtraOptions . Nilai ini harus nol untuk sebagian besar klien.

ConfigOut.ExtraOptions

Jumlah item array yang terkandung dalam anggota ExtraOptions . Nilai ini harus nol untuk sebagian besar klien.

ConfigOut.LocalQos

Disiapkan untuk penggunaan masa mendatang. Jangan gunakan.

ConfigOut.LocalQos.ServiceType

Disiapkan untuk penggunaan masa mendatang. Jangan gunakan.

ConfigOut.LocalQos.Latency

Disiapkan untuk penggunaan masa mendatang. Jangan gunakan.

ConfigIn

Substruktur yang berisi pengaturan parameter untuk memvalidasi BRB BRB_L2CA_OPEN_CHANNEL_RESPONSE masuk yang dikirim dari perangkat jarak jauh.

ConfigIn.Flags

Bendera yang menentukan persyaratan saluran yang akan dibuka. Nilai bendera yang valid tercantum dalam tabel berikut ini:

Bendera	Deskripsi
CF_LINK_AUTHENTICATED	Tautan harus diautentikasi.
CF_LINK_ENCRYPTED	Tautan harus dienkripsi. Mengatur bendera ini juga mengatur bendera CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Driver profil menunjukkan preferensinya bahwa pengguna tidak dimintai PIN.

ConfigIn.Mtu

Rentang unit transfer pesan (MTU) yang digunakan untuk menegosiasikan ukuran setengah saluran keluar.

ConfigIn.FlushTO

Rentang nilai yang mungkin digunakan untuk batas waktu flush untuk setengah saluran keluar.

CallbackFlags

Bendera yang menentukan peristiwa mana yang harus menghasilkan rutinitas panggilan balik untuk memberi tahu driver profil bahwa peristiwa telah terjadi. Nilai bendera yang valid terkandung dalam tabel berikut.

Bendera	Deskripsi
CALLBACK_CONFIG_EXTRA_IN	Jika diatur, rutinitas panggilan balik akan dipanggil ketika permintaan konfigurasi untuk perangkat jarak jauh berisi opsi tambahan. Jika tidak diatur, opsi konfigurasi tambahan akan ditolak sebagai opsi yang tidak diketahui. Bendera ini digunakan dengan BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB.
CALLBACK_CONFIG_EXTRA_OUT	Jika diatur, rutinitas panggilan balik akan dipanggil ketika perangkat jarak jauh menolak opsi konfigurasi tambahan dari permintaan BRB_L2CA_OPEN_CHANNEL. Jika tidak diatur dan perangkat jarak jauh menolak permintaan konfigurasi karena opsi tambahan, koneksi akan ditutup.
CALLBACK_CONFIG_QOS	Jika diatur, rutinitas panggilan balik akan dipanggil saat perangkat jarak jauh mengirim permintaan konfigurasi yang berisi nilai QOS. Jika bendera ini tidak diatur dan perangkat jarak jauh mengirim parameter QOS dalam permintaan konfigurasi atau menolak parameter QOS yang diminta driver profil, koneksi terputus.
CALLBACK_DISCONNECT	Jika diatur, rutinitas panggilan balik akan dipanggil ketika perangkat jarak jauh terputus dari saluran L2CAP.
CALLBACK_RECV_PACKET	Jika diatur, rutinitas panggilan balik akan dipanggil ketika driver profil menerima paket L2CAP yang masuk.

Callback

Fungsi Panggilan Balik L2CAP yang diimplementasikan oleh driver profil, yang harus dipanggil oleh tumpukan driver Bluetooth untuk memberi tahu driver profil tentang perubahan apa pun pada koneksi L2CAP.

CallbackContext

Konteks untuk diteruskan ke fungsi panggilan balik yang ditentukan dalam anggota Panggilan Balik . Driver profil menentukan nilai ini.

ReferenceObject

Pointer ke objek untuk diteruskan ke ObReferenceObject dan ObDereferenceObject untuk mempertahankan jumlah referensi.

OutResults

Struktur CHANNEL_CONFIG_RESULTS yang berisi parameter konfigurasi untuk permintaan keluar.

InResults

Struktur CHANNEL_CONFIG_RESULTS yang berisi parameter konfigurasi untuk permintaan masuk.

IncomingQueueDepth

Menentukan panjang antrean masuk dalam unit transfer pesan (MTU).

Respons

Anggota ini digunakan sebagai parameter input untuk permintaan BRB_L2CA_OPEN_CHANNEL_RESPONSE dan parameter output untuk permintaan BRB_L2CA_OPEN_CHANNEL .

Untuk permintaan BRB_L2CA_OPEN_CHANNEL_RESPONSE , anggota ini memegang bendera yang menunjukkan respons driver profil terhadap perangkat jarak jauh. Nilai bendera yang valid terkandung dalam tabel berikut.

Bendera	Deskripsi
CONNECT_RSP_RESULT_NO_RESOURCES	Driver profil menolak koneksi karena kurangnya sumber daya.
CONNECT_RSP_RESULT_PENDING	Pengandar profil saat ini sibuk dan tidak dapat menerima koneksi. Coba lagi nanti.
CONNECT_RSP_RESULT_PSM_NEG	Driver profil menolak koneksi karena PSM tidak didukung.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Driver profil menolak koneksi karena alasan keamanan.
CONNECT_RSP_RESULT_SUCCESS	Driver profil menerima koneksi.

Untuk BRB_L2CA_OPEN_CHANNEL BRB, anggota ini berisi respons dari perangkat jarak jauh tempat driver profil mencoba terhubung. Nilai bendera yang valid terkandung dalam tabel berikut.

Bendera	Deskripsi
CONNECT_RSP_RESULT_NO_RESOURCES	Perangkat jarak jauh menolak koneksi karena kurangnya sumber daya.
CONNECT_RSP_RESULT_PSM_NEG	Perangkat jarak jauh menolak koneksi.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Perangkat jarak jauh menolak koneksi karena alasan keamanan.
CONNECT_RSP_RESULT_SUCCESS	Perangkat jarak jauh menerima koneksi.

ResponseStatus

Jika selama panggilan ke BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB, anggota Respons diatur ke CONNECT_RSP_RESULT_PENDING, anggota ini valid dan berisi salah satu nilai berikut:

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Keterangan

Untuk membuka saluran L2CAP, driver profil harus membangun dan mengirim permintaan BRB_L2CA_OPEN_CHANNEL .

Driver profil yang bertindak sebagai klien menentukan alamat tujuan, PSM, dan berbagai parameter konfigurasi.

Jika permintaan BRB_L2CA_OPEN_CHANNEL berhasil diselesaikan, berbagai informasi tentang koneksi yang baru dibuat tersedia di anggota OutResults dan InResults . OutResults menentukan parameter untuk setengah saluran keluar, dan InResults menentukan parameter untuk setengah saluran masuk.

Beberapa parameter konfigurasi yang diteruskan dalam struktur ini, seperti anggota Mtu , adalah rentang yang digunakan untuk negosiasi dengan radio jarak jauh. Klien harus menyediakan jangkauan seluas mungkin untuk meningkatkan kemungkinan negosiasi saluran yang berhasil. Menentukan ukuran MTU minimum yang lebih besar dari ukuran MTU minimum Bluetooth dasar hanya boleh dilakukan jika benar-benar diperlukan. Jika negosiasi gagal, koneksi akan gagal.

Driver profil harus mengalokasikan memori untuk menyimpan array yang disimpan di anggota ExtraOptions dan tidak boleh membebaskan memori ini sampai fungsi panggilan balik yang ditentukan dalam anggota Callback kembali dengan pemberitahuan IndicationFreeExtraOptionsINDICATION_CODE nilai yang diteruskan dalam parameter Indikasinya .

Anggota IncomingQueueDepth dari struktur _BRB_L2CA_OPEN_CHANNEL menentukan jumlah maksimum MTU yang akan diterima tumpukan driver Bluetooth dan mengantre pada koneksi sebelum mulai membuangnya. Mengatur nilai ini ke angka yang sangat kecil meningkatkan kemungkinan kehilangan data, sambil mengaturnya ke jumlah yang sangat besar dapat meningkatkan penggunaan memori. Mengatur anggota ini ke 10 adalah kompromi yang efektif.

Untuk menerima atau menolak permintaan koneksi L2CAP masuk yang dimulai oleh perangkat jarak jauh, driver profil harus membangun dan mengirim permintaan BRB_L2CA_OPEN_CHANNEL_RESPONSE .

Driver profil harus membangun dan mengirim permintaan BRB_L2CA_OPEN_CHANNEL_RESPONSE ketika tumpukan driver Bluetooth memanggil Fungsi Panggilan Balik L2CAP driver profil dan meneruskan IndicationRemoteConnect dalam parameter Indikasi fungsi panggilan balik.

Berdasarkan nilai anggota Respons struktur ini, tumpukan driver Bluetooth kemudian akan menerima atau menolak permintaan koneksi.

Driver profil menentukan apakah koneksi harus diterima dengan menyimpan nilai yang sesuai dalam anggota Respons struktur ini.

Setelah menerima respons CONNECT_RSP_RESULT_PENDING, klien yang terhubung harus mengatur ulang timer koneksinya dan menunggu pesan respons koneksi yang diperbarui. Driver profil yang memanggil BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB di mana anggota Respons diatur ke CONNECT_RSP_RESULT_PENDING harus segera mengeluarkan BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB tambahan dengan nilai koneksi yang diperbarui. Nilai yang diperbarui dapat berupa salah satu kode status yang dijelaskan dalam anggota Respons , termasuk mengirim ulang nilai CONNECT_RSP_RESULT_PENDING.

Driver profil harus mengalokasikan memori untuk menyimpan array yang disimpan di anggota ExtraOptions dan tidak boleh membebaskan memori ini sampai fungsi panggilan balik yang ditentukan dalam anggota Callback kembali dengan pemberitahuan IndicationFreeExtraOptionsINDICATION_CODE nilai yang diteruskan dalam parameter Indikasinya .