1 <!-- generated by ../../tools/undiag. DON'T CHANGE (change .mdx source) -->
2 \page clientserver Client / Server Protocol
4 The Guitarix engine can act as TCP server using the
5 [JSON-RPC 2.0](http://www.jsonrpc.org/specification) format, and the
6 Guitarix user interface can connect as a client. The engine can be
7 started in a "headless" mode, or include the user interface (called
8 "local UI" in the diagrams).
10 \image html client_server_notify.png
12 The client works synchronously, i.e. it waits for the servers answer
13 to an JSON-RPC call (blocking the glib main loop):
15 \image html client_server_call.png
17 Server state changes are broadcasted to all clients except the one
18 that triggered the state change (this client generally already knows
19 the new state). Clients notified of a state change must not reflect
20 that change back to the server (otherwise network delays and the
21 delayed processing of asynchronous responses in the glib main loop can
22 lead to strange effects or endless loops):
24 \image html client_server_notify_state_changed.png
26 The Guitarix UI is constructed on the assumption that requested state
27 changes happen synchronously. If the client needs to get information
28 about the state change after triggering it, a call should be used
29 instead of a notify, and the answer should include that information
30 (the answer to the calling client might be sent before notifying other
31 clients, the order is unspecified):
33 \image html client_server_call_state_changed.png
35 State changes can also be triggered by the local UI (or from inside the server engine):
37 \image html client_server_local_state_changed.png
39 Asynchronous notifications from the server are stashed away for the
40 main glib event loop while waiting for a call answer:
42 \image html client_server_call_state_changed_broadcast.png