QMI Client API - Qualcomm Dragonwing Documentation

A QMI client owns a handle, connects that handle to a service instance, registers indication handling when needed, and sends requests to the service.

Client lifecycle

A client goes through these stages:

Create a handle – Create a QMI handle and supply a callback to be notified of service and transport events.
Connect to a service – Connect the handle to a service by specifying the service ID and instance ID.
Send requests and receive responses – Send requests to the service and receive responses. Optionally register a callback to receive unsolicited indications from the service.
Disconnect and destroy – Disconnect from the service and destroy the handle.

Keep the private context passed to handle creation alive until the handle is destroyed.

Create and connect a handle

To create a client:

Create a QMI handle with a callback function that will be called when service or transport events occur.
Connect the handle to a service by specifying the service ID and instance ID.
Optionally register a service event notifier to react to service availability changes.

Message descriptors

A descriptor tells the codec how to convert between your C structures and the QMI wire format. A descriptor identifies:

The message ID (which operation or event this is)
The maximum message size
An array of field descriptions, each specifying the data type, array behavior, field tag, and location in the C structure

Descriptors can represent primitive values, fixed and variable-length arrays, nested structures, and optional fields. You describe a message once and reuse the descriptor for requests, responses, and indications.

Encode and decode

You can encode and decode messages explicitly when you need to construct or inspect a message outside the request helpers. The codec converts between your C structures and the wire format.

Synchronous request

Send a request and wait for its response up to a supplied timeout. Use this form only when the caller can safely block. A timeout is a transaction failure from the caller’s perspective; it does not prove that the remote service did not receive or process the request.

Asynchronous request

Send a request without waiting for the response. The response callback receives the message ID, decoded response storage, and caller-private callback data. The request, response storage, descriptors, and callback context must remain valid for the lifetime required by the interface implementation.

Indication callbacks

Register an indication callback for unsolicited service events. The callback receives the message ID, message buffer, message length, and private context. Decode the indication with the descriptor for that message ID and treat every length and optional field as untrusted input.

Receive and destroy

Destroy the handle only after outstanding callbacks and transactions have been quiesced. The exact teardown order should ensure that no callback can access the handle or client context after it is released.

API Reference

Callback function prototypes

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

void qmi_client_notify_cb(qmi_client_type user_handle,
                          qmi_idl_service_object_type service_obj,
                          qmi_client_notify_event_type service_event,
                          void *notify_cb_data);

void qmi_client_recv_raw_msg_async_cb(qmi_client_type user_handle,
                                      unsigned int msg_id,
                                      void *resp_buf,
                                      unsigned int resp_buf_len,
                                      void *resp_cb_data,
                                      qmi_client_error_type transp_err);

void qmi_client_recv_msg_async_cb(qmi_client_type user_handle,
                                  unsigned int msg_id,
                                  void *resp_c_struct,
                                  unsigned int resp_c_struct_len,
                                  void *resp_cb_data,
                                  qmi_client_error_type transp_err);

void qmi_client_ind_cb(qmi_client_type user_handle,
                       unsigned int msg_id,
                       void *ind_buf,
                       unsigned int ind_buf_len,
                       void *resp_cb_data);

void qmi_client_error_cb(qmi_client_type user_handle,
                         qmi_client_error_type error,
                         void *err_cb_data);

void qmi_client_release_cb(void *release_cb_data);

Connection APIs

These functions manage the client’s connection to a service:

qmi_client_notifier_init(qmi_idl_service_object_type service_obj, qmi_client_os_params *os_params, qmi_client_type *user_handle) – Initialize a notifier with a service object and OS-specific parameters to receive service availability events.
qmi_client_init(qmi_service_info *service_info, qmi_idl_service_object_type service_obj, qmi_client_ind_cb ind_cb, void *ind_cb_data, qmi_client_os_params *os_params, qmi_client_type *user_handle) – Create a client handle for a specific service instance.
qmi_client_init_instance(qmi_idl_service_object_type service_obj, qmi_service_instance instance_id, qmi_client_ind_cb ind_cb, void *ind_cb_data, qmi_client_os_params *os_params, uint32_t timeout, qmi_client_type *user_handle) – Create a client handle for a service with a specific instance ID, with optional timeout support.
qmi_client_get_service_list(qmi_idl_service_object_type service_obj, qmi_service_info *service_info_array, uint32_t num_entries, uint32_t *num_services) – Query available services matching a service object.
qmi_client_get_any_service(qmi_idl_service_object_type service_obj, qmi_service_info *service_info) – Retrieve the first available service matching a service object.
qmi_client_get_service_instance(qmi_idl_service_object_type service_obj, qmi_service_instance instance_id, qmi_service_info *service_info) – Retrieve a specific service instance by instance ID.
qmi_client_register_error_cb(qmi_client_type user_handle, qmi_client_error_cb err_cb, void *err_cb_data) – Register a callback to be invoked when the service terminates or deregisters.
qmi_client_register_notify_cb(qmi_client_type user_handle, qmi_client_notify_cb notify_cb, void *notify_cb_data) – Register a callback for service availability events.

Message sending APIs

These functions send requests to the service:

qmi_client_send_raw_msg_sync(qmi_client_type user_handle, unsigned int msg_id, void *req_buf, unsigned int req_buf_len, void *resp_buf, unsigned int resp_buf_len, unsigned int resp_buf_recv_len, unsigned int timeout_msecs) – Send a request and wait for the response (raw format).
qmi_client_send_msg_sync(qmi_client_type user_handle, unsigned int msg_id, void *req_c_struct, unsigned int req_c_struct_len, void *resp_c_struct, unsigned int resp_c_struct_len, unsigned int resp_c_struct_recv_len, unsigned int timeout_msecs) – Send a request with automatic encoding and decoding.
qmi_client_send_raw_msg_async(qmi_client_type user_handle, unsigned int msg_id, void *req_buf, unsigned int req_buf_len, void *resp_buf, unsigned int resp_buf_len, qmi_client_async_rsp_cb resp_cb, void *resp_cb_data, qmi_txn_handle *txn_handle) – Send a request without waiting (raw format).
qmi_client_send_msg_async(qmi_client_type user_handle, unsigned int msg_id, void *req_c_struct, unsigned int req_c_struct_len, void *resp_c_struct, unsigned int resp_c_struct_len, qmi_client_recv_msg_async_cb resp_cb, void *resp_cb_data, qmi_txn_handle *txn_handle) – Send a request with automatic encoding.
qmi_client_delete_async_txn(qmi_client_type user_handle, qmi_txn_handle async_txn_handle) – Cancel a pending asynchronous request.
qmi_client_get_async_txn_id(qmi_client_type user_handle, qmi_txn_handle async_txn_handle, uint32_t *txn_id) – Obtain the transaction ID for a pending asynchronous request (deprecated).

Encode and decode APIs

These functions convert between C structures and the QMI wire format:

qmi_client_message_encode(qmi_client_type user_handle, qmi_idl_type_of_message_type req_resp_ind, unsigned int message_id, const void *p_src, unsigned int src_len, void *p_dst, unsigned int dst_len, unsigned int *dst_encoded_len) – Encode a C structure into QMI wire format.
qmi_client_message_decode(qmi_client_type user_handle, qmi_idl_type_of_message_type req_resp_ind, unsigned int message_id, const void *p_src, unsigned int src_len, void *p_dst, unsigned int dst_len) – Decode a QMI wire-format message into a C structure.

Release APIs

qmi_client_release_async(qmi_client_type user_handle, qmi_client_release_cb release_cb, void *release_cb_data) – Release the client handle asynchronously.

​Client lifecycle

​Create and connect a handle

​Message descriptors

​Encode and decode

​Synchronous request

​Asynchronous request

​Indication callbacks

​Receive and destroy

​API Reference

​Callback function prototypes

​Connection APIs

​Message sending APIs

​Encode and decode APIs

​Release APIs