client API: add mpv_command_ret

This change adds a version of `mpv_command` that also returns a result.
The main rationale behind this is `mpv_command_node` requires defining
multiple structs before you can even use it, which results in a pretty
painful to use interface just to get the result from a command.

There isn't really a good name for this function, so I'm open to
suggestions on a better name for it.

1 files changed, 16 insertions, 0 deletions

diff --git a/libmpv/client.h b/libmpv/client.h
index eeaa687318..2fea40de13 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -970,6 +970,22 @@ int mpv_command(mpv_handle *ctx, const char **args);
 int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result);
 
 /**
+ * This is essentially identical to mpv_command() but it also returns a result.
+ *
+ * Does not use OSD and string expansion by default.
+ *
+ * @param[in] args NULL-terminated list of strings. Usually, the first item
+ *                 is the command, and the following items are arguments.
+ * @param[out] result Optional, pass NULL if unused. If not NULL, and if the
+ *                    function succeeds, this is set to command-specific return
+ *                    data. You must call mpv_free_node_contents() to free it
+ *                    (again, only if the command actually succeeds).
+ *                    Not many commands actually use this at all.
+ * @return error code (the result parameter is not set on error)
+ */
+int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result);
+
+/**
  * Same as mpv_command, but use input.conf parsing for splitting arguments.
  * This is slightly simpler, but also more error prone, since arguments may
  * need quoting/escaping.