структура _BRB_L2CA_OPEN_CHANNEL (bthddi.h)

Статья
08/07/2023

Структура _BRB_L2CA_OPEN_CHANNEL описывает канал L2CAP для открытия удаленного устройства или ответ драйвера профиля, принимающего или отклоняющего входящий запрос на подключение L2CAP, инициированный удаленным устройством.

Синтаксис

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

Члены

Hdr

Структура BRB_HEADER , содержащая сведения о текущем BRB.

ChannelHandle

Дескриптор, используемый для идентификации подключения при успешном подключении. При отправке BRB_L2CA_OPEN_CHANNEL оно будет заполнено по завершении BRB. При отправке BRB_L2CA_OPEN_CHANNEL_RESPONSE он должен быть заполнен сервером перед отправкой brb. Присвоенное значение должно быть INDICATION_PARAMETERS::ConnectionHandle передано во время IndicationRemoteConnect.

Response

Используется только с BRB_L2CA_OPEN_CHANNEL_RESPONSE. Используется одно из CONNECT_RSP_RESULT_Xxx значений.

Если BRB возвращается с состоянием STATUS_REQUEST_NOT_ACCEPTED, ответ будет содержать отрицательный ответ от удаленного узла.

ResponseStatus

Если значение Response равно CONNECT_RSP_RESULT_PENDING, это поле является допустимым. Используется одно из CONNECT_RSP_STATUS_XXX значений.

Psm

Протокол/сервисный мультиплексор (PSM), используемый каналом для подключения к удаленному устройству. При использовании с запросом BRB_L2CA_OPEN_CHANNEL этот элемент задается в качестве поля ввода. При использовании с запросом BRB_L2CA_OPEN_CHANNEL_RESPONSE этот элемент используется в качестве поля вывода.

ChannelFlags

Флаги, указывающие требования к каналу, который должен быть открыт. Допустимые значения флагов перечислены в следующей таблице:

Flag	Описание
CF_LINK_AUTHENTICATED	Ссылка должна пройти проверку подлинности.
CF_LINK_ENCRYPTED	Ссылка должна быть зашифрована. Установка этого флага также задает флаг CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Драйвер профиля указывает на то, что пользователям не предлагается ввести ПИН-код.

BtAddress

Адрес Bluetooth устройства, для которого предназначено подключение.

ConfigOut

Подструктура, содержащая параметры для BRB_L2CA_OPEN_CHANNEL BRB, отправленного на удаленное устройство.

ConfigOut.Flags

Flag	Описание
CF_LINK_AUTHENTICATED	Ссылка должна пройти проверку подлинности.
CF_LINK_ENCRYPTED	Ссылка должна быть зашифрована. Установка этого флага также задает флаг CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Драйвер профиля указывает на то, что пользователям не предлагается ввести ПИН-код.

ConfigOut.Mtu

Диапазон единиц передачи сообщений (MTU), используемый для согласования размера исходящей половины канала.

ConfigOut.FlushTO

Диапазон возможных значений, используемых для истечения времени ожидания очистки для исходящей половины канала.

ConfigOut.Flow

Зарезервировано для последующего использования. Не используйте.

ConfigOut.LinkTO

Время ожидания связи диспетчера ссылок.

ConfigOut.NumExtraOptions

Количество элементов массива, содержащихся в элементе ExtraOptions . Для большинства клиентов это значение должно быть равным нулю.

ConfigOut.ExtraOptions

ConfigOut.LocalQos

Зарезервировано для последующего использования. Не используйте.

ConfigOut.LocalQos.ServiceType

Зарезервировано для последующего использования. Не используйте.

ConfigOut.LocalQos.Latency

Зарезервировано для последующего использования. Не используйте.

ConfigIn

Подструктура, содержащая параметры параметров для проверки входящих BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB, отправляемых с удаленного устройства.

ConfigIn.Flags

