mirror of
https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git
synced 2025-11-01 22:58:47 -04:00
ff64defc13
The following new functions have been added: pa_message_params_read_double_array() - read an array of double from list pa_message_params_read_int64_array() - read an array of int64 from list pa_message_params_read_uint64_array() - read an array of uint64 from list pa_message_params_read_string_array() - read an array of strings from list Part-of: <https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/51>
158 lines
7 KiB
C
158 lines
7 KiB
C
#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
|