1 /*
2  * Copyright (c) 2020 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 /**
17  * @addtogroup MultiMedia_MediaCommon
18  * @{
19  *
20  * @brief Provides data types and media formats required for recording and playing audio and videos.
21  *
22  *
23  * @since 1.0
24  * @version 1.0
25  */
26 
27 /**
28  * @file format.h
29  *
30  * @brief Declares the media formats provided in the </b>Format</b> class.
31  *
32  *
33  * @since 1.0
34  * @version 1.0
35  */
36 
37 
38 #ifndef FORMAT_H
39 #define FORMAT_H
40 
41 #include <map>
42 #include <string>
43 #include <functional>
44 
45 namespace OHOS {
46 namespace Media {
47 /** Indicates the key representing the codec type. */
48 extern const char *CODEC_MIME;
49 
50 /** Indicates the codec for Advanced Audio Coding (AAC) streams, which is a value of the codec type key. */
51 extern const char *MIME_AUDIO_AAC;
52 
53 /** Indicates the codec for RAW audios (not supported yet), which is a value of the codec type key. */
54 extern const char *MIME_AUDIO_RAW;
55 extern const char *PAUSE_AFTER_PLAY;
56 
57 /**
58  * @brief Enumerates formats.
59  *
60  * @since 1.0
61  * @version 1.0
62  */
63 enum FormatDataType : uint32_t {
64     /** None */
65     FORMAT_TYPE_NONE,
66     /** Int32 */
67     FORMAT_TYPE_INT32,
68     /** Int64 */
69     FORMAT_TYPE_INT64,
70     /** Float */
71     FORMAT_TYPE_FLOAT,
72     /** Double */
73     FORMAT_TYPE_DOUBLE,
74     /** String */
75     FORMAT_TYPE_STRING
76 };
77 
78 /**
79  * @brief Represents the data format.
80  *
81  * @since 1.0
82  * @version 1.0
83  */
84 class FormatData {
85 public:
86     explicit FormatData(FormatDataType type);
87     FormatData();
88     ~FormatData();
89 
90     /**
91      * @brief Obtains the format type.
92      *
93      * @return Returns the format type. For details, see {@link OHOS::Media::FormatDataType}.
94      * @since 1.0
95      * @version 1.0
96      */
GetType()97     FormatDataType GetType() const
98     {
99         return type_;
100     }
101 
102     /**
103      * @brief Sets a 32-bit integer.
104      *
105      * @param val Indicates the 32-bit integer to set.
106      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
107      * @since 1.0
108      * @version 1.0
109      */
110     bool SetValue(int32_t val);
111 
112     /**
113      * @brief Sets a 64-bit long integer.
114      *
115      * @param val Indicates the 64-bit long integer to set.
116      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
117      * @since 1.0
118      * @version 1.0
119      */
120     bool SetValue(int64_t val);
121 
122     /**
123      * @brief Sets a single-precision floating-point number.
124      *
125      * @param val Indicates the single-precision floating-point number to set.
126      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
127      * @since 1.0
128      * @version 1.0
129      */
130     bool SetValue(float val);
131 
132     /**
133      * @brief Sets a double-precision floating-point number.
134      *
135      * @param val Indicates the double-precision floating-point number to set.
136      * @return Returns <b>true</b> if the double-precision floating-point number is successfully set; returns
137      * <b>false</b> otherwise.
138      * @since 1.0
139      * @version 1.0
140      */
141     bool SetValue(double val);
142 
143     /**
144      * @brief Sets a string.
145      *
146      * @param val Indicates the string to set.
147      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
148      * @since 1.0
149      * @version 1.0
150      */
151     bool SetValue(const std::string &val);
152 
153     /**
154      * @brief Obtains a 32-bit integer.
155      *
156      * @param val Indicates the 32-bit integer to obtain.
157      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
158      * @since 1.0
159      * @version 1.0
160      */
161     bool GetInt32Value(int32_t &val) const;
162 
163     /**
164      * @brief Obtains a long integer.
165      *
166      * @param val Indicates the long integer to obtain.
167      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
168      * @since 1.0
169      * @version 1.0
170      */
171     bool GetInt64Value(int64_t &val) const;
172 
173     /**
174      * @brief Obtains a single-precision floating-point number.
175      *
176      * @param val Indicates the single-precision floating-point number to obtain.
177      * @return Returns <b>true</b> if the single-precision number is successfully obtained; returns
178      * <b>false</b> otherwise.
179      * @since 1.0
180      * @version 1.0
181      */
182     bool GetFloatValue(float &val) const;
183 
184     /**
185      * @brief Obtains a double-precision floating-point number.
186      *
187      * @param val Indicates the double-precision floating-point number to obtain.
188      * @return Returns <b>true</b> if the double-precision number is successfully obtained; returns
189      * <b>false</b> otherwise.
190      * @since 1.0
191      * @version 1.0
192      */
193     bool GetDoubleValue(double &val) const;
194 
195     /**
196      * @brief Obtains a string.
197      *
198      * @param val Indicates the string to obtain.
199      * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise.
200      * @since 1.0
201      * @version 1.0
202      */
203     bool GetStringValue(std::string &val) const;
204 private:
205     FormatDataType type_;
206     union {
207         int32_t int32Val;
208         int64_t int64Val;
209         float floatVal;
210         double doubleVal;
211         std::string *stringVal;
212     } val_;
213 };
214 
215 /**
216  * @brief Saves and sets media metadata, such as the media playback duration.
217  *
218  * @since 1.0
219  * @version 1.0
220  */
221 class Format {
222 public:
223     /**
224      * @brief Default constructor of the {@link Format} instance.
225      *
226      */
227     Format();
228     ~Format();
229 
230     /**
231      * @brief Sets metadata of the integer type.
232      *
233      * @param key Indicates the metadata key.
234      * @param value Indicates the metadata value, which is a 32-bit integer.
235      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
236      * @since 1.0
237      * @version 1.0
238      */
239     bool PutIntValue(const std::string &key, int32_t value);
240 
241     /**
242      * @brief Sets metadata of the long integer type.
243      *
244      * @param key Indicates the metadata key.
245      * @param value Indicates the metadata value, which is a 64-bit integer.
246      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
247      * @since 1.0
248      * @version 1.0
249      */
250     bool PutLongValue(const std::string &key, int64_t value);
251 
252     /**
253      * @brief Sets metadata of the single-precision floating-point type.
254      *
255      * @param key Indicates the metadata key.
256      * @param value Indicates the metadata value, which is a single-precision floating-point number.
257      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
258      * @since 1.0
259      * @version 1.0
260      */
261     bool PutFloatValue(const std::string &key, float value);
262 
263     /**
264      * @brief Sets metadata of the double-precision floating-point type.
265      *
266      * @param key Indicates the metadata key.
267      * @param value Indicates the metadata value, which is a double-precision floating-point number.
268      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
269      * @since 1.0
270      * @version 1.0
271      */
272     bool PutDoubleValue(const std::string &key, double value);
273 
274     /**
275      * @brief Sets metadata of the string type.
276      *
277      * @param key Indicates the metadata key.
278      * @param value Indicates the metadata value, which is a string.
279      * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise.
280      * @since 1.0
281      * @version 1.0
282      */
283     bool PutStringValue(const std::string &key, const std::string &value);
284 
285     /**
286      * @brief Obtains the metadata value of the integer type.
287      *
288      * @param key Indicates the metadata key.
289      * @param value Indicates the metadata value to obtain, which is a 32-bit integer.
290      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
291      * @since 1.0
292      * @version 1.0
293      */
294     bool GetIntValue(const std::string &key, int32_t &value) const;
295 
296     /**
297      * @brief Obtains the metadata value of the long integer type.
298      *
299      * @param key Indicates the metadata key.
300      * @param value Indicates the metadata value to obtain, which is a 64-bit long integer.
301      * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise.
302      * @since 1.0
303      * @version 1.0
304      */
305     bool GetLongValue(const std::string &key, int64_t &value) const;
306 
307     /**
308      * @brief Obtains the metadata value of the single-precision floating-point type.
309      *
310      * @param key Indicates the metadata key.
311      * @param value Indicates the metadata value to obtain, which is a single-precision floating-point number.
312      * @return Returns <b>true</b> if the single-precision number is successfully obtained; returns
313      * <b>false</b> otherwise.
314      * @since 1.0
315      * @version 1.0
316      */
317     bool GetFloatValue(const std::string &key, float &value) const;
318 
319     /**
320      * @brief Obtains the metadata value of the double-precision floating-point type.
321      *
322      * @param key Indicates the metadata key.
323      * @param value Indicates the metadata value to obtain, which is a double-precision floating-point number.
324      * @return Returns <b>true</b> if the double-precision number is successfully obtained; returns
325      * <b>false</b> otherwise.
326      * @since 1.0
327      * @version 1.0
328      */
329     bool GetDoubleValue(const std::string &key, double &value) const;
330 
331     /**
332      * @brief Obtains the metadata value of the string type.
333      *
334      * @param key Indicates the metadata key.
335      * @param value Indicates the metadata value to obtain, which is a string.
336      * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise.
337      * @since 1.0
338      * @version 1.0
339      */
340     bool GetStringValue(const std::string &key, std::string &value) const;
341 
342     /**
343      * @brief Obtains the metadata map.
344      *
345      * @return Returns the map object.
346      * @since 1.0
347      * @version 1.0
348      */
349     const std::map<std::string, FormatData *> &GetFormatMap() const;
350 
351     /**
352      * @brief Sets all metadata to a specified format.
353      *
354      * @param format Indicates the format. For details, see {@link Format}.
355      * @return Returns <b>true</b> if the setting is successful; returns <b>false</b> otherwise.
356      * @since 1.0
357      * @version 1.0
358      */
359     bool CopyFrom(const Format &format);
360 
361 private:
362     template<typename T>
363     bool SetFormatCommon(const std::string &key, const T &value, FormatDataType type);
364     std::map<std::string, FormatData *> formatMap_;
365 };
366 }  // namespace Media
367 }  // namespace OHOS
368 #endif  // FORMAT_H
369