Flag	Описание
CF_LINK_AUTHENTICATED	Ссылка должна пройти проверку подлинности.
CF_LINK_ENCRYPTED	Ссылка должна быть зашифрована. Установка этого флага также задает флаг CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Драйвер профиля указывает на то, что пользователям не предлагается ввести ПИН-код.

ConfigIn.Mtu

Диапазон единиц передачи сообщений (MTU), используемый для согласования размера исходящей половины канала.

ConfigIn.FlushTO

CallbackFlags

Флаг, указывающий, какие события должны создавать подпрограмму обратного вызова для уведомления драйвера профиля о возникновении события. Допустимые значения флагов содержатся в следующей таблице.

Flag	Описание
CALLBACK_CONFIG_EXTRA_IN	Если задано значение , подпрограмма обратного вызова будет вызываться, когда запрос конфигурации для удаленного устройства содержит дополнительные параметры. Если значение не задано, дополнительные параметры конфигурации будут отклонены как неизвестные. Этот флаг используется с BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB.
CALLBACK_CONFIG_EXTRA_OUT	Если этот параметр задан, подпрограмма обратного вызова будет вызываться, когда удаленное устройство отклоняет дополнительный параметр конфигурации из запроса BRB_L2CA_OPEN_CHANNEL. Если значение не задано и удаленное устройство отклоняет запрос конфигурации из-за дополнительного параметра, подключение будет закрыто.
CALLBACK_CONFIG_QOS	Если этот параметр задан, подпрограмма обратного вызова будет вызываться, когда удаленное устройство отправляет запрос конфигурации, содержащий значение QOS. Если этот флаг не установлен и удаленное устройство отправляет параметры QOS в запросе конфигурации или отклоняет запрошенные драйвером профиля параметры QOS, подключение отключается.
CALLBACK_DISCONNECT	Если этот параметр задан, подпрограмма обратного вызова будет вызываться при отключении удаленного устройства от канала L2CAP.
CALLBACK_RECV_PACKET	Если этот параметр задан, подпрограмма обратного вызова будет вызываться, когда драйвер профиля получает входящий пакет L2CAP.

Callback

Функция обратного вызова L2CAP, реализованная драйвером профиля, которую должен вызывать стек драйверов Bluetooth для уведомления драйвера профиля о любых изменениях подключения L2CAP.

CallbackContext

Контекст для передачи функции обратного вызова, указанной в элементе Callback . Это значение определяется драйвером профиля.

ReferenceObject

Указатель на объект, передаваемый в ObReferenceObject и ObDereferenceObject , для которых требуется сохранить количество ссылок.

OutResults

Структура CHANNEL_CONFIG_RESULTS , содержащая параметры конфигурации для исходящего запроса.

InResults

Структура CHANNEL_CONFIG_RESULTS, содержащая параметры конфигурации для входящего запроса.

IncomingQueueDepth

Указывает длину входящей очереди в единицах передачи сообщений (MTU).

Ответ

Этот элемент используется в качестве входного параметра для запроса BRB_L2CA_OPEN_CHANNEL_RESPONSE и выходного параметра для запроса BRB_L2CA_OPEN_CHANNEL .

Для запроса BRB_L2CA_OPEN_CHANNEL_RESPONSE этот элемент содержит флаг, указывающий на ответ драйвера профиля на удаленное устройство. Допустимые значения флагов содержатся в следующей таблице.

Flag	Описание
CONNECT_RSP_RESULT_NO_RESOURCES	Драйвер профиля отказал в подключении из-за нехватки ресурсов.
CONNECT_RSP_RESULT_PENDING	Драйвер профиля в настоящее время занят и не может принять подключение. Повторите попытку позже.
CONNECT_RSP_RESULT_PSM_NEG	Драйвер профиля отказал в подключении, так как PSM не поддерживается.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Драйвер профиля отказал в подключении по соображениям безопасности.
CONNECT_RSP_RESULT_SUCCESS	Драйвер профиля принял подключение.

