_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 相关信息的 BRB_HEADER 结构。

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

指定要打开的通道的要求的标志。下表列出了有效的标志值：

标志	描述
CF_LINK_AUTHENTICATED	必须对链接进行身份验证。
CF_LINK_ENCRYPTED	链接必须加密。设置此标志还会设置CF_LINK_AUTHENTICATED标志。
CF_LINK_SUPPRESS_PIN	配置文件驱动程序指示其首选项，即不会提示用户输入 PIN。

BtAddress

要连接的设备的蓝牙地址。

ConfigOut

包含发送到远程设备的 BRB_L2CA_OPEN_CHANNEL BRB 的参数设置的子结构。

ConfigOut.Flags

指定要打开的通道的要求的标志。下表列出了有效的标志值：

标志	描述
CF_LINK_AUTHENTICATED	必须对链接进行身份验证。
CF_LINK_ENCRYPTED	链接必须加密。设置此标志还会设置CF_LINK_AUTHENTICATED标志。
CF_LINK_SUPPRESS_PIN	配置文件驱动程序指示其首选项，即不会提示用户输入 PIN。

ConfigOut.Mtu

消息传输单位的范围 (MTU) ，用于协商通道出站一半的大小。

ConfigOut.FlushTO

要用于通道出站一半的刷新超时的可能值的范围。

ConfigOut.Flow

保留供将来使用。请勿使用。

ConfigOut.LinkTO

链接管理器链接超时。

ConfigOut.NumExtraOptions

ExtraOptions 成员中包含的数组项数。对于大多数客户端，此值应为零。

ConfigOut.ExtraOptions

ExtraOptions 成员中包含的数组项数。对于大多数客户端，此值应为零。

ConfigOut.LocalQos

保留供将来使用。请勿使用。

ConfigOut.LocalQos.ServiceType

保留供将来使用。请勿使用。

ConfigOut.LocalQos.Latency

保留供将来使用。请勿使用。

ConfigIn

包含参数设置的子结构，用于验证从远程设备发送 的传入BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB。

ConfigIn.Flags

指定要打开的通道的要求的标志。下表列出了有效的标志值：

标志	描述
CF_LINK_AUTHENTICATED	必须对链接进行身份验证。
CF_LINK_ENCRYPTED	链接必须加密。设置此标志还会设置CF_LINK_AUTHENTICATED标志。
CF_LINK_SUPPRESS_PIN	配置文件驱动程序指示其首选项，即不会提示用户输入 PIN。

ConfigIn.Mtu

消息传输单位的范围 (MTU) ，用于协商通道出站一半的大小。

ConfigIn.FlushTO

要用于通道出站一半的刷新超时的可能值的范围。

CallbackFlags

一个标志，指定哪些事件应生成回调例程，以通知配置文件驱动程序已发生该事件。下表中包含有效的标志值。

标志	描述
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 回调函数，蓝牙驱动程序堆栈应调用该函数，以通知配置文件驱动程序有关 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 请求，此成员包含一个标志，指示配置文件驱动程序对远程设备的响应。下表中包含有效的标志值。

标志	描述
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，此成员包含配置文件驱动程序尝试连接的远程设备的响应。下表中包含有效的标志值。

标志	描述
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 期间 ，响应 成员设置为 CONNECT_RSP_RESULT_PENDING，则此成员有效且包含以下值之一：

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

注解

若要打开 L2CAP 通道，配置文件驱动程序应生成并发送 BRB_L2CA_OPEN_CHANNEL请求。

充当客户端的配置文件驱动程序指定目标地址、PSM 和各种配置参数。

如果BRB_L2CA_OPEN_CHANNEL请求成功完成，则 OutResults 和 InResults 成员中提供了有关新创建连接的各种信息。 OutResults 指定通道出站一半的参数， InResults 指定通道入站一半的参数。

在此结构中传递的几个配置参数（如 Mtu 成员）是用于与远程无线电协商的范围。客户端应提供尽可能广泛的范围，以增加成功通道协商的机会。仅当绝对必要时，才应指定大于基本蓝牙最小 MTU 大小的最小 MTU 大小。如果协商失败，连接将失败。

配置文件驱动程序必须分配内存来存储存储在 ExtraOptions 成员中的数组，并且不应释放此内存，直到 Callback 成员中定义的回调函数返回 一个 IndicationFreeExtraOptions 通知 INDICATION_CODE 在其 Indication 参数中传递的值。

_BRB_L2CA_OPEN_CHANNEL 结构的 IncomingQueueDepth 成员指定蓝牙驱动程序堆栈在开始放弃这些 MTU 之前在连接上接收和排队的最大 MTU 数。将此值设置为非常小的数字会增加数据丢失的可能性，而将其设置为非常大的数字可能会增加内存使用率。将此成员设置为 10 是一种有效的妥协。

若要接受或拒绝远程设备发起的传入 L2CAP 连接请求，配置文件驱动程序应生成并发送 BRB_L2CA_OPEN_CHANNEL_RESPONSE 请求。

当蓝牙驱动程序堆栈调用配置文件驱动程序的 L2CAP 回调函数并在回调函数的指示参数中传递 IndicationRemoteConnect 时，配置文件驱动程序应生成并发送BRB_L2CA_OPEN_CHANNEL_RESPONSE请求。

根据此结构的 Response 成员的值，蓝牙驱动程序堆栈随后将接受或拒绝连接请求。

配置文件驱动程序指定是否应通过在此结构的 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 成员中的数组，在回调成员中定义的回调函数返回 指示FreeExtraOptions 通知 INDICATION_CODE 在其 Indication 参数中传递的值之前，不应释放此内存。