src/cx/properties.h

Sat, 19 Oct 2024 13:49:44 +0200

author
Mike Becker <universe@uap-core.de>
date
Sat, 19 Oct 2024 13:49:44 +0200
changeset 934
a43ed636d1ff
parent 932
484dab606292
permissions
-rw-r--r--

remove <sys/types.h> include from common.h

923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2024 Mike Becker, Olaf Wintermann All rights reserved.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
28 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
29 * \file properties.h
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
30 * \brief Interface for parsing data from properties files.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
31 * \author Mike Becker
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
32 * \author Olaf Wintermann
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
33 * \copyright 2-Clause BSD License
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
36 #ifndef UCX_PROPERTIES
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37 #define UCX_PROPERTIES
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
38
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
39 #include "common.h"
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
40 #include "string.h"
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
41 #include "map.h"
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
42 #include "array_list.h"
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
43
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
44 #include <stdio.h>
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
45
932
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
46 #ifdef __cplusplus
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
47 extern "C" {
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
48 #endif
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
49
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
50 struct cx_properties_config_s {
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
51 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
52 * The key/value delimiter that shall be used.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
53 * This is '=' by default.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
54 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
55 char delimiter;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
56
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
57 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
58 * The character, when appearing at the end of a line, continues that line.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
59 * This is '\' by default.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
60 */
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
61 // char continuation; // TODO: line continuation in properties
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
62
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
63 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
64 * The first comment character.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
65 * This is '#' by default.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
66 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
67 char comment1;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
68
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
69 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
70 * The second comment character.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
71 * This is not set by default.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
72 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
73 char comment2;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
74
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
75 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
76 * The third comment character.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
77 * This is not set by default.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
78 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
79 char comment3;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
80 };
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
81
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
82 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
83 * Typedef for the properties config.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
84 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
85 typedef struct cx_properties_config_s CxPropertiesConfig;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
86
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
87 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
88 * Default properties configuration.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
89 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
90 extern const CxPropertiesConfig cx_properties_config_default;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
91
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
92 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
93 * Status codes for the properties interface.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
94 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
95 enum cx_properties_status {
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
96 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
97 * Everything is fine.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
98 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
99 CX_PROPERTIES_NO_ERROR,
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
100 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
101 * The input buffer does not contain more data.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
102 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
103 CX_PROPERTIES_NO_DATA,
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
104 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
105 * The input ends unexpectedly.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
106 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
107 * This either happens when the last line does not terminate with a line
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
108 * break, or when the input ends with a parsed key but no value.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
109 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
110 CX_PROPERTIES_INCOMPLETE_DATA,
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
111 /**
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
112 * Not used as a status and never returned by any function.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
113 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
114 * You can use this enumerator to check for all "good" status results
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
115 * by checking if the status is less than \c CX_PROPERTIES_OK.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
116 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
117 * A "good" status means, that you can refill data and continue parsing.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
118 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
119 CX_PROPERTIES_OK,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
120 /**
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
121 * Input buffer is \c NULL.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
122 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
123 CX_PROPERTIES_NULL_INPUT,
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
124 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
125 * The line contains a delimiter, but no key.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
126 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
127 CX_PROPERTIES_INVALID_EMPTY_KEY,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
128 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
129 * The line contains data, but no delimiter.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
130 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
131 CX_PROPERTIES_INVALID_MISSING_DELIMITER,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
132 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
133 * More internal buffer was needed, but could not be allocated.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
134 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
135 CX_PROPERTIES_BUFFER_ALLOC_FAILED,
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
136 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
137 * Initializing the properties source failed.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
138 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
139 * @see cx_properties_read_init_func
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
140 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
141 CX_PROPERTIES_READ_INIT_FAILED,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
142 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
143 * Reading from a properties source failed.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
144 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
145 * @see cx_properties_read_func
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
146 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
147 CX_PROPERTIES_READ_FAILED,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
148 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
149 * Sinking a k/v-pair failed.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
150 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
151 * @see cx_properties_sink_func
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
152 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
153 CX_PROPERTIES_SINK_FAILED,
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
154 };
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
155
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
156 /**
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
157 * Typedef for the properties status enum.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
158 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
159 typedef enum cx_properties_status CxPropertiesStatus;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
160
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
161 /**
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
162 * Interface for working with properties data.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
163 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
164 struct cx_properties_s {
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
165 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
166 * The configuration.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
167 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
168 CxPropertiesConfig config;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
169
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
170 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
171 * The text buffer.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
172 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
173 const char *text;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
174
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
175 /**
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
176 * Size of the text buffer.
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
177 */
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
178 size_t text_size;
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
179
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
180 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
181 * Position in the text buffer.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
182 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
183 size_t text_pos;
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
184
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
185 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
186 * Temporary internal buffer.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
187 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
188 char *buf;
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
189
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
190 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
191 * Size of the internal buffer.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
192 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
193 size_t buf_size;
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
194
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
195 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
196 * Capacity of the internal buffer.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
197 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
198 size_t buf_capacity;
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
199
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
200 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
201 * Internal flags.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
202 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
203 int flags;
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
204 };
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
205
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
206 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
207 * Typedef for the properties interface.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
208 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
209 typedef struct cx_properties_s CxProperties;
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
210
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
211
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
212 /**
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
213 * Typedef for a properties sink.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
214 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
215 typedef struct cx_properties_sink_s CxPropertiesSink;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
216
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
217 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
218 * A function that consumes a k/v-pair in a sink.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
219 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
220 * The sink could be e.g. a map and the sink function would be calling
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
221 * a map function to store the k/v-pair.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
222 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
223 * @param prop the properties interface that wants to sink a k/v-pair
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
224 * @param sink the sink
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
225 * @param key the key
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
226 * @param value the value
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
227 * @return zero on success, non-zero when sinking the k/v-pair failed
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
228 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
229 __attribute__((__nonnull__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
230 typedef int(*cx_properties_sink_func)(
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
231 CxProperties *prop,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
232 CxPropertiesSink *sink,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
233 cxstring key,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
234 cxstring value
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
235 );
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
236
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
237 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
238 * Defines a sink for k/v-pairs.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
239 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
240 struct cx_properties_sink_s {
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
241 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
242 * The sink object.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
243 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
244 void *sink;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
245 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
246 * Optional custom data.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
247 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
248 void *data;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
249 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
250 * A function for consuming k/v-pairs into the sink.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
251 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
252 cx_properties_sink_func sink_func;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
253 };
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
254
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
255
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
256 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
257 * Typedef for a properties source.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
258 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
259 typedef struct cx_properties_source_s CxPropertiesSource;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
260
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
261 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
262 * A function that reads data from a source.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
263 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
264 * When the source is depleted, implementations SHALL provide an empty
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
265 * string in the \p target and return zero.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
266 * A non-zero return value is only permitted in case of an error.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
267 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
268 * The meaning of the optional parameters is implementation-dependent.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
269 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
270 * @param prop the properties interface that wants to read from the source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
271 * @param src the source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
272 * @param target a string buffer where the read data shall be stored
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
273 * @return zero on success, non-zero when reading data failed
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
274 */
932
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
275 __attribute__((__nonnull__))
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
276 typedef int(*cx_properties_read_func)(
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
277 CxProperties *prop,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
278 CxPropertiesSource *src,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
279 cxstring *target
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
280 );
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
281
932
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
282 /**
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
283 * A function that may initialize additional memory for the source.
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
284 *
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
285 * @param prop the properties interface that wants to read from the source
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
286 * @param src the source
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
287 * @return zero when initialization was successful, non-zero otherwise
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
288 */
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
289 __attribute__((__nonnull__))
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
290 typedef int(*cx_properties_read_init_func)(
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
291 CxProperties *prop,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
292 CxPropertiesSource *src
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
293 );
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
294
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
295 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
296 * A function that cleans memory initialized by the read_init_func.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
297 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
298 * @param prop the properties interface that wants to read from the source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
299 * @param src the source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
300 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
301 __attribute__((__nonnull__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
302 typedef void(*cx_properties_read_clean_func)(
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
303 CxProperties *prop,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
304 CxPropertiesSource *src
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
305 );
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
306
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
307 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
308 * Defines a properties source.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
309 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
310 struct cx_properties_source_s {
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
311 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
312 * The source object.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
313 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
314 * For example a file stream or a string.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
315 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
316 void *src;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
317 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
318 * Optional additional data pointer.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
319 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
320 void *data_ptr;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
321 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
322 * Optional size information.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
323 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
324 size_t data_size;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
325 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
326 * A function that reads data from the source.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
327 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
328 cx_properties_read_func read_func;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
329 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
330 * Optional function that may prepare the source for reading data.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
331 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
332 cx_properties_read_init_func read_init_func;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
333 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
334 * Optional function that cleans additional memory allocated by the
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
335 * read_init_func.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
336 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
337 cx_properties_read_clean_func read_clean_func;
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
338 };
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
339
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
340 /**
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
341 * Initialize a properties interface.
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
342 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
343 * @param prop the properties interface
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
344 * @param config the properties configuration
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
345 * @see cxPropertiesInitDefault()
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
346 */
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
347 __attribute__((__nonnull__))
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
348 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
349
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
350 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
351 * Destroys the properties interface.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
352 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
353 * \note Even when you are certain that you did not use the interface in a
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
354 * way that caused a memory allocation, you should call this function anyway.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
355 * Future versions of the library might add features that need additional memory
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
356 * and you really don't want to search the entire code where you might need
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
357 * add call to this function.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
358 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
359 * @param prop the properties interface
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
360 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
361 __attribute__((__nonnull__))
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
362 void cxPropertiesDestroy(CxProperties *prop);
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
363
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
364 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
365 * Initialize a properties parser with the default configuration.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
366 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
367 * @param prop the properties interface
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
368 * @see cxPropertiesInit()
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
369 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
370 #define cxPropertiesInitDefault(prop) \
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
371 cxPropertiesInit(prop, cx_properties_config_default)
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
372
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
373 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
374 * Sets an input buffer.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
375 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
376 * After calling this function, you can parse the data by calling
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
377 * cxPropertiesNext() until the status is #CX_PROPERTIES_NO_DATA.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
378 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
379 * @param prop the properties interface
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
380 * @param buf a pointer to data
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
381 * @param len the length of the data
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
382 */
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
383 __attribute__((__nonnull__))
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
384 void cxPropertiesInput(
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
385 CxProperties *prop,
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
386 const char *buf,
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
387 size_t len
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
388 );
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
389
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
390 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
391 * Sets a new input buffer after copying the current unprocessed data
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
392 * to a temporary buffer.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
393 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
394 * This temporary buffer is allocated on the heap, unless you specified
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
395 * a buffer on the stack with #cxPropertiesUseStack().
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
396 * In that case, the stack buffer is used, until the capacity is not sufficient
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
397 * anymore.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
398 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
399 * When this function is called without any unprocessed data that needs to be
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
400 * copied, it behaves exactly as #cxPropertiesInput().
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
401 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
402 * @param prop the properties interface
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
403 * @param buf a pointer to data
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
404 * @param len the length of the data
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
405 * @return non-zero when a memory allocation was necessary but failed
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
406 */
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
407 __attribute__((__nonnull__))
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
408 int cxPropertiesFill(
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
409 CxProperties *prop,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
410 const char *buf,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
411 size_t len
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
412 );
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
413
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
414 /**
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
415 * Specifies stack memory that shall be used by #cxPropertiesFill().
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
416 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
417 * @param prop the properties interface
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
418 * @param buf a pointer to stack memory
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
419 * @param capacity the capacity of the stack memory
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
420 */
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
421 __attribute__((__nonnull__))
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
422 void cxPropertiesUseStack(
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
423 CxProperties *prop,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
424 char *buf,
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
425 size_t capacity
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
426 );
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
427
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
428 /**
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
429 * Retrieves the next key/value-pair.
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
430 *
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
431 * This function returns zero as long as there are key/value-pairs found.
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
432 * If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
433 *
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
434 * When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
435 * returned and the position of the input buffer will be the start of the
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
436 * affected line. You can then add more data with #cxPropertiesFill().
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
437 *
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
438 * \attention The returned strings will point into a buffer that might not be
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
439 * available later. It is strongly recommended to copy the strings for further
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
440 * use.
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
441 *
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
442 * @param prop the properties interface
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
443 * @param key a pointer to the cxstring that shall contain the property name
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
444 * @param value a pointer to the cxstring that shall contain the property value
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
445 * @return the status code as defined above
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
446 * @see cxPropertiesFill()
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
447 */
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
448 __attribute__((__nonnull__, __warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
449 CxPropertiesStatus cxPropertiesNext(
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
450 CxProperties *prop,
924
3c90dfc35f06 add implementation for the properties parser
Mike Becker <universe@uap-core.de>
parents: 923
diff changeset
451 cxstring *key,
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
452 cxstring *value
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
453 );
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
454
928
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
455 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
456 * Creates a properties sink for an UCX map.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
457 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
458 * The values stored in the map will be pointers to strings allocated
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
459 * by #cx_strdup_a().
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
460 * The default stdlib allocator will be used, unless you specify a custom
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
461 * allocator in the optional \c data of the sink.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
462 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
463 * @param map the map that shall consume the k/v-pairs.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
464 * @return the sink
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
465 * @see cxPropertiesLoad()
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
466 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
467 __attribute__((__nonnull__, __warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
468 CxPropertiesSink cxPropertiesMapSink(CxMap *map);
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
469
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
470 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
471 * Creates a properties source based on an UCX string.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
472 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
473 * @param str the string
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
474 * @return the properties source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
475 * @see cxPropertiesLoad()
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
476 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
477 __attribute__((__warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
478 CxPropertiesSource cxPropertiesStringSource(cxstring str);
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
479
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
480 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
481 * Creates a properties source based on C string with the specified length.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
482 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
483 * @param str the string
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
484 * @param len the length
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
485 * @return the properties source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
486 * @see cxPropertiesLoad()
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
487 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
488 __attribute__((__nonnull__, __warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
489 CxPropertiesSource cxPropertiesCstrnSource(const char *str, size_t len);
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
490
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
491 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
492 * Creates a properties source based on a C string.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
493 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
494 * The length will be determined with strlen(), so the string MUST be
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
495 * zero-terminated.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
496 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
497 * @param str the string
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
498 * @return the properties source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
499 * @see cxPropertiesLoad()
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
500 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
501 __attribute__((__nonnull__, __warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
502 CxPropertiesSource cxPropertiesCstrSource(const char *str);
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
503
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
504 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
505 * Creates a properties source based on an FILE.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
506 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
507 * @param file the file
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
508 * @param chunk_size how many bytes may be read in one operation
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
509 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
510 * @return the properties source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
511 * @see cxPropertiesLoad()
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
512 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
513 __attribute__((__nonnull__, __warn_unused_result__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
514 CxPropertiesSource cxPropertiesFileSource(FILE *file, size_t chunk_size);
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
515
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
516
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
517 /**
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
518 * Loads properties data from a source and transfers it to a sink.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
519 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
520 * This function tries to read as much data from the source as possible.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
521 * When the source was completely consumed and at least on k/v-pair was found,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
522 * the return value will be #CX_PROPERTIES_NO_ERROR.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
523 * When the source was consumed but no k/v-pairs were found, the return value
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
524 * will be #CX_PROPERTIES_NO_DATA.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
525 * The other result codes apply, according to their description.
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
526 *
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
527 * @param prop the properties interface
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
528 * @param sink the sink
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
529 * @param source the source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
530 * @return the status of the last operation
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
531 */
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
532 __attribute__((__nonnull__))
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
533 CxPropertiesStatus cxPropertiesLoad(
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
534 CxProperties *prop,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
535 CxPropertiesSink sink,
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
536 CxPropertiesSource source
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
537 );
d2d42cb1d59e add source/sink facility for properties - fixes #430
Mike Becker <universe@uap-core.de>
parents: 924
diff changeset
538
932
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
539 #ifdef __cplusplus
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
540 } // extern "C"
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
541 #endif
484dab606292 add extern "C" to properties.h
Mike Becker <universe@uap-core.de>
parents: 928
diff changeset
542
923
45da884269c8 add ucx2.1 style interface for a properties parser
Mike Becker <universe@uap-core.de>
parents:
diff changeset
543 #endif // UCX_PROPERTIES

mercurial