ipc: add request_id to json

If the request contains a "request_id", copy it back into the
response. There is no interpretation of the request_id value by mpv; the
only purpose is to make it easier on the requester by providing an
ability to match up responses with requests.

Because the IPC mechanism sends events continously, it's possible for
the response to a request to arrive several events after the request was
made. This can make it very difficult on the requester to determine
which response goes to which request.

2 files changed, 28 insertions, 0 deletions

diff --git a/DOCS/man/ipc.rst b/DOCS/man/ipc.rst
index bbe07f0aba..31333a2c6a 100644
--- a/DOCS/man/ipc.rst
+++ b/DOCS/man/ipc.rst
@@ -79,6 +79,24 @@ mpv will also send events to clients with JSON messages of the following form:
 where ``event_name`` is the name of the event. Additional event-specific fields
 can also be present. See `List of events`_ for a list of all supported events.
 
+Because events can occur at any time, it may be difficult at times to determine
+which response goes with which command. Commands may optionally include a
+``request_id`` which, if provided in the command request, will be copied
+verbatim into the response. mpv does not intrepret the ``request_id`` in any
+way; it is solely for the use of the requester.
+
+For example, this request:
+
+::
+
+    { "command": ["get_property", "time-pos"], "request_id": 100 }
+
+Would generate this response:
+
+::
+
+    { "error": "success", "data": 1.468135, "request_id": 100 }
+
 All commands, replies, and events are separated from each other with a line
 break character (``\n``).
 
diff --git a/input/ipc.c b/input/ipc.c
index b49d64b8d4..ec219da31f 100644
--- a/input/ipc.c
+++ b/input/ipc.c
@@ -257,6 +257,8 @@ static char *json_execute_command(struct client_arg *arg, void *ta_parent,
         goto error;
     }
 
+    mpv_node *reqid_node = mpv_node_map_get(&msg_node, "request_id");
+
     mpv_node *cmd_node = mpv_node_map_get(&msg_node, "command");
     if (!cmd_node ||
         (cmd_node->format != MPV_FORMAT_NODE_ARRAY) ||
@@ -470,6 +472,14 @@ static char *json_execute_command(struct client_arg *arg, void *ta_parent,
     }
 
 error:
+    /* If the request contains a "request_id", copy it back into the response.
+     * This makes it easier on the requester to match up the IPC results with
+     * the original requests.
+     */
+    if (reqid_node) {
+        mpv_node_map_add(ta_parent, &reply_node, "request_id", reqid_node);
+    }
+
     mpv_node_map_add_string(ta_parent, &reply_node, "error", mpv_error_string(rc));
 
     char *output = talloc_strdup(ta_parent, "");