Для BRB_L2CA_OPEN_CHANNEL BRB этот элемент содержит ответ от удаленного устройства, к которому драйвер профиля пытался подключиться. Допустимые значения флагов содержатся в следующей таблице.

Flag	Описание
CONNECT_RSP_RESULT_NO_RESOURCES	Удаленное устройство отклонило подключение из-за нехватки ресурсов.
CONNECT_RSP_RESULT_PSM_NEG	Удаленное устройство отказало в подключении.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Удаленное устройство отказало в подключении по соображениям безопасности.
CONNECT_RSP_RESULT_SUCCESS	Удаленное устройство приняло подключение.

ResponseStatus

Если во время вызова BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB для элемента Response задано значение CONNECT_RSP_RESULT_PENDING, этот член является допустимым и содержит одно из следующих значений:

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Если запрос BRB_L2CA_OPEN_CHANNEL завершается успешно, в элементах OutResults и InResults доступны различные сведения о созданном подключении . OutResults задает параметры для исходящей половины канала, а InResults — параметры для входящей половины канала.

Некоторые из параметров конфигурации, передаваемых в этой структуре, например элемент MTU , являются диапазонами, используемыми для согласования с удаленным радио. Клиенты должны предоставлять как можно более широкий диапазон, чтобы увеличить шансы на успешное согласование каналов. Указание минимального размера MTU, превышающего базовый минимальный размер MTU Bluetooth, следует выполнять только при крайней необходимости. Если согласование завершается сбоем, подключение завершится ошибкой.

Драйверы профилей должны выделять память для хранения массива, хранящегося в элементе ExtraOptions , и не освобождать эту память до тех пор, пока функция обратного вызова, определенная в члене callback , не вернет с уведомлением IndicationFreeExtraOptionsINDICATION_CODE значение, переданное в параметре Indication .

Член IncomingQueueDepth структуры _BRB_L2CA_OPEN_CHANNEL указывает максимальное количество единиц mtu, которые стек драйверов Bluetooth будет получать и помещать в очередь на подключение, прежде чем начнет их удалять. Установка этого значения в очень небольшое число увеличивает вероятность потери данных, а установка очень большого числа может увеличить использование памяти. Установка для этого элемента значения 10 является эффективным компрометацией.

Чтобы принять или отклонить входящий запрос на подключение L2CAP, инициированный удаленным устройством, драйверы профилей должны создать и отправить запрос BRB_L2CA_OPEN_CHANNEL_RESPONSE .

Драйвер профиля должен создавать и отправлять запрос BRB_L2CA_OPEN_CHANNEL_RESPONSE , когда стек драйверов Bluetooth вызывает функцию обратного вызова L2CAP драйвера профиля и передает IndicationRemoteConnect в параметре Indication функции обратного вызова.

В зависимости от значения элемента Response этой структуры стек драйверов Bluetooth будет принимать или отклонять запрос на подключение.

Драйвер профиля указывает, следует ли принимать подключение, сохраняя соответствующее значение в элементе Response этой структуры.

Получив ответ CONNECT_RSP_RESULT_PENDING, подключающийся клиент должен сбросить таймер подключения и дождаться обновленного сообщения ответа подключения. Профилирование драйверов, вызывающих BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB, для которого для элемента ответа задано значение CONNECT_RSP_RESULT_PENDING, должны немедленно выдавать дополнительный BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB с обновленным значением подключения. Обновленным значением может быть любой из кодов состояния, описанных в элементе Response , включая повторную отправка значения CONNECT_RSP_RESULT_PENDING.

Драйверы профилей должны выделять память для хранения массива, хранящегося в элементе ExtraOptions , и не должны освобождать эту память до тех пор, пока функция обратного вызова, определенная в элементе callback , не вернет с уведомлением IndicationFreeExtraOptionsINDICATION_CODE значение, переданное в параметре Indication .

Требования

Требование	Значение
Минимальная версия клиента	Versions:_Supported в Windows Vista и более поздних версий.
Верхняя часть	bthddi.h (включая Bthddi.h)