> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QMI 服务 API

> 注册 QMI 服务、处理请求、发送响应以及发布指示。

QMI 服务注册一个带有服务和实例标识的句柄，接受客户端连接，通过消息 ID 查找请求描述符，处理请求，并发送响应或指示。

## 服务生命周期

服务会经历以下阶段：

1. **注册** —— 使用服务 ID、实例 ID 和一组回调注册服务。
2. **接受客户端** —— 当客户端连接时，服务会收到通知，可以初始化每客户端状态。
3. **处理请求** —— 当客户端发送请求时，服务接收、处理并发送响应。
4. **发送指示** —— 服务可以向已注册接收事件的客户端发送非请求触发的事件。
5. **处理断开** —— 当客户端断开时，服务会收到通知，可以清理每客户端状态。
6. **注销** —— 在服务停止时注销该服务。

## 服务操作

在注册服务时，你提供一些回调，服务框架将在关键节点调用它们：

* **连接回调** —— 客户端连接时调用。初始化每客户端状态、订阅和策略。
* **断开回调** —— 客户端断开时调用。释放每客户端状态并取消挂起的工作。
* **请求描述符回调** —— 请求到达时调用。返回该消息 ID 对应的描述符，以便框架解码该请求。
* **请求回调** —— 请求解码之后调用。处理请求并发送响应，或保存请求上下文以稍后完成。

## 处理请求

请求回调会收到服务句柄、客户端身份、请求句柄、消息 ID 以及解码后的请求结构。请求句柄在发送响应时用于标识该事务。

服务可以同步处理请求，或者保存请求上下文以稍后完成，前提是实现保持客户端和请求状态在响应发送之前或客户端断开之前有效。

## 发送响应

将一个请求的响应发送给一个客户端。使用与响应消息关联的描述符构造响应。检查返回值，并仅在接口接受响应之后才释放请求特定的资源。

## 发送指示

使用指示来传递非请求触发的事件。指示不与某个请求事务匹配。服务可以向单个客户端发送指示，也可以向每个已订阅的客户端发送。请将订阅和每客户端状态分开保存，这样断开一个客户端不会影响其他客户端。

## 连接与断开清理

连接回调是分配客户端特定状态、初始化订阅以及设置初始策略的位置。断开回调必须取消或完成挂起的工作、释放客户端状态，并防止延迟工作通过陈旧的客户端指针发送。

只有当所有客户端都已断开，或者服务实现为其定义了明确的关闭路径之后，才可注销服务。

## 描述符选择

请求描述符回调在被调用时会收到一个消息 ID 和用于承载解码后请求的存储指针。回调应返回该消息的精确描述符，并拒绝对解码结构而言过小的缓冲区。描述符是服务契约的一部分：改变其字段类型、数组规则或字段标签会改变客户端对消息的解释方式。

## API 参考

### 回调函数原型

服务框架在服务生命周期的关键节点调用以下回调：

```c theme={null}
qmi_csi_cb_error qmi_csi_connect(qmi_client_handle client_handle,
                                 void *service_cookie,
                                 void **connection_handle);

qmi_csi_cb_error qmi_csi_disconnect(void *connection_handle,
                                    void *service_cookie);

qmi_csi_cb_error qmi_csi_process_req(void *connection_handle,
                                     qmi_req_handle req_handle,
                                     unsigned int msg_id,
                                     void *req_c_struct,
                                     unsigned int req_c_struct_len,
                                     void *service_cookie);

qmi_csi_cb_error qmi_csi_send_resp(qmi_req_handle req_handle,
                                   unsigned int msg_id,
                                   void *resp_c_struct,
                                   unsigned int resp_c_struct_len);

qmi_csi_cb_error qmi_csi_send_ind(qmi_client_handle client_handle,
                                  unsigned int msg_id,
                                  void *ind_c_struct,
                                  unsigned int ind_c_struct_len);

qmi_csi_cb_error qmi_csi_broadcast_ind(qmi_csi_service_handle service_provider,
                                       unsigned int msg_id,
                                       void *ind_c_struct,
                                       unsigned int ind_c_struct_len);
```

### 注册函数

以下函数用于注册和注销服务：

* `qmi_csi_register(qmi_idl_service_object_type service_obj, qmi_csi_connect service_connect, qmi_csi_disconnect service_disconnect, qmi_csi_process_req service_process_req, void *service_cookie, qmi_csi_os_params *os_params, qmi_csi_service_handle *service_provider)` —— 向框架注册一个服务。

* `qmi_csi_register_with_options(qmi_idl_service_object_type service_obj, qmi_csi_connect service_connect, qmi_csi_disconnect service_disconnect, qmi_csi_process_req service_process_req, void *service_cookie, qmi_csi_os_params *os_params, qmi_csi_options *options, qmi_csi_service_handle *service_provider)` —— 使用额外的配置选项注册服务。

* `qmi_csi_unregister(qmi_csi_service_handle service_provider)` —— 注销一个服务。

### 消息发送函数

以下函数向客户端发送响应和指示：

* `qmi_csi_send_resp(qmi_req_handle req_handle, unsigned int msg_id, void *resp_c_struct, unsigned int resp_c_struct_len)` —— 向指定请求发送响应。

* `qmi_csi_send_ind(qmi_client_handle client_handle, unsigned int msg_id, void *ind_c_struct, unsigned int ind_c_struct_len)` —— 向指定客户端发送指示。

* `qmi_csi_broadcast_ind(qmi_csi_service_handle service_provider, unsigned int msg_id, void *ind_c_struct, unsigned int ind_c_struct_len)` —— 向所有已连接的客户端发送指示。

### 事件处理

* `qmi_csi_handle_event(qmi_csi_service_handle service_provider, qmi_csi_os_params *os_params)` —— 处理服务的挂起事件。由服务的事件循环调用，以分派客户端连接、断开和请求的回调。