1 /*
2  * Copyright (C) 2023 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef OHOS_MEDIA_FORMAT_H
17 #define OHOS_MEDIA_FORMAT_H
18 
19 #include <map>
20 #include <memory>
21 #include <string>
22 #include <vector>
23 
24 namespace OHOS {
25 namespace Media {
26 class Meta;
27 enum FormatDataType : uint32_t {
28     /* None */
29     FORMAT_TYPE_NONE,
30     /* Int32 */
31     FORMAT_TYPE_INT32,
32     /* Int64 */
33     FORMAT_TYPE_INT64,
34     /* Float */
35     FORMAT_TYPE_FLOAT,
36     /* Double */
37     FORMAT_TYPE_DOUBLE,
38     /* String */
39     FORMAT_TYPE_STRING,
40     /* Addr */
41     FORMAT_TYPE_ADDR,
42 };
43 
44 struct FormatData {
45     FormatDataType type = FORMAT_TYPE_NONE;
46     union Val {
47         int32_t int32Val;
48         int64_t int64Val;
49         float floatVal;
50         double doubleVal;
51     } val = {0};
52     std::string stringVal = "";
53     uint8_t *addr = nullptr;
54     size_t size = 0;
55 };
56 
57 class __attribute__((visibility("default"))) Format {
58 public:
59     Format();
60     ~Format();
61 
62     Format(const Format &rhs);
63     Format(Format &&rhs) noexcept;
64     Format &operator=(const Format &rhs);
65     Format &operator=(Format &&rhs) noexcept;
66 
67     /**
68      * @brief Sets metadata of the integer or boolean type.
69      *
70      * @param key Indicates the metadata key.
71      * @param value Indicates the metadata value, which is a 32-bit integer.
72      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
73      * @since 10
74      * @version 1.0
75      */
76     bool PutIntValue(const std::string_view &key, int32_t value);
77 
78     /**
79      * @brief Sets metadata of the long integer type.
80      *
81      * @param key Indicates the metadata key.
82      * @param value Indicates the metadata value, which is a 64-bit integer.
83      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
84      * @since 10
85      * @version 1.0
86      */
87     bool PutLongValue(const std::string_view &key, int64_t value);
88 
89     /**
90      * @brief Sets metadata of the single-precision floating-point type.
91      *
92      * @param key Indicates the metadata key.
93      * @param value Indicates the metadata value, which is a single-precision floating-point number.
94      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
95      * @since 10
96      * @version 1.0
97      */
98     bool PutFloatValue(const std::string_view &key, float value);
99 
100     /**
101      * @brief Sets metadata of the double-precision floating-point type.
102      *
103      * @param key Indicates the metadata key.
104      * @param value Indicates the metadata value, which is a double-precision floating-point number.
105      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
106      * @since 10
107      * @version 1.0
108      */
109     bool PutDoubleValue(const std::string_view &key, double value);
110 
111     /**
112      * @brief Sets metadata of the string type.
113      *
114      * @param key Indicates the metadata key.
115      * @param value Indicates the metadata value, which is a string.
116      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
117      * @since 10
118      * @version 1.0
119      */
120     bool PutStringValue(const std::string_view &key, const std::string_view &value);
121 
122     /**
123      * @brief Sets metadata of the string type.
124      *
125      * @param key Indicates the metadata key.
126      * @param addr Indicates the metadata addr, which is a uint8_t *.
127      * @param size Indicates the metadata addr size, which is a size_t.
128      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
129      * @since 10
130      * @version 1.0
131      */
132     bool PutBuffer(const std::string_view &key, const uint8_t *addr, size_t size);
133 
134     /**
135      * @brief Sets metadata of the format vector type.
136      *
137      * @param key Indicates the metadata key.
138      * @param value Indicates the metadata value, which is a format vector.
139      * @return Returns <b>true</b> if the format vector is successfully set; returns <b>false</b> otherwise.
140      * @since 10
141      * @version 1.0
142      */
143     bool PutFormatVector(const std::string_view &key, std::vector<Format> &value);
144 
145     /**
146      * @brief Obtains the metadata value of the integer or boolean type.
147      *
148      * @param key Indicates the metadata key.
149      * @param value Indicates the metadata value to obtain, which is a 32-bit integer.
150      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
151      * @since 10
152      * @version 1.0
153      */
154     bool GetIntValue(const std::string_view &key, int32_t &value) const;
155 
156     /**
157      * @brief Obtains the metadata value of the long integer type.
158      *
159      * @param key Indicates the metadata key.
160      * @param value Indicates the metadata value to obtain, which is a 64-bit long integer.
161      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
162      * @since 10
163      * @version 1.0
164      */
165     bool GetLongValue(const std::string_view &key, int64_t &value) const;
166 
167     /**
168      * @brief Obtains the metadata value of the single-precision floating-point type.
169      *
170      * @param key Indicates the metadata key.
171      * @param value Indicates the metadata value to obtain, which is a single-precision floating-point number.
172      * @return Returns <b>true</b> if the single-precision number is successfully obtained; returns
173      * <b>false</b> otherwise.
174      * @since 10
175      * @version 1.0
176      */
177     bool GetFloatValue(const std::string_view &key, float &value) const;
178 
179     /**
180      * @brief Obtains the metadata value of the double-precision floating-point type.
181      *
182      * @param key Indicates the metadata key.
183      * @param value Indicates the metadata value to obtain, which is a double-precision floating-point number.
184      * @return Returns <b>true</b> if the double-precision number is successfully obtained; returns
185      * <b>false</b> otherwise.
186      * @since 10
187      * @version 1.0
188      */
189     bool GetDoubleValue(const std::string_view &key, double &value) const;
190 
191     /**
192      * @brief Obtains the metadata value of the string type.
193      *
194      * @param key Indicates the metadata key.
195      * @param value Indicates the metadata value to obtain, which is a string.
196      * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise.
197      * @since 10
198      * @version 1.0
199      */
200     bool GetStringValue(const std::string_view &key, std::string &value) const;
201 
202     /**
203      * @brief Obtains the metadata value of the string type.
204      *
205      * @param key Indicates the metadata key.
206      * @param addr Indicates the metadata addr to obtain, which is a uint8_t **.
207      * @param size Indicates the metadata addr size to obtain, which is a size_t.
208      * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise.
209      * @since 10
210      * @version 1.0
211      */
212     bool GetBuffer(const std::string_view &key, uint8_t **addr, size_t &size) const;
213 
214     /**
215      * @brief Obtains the metadata value of the format vector type.
216      *
217      * @param key Indicates the metadata key.
218      * @param value Indicates the metadata value to obtain, which is a format vector.
219      * @return Returns <b>true</b> if the format vector is successfully obtained; returns <b>false</b> otherwise.
220      * @since 10
221      * @version 1.0
222      */
223     bool GetFormatVector(const std::string_view &key, std::vector<Format> &value) const;
224 
225     /**
226      * @brief Query whether the key exists in this Format.
227      *
228      * @param key Indicates the metadata key.
229      * @return true
230      * @return false
231      */
232     bool ContainKey(const std::string_view &key) const;
233 
234     /**
235      * @brief Get the value type for the key if the key exists in this Format.
236      *
237      * @param key Indicates the metadata key.
238      * @return FormatDataType. If the key does not exists, return FORMAT_TYPE_NONE.
239      */
240     FormatDataType GetValueType(const std::string_view &key) const;
241 
242     /**
243      * @brief Remove the key from the Format
244      *
245      * @param keys the key will be removed.
246      */
247     void RemoveKey(const std::string_view &key);
248 
249     /**
250      * @brief A trick to enable the comparision between the std::string and std::string_view for
251      * std::map, the trick called Transparent Comparator.
252      *
253      */
254     using FormatDataMap = std::map<std::string, FormatData, std::less<>>;
255 
256     /**
257      * @brief Obtains the metadata map.
258      *
259      * @return Returns the map object.
260      * @since 10
261      * @version 1.0
262      */
263     const FormatDataMap &GetFormatMap() const;
264 
265     /**
266      * @brief A trick to enable the comparision between the std::string and std::string_view for
267      * std::map, the trick called Transparent Comparator.
268      *
269      */
270     using FormatVectorMap = std::map<std::string, std::vector<Format>, std::less<>>;
271 
272     /**
273      * @brief Obtains the metadata vector map.
274      *
275      * @return Returns the map object.
276      * @since 10
277      * @version 1.0
278      */
279     const FormatVectorMap &GetFormatVectorMap() const;
280 
281     /**
282      * @brief Convert the metadata map to string.
283      *
284      * @return Returns a converted string.
285      * @since 10
286      * @version 1.0
287      */
288     std::string Stringify() const;
289 
290     /**
291      * @brief Get the metadata.
292      *
293      * @return Returns the meta of Format.
294      * @since 10
295      * @version 1.0
296      */
297     std::shared_ptr<Meta> GetMeta();
298 
299     /**
300      * @brief Set the metadata map to Format.
301      *
302      * @param meta the meta be set.
303      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
304      * @since 10
305      * @version 1.0
306      */
307     bool SetMeta(std::shared_ptr<Meta> meta);
308 
309 private:
310     FormatDataMap formatMap_;
311     FormatVectorMap formatVecMap_;
312     std::shared_ptr<Meta> meta_;
313 };
314 } // namespace Media
315 } // namespace OHOS
316 #endif // FORMAT_H
317