> ## 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 Service API

> Register QMI services, process requests, send responses, and publish indications.

A QMI service registers a handle with service and instance identity, accepts client connections, resolves request descriptors by message ID, processes requests, and sends responses or indications.

## Service lifecycle

A service goes through these stages:

1. **Register** – Register the service with a service ID, instance ID, and a set of callbacks.
2. **Accept clients** – When a client connects, the service is notified and can initialize per-client state.
3. **Process requests** – When a client sends a request, the service receives it, processes it, and sends a response.
4. **Send indications** – The service can send unsolicited events to clients that have registered to receive them.
5. **Handle disconnects** – When a client disconnects, the service is notified and can clean up per-client state.
6. **Unregister** – Unregister the service when it stops.

## Service operations

When registering a service, you supply callbacks that the service framework will call at key points:

* **Connect callback** – Called when a client connects. Initialize per-client state, subscriptions, and policy.
* **Disconnect callback** – Called when a client disconnects. Release per-client state and cancel pending work.
* **Request descriptor callback** – Called when a request arrives. Return the descriptor for that message ID so the framework can decode the request.
* **Request callback** – Called after the request is decoded. Process the request and send a response, or save the request context and complete it later.

## Process a request

The request callback receives the service handle, client identity, request handle, message ID, and decoded request structure. The request handle identifies the transaction when the response is sent.

A service can process a request synchronously or save the request context and complete it later, provided the implementation keeps the client and request state alive until the response is sent or the client disconnects.

## Send a response

Send the response for one request to one client. Build the response using the descriptor associated with the response message. Check the return value and release request-specific resources only after the interface accepts the response.

## Send an indication

Use an indication for an unsolicited event. An indication is not matched to a request transaction. A service may send indications to one client or to each subscribed client. Keep subscription and per-client state separate so that disconnecting one client does not affect others.

## Connect and disconnect cleanup

The connect callback is the place to allocate client-specific state, initialize subscriptions, and set initial policy. The disconnect callback must cancel or complete pending work, release client state, and prevent delayed work from sending through a stale client pointer.

Unregister the service only after all clients have been disconnected or the service implementation has a defined shutdown path for them.

## Descriptor selection

The request descriptor callback is called with a message ID and receives storage pointers for the decoded request. The callback should return the exact descriptor for that message and reject a buffer that is too small for the decoded structure. A descriptor is part of the service contract: changing its field types, array rules, or field tags changes how clients interpret the message.

## API Reference

### Callback function prototypes

The service framework calls these callbacks at key points in the service lifecycle:

```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);
```

### Registration functions

These functions register and unregister services:

* `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)` – Register a service with the framework.

* `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)` – Register a service with additional configuration options.

* `qmi_csi_unregister(qmi_csi_service_handle service_provider)` – Unregister a service.

### Message sending functions

These functions send responses and indications to clients:

* `qmi_csi_send_resp(qmi_req_handle req_handle, unsigned int msg_id, void *resp_c_struct, unsigned int resp_c_struct_len)` – Send a response to a specific request.

* `qmi_csi_send_ind(qmi_client_handle client_handle, unsigned int msg_id, void *ind_c_struct, unsigned int ind_c_struct_len)` – Send an indication to a specific client.

* `qmi_csi_broadcast_ind(qmi_csi_service_handle service_provider, unsigned int msg_id, void *ind_c_struct, unsigned int ind_c_struct_len)` – Send an indication to all connected clients.

### Event handling

* `qmi_csi_handle_event(qmi_csi_service_handle service_provider, qmi_csi_os_params *os_params)` – Process pending events for the service. Called by the service's event loop to dispatch callbacks for client connections, disconnections, and requests.