summaryrefslogtreecommitdiffstats
path: root/libmpv/client.h
diff options
context:
space:
mode:
Diffstat (limited to 'libmpv/client.h')
-rw-r--r--libmpv/client.h105
1 files changed, 88 insertions, 17 deletions
diff --git a/libmpv/client.h b/libmpv/client.h
index 39df20a8c0..51beb1a41b 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -107,8 +107,9 @@ extern "C" {
* careful not accidentally interpret the mpv_event->reply_userdata if an
* event is not a reply. (For non-replies, this field is set to 0.)
*
- * Currently, asynchronous calls are always strictly ordered (even with
- * synchronous calls) for each client, although that may change in the future.
+ * Asynchronous calls may be reordered in arbitrarily with other synchronous
+ * and asynchronous calls. If you want a guaranteed order, you need to wait
+ * until asynchronous calls report completion before doing the next call.
*
* Multithreading
* --------------
@@ -195,6 +196,18 @@ extern "C" {
* or change the underlying datatypes. It might be a good idea to prefer
* MPV_FORMAT_STRING over other types to decouple your code from potential
* mpv changes.
+ *
+ * Future changes
+ * --------------
+ *
+ * This are the planned changes that will most likely be done on the next major
+ * bump of the library:
+ *
+ * - remove all symbols and include files that are marked as deprecated
+ * - reassign enum numerical values to remove gaps
+ * - remove the mpv_opengl_init_params.extra_exts field
+ * - change the type of mpv_event_end_file.reason
+ * - disabling all events by default
*/
/**
@@ -210,7 +223,7 @@ extern "C" {
* relational operators (<, >, <=, >=).
*/
#define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
-#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 102)
+#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 103)
/**
* The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before
@@ -928,10 +941,25 @@ int mpv_command(mpv_handle *ctx, const char **args);
*
* Does not use OSD and string expansion by default.
*
- * @param[in] args mpv_node with format set to MPV_FORMAT_NODE_ARRAY; each entry
- * is an argument using an arbitrary format (the format must be
- * compatible to the used command). Usually, the first item is
- * the command name (as MPV_FORMAT_STRING).
+ * The args argument can have one of the following formats:
+ *
+ * MPV_FORMAT_NODE_ARRAY:
+ * Positional arguments. Each entry is an argument using an arbitrary
+ * format (the format must be compatible to the used command). Usually,
+ * the first item is the command name (as MPV_FORMAT_STRING). The order
+ * of arguments is as documented in each command description.
+ *
+ * MPV_FORMAT_NODE_MAP:
+ * Named arguments. This requires at least an entry with the key "name"
+ * to be present, which must be a string, and contains the command name.
+ * The special entry "_flags" is optional, and if present, must be an
+ * array of strings, each being a command prefix to apply. All other
+ * entries are interpreted as arguments. They must use the argument names
+ * as documented in each command description. Some commands do not
+ * support named arguments at all, and must use MPV_FORMAT_NODE_ARRAY.
+ *
+ * @param[in] args mpv_node with format set to one of the values documented
+ * above (see there for details)
* @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
@@ -954,14 +982,11 @@ int mpv_command_string(mpv_handle *ctx, const char *args);
* Same as mpv_command, but run the command asynchronously.
*
* Commands are executed asynchronously. You will receive a
- * MPV_EVENT_COMMAND_REPLY event. (This event will also have an
- * error code set if running the command failed.)
- *
- * This has nothing to do with the "async" command prefix, although they might
- * be unified in the future. For now, calling this API means that the command
- * will be synchronously executed on the core, without blocking the API user.
+ * MPV_EVENT_COMMAND_REPLY event. This event will also have an
+ * error code set if running the command failed. For commands that
+ * return data, the data is put into mpv_event_command.result.
*
- * * Safe to be called from mpv render API threads.
+ * Safe to be called from mpv render API threads.
*
* @param reply_userdata the value mpv_event.reply_userdata of the reply will
* be set to (see section about asynchronous calls)
@@ -976,8 +1001,7 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata,
* function is to mpv_command_node() what mpv_command_async() is to
* mpv_command().
*
- * See mpv_command_async() for details. Retrieving the result is not
- * supported yet.
+ * See mpv_command_async() for details.
*
* Safe to be called from mpv render API threads.
*
@@ -990,6 +1014,38 @@ int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata,
mpv_node *args);
/**
+ * Signal to all async requests with the matching ID to abort. This affects
+ * the following API calls:
+ *
+ * mpv_command_async
+ * mpv_command_node_async
+ *
+ * All of these functions take a reply_userdata parameter. This API function
+ * tells all requests with the matching reply_userdata value to try to return
+ * as soon as possible. If there are multiple requests with matching ID, it
+ * aborts all of them.
+ *
+ * This API function is mostly asynchronous itself. It will not wait until the
+ * command is aborted. Instead, the command will terminate as usual, but with
+ * some work not done. How this is signaled depends on the specific command (for
+ * example, the "subprocess" command will indicate it by "killed_by_us" set to
+ * true in the result). How long it takes also depends on the situation. The
+ * aborting process is completely asynchronous.
+ *
+ * Not all commands may support this functionality. In this case, this function
+ * will have no effect. The same is true if the request using the passed
+ * reply_userdata has already terminated, has not been started yet, or was
+ * never in use at all.
+ *
+ * You have to be careful of race conditions: the time during which the abort
+ * request will be effective is _after_ e.g. mpv_command_async() has returned,
+ * and before the command has signaled completion with MPV_EVENT_COMMAND_REPLY.
+ *
+ * @param reply_userdata ID of the request to be aborted (see above)
+ */
+void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata);
+
+/**
* Set a property to a given value. Properties are essentially variables which
* can be queried or set at runtime. For example, writing to the pause property
* will actually pause or unpause playback.
@@ -1202,7 +1258,8 @@ typedef enum mpv_event_id {
*/
MPV_EVENT_SET_PROPERTY_REPLY = 4,
/**
- * Reply to a mpv_command_async() request.
+ * Reply to a mpv_command_async() or mpv_command_node_async() request.
+ * See also mpv_event and mpv_event_command.
*/
MPV_EVENT_COMMAND_REPLY = 5,
/**
@@ -1549,6 +1606,17 @@ typedef struct mpv_event_hook {
uint64_t id;
} mpv_event_hook;
+// Since API version 1.102.
+typedef struct mpv_event_command {
+ /**
+ * Result data of the command. Note that success/failure is signaled
+ * separately via mpv_event.error. This field is only for result data
+ * in case of success. Most commands leave it at MPV_FORMAT_NONE. Set
+ * to MPV_FORMAT_NONE on failure.
+ */
+ mpv_node result;
+} mpv_event_command;
+
typedef struct mpv_event {
/**
* One of mpv_event. Keep in mind that later ABI compatible releases might
@@ -1575,6 +1643,7 @@ typedef struct mpv_event {
* MPV_EVENT_SET_PROPERTY_REPLY
* MPV_EVENT_COMMAND_REPLY
* MPV_EVENT_PROPERTY_CHANGE
+ * MPV_EVENT_HOOK
*/
uint64_t reply_userdata;
/**
@@ -1584,6 +1653,8 @@ typedef struct mpv_event {
* MPV_EVENT_LOG_MESSAGE: mpv_event_log_message*
* MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message*
* MPV_EVENT_END_FILE: mpv_event_end_file*
+ * MPV_EVENT_HOOK: mpv_event_hook*
+ * MPV_EVENT_COMMAND_REPLY* mpv_event_command*
* other: NULL
*
* Note: future enhancements might add new event structs for existing or new