1 /*
2  * This file is part of mpv.
3  *
4  * mpv is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * mpv is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with mpv.  If not, see <http://www.gnu.org/licenses/>.
16  */
17 
18 #ifndef MPLAYER_M_PROPERTY_H
19 #define MPLAYER_M_PROPERTY_H
20 
21 #include <stdbool.h>
22 #include <stdint.h>
23 
24 #include "m_option.h"
25 
26 struct mp_log;
27 
28 enum mp_property_action {
29     // Get the property type. This defines the fundamental data type read from
30     // or written to the property.
31     // If unimplemented, the m_option entry that defines the property is used.
32     //  arg: m_option*
33     M_PROPERTY_GET_TYPE,
34 
35     // Get the current value.
36     //  arg: pointer to a variable of the type according to the property type
37     M_PROPERTY_GET,
38 
39     // Set a new value. The property wrapper will make sure that only valid
40     // values are set (e.g. according to the property type's min/max range).
41     // If unimplemented, the property is read-only.
42     //  arg: pointer to a variable of the type according to the property type
43     M_PROPERTY_SET,
44 
45     // Get human readable string representing the current value.
46     // If unimplemented, the property wrapper uses the property type as
47     // fallback.
48     //  arg: char**
49     M_PROPERTY_PRINT,
50 
51     // Like M_PROPERTY_GET_TYPE, but get a type that is compatible to the real
52     // type, but reflect practical limits, such as runtime-available values.
53     // This is mostly used for "UI" related things.
54     // (Example: volume property.)
55     M_PROPERTY_GET_CONSTRICTED_TYPE,
56 
57     // Switch the property up/down by a given value.
58     // If unimplemented, the property wrapper uses the property type as
59     // fallback.
60     //  arg: struct m_property_switch_arg*
61     M_PROPERTY_SWITCH,
62 
63     // Get a string containing a parseable representation.
64     // Can't be overridden by property implementations.
65     //  arg: char**
66     M_PROPERTY_GET_STRING,
67 
68     // Set a new value from a string. The property wrapper parses this using the
69     // parse function provided by the property type.
70     // Can't be overridden by property implementations.
71     //  arg: char*
72     M_PROPERTY_SET_STRING,
73 
74     // Set a mpv_node value.
75     //  arg: mpv_node*
76     M_PROPERTY_GET_NODE,
77 
78     // Get a mpv_node value.
79     //  arg: mpv_node*
80     M_PROPERTY_SET_NODE,
81 
82     // Multiply numeric property with a factor.
83     //  arg: double*
84     M_PROPERTY_MULTIPLY,
85 
86     // Pass down an action to a sub-property.
87     //  arg: struct m_property_action_arg*
88     M_PROPERTY_KEY_ACTION,
89 };
90 
91 // Argument for M_PROPERTY_SWITCH
92 struct m_property_switch_arg {
93     double inc;         // value to add to property, or cycle direction
94     bool wrap;          // whether value should wrap around on over/underflow
95 };
96 
97 // Argument for M_PROPERTY_KEY_ACTION
98 struct m_property_action_arg {
99     const char* key;
100     int action;
101     void* arg;
102 };
103 
104 enum mp_property_return {
105     // Returned on success.
106     M_PROPERTY_OK = 1,
107 
108     // Returned on error.
109     M_PROPERTY_ERROR = 0,
110 
111     // Returned when the property can't be used, for example video related
112     // properties while playing audio only.
113     M_PROPERTY_UNAVAILABLE = -1,
114 
115     // Returned if the requested action is not implemented.
116     M_PROPERTY_NOT_IMPLEMENTED = -2,
117 
118     // Returned when asking for a property that doesn't exist.
119     M_PROPERTY_UNKNOWN = -3,
120 
121     // When trying to set invalid or incorrectly formatted data.
122     M_PROPERTY_INVALID_FORMAT = -4,
123 };
124 
125 struct m_property {
126     const char *name;
127     // ctx: opaque caller context, which the property might use
128     // prop: pointer to this struct
129     // action: one of enum mp_property_action
130     // arg: specific to the action
131     // returns: one of enum mp_property_return
132     int (*call)(void *ctx, struct m_property *prop, int action, void *arg);
133     void *priv;
134     // Special-case: mark options for which command.c uses the option-bridge
135     bool is_option;
136 };
137 
138 struct m_property *m_property_list_find(const struct m_property *list,
139                                         const char *name);
140 
141 // Access a property.
142 // action: one of m_property_action
143 // ctx: opaque value passed through to property implementation
144 // returns: one of mp_property_return
145 int m_property_do(struct mp_log *log, const struct m_property* prop_list,
146                   const char* property_name, int action, void* arg, void *ctx);
147 
148 // Given a path of the form "a/b/c", this function will set *prefix to "a",
149 // and rem to "b/c", and return true.
150 // If there is no '/' in the path, set prefix to path, and rem to "", and
151 // return false.
152 bool m_property_split_path(const char *path, bstr *prefix, char **rem);
153 
154 // Print a list of properties.
155 void m_properties_print_help_list(struct mp_log *log,
156                                   const struct m_property *list);
157 
158 // Expand a property string.
159 // This function allows to print strings containing property values.
160 //  ${NAME} is expanded to the value of property NAME.
161 //  If NAME starts with '=', use the raw value of the property.
162 //  ${NAME:STR} expands to the property, or STR if the property is not
163 //  available.
164 //  ${?NAME:STR} expands to STR if the property is available.
165 //  ${!NAME:STR} expands to STR if the property is not available.
166 // General syntax: "${" ["?" | "!"] ["="] NAME ":" STR "}"
167 // STR is recursively expanded using the same rules.
168 // "$$" can be used to escape "$", and "$}" to escape "}".
169 // "$>" disables parsing of "$" for the rest of the string.
170 char* m_properties_expand_string(const struct m_property *prop_list,
171                                  const char *str, void *ctx);
172 
173 // Trivial helpers for implementing properties.
174 int m_property_flag_ro(int action, void* arg, int var);
175 int m_property_int_ro(int action, void* arg, int var);
176 int m_property_int64_ro(int action, void* arg, int64_t var);
177 int m_property_float_ro(int action, void* arg, float var);
178 int m_property_double_ro(int action, void* arg, double var);
179 int m_property_strdup_ro(int action, void* arg, const char *var);
180 
181 struct m_sub_property {
182     // Name of the sub-property - this will be prefixed with the parent
183     // property's name.
184     const char *name;
185     // Type of the data stored in the value member. See m_option.
186     struct m_option type;
187     // Data returned by the sub-property. m_property_read_sub() will make a
188     // copy of this if needed. It will never write or free the data.
189     union m_option_value value;
190     // This can be set to true if the property should be hidden.
191     bool unavailable;
192 };
193 
194 // Convenience macros which can be used as part of a sub_property entry.
195 #define SUB_PROP_INT(i) \
196     .type = {.type = CONF_TYPE_INT}, .value = {.int_ = (i)}
197 #define SUB_PROP_INT64(i) \
198     .type = {.type = CONF_TYPE_INT64}, .value = {.int64 = (i)}
199 #define SUB_PROP_STR(s) \
200     .type = {.type = CONF_TYPE_STRING}, .value = {.string = (char *)(s)}
201 #define SUB_PROP_FLOAT(f) \
202     .type = {.type = CONF_TYPE_FLOAT}, .value = {.float_ = (f)}
203 #define SUB_PROP_DOUBLE(f) \
204     .type = {.type = CONF_TYPE_DOUBLE}, .value = {.double_ = (f)}
205 #define SUB_PROP_FLAG(f) \
206     .type = {.type = CONF_TYPE_FLAG}, .value = {.flag = (f)}
207 #define SUB_PROP_PTS(f) \
208     .type = {.type = &m_option_type_time}, .value = {.double_ = (f)}
209 
210 int m_property_read_sub(const struct m_sub_property *props, int action, void *arg);
211 
212 
213 // Used with m_property_read_list().
214 // Get an entry. item is the 0-based index of the item. This behaves like a
215 // top-level property request (but you must implement M_PROPERTY_GET_TYPE).
216 // item will be in range [0, count), for count see m_property_read_list()
217 // action, arg are for property access.
218 // ctx is userdata passed to m_property_read_list.
219 typedef int (*m_get_item_cb)(int item, int action, void *arg, void *ctx);
220 
221 int m_property_read_list(int action, void *arg, int count,
222                          m_get_item_cb get_item, void *ctx);
223 
224 #endif /* MPLAYER_M_PROPERTY_H */
225