1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
#ifndef foomessagehelperhfoo
#define foomessagehelperhfoo
/***
This file is part of PulseAudio.
PulseAudio is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.
PulseAudio is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
***/
#include <stddef.h>
#include <stdbool.h>
#include <inttypes.h>
#include <pulse/cdecl.h>
#include <pulse/version.h>
/** \file
* Utility functions for reading and writing message parameters.
* All read functions return a value from pa_message_params_error_code
* and the read value in result (or *result for string functions).
* The string read functions read_string() and read_raw() return a pointer
* to a sub-string within the parameter list in *result, therefore the
* string in *result must not be freed and is only valid within the
* message handler callback function. If the string is needed outside
* the callback, it must be copied using pa_xstrdup().
* When a read function is called, the state pointer is advanced to the
* next list element. The variable state points to should be initialized
* to NULL before the first call.
* All read functions except read_raw() preserve a default value passed
* in result if the call fails. For the array functions, results must be
* initialized prior to the call either to NULL or to an array with default
* values. If the function succeeds, the default array will be freed and
* the number of elements in the result array is returned.\n\n
* Write functions operate on a pa_message_params structure which is a
* wrapper for pa_strbuf. A parameter list or sub-list is started by a
* call to begin_list() and ended by a call to end_list().
* A pa_message_params structure must be converted to a string using
* pa_message_params_to_string_free() before it can be passed to a
* message handler. */
PA_C_DECL_BEGIN
/** Structure which holds a parameter list. Wrapper for pa_strbuf \since 15.0 */
typedef struct pa_message_params pa_message_params;
/** Read function return values \since 15.0 */
enum pa_message_params_error_code {
/** No value (empty element) found for numeric or boolean value */
PA_MESSAGE_PARAMS_IS_NULL = -2,
/** Error encountered while parsing a value */
PA_MESSAGE_PARAMS_PARSE_ERROR = -1,
/** End of parameter list reached */
PA_MESSAGE_PARAMS_LIST_END = 0,
/** Parsing successful */
PA_MESSAGE_PARAMS_OK = 1,
};
/** @{ \name Read functions */
/** Read a boolean from parameter list in c. \since 15.0 */
int pa_message_params_read_bool(char *c, bool *result, void **state);
/** Read a double from parameter list in c. \since 15.0 */
int pa_message_params_read_double(char *c, double *result, void **state);
/** Converts a parameter list to a double array. Empty elements in the parameter
* list are treated as error. Before the call, results must be initialized, either
* to NULL or to an array with default values. \since 15.0 */
int pa_message_params_read_double_array(char *c, double **results);
/** Read an integer from parameter list in c. \since 15.0 */
int pa_message_params_read_int64(char *c, int64_t *result, void **state);
/** Converts a parameter list to an int64 array. Empty elements in the parameter
* list are treated as error. Before the call, results must be initialized, either
* to NULL or to an array with default values. \since 15.0 */
int pa_message_params_read_int64_array(char *c, int64_t **results);
/** Read raw data from parameter list in c. Used to split a message parameter
* string into list elements. The string returned in *result must not be freed. \since 15.0 */
int pa_message_params_read_raw(char *c, char **result, void **state);
/** Read a string from a parameter list in c. Escaped curly braces and backslashes
* will be unescaped. \since 15.0 */
int pa_message_params_read_string(char *c, const char **result, void **state);
/** Convert a parameter list to a string array. Escaping is removed from
* the strings. Returns an array of pointers to sub-strings within c in
* *results. The returned array must be freed, but not the strings
* within the array. Before the call, results must be initialized, either
* to NULL or to an array with default values. \since 15.0 */
int pa_message_params_read_string_array(char *c, const char ***results);
/** Read an unsigned integer from parameter list in c. \since 15.0 */
int pa_message_params_read_uint64(char *c, uint64_t *result, void **state);
/** Converts a parameter list to an uint64 array. Empty elements in the parameter
* list are treated as error. Before the call, results must be initialized, either
* to NULL or to an array with default values. \since 15.0 */
int pa_message_params_read_uint64_array(char *c, uint64_t **results);
/** @} */
/** @{ \name Write functions */
/** Create a new pa_message_params structure. \since 15.0 */
pa_message_params *pa_message_params_new(void);
/** Free a pa_message_params structure. \since 15.0 */
void pa_message_params_free(pa_message_params *params);
/** Convert pa_message_params to string, free pa_message_params structure. \since 15.0 */
char *pa_message_params_to_string_free(pa_message_params *params);
/** Start a list by writing an opening brace. \since 15.0 */
void pa_message_params_begin_list(pa_message_params *params);
/** End a list by writing a closing brace. \since 15.0 */
void pa_message_params_end_list(pa_message_params *params);
/** Append a boolean to parameter list. \since 15.0 */
void pa_message_params_write_bool(pa_message_params *params, bool value);
/** Append a double to parameter list. Precision gives the number of
* significant digits. The decimal separator will always be written as
* dot, regardless which locale is used. \since 15.0 */
void pa_message_params_write_double(pa_message_params *params, double value, int precision);
/** Append an integer to parameter list. \since 15.0 */
void pa_message_params_write_int64(pa_message_params *params, int64_t value);
/** Append string to parameter list. Curly braces and backslashes will be escaped. \since 15.0 */
void pa_message_params_write_string(pa_message_params *params, const char *value);
/** Append raw string to parameter list. Used to write incomplete strings
* or complete parameter lists (for example arrays). Adds curly braces around
* the string if add_braces is true. \since 15.0 */
void pa_message_params_write_raw(pa_message_params *params, const char *value, bool add_braces);
/** Append an unsigned integer to parameter list. \since 15.0 */
void pa_message_params_write_uint64(pa_message_params *params, uint64_t value);
/** @} */
PA_C_DECL_END
#endif
|
