1// Copyright 2013 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef FLUTTER_SHELL_PLATFORM_LINUX_FL_VALUE_H_
6#define FLUTTER_SHELL_PLATFORM_LINUX_FL_VALUE_H_
7
8#include <glib.h>
9#include <stdbool.h>
10#include <stdint.h>
11
12#if !defined(__FLUTTER_LINUX_INSIDE__) && !defined(FLUTTER_LINUX_COMPILATION)
13#error "Only <flutter_linux/flutter_linux.h> can be included directly."
14#endif
15
16G_BEGIN_DECLS
17
18/**
19 * FlValue:
20 *
21 * #FlValue is an object that contains the data types used in the platform
22 * channel used by Flutter.
23 *
24 * In Dart the values are represented as follows:
25 * - #FL_VALUE_TYPE_NULL: Null
26 * - #FL_VALUE_TYPE_BOOL: bool
27 * - #FL_VALUE_TYPE_INT: num
28 * - #FL_VALUE_TYPE_FLOAT: num
29 * - #FL_VALUE_TYPE_STRING: String
30 * - #FL_VALUE_TYPE_UINT8_LIST: Uint8List
31 * - #FL_VALUE_TYPE_INT32_LIST: Int32List
32 * - #FL_VALUE_TYPE_INT64_LIST: Int64List
33 * - #FL_VALUE_TYPE_FLOAT32_LIST: Float32List
34 * - #FL_VALUE_TYPE_FLOAT_LIST: Float64List
35 * - #FL_VALUE_TYPE_LIST: List<dynamic>
36 * - #FL_VALUE_TYPE_MAP: Map<dynamic>
37 *
38 * See #FlMessageCodec to encode and decode these values.
39 */
40typedef struct _FlValue FlValue;
41
42/**
43 * FlValueType:
44 * @FL_VALUE_TYPE_NULL: The null value.
45 * @FL_VALUE_TYPE_BOOL: A boolean.
46 * @FL_VALUE_TYPE_INT: A 64 bit signed integer.
47 * @FL_VALUE_TYPE_FLOAT: A 64 bit floating point number.
48 * @FL_VALUE_TYPE_STRING: UTF-8 text.
49 * @FL_VALUE_TYPE_UINT8_LIST: An ordered list of unsigned 8 bit integers.
50 * @FL_VALUE_TYPE_INT32_LIST: An ordered list of 32 bit integers.
51 * @FL_VALUE_TYPE_INT64_LIST: An ordered list of 64 bit integers.
52 * @FL_VALUE_TYPE_FLOAT_LIST: An ordered list of floating point numbers.
53 * @FL_VALUE_TYPE_LIST: An ordered list of #FlValue objects.
54 * @FL_VALUE_TYPE_MAP: A map of #FlValue objects keyed by #FlValue object.
55 * @FL_VALUE_TYPE_FLOAT32_LIST: An ordered list of 32bit floating point numbers.
56 *
57 * Types of #FlValue.
58 */
59typedef enum {
60 FL_VALUE_TYPE_NULL,
61 FL_VALUE_TYPE_BOOL,
62 FL_VALUE_TYPE_INT,
63 FL_VALUE_TYPE_FLOAT,
64 FL_VALUE_TYPE_STRING,
65 FL_VALUE_TYPE_UINT8_LIST,
66 FL_VALUE_TYPE_INT32_LIST,
67 FL_VALUE_TYPE_INT64_LIST,
68 FL_VALUE_TYPE_FLOAT_LIST,
69 FL_VALUE_TYPE_LIST,
70 FL_VALUE_TYPE_MAP,
71 FL_VALUE_TYPE_FLOAT32_LIST,
72} FlValueType;
73
74/**
75 * fl_value_new_null:
76 *
77 * Creates an #FlValue that contains a null value. The equivalent Dart type is
78 * null.
79 *
80 * Returns: a new #FlValue.
81 */
82FlValue* fl_value_new_null();
83
84/**
85 * fl_value_new_bool:
86 * @value: the value.
87 *
88 * Creates an #FlValue that contains a boolean value. The equivalent Dart type
89 * is a bool.
90 *
91 * Returns: a new #FlValue.
92 */
93FlValue* fl_value_new_bool(bool value);
94
95/**
96 * fl_value_new_int:
97 * @value: the value.
98 *
99 * Creates an #FlValue that contains an integer number. The equivalent Dart type
100 * is a num.
101 *
102 * Returns: a new #FlValue.
103 */
104FlValue* fl_value_new_int(int64_t value);
105
106/**
107 * fl_value_new_float:
108 * @value: the value.
109 *
110 * Creates an #FlValue that contains a floating point number. The equivalent
111 * Dart type is a num.
112 *
113 * Returns: a new #FlValue.
114 */
115FlValue* fl_value_new_float(double value);
116
117/**
118 * fl_value_new_string:
119 * @value: a %NULL-terminated UTF-8 string.
120 *
121 * Creates an #FlValue that contains UTF-8 text. The equivalent Dart type is a
122 * String.
123 *
124 * Returns: a new #FlValue.
125 */
126FlValue* fl_value_new_string(const gchar* value);
127
128/**
129 * fl_value_new_string_sized:
130 * @value: a buffer containing UTF-8 text. It does not require a nul terminator.
131 * @value_length: the number of bytes to use from @value.
132 *
133 * Creates an #FlValue that contains UTF-8 text. The equivalent Dart type is a
134 * String.
135 *
136 * Returns: a new #FlValue.
137 */
138FlValue* fl_value_new_string_sized(const gchar* value, size_t value_length);
139
140/**
141 * fl_value_new_uint8_list:
142 * @value: an array of unsigned 8 bit integers.
143 * @value_length: number of elements in @value.
144 *
145 * Creates an ordered list containing 8 bit unsigned integers. The data is
146 * copied. The equivalent Dart type is a Uint8List.
147 *
148 * Returns: a new #FlValue.
149 */
150FlValue* fl_value_new_uint8_list(const uint8_t* value, size_t value_length);
151
152/**
153 * fl_value_new_uint8_list_from_bytes:
154 * @value: a #GBytes.
155 *
156 * Creates an ordered list containing 8 bit unsigned integers. The data is
157 * copied. The equivalent Dart type is a Uint8List.
158 *
159 * Returns: a new #FlValue.
160 */
161FlValue* fl_value_new_uint8_list_from_bytes(GBytes* value);
162
163/**
164 * fl_value_new_int32_list:
165 * @value: an array of signed 32 bit integers.
166 * @value_length: number of elements in @value.
167 *
168 * Creates an ordered list containing 32 bit integers. The equivalent Dart type
169 * is a Int32List.
170 *
171 * Returns: a new #FlValue.
172 */
173FlValue* fl_value_new_int32_list(const int32_t* value, size_t value_length);
174
175/**
176 * fl_value_new_int64_list:
177 * @value: an array of signed 64 bit integers.
178 * @value_length: number of elements in @value.
179 *
180 * Creates an ordered list containing 64 bit integers. The equivalent Dart type
181 * is a Int64List.
182 *
183 * Returns: a new #FlValue.
184 */
185FlValue* fl_value_new_int64_list(const int64_t* value, size_t value_length);
186
187/**
188 * fl_value_new_float32_list:
189 * @value: an array of floating point numbers.
190 * @value_length: number of elements in @value.
191 *
192 * Creates an ordered list containing 32 bit floating point numbers.
193 * The equivalent Dart type is a Float32List.
194 *
195 * Returns: a new #FlValue.
196 */
197FlValue* fl_value_new_float32_list(const float* value, size_t value_length);
198
199/**
200 * fl_value_new_float_list:
201 * @value: an array of floating point numbers.
202 * @value_length: number of elements in @value.
203 *
204 * Creates an ordered list containing floating point numbers. The equivalent
205 * Dart type is a Float64List.
206 *
207 * Returns: a new #FlValue.
208 */
209FlValue* fl_value_new_float_list(const double* value, size_t value_length);
210
211/**
212 * fl_value_new_list:
213 *
214 * Creates an ordered list. Children can be added to the list using
215 * fl_value_append(). The children are accessed using fl_value_get_length()
216 * and fl_value_get_list_value(). The equivalent Dart type is a List<dynamic>.
217 *
218 * The following example shows a simple list of values:
219 *
220 * |[<!-- language="C" -->
221 * g_autoptr(FlValue) value = fl_value_new_list ();
222 * fl_value_append_take (value, fl_value_new_string ("one");
223 * fl_value_append_take (value, fl_value_new_int (2);
224 * fl_value_append_take (value, fl_value_new_double (3.0);
225 * ]|
226 *
227 * This value can be decoded using:
228 *
229 * |[<!-- language="C" -->
230 * g_assert (fl_value_get_type (value) == FL_VALUE_TYPE_LIST);
231 * for (size_t i = 0; i < fl_value_get_length (value); i++) {
232 * FlValue *child = fl_value_get_list_value (value, i);
233 * process_value (child);
234 * }
235 * ]|
236 *
237 * Returns: a new #FlValue.
238 */
239FlValue* fl_value_new_list();
240
241/**
242 * fl_value_new_list_from_strv:
243 * @value: a %NULL-terminated array of strings.
244 *
245 * Creates an ordered list containing #FlString values.
246 *
247 * Returns: a new #FlValue.
248 */
249FlValue* fl_value_new_list_from_strv(const gchar* const* value);
250
251/**
252 * fl_value_new_map:
253 *
254 * Creates an ordered associative array. Children can be added to the map
255 * using fl_value_set(), fl_value_set_take(), fl_value_set_string(),
256 * fl_value_set_string_take(). The children are accessed using
257 * fl_value_get_length(), fl_value_get_map_key(), fl_value_get_map_value(),
258 * fl_value_lookup() and fl_value_lookup_string(). The equivalent Dart type is a
259 * Map<dynamic>.
260 *
261 * The following example shows how to create a map of values keyed by strings:
262 *
263 * |[<!-- language="C" -->
264 * g_autoptr(FlValue) value = fl_value_new_map ();
265 * fl_value_set_string_take (value, "name", fl_value_new_string ("Gandalf"));
266 * fl_value_set_string_take (value, "occupation",
267 * fl_value_new_string ("Wizard"));
268 * fl_value_set_string_take (value, "age", fl_value_new_int (2019));
269 * ]|
270 *
271 * This value can be decoded using:
272 * |[<!-- language="C" -->
273 * g_assert (fl_value_get_type (value) == FL_VALUE_TYPE_MAP);
274 * FlValue *name = fl_value_lookup_string (value, "name");
275 * g_assert (fl_value_get_type (name) == FL_VALUE_TYPE_STRING);
276 * FlValue *age = fl_value_lookup_string (value, "age");
277 * g_assert (fl_value_get_type (age) == FL_VALUE_TYPE_INT);
278 * g_message ("Next customer is %s (%d years old)",
279 * fl_value_get_string (name),
280 * fl_value_get_int (age));
281 * ]|
282 *
283 * Returns: a new #FlValue.
284 */
285FlValue* fl_value_new_map();
286
287/**
288 * fl_value_ref:
289 * @value: an #FlValue.
290 *
291 * Increases the reference count of an #FlValue.
292 *
293 * Returns: the value that was referenced.
294 */
295FlValue* fl_value_ref(FlValue* value);
296
297/**
298 * fl_value_unref:
299 * @value: an #FlValue.
300 *
301 * Decreases the reference count of an #FlValue. When the reference count hits
302 * zero @value is destroyed and no longer valid.
303 */
304void fl_value_unref(FlValue* value);
305
306/**
307 * fl_value_get_type:
308 * @value: an #FlValue.
309 *
310 * Gets the type of @value.
311 *
312 * Returns: an #FlValueType.
313 */
314FlValueType fl_value_get_type(FlValue* value);
315
316/**
317 * fl_value_equal:
318 * @a: an #FlValue.
319 * @b: an #FlValue.
320 *
321 * Compares two #FlValue to see if they are equivalent. Two values are
322 * considered equivalent if they are of the same type and their data is the same
323 * including any child values. For values of type #FL_VALUE_TYPE_MAP the order
324 * of the values does not matter.
325 *
326 * Returns: %TRUE if both values are equivalent.
327 */
328bool fl_value_equal(FlValue* a, FlValue* b);
329
330/**
331 * fl_value_append:
332 * @value: an #FlValue of type #FL_VALUE_TYPE_LIST.
333 * @child: an #FlValue.
334 *
335 * Adds @child to the end of @value. Calling this with an #FlValue that is not
336 * of type #FL_VALUE_TYPE_LIST is a programming error.
337 */
338void fl_value_append(FlValue* value, FlValue* child);
339
340/**
341 * fl_value_append_take:
342 * @value: an #FlValue of type #FL_VALUE_TYPE_LIST.
343 * @child: (transfer full): an #FlValue.
344 *
345 * Adds @child to the end of @value. Ownership of @child is taken by @value.
346 * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_LIST is a
347 * programming error.
348 */
349void fl_value_append_take(FlValue* value, FlValue* child);
350
351/**
352 * fl_value_set:
353 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
354 * @key: an #FlValue.
355 * @child_value: an #FlValue.
356 *
357 * Sets @key in @value to @child_value. If an existing value was in the map with
358 * the same key it is replaced. Calling this with an #FlValue that is not of
359 * type #FL_VALUE_TYPE_MAP is a programming error.
360 */
361void fl_value_set(FlValue* value, FlValue* key, FlValue* child_value);
362
363/**
364 * fl_value_set_take:
365 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
366 * @key: (transfer full): an #FlValue.
367 * @child_value: (transfer full): an #FlValue.
368 *
369 * Sets @key in @value to @child_value. Ownership of both @key and @child_value
370 * is taken by @value. If an existing value was in the map with the same key it
371 * is replaced. Calling this with an #FlValue that is not of type
372 * #FL_VALUE_TYPE_MAP is a programming error.
373 */
374void fl_value_set_take(FlValue* value, FlValue* key, FlValue* child_value);
375
376/**
377 * fl_value_set_string:
378 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
379 * @key: a UTF-8 text key.
380 * @child_value: an #FlValue.
381 *
382 * Sets a value in the map with a text key. If an existing value was in the map
383 * with the same key it is replaced. Calling this with an #FlValue that is not
384 * of type #FL_VALUE_TYPE_MAP is a programming error.
385 */
386void fl_value_set_string(FlValue* value,
387 const gchar* key,
388 FlValue* child_value);
389
390/**
391 * fl_value_set_string_take:
392 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
393 * @key: a UTF-8 text key.
394 * @child_value: (transfer full): an #FlValue.
395 *
396 * Sets a value in the map with a text key, taking ownership of the value. If an
397 * existing value was in the map with the same key it is replaced. Calling this
398 * with an #FlValue that is not of type #FL_VALUE_TYPE_MAP is a programming
399 * error.
400 */
401void fl_value_set_string_take(FlValue* value,
402 const gchar* key,
403 FlValue* child_value);
404
405/**
406 * fl_value_get_bool:
407 * @value: an #FlValue of type #FL_VALUE_TYPE_BOOL.
408 *
409 * Gets the boolean value of @value. Calling this with an #FlValue that is
410 * not of type #FL_VALUE_TYPE_BOOL is a programming error.
411 *
412 * Returns: a boolean value.
413 */
414bool fl_value_get_bool(FlValue* value);
415
416/**
417 * fl_value_get_int:
418 * @value: an #FlValue of type #FL_VALUE_TYPE_INT.
419 *
420 * Gets the integer number of @value. Calling this with an #FlValue that is
421 * not of type #FL_VALUE_TYPE_INT is a programming error.
422 *
423 * Returns: an integer number.
424 */
425int64_t fl_value_get_int(FlValue* value);
426
427/**
428 * fl_value_get_float:
429 * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT.
430 *
431 * Gets the floating point number of @value. Calling this with an #FlValue
432 * that is not of type #FL_VALUE_TYPE_FLOAT is a programming error.
433 *
434 * Returns: a floating point number.
435 */
436double fl_value_get_float(FlValue* value);
437
438/**
439 * fl_value_get_string:
440 * @value: an #FlValue of type #FL_VALUE_TYPE_STRING.
441 *
442 * Gets the UTF-8 text contained in @value. Calling this with an #FlValue
443 * that is not of type #FL_VALUE_TYPE_STRING is a programming error.
444 *
445 * Returns: a UTF-8 encoded string.
446 */
447const gchar* fl_value_get_string(FlValue* value);
448
449/**
450 * fl_value_get_length:
451 * @value: an #FlValue of type #FL_VALUE_TYPE_UINT8_LIST,
452 * #FL_VALUE_TYPE_INT32_LIST, #FL_VALUE_TYPE_INT64_LIST,
453 * #FL_VALUE_TYPE_FLOAT32_LIST, #FL_VALUE_TYPE_FLOAT_LIST, #FL_VALUE_TYPE_LIST
454 * or #FL_VALUE_TYPE_MAP.
455 *
456 * Gets the number of elements @value contains. This is only valid for list
457 * and map types. Calling this with other types is a programming error.
458 *
459 * Returns: the number of elements inside @value.
460 */
461size_t fl_value_get_length(FlValue* value);
462
463/**
464 * fl_value_get_uint8_list:
465 * @value: an #FlValue of type #FL_VALUE_TYPE_UINT8_LIST.
466 *
467 * Gets the array of unisigned 8 bit integers @value contains. The data
468 * contains fl_value_get_length() elements. Calling this with an #FlValue that
469 * is not of type #FL_VALUE_TYPE_UINT8_LIST is a programming error.
470 *
471 * Returns: an array of unsigned 8 bit integers.
472 */
473const uint8_t* fl_value_get_uint8_list(FlValue* value);
474
475/**
476 * fl_value_get_int32_list:
477 * @value: an #FlValue of type #FL_VALUE_TYPE_INT32_LIST.
478 *
479 * Gets the array of 32 bit integers @value contains. The data contains
480 * fl_value_get_length() elements. Calling this with an #FlValue that is not of
481 * type #FL_VALUE_TYPE_INT32_LIST is a programming error.
482 *
483 * Returns: an array of 32 bit integers.
484 */
485const int32_t* fl_value_get_int32_list(FlValue* value);
486
487/**
488 * fl_value_get_int64_list:
489 * @value: an #FlValue of type #FL_VALUE_TYPE_INT64_LIST.
490 *
491 * Gets the array of 64 bit integers @value contains. The data contains
492 * fl_value_get_length() elements. Calling this with an #FlValue that is not of
493 * type #FL_VALUE_TYPE_INT64_LIST is a programming error.
494 *
495 * Returns: an array of 64 bit integers.
496 */
497const int64_t* fl_value_get_int64_list(FlValue* value);
498
499/**
500 * fl_value_get_float32_list:
501 * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT32_LIST.
502 *
503 * Gets the array of floating point numbers @value contains. The data
504 * contains fl_value_get_length() elements. Calling this with an #FlValue that
505 * is not of type #FL_VALUE_TYPE_FLOAT32_LIST is a programming error.
506 *
507 * Returns: an array of floating point numbers.
508 */
509const float* fl_value_get_float32_list(FlValue* value);
510
511/**
512 * fl_value_get_float_list:
513 * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT_LIST.
514 *
515 * Gets the array of floating point numbers @value contains. The data
516 * contains fl_value_get_length() elements. Calling this with an #FlValue that
517 * is not of type #FL_VALUE_TYPE_FLOAT_LIST is a programming error.
518 *
519 * Returns: an array of floating point numbers.
520 */
521const double* fl_value_get_float_list(FlValue* value);
522
523/**
524 * fl_value_get_list_value:
525 * @value: an #FlValue of type #FL_VALUE_TYPE_LIST.
526 * @index: an index in the list.
527 *
528 * Gets a child element of the list. It is a programming error to request an
529 * index that is outside the size of the list as returned from
530 * fl_value_get_length(). Calling this with an #FlValue that is not of type
531 * #FL_VALUE_TYPE_LIST is a programming error.
532 *
533 * Returns: an #FlValue.
534 */
535FlValue* fl_value_get_list_value(FlValue* value, size_t index);
536
537/**
538 * fl_value_get_map_key:
539 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
540 * @index: an index in the map.
541 *
542 * Gets a key from the map. It is a programming error to request an index that
543 * is outside the size of the list as returned from fl_value_get_length().
544 * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_MAP is a
545 * programming error.
546 *
547 * Returns: an #FlValue.
548 */
549FlValue* fl_value_get_map_key(FlValue* value, size_t index);
550
551/**
552 * fl_value_get_map_value:
553 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
554 * @index: an index in the map.
555 *
556 * Gets a value from the map. It is a programming error to request an index that
557 * is outside the size of the list as returned from fl_value_get_length().
558 * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_MAP is a
559 * programming error.
560 *
561 * Returns: an #FlValue.
562 */
563FlValue* fl_value_get_map_value(FlValue* value, size_t index);
564
565/**
566 * fl_value_lookup:
567 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
568 * @key: a key value.
569 *
570 * Gets the map entry that matches @key. Keys are checked using
571 * fl_value_equal(). Calling this with an #FlValue that is not of type
572 * #FL_VALUE_TYPE_MAP is a programming error.
573 *
574 * Map lookups are not optimized for performance - if you have a large map or
575 * need frequent access you should copy the data into another structure, e.g.
576 * #GHashTable.
577 *
578 * Returns: (allow-none): the value with this key or %NULL if not one present.
579 */
580FlValue* fl_value_lookup(FlValue* value, FlValue* key);
581
582/**
583 * fl_value_lookup_string:
584 * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
585 * @key: a key value.
586 *
587 * Gets the map entry that matches @key. Keys are checked using
588 * fl_value_equal(). Calling this with an #FlValue that is not of type
589 * #FL_VALUE_TYPE_MAP is a programming error.
590 *
591 * Map lookups are not optimized for performance - if you have a large map or
592 * need frequent access you should copy the data into another structure, e.g.
593 * #GHashTable.
594 *
595 * Returns: (allow-none): the value with this key or %NULL if not one present.
596 */
597FlValue* fl_value_lookup_string(FlValue* value, const gchar* key);
598
599/**
600 * fl_value_to_string:
601 * @value: an #FlValue.
602 *
603 * Converts an #FlValue to a text representation, suitable for logging purposes.
604 * The text is formatted to be the equivalent of Dart toString() methods.
605 *
606 * Returns: UTF-8 text.
607 */
608gchar* fl_value_to_string(FlValue* value);
609
610G_DEFINE_AUTOPTR_CLEANUP_FUNC(FlValue, fl_value_unref)
611
612G_END_DECLS
613
614#endif // FLUTTER_SHELL_PLATFORM_LINUX_FL_VALUE_H_
615

Provided by KDAB

Privacy Policy
Improve your Profiling and Debugging skills
Find out more

source code of flutter_engine/flutter/shell/platform/linux/public/flutter_linux/fl_value.h