Service lifecycle
A service goes through these stages:- Register – Register the service with a service ID, instance ID, and a set of callbacks.
- Accept clients – When a client connects, the service is notified and can initialize per-client state.
- Process requests – When a client sends a request, the service receives it, processes it, and sends a response.
- Send indications – The service can send unsolicited events to clients that have registered to receive them.
- Handle disconnects – When a client disconnects, the service is notified and can clean up per-client state.
- 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: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.