1/*
2 * Copyright (c) 2015, Intel Corporation
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice, this
9 * list of conditions and the following disclaimer.
10 *
11 * 2. Redistributions in binary form must reproduce the above copyright notice,
12 * this list of conditions and the following disclaimer in the documentation and/or
13 * other materials provided with the distribution.
14 *
15 * 3. Neither the name of the copyright holder nor the names of its contributors
16 * may be used to endorse or promote products derived from this software without
17 * specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30#pragma once
31
32#include "parameter_export.h"
33
34#include <stdint.h>
35#include <string>
36#include <vector>
37
38/** Forward declaration of private classes.
39 * Client should not use those class.
40 * They are not part of the public api and may be remove/renamed in any release.
41 * @{
42 */
43class CParameterMgr;
44class CConfigurableElement;
45class CBaseParameter;
46/** @} */
47
48/** TODO */
49class PARAMETER_EXPORT ElementHandle
50{
51public:
52    /** @return element's name. */
53    std::string getName() const;
54
55    /** @return element's size in bytes.
56     *
57     * If the element size in bit is not a multiple of CHAR_BIT (8)
58     * it is rounded to the upper multiple.
59     * Effectively returning the element memory footprint.
60     */
61    size_t getSize() const;
62
63    /** @return true if the element is a parameter, false otherwise. */
64    bool isParameter() const;
65
66    /** @return a human readable description of the element. */
67    std::string getDescription() const;
68
69    /** @return is the element and all its descendant not in a domain.
70     *
71     * Only rogue elements are allowed to be set.
72     * */
73    bool isRogue() const;
74
75    /** @return true if the element is an array, false otherwise.*/
76    bool isArray() const;
77
78    /** @return the parameter array length.
79     *          0 if the element is not an array (scalar).
80     */
81    size_t getArrayLength() const;
82
83    /** @return element's path in the parameter hierarchy tree. */
84    std::string getPath() const;
85
86    /** @return element's kind.
87     *
88     * Ie: a string identifying the type of Element.
89     */
90    std::string getKind() const;
91
92    std::vector<ElementHandle> getChildren();
93
94    /** Get mapping data of the element context
95     *
96     * Retrieve mapping data associated to a given key if any.
97     * If the key is not present in this element, query ancestors.
98     *
99     * @param[in] strKey the input mapping key
100     * @param[out] strValue the resulting mapping value in case of success
101     * @return true for if mapping key exists, false otherwise
102     */
103    bool getMappingData(const std::string &strKey, std::string &strValue) const;
104
105    /** Gets element structure description as XML string
106     *
107     * @return the output XML string
108     */
109    bool getStructureAsXML(std::string &xmlStructure, std::string &error) const;
110
111    /** Gets element settings as XML string
112     *
113     * @param[out] xmlValue the values to get
114     * @param[out] error On failure (false returned) will contain a human
115     *                   readable description of the error.
116     *                   On success (true returned) the content is not
117     *                   specified.
118     *
119     * @note returned value format depends on the current ParameterMgr format
120     *       control properties, including value space and output raw format.
121     *       @see ParameterMgrPlatformConnector::setOutputRawFormat
122     *       @see ParameterMgrPlatformConnector::setValueSpace
123     *
124     * @return true on success, false on failure
125     */
126    bool getAsXML(std::string &xmlValue, std::string &error) const;
127
128    /** Sets element settings as XML string
129     *
130     * @param[in] xmlValue the values to set
131     * @param[out] error On failure (false returned) will contain a human
132     *                   readable description of the error.
133     *                   On success (true returned) the content is not
134     *                   specified.
135     *
136     * @note
137     *    - targeted element needs to be rogue for this operation to be allowed
138     *    - structure of the passed XML element must match the targeted
139     *      configurable element's one otherwise this operation will fail
140     *    - expected value format depends on current value space.
141     *      @see ParameterMgrPlatformConnector::valueSpaceIsRaw
142     *
143     * @return true on success, false otherwise
144     */
145    bool setAsXML(const std::string &xmlValue, std::string &error);
146
147    /** Gets element settings in binary format
148     *
149     * @param[out] bytesValue the output vector
150     * @param[out] error unused
151     *
152     * @returns true
153     */
154    bool getAsBytes(std::vector<uint8_t> &bytesValue, std::string &error) const;
155
156    /** Sets element settings in binary format
157     *
158     * @param[out] bytesValue the output vector
159     * @param[out] error On failure (false returned) will contain a human
160     *                   readable description of the error.
161     *                   On success (true returned) the content is not
162     *                   specified.
163     *
164     * @note
165     *    - targeted element needs to be rogue for this operation to be allowed
166     *    - size of the passed array must match that of the element
167     */
168    bool setAsBytes(const std::vector<uint8_t> &bytesValue, std::string &error);
169
170    /** Access (get or set) parameters as different types.
171     *
172     * Will fail if the element is not a paramete.
173     * Array access will fail if the parameter is not an array.
174     *
175     * @param value if get, the value to get (in parameter)
176     *              if set, the value to set (out parameter)
177     *
178     * Setting an array requires the std::vector size to match the arrayLength.
179     * Ie: value.size() == arrayLength()
180     *
181     * @param[out] error On failure (false returned) will contain a human
182     *                   readable description of the error.
183     *                   On success (true returned) the content is not
184     *                   specified.
185     * @return true if the access was successful,
186     *         false otherwise (see error for the detail)
187     * @{
188     */
189
190    /** Boolean access @{ */
191    bool getAsBoolean(bool &value, std::string &error) const;
192    bool setAsBoolean(bool value, std::string &error);
193    bool setAsBooleanArray(const std::vector<bool> &value, std::string &error);
194    bool getAsBooleanArray(std::vector<bool> &value, std::string &error) const;
195    /** @} */
196
197    /** Integer Access @{ */
198    bool setAsInteger(uint32_t value, std::string &error);
199    bool getAsInteger(uint32_t &value, std::string &error) const;
200    bool setAsIntegerArray(const std::vector<uint32_t> &value, std::string &error);
201    bool getAsIntegerArray(std::vector<uint32_t> &value, std::string &error) const;
202    /** @} */
203
204    /** Signed Integer Access @{ */
205    bool setAsSignedInteger(int32_t value, std::string &error);
206    bool getAsSignedInteger(int32_t &value, std::string &error) const;
207    bool setAsSignedIntegerArray(const std::vector<int32_t> &value, std::string &error);
208    bool getAsSignedIntegerArray(std::vector<int32_t> &value, std::string &error) const;
209    /** @} */
210
211    /** Double Access @{ */
212    bool setAsDouble(double value, std::string &error);
213    bool getAsDouble(double &value, std::string &error) const;
214    bool setAsDoubleArray(const std::vector<double> &value, std::string &error);
215    bool getAsDoubleArray(std::vector<double> &value, std::string &error) const;
216    /** @} */
217
218    /** String Access @{ */
219    bool setAsString(const std::string &value, std::string &error);
220    bool getAsString(std::string &value, std::string &error) const;
221    bool setAsStringArray(const std::vector<std::string> &value, std::string &error);
222    bool getAsStringArray(std::vector<std::string> &value, std::string &error) const;
223    /** @} */
224
225    /** @} */
226
227protected:
228    ElementHandle(CConfigurableElement &element, CParameterMgr &parameterMgr);
229    friend CParameterMgr; // So that it can build the handler
230
231private:
232    template <class T>
233    bool setAs(const T value, std::string &error) const;
234    template <class T>
235    bool getAs(T &value, std::string &error) const;
236
237    CBaseParameter &getParameter();
238    const CBaseParameter &getParameter() const;
239
240    /** Check that the parameter value can be modify.
241     *
242     * @param arrayLength[in] If accessing as an array: the new value array length
243     *                        Otherwise: 0
244     * @param error[out] If access is forbidden: a human readable message explaining why
245     *                   Otherwise: not modified.
246     *
247     * @return true if the parameter value can be retrieved, false otherwise.
248     */
249    bool checkSetValidity(size_t arrayLength, std::string &error) const;
250
251    /** Check that the parameter value can be retrieved.
252     *
253     * @param asArray[in] true if accessing as an array, false otherwise.
254     * @param error[out] If access is forbidden, a human readable message explaining why
255     *                   Otherwise, not modified.
256     *
257     * @return true if the parameter value can be retrieved, false otherwise.
258     */
259    bool checkGetValidity(bool asArray, std::string &error) const;
260
261    /** Reference to the handled Configurable element. */
262    CConfigurableElement &mElement;
263
264    CParameterMgr &mParameterMgr;
265};
266