【0x0002】HCI_Inquiry_Cancel命令详解

一、命令概述

二、命令格式及参数说明

三、返回事件及参数说明

3.1. HCI_Command_Complete事件

3.2. Status

3.3. 示例

四、命令执行过程

4.1. 前提条件检查

4.2. 命令构建与发送

4.3. 控制器处理

4.4. 返回状态参数

4.5. 主机接收反馈与处理

4.6. 执行流程结束

4.7. 示例代码

五、使用场景

5.1. 用户手动终止查询

5.2. 系统资源优化需求

5.3. 设备连接策略调整

5.4. 异常情况处理

六、注意事项

6.1. 命令发送时机

6.2. 命令参数和格式

6.3. 控制器处理过程中的注意事项

6.4. 返回状态参数的处理

6.5. 其他注意事项

HCI_Inquiry_Cancel 是蓝牙主机控制器接口（HCI）中的一个命令，主要用于在蓝牙设备查询（Inquiry）过程中，由主机（Host）向主机控制器（Controller）发送取消查询的指令。当主机不再需要继续查询周围的蓝牙设备，或者由于某些紧急情况（如系统资源紧张、用户手动停止等）需要终止查询操作时，就会使用这个命令。

一、命令概述

在整个蓝牙通信协议栈中，HCI_Inquiry_Cancel 命令处于主机和主机控制器之间的控制层面。它是主机对查询操作进行管理和控制的重要手段之一，与其他查询相关命令（如 HCI_Inquiry 命令用于发起查询）和事件（如 HCI_Inquiry_Result 事件用于返回查询结果、HCI_Inquiry_Complete 事件用于通知查询完成）相互配合，共同构成了蓝牙设备查询的完整流程。【0x0001】HCI_Inquiry命令详解-CSDN博客

【0x01】HCI_Inquiry_Complete事件详解-CSDN博客

HCI_Inquiry_Cancel命令用于使BR/EDR（Basic Rate/Enhanced Data Rate）控制器停止当前的查询（Inquiry）操作。其主要作用如下：

停止查询：当BR/EDR控制器正在执行查询操作时，此命令将立即停止查询。
资源释放：停止查询后，可以释放相关资源，以便BR/EDR控制器执行其他任务。
避免超时：如果查询操作可能因为某种原因而超时，使用此命令可以避免不必要的等待。

该命令应在以下条件下发出：

已经发出了HCI_Inquiry命令。
已经接收到了针对HCI_Inquiry命令的HCI_Command_Status事件。
在接收到HCI_Inquiry_Complete事件之前。

二、命令格式及参数说明

HCI_Inquiry_Cancel命令的格式通常遵循HCI协议的通用命令结构。

具体包括：

Packet Indicator：指示数据包类型，对于命令包通常为0x01。
OGF（OpCode Group Field）：操作码组字段，用于指示命令所属的类别。对于HCI_Inquiry_Cancel命令，OGF为0x01，表示该命令属于Link Control类别。
OCF（OpCode Command Field）：操作码命令字段，用于指示具体的命令。对于HCI_Inquiry_Cancel命令，OCF为0x0002。
Parameter Total Length：参数总长度字段，对于HCI_Inquiry_Cancel命令，该字段通常为0，因为该命令不需要任何参数。

三、返回事件及参数说明

HCI_Inquiry_Cancel 命令的返回参数及生成的事件为蓝牙设备间的交互提供了清晰的反馈机制，主机通过对这些返回信息的解析和判断，能够准确掌握命令执行情况，合理地安排后续操作以及进行相应的错误处理等，保障整个蓝牙设备查询及管理流程的有序进行。

`3.1. HCI_Command_Complete`事件

当 HCI_Inquiry_Cancel 命令完成执行后，蓝牙控制器会生成一个 HCI_Command_Complete 事件。这个事件是向主机传达命令执行结果的重要途径，确保主机能够知晓其发送的取消查询命令在控制器端的最终处理情况。

其中包含以下信息：

Event Code：指示这是一个事件包，并且是一个Command Complete事件。
Number of HCI Command Packets：表示与此次事件相关的HCI命令包的数量，对于HCI_Inquiry_Cancel命令，该字段通常为1。
Opcode：表示触发此事件的HCI命令的操作码，对于HCI_Inquiry_Cancel命令，该字段为0x0402（OGF=0x01，OCF=0x0002）。
Status：表示命令执行的结果。0x00表示成功，其他值表示失败，并伴随相应的错误代码。

事件与查询过程的关联：特别需要注意的是，一旦 HCI_Inquiry_Cancel 命令成功执行，对于此次被取消的查询（Inquiry）过程，将不会再生成 HCI_Inquiry_Complete 事件。因为查询过程由于取消命令的介入而提前终止，并非正常完成，所以不会出现用于表示正常查询结束的 HCI_Inquiry_Complete 事件，主机可以依据这一特点来判断查询是正常结束还是被中途取消，进而做出后续不同的操作处理，比如在用户界面上给出相应的提示信息，或者调整后续的蓝牙设备管理策略等。

3.2. Status

Status 参承载着关键的命令执行结果信息，用于向主机反馈 HCI_Inquiry_Cancel 命令执行情况。

取值为 0x00 时：表示 HCI_Inquiry_Cancel 命令成功执行。意味着蓝牙控制器接收到主机发送的取消查询命令后，顺利完成了停止当前正在进行的查询操作，包括停止发送查询请求包、不再处理接收到的查询响应包等一系列相关动作，并且已释放了与查询操作相关的资源，更新了内部状态机等相应状态标识。例如，在蓝牙设备查找周边设备的过程中，主机发送取消命令后，若控制器成功停止查询，就会返回此状态值告知主机查询已成功取消。
取值在 0x01 到 0xFF 之间时：代表 HCI_Inquiry_Cancel 命令执行失败。出现这种情况可能是由于多种原因导致的，比如查询操作已经自然结束（此时再发送取消命令就无法生效了），或者蓝牙控制器本身处于某种错误状态，无法按照要求执行取消操作等。当返回该范围内的值时，如需了解具体的错误原因，可以参照蓝牙协议文档中 [Vol 1] Part F 所列出的控制器错误代码（Controller Error Codes）。蓝牙Controller错误代码全面概览_connection rejected due to limited resources-CSDN博客

3.3. 示例

假设主机已经发送了一个HCI_Inquiry命令，并且随后决定取消该查询操作，它会发送一个HCI_Inquiry_Cancel命令给蓝牙控制器。蓝牙控制器接收到该命令后，会停止正在进行的查询操作（如果有的话），并生成一个HCI_Command_Complete事件来通知主机。主机接收到该事件后，会检查状态码来确定命令是否成功执行。

// 伪代码示例，用于说明HCI_Inquiry_Cancel命令的执行流程
void HandleHCIInquiryCancelResponse(uint8_t status) {if (status == 0x00) {// HCI_Inquiry_Cancel命令成功执行printf("Inquiry successfully cancelled.\n");} else {// HCI_Inquiry_Cancel命令执行失败printf("Failed to cancel inquiry. Status: 0x%02X\n", status);// 根据错误代码进行错误处理}
}// 假设这是接收HCI_Command_Complete事件的回调函数
void OnHCICommandComplete(uint8_t opcode, uint8_t status, uint8_t* data, uint16_t dataLength) {// 检查是否是HCI_Inquiry_Cancel命令的响应if (opcode == /* HCI_Inquiry_Cancel命令的Opcode */) {HandleHCIInquiryCancelResponse(status);}// 处理其他HCI命令的响应...
}

请注意，上述伪代码中的opcode应该替换为HCI_Inquiry_Cancel命令的实际操作码（Opcode），这通常是在蓝牙HCI协议中定义的。同时，OnHCICommandComplete函数是一个假设的回调函数，用于处理接收到的HCI_Command_Complete事件。在实际应用中，需要根据蓝牙协议栈提供的API来实现这个函数。

四、命令执行过程

HCI_Inquiry_Cancel命令的执行流程涉及蓝牙设备的主机（Host）和蓝牙控制器（Controller）之间的交互。以下是该命令执行流程的详细步骤。

4.1. 前提条件检查

确认查询状态：
- 主机首先检查是否已经发出了HCI_Inquiry命令。
- 确认已经接收到针对该HCI_Inquiry命令的HCI_Command_Status事件。
- 确保HCI_Inquiry_Complete事件尚未发生，即查询操作仍在进行中。

4.2. 命令构建与发送

构建命令：
- 根据HCI协议的规范，主机构建HCI_Inquiry_Cancel命令的数据包。
- 数据包包括Packet Indicator（0x01）、OGF（0x01，表示Link Control类别）、OCF（0x0002，表示HCI_Inquiry_Cancel命令）以及Parameter Total Length（0，因为此命令无参数）。
发送命令：主机通过HCI接口将构建好的HCI_Inquiry_Cancel命令数据包发送给蓝牙控制器。

4.3. 控制器处理

命令解析：蓝牙控制器接收到命令后，解析数据包，识别出这是一个HCI_Inquiry_Cancel命令。
停止查询：
- 控制器检查当前是否处于查询模式。
- 如果是，则立即停止发送查询请求包，并停止处理接收到的任何查询响应包。
资源释放与状态更新：
- 控制器释放与查询操作相关的资源，如临时缓冲区、定时器等。
- 更新内部状态机，将查询相关的状态标记为已取消。

4.4. 返回状态参数

生成Command Complete事件：
- 控制器生成一个Command Complete事件，用于表示HCI_Inquiry_Cancel命令的执行结果。
- 事件中包含状态码（Status），用于指示命令是否成功执行。
发送状态参数：控制器通过HCI接口将Command Complete事件发送给主机。

4.5. 主机接收反馈与处理

事件接收：主机通过HCI接口接收蓝牙控制器发送的Command Complete事件。
结果处理：
- 主机解析Command Complete事件，检查状态码。
- 如果状态码表示成功（0x00），则继续执行其他任务或进行后续操作。
- 如果状态码表示失败（0x01-0xFF），则根据错误代码进行相应的错误处理。

4.6. 执行流程结束

流程结束：至此，HCI_Inquiry_Cancel命令的执行流程结束。主机和控制器均已完成各自的任务，并释放了相关资源。

4.7. 示例代码

以下是一个简化的示例，展示上述个流程的关键步骤。请注意，这个示例不会与实际的蓝牙硬件交互，而是模拟了主机和控制器之间的交互过程。

#include <stdio.h>
#include <stdbool.h>// 模拟的HCI接口结构体
typedef struct {bool inquiryActive; // 查询操作是否正在进行int statusCode;     // 命令执行的状态码
} HCI_Interface;// 初始化HCI接口
void HCI_Init(HCI_Interface *hci) {hci->inquiryActive = false;hci->statusCode = 0;
}// 模拟发送HCI_Inquiry_Cancel命令的函数
bool Send_HCI_Inquiry_Cancel(HCI_Interface *hci) {// 检查查询是否正在进行if (!hci->inquiryActive) {printf("Error: Inquiry is not active.\n");return false;}// 停止查询操作hci->inquiryActive = false;// 模拟成功执行命令hci->statusCode = 0x00; // 0x00表示成功// 在实际应用中，这里会调用蓝牙控制器的接口来发送命令// 并且等待控制器的响应return true;
}// 模拟接收Command Complete事件的函数
void Receive_Command_Complete(HCI_Interface *hci) {// 在实际应用中，这里会从蓝牙控制器接收Command Complete事件// 并解析其中的状态码// 这里我们直接打印状态码printf("Command Complete Event Received. Status Code: 0x%02X\n", hci->statusCode);
}int main() {HCI_Interface hci;HCI_Init(&hci);// 模拟开始查询操作hci.inquiryActive = true;printf("Inquiry started.\n");// 发送HCI_Inquiry_Cancel命令if (Send_HCI_Inquiry_Cancel(&hci)) {printf("HCI_Inquiry_Cancel command sent successfully.\n");}// 模拟接收Command Complete事件Receive_Command_Complete(&hci);// 执行流程结束printf("HCI_Inquiry_Cancel execution flow ended.\n");return 0;
}

在这个示例中，我们定义了一个HCI_Interface结构体来模拟HCI接口的状态。HCI_Init函数用于初始化这个接口。Send_HCI_Inquiry_Cancel函数模拟了发送HCI_Inquiry_Cancel命令的过程，包括检查查询是否正在进行、停止查询操作以及设置状态码。Receive_Command_Complete函数模拟了接收Command Complete事件并打印状态码的过程。

请注意，这个示例代码并没有实际的蓝牙硬件交互，也没有使用任何蓝牙协议栈的API。仅仅是为了展示HCI_Inquiry_Cancel命令执行流程的关键步骤。在实际应用中，需要使用蓝牙芯片制造商提供的API来与蓝牙硬件进行交互，并处理实际的HCI命令和事件。

五、使用场景

HCI_Inquiry_Cancel命令在蓝牙通信中具有特定的使用场景，主要用于取消当前正在进行的设备查询（inquiry）操作。以下是该命令的主要使用场景：

5.1. 用户手动终止查询

移动设备场景：
- 用户通过蓝牙设置界面发起设备查询，如查找附近的蓝牙耳机或蓝牙音箱。
- 在查询过程中，用户找到想要连接的设备或决定不再继续等待查询结果。
- 用户手动停止查询，软件系统发送HCI_Inquiry_Cancel命令给蓝牙控制器，终止查询。
智能穿戴设备场景：
- 智能手表等设备在查找周边蓝牙设备进行数据同步或功能扩展。
- 用户发现不需要的设备过多或找到目标设备，通过手表操作按钮取消查询。
- 软件调用HCI_Inquiry_Cancel命令中断查询，节省电量和系统资源。

5.2. 系统资源优化需求

多任务处理环境下的资源分配：
- 设备同时运行多个应用程序，如蓝牙查询、文件下载、视频播放等。
- 蓝牙查询占用过多的系统资源时，系统根据资源监控情况自动发送HCI_Inquiry_Cancel命令。
- 优先保障其他关键应用程序的资源需求，如视频播放的流畅性。
低功耗设备的资源管理：
- 低功耗蓝牙设备（如蓝牙传感器节点）的电池电量和计算资源有限。
- 电量低于一定阈值或内存等资源不足时，系统使用HCI_Inquiry_Cancel命令停止查询。
- 延长设备使用寿命和维持基本功能的稳定运行。

5.3. 设备连接策略调整

从主动查询到被动等待连接的转换：
- 设备最初处于主动查询模式，寻找可连接的设备。
- 接收到特定设备的连接请求信号或根据预设规则改变策略。
- 发送HCI_Inquiry_Cancel命令停止查询，从主动查询转为被动等待连接。
连接特定设备优先策略：
- 设备确定要连接特定蓝牙设备，查询可能干扰连接过程。
- 发送HCI_Inquiry_Cancel命令，集中资源和信号通道用于与特定设备的连接。

5.4. 异常情况处理

查询时间过长或无响应设备过多：
- 查询持续时间过长或查询到大量无响应设备。
- 系统发送HCI_Inquiry_Cancel命令终止查询，避免浪费资源。
- 重新调整查询策略或等待更合适的时机进行查询。
设备硬件或软件故障导致的异常查询：
- 蓝牙设备硬件（如蓝牙芯片过热）或软件（如查询程序错误）出现故障。
- 系统发送HCI_Inquiry_Cancel命令尝试停止异常查询。
- 触发故障恢复机制，如重启蓝牙模块或相关软件服务。

HCI_Inquiry_Cancel命令在蓝牙通信中具有多种使用场景，主要用于提前终止不必要的查询、避免干扰和冲突、优化用户体验、响应系统资源变化以及处理异常情况。这些场景涵盖了从用户手动操作到系统自动管理，从正常操作到异常处理的多个方面。

六、注意事项

在使用HCI_Inquiry_Cancel命令时，需要注意以下几个事项以确保命令的有效性和系统的稳定性。

6.1. 命令发送时机

确认查询状态：
- 在运用 HCI_Inquiry_Cancel 命令前，主机务必严谨确认当前蓝牙控制器所处的查询状态。
- 这要求主机已成功发出 HCI_Inquiry 命令，并且接收到与之对应的 HCI_Command_Status 事件，同时 HCI_Inquiry_Complete 事件还未发生，只有满足这一系列条件，才意味着查询操作正在进行，此时发送取消命令才是有效的。
避免频繁发送：
- 不要频繁发送取消命令，以免对蓝牙设备性能产生负面影响。
- 合理设置扫描间隔或提供智能取消机制，避免过度消耗系统资源。

6.2. 命令参数和格式

严格遵循协议格式
- 严格按照蓝牙协议规定的格式构建命令数据包。
- 确保Packet Indicator、OGF、OCF和Parameter Total Length等字段设置正确。
注意参数变化
- 在某些蓝牙协议扩展或特定设备实现中，可能存在参数。
- 仔细研究相关文档，了解参数的含义、取值范围和作用，确保正确使用命令。

6.3. 控制器处理过程中的注意事项

资源释放的完整性
- 确保蓝牙控制器在停止查询后，所有与查询操作相关的资源都被正确释放。
- 关注内存缓冲区、定时器等资源的释放情况，避免内存泄漏或定时器混乱等问题。
状态更新的准确性
- 蓝牙控制器内部的状态机需要准确更新状态，将查询相关的状态标记为已取消。
- 确保后续操作和查询状态判断的准确性，避免设备出现混乱或错误提示。

6.4. 返回状态参数的处理

正确解析状态码
- 主机需要正确解析蓝牙控制器返回的Command Complete事件中的状态码。
- 根据状态码判断命令是否成功执行，并采取相应的处理措施。
考虑错误处理策略
- 根据返回的状态码，制定完善的错误处理策略。
- 对不同的错误原因采取不同的措施，如重试取消操作、提示用户、记录错误日志等。

6.5. 其他注意事项

系统兼容性
- 不同的蓝牙设备和控制器可能对HCI_Inquiry_Cancel命令的支持程度不同。
- 在开发或部署相关应用程序时，应考虑到系统的兼容性，确保命令能够在目标设备上正确执行。
遵循安全要求
- 在使用HCI_Inquiry_Cancel命令时，应始终遵循蓝牙核心规范和相关安全要求。
- 确保命令的发送和接收符合规范定义的数据格式和通信协议。
记录日志和调试信息
- 在开发和调试阶段，应记录相关的日志和调试信息。
- 这有助于在出现问题时进行排查和修复，包括命令的发送时间、接收到的响应、错误代码等。