client API: change semantics for MPV_FORMAT_STRING

With mpv_set_property(h, "property", MPV_FORMAT_STRING, ptr), ptr now
has to be of type char** instead of char*. This makes it more consistent
with mpv_get_property() and also non-pointer formats, which will be
introduced in the following commits. mpv_set_property() of course does
not change its interface (only its implementation is adjusted to keep
its interface).

This also affects mpv_set_option(), but again not
mpv_set_option_string().

1 files changed, 14 insertions, 2 deletions

diff --git a/libmpv/client.h b/libmpv/client.h
index 901995ab29..2ad2fc4c0e 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -372,10 +372,16 @@ typedef enum mpv_format {
      *     printf("%s\n", result);
      *     mpv_free(result);
      *
+     * Or just use mpv_get_property_string().
+     *
      * Example for writing:
      *
      *     char *value = "the new value";
-     *     mpv_set_property(ctx, "property", MPV_FORMAT_STRING, (void *)value);
+     *     // yep, you pass the address to the variable
+     *     // (needed for symmetry with other types and mpv_get_property)
+     *     mpv_set_property(ctx, "property", MPV_FORMAT_STRING, &value);
+     *
+     * Or just use mpv_set_property_string().
      *
      */
     MPV_FORMAT_STRING           = 1,
@@ -673,7 +679,13 @@ typedef struct mpv_event_property {
      */
     mpv_format format;
     /**
-     * Received property value. Depends on the format.
+     * Received property value. Depends on the format. This is like the
+     * pointer argument passed to mpv_get_property().
+     *
+     * For example, for MPV_FORMAT_STRING you get the string with:
+     *
+     *    char *value = *(char **)(event_property->data);
+     *
      * Note that this is set to NULL if retrieving the property failed.
      * See mpv_event.error for the status.
      */