1 /* 2 * Copyright (C) 2023-2025 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 string type. 136 * 137 * @param key Indicates the metadata key. 138 * @param addr Indicates the metadata addr, which is a int32_t *. 139 * @param size Indicates the metadata addr size, which is a size_t. 140 * @return Returns <b>true</b> if the metadata is successfully set; returns <b>false</b> otherwise. 141 * @since 20 142 * @version 1.0 143 */ 144 bool PutIntBuffer(const std::string_view &key, const int32_t *addr, size_t size); 145 146 /** 147 * @brief Sets metadata of the format vector type. 148 * 149 * @param key Indicates the metadata key. 150 * @param value Indicates the metadata value, which is a format vector. 151 * @return Returns <b>true</b> if the format vector is successfully set; returns <b>false</b> otherwise. 152 * @since 10 153 * @version 1.0 154 */ 155 bool PutFormatVector(const std::string_view &key, std::vector<Format> &value); 156 157 /** 158 * @brief Obtains the metadata value of the integer or boolean type. 159 * 160 * @param key Indicates the metadata key. 161 * @param value Indicates the metadata value to obtain, which is a 32-bit integer. 162 * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise. 163 * @since 10 164 * @version 1.0 165 */ 166 bool GetIntValue(const std::string_view &key, int32_t &value) const; 167 168 /** 169 * @brief Obtains the metadata value of the long integer type. 170 * 171 * @param key Indicates the metadata key. 172 * @param value Indicates the metadata value to obtain, which is a 64-bit long integer. 173 * @return Returns <b>true</b> if the integer is successfully obtained; returns <b>false</b> otherwise. 174 * @since 10 175 * @version 1.0 176 */ 177 bool GetLongValue(const std::string_view &key, int64_t &value) const; 178 179 /** 180 * @brief Obtains the metadata value of the single-precision floating-point type. 181 * 182 * @param key Indicates the metadata key. 183 * @param value Indicates the metadata value to obtain, which is a single-precision floating-point number. 184 * @return Returns <b>true</b> if the single-precision number is successfully obtained; returns 185 * <b>false</b> otherwise. 186 * @since 10 187 * @version 1.0 188 */ 189 bool GetFloatValue(const std::string_view &key, float &value) const; 190 191 /** 192 * @brief Obtains the metadata value of the double-precision floating-point type. 193 * 194 * @param key Indicates the metadata key. 195 * @param value Indicates the metadata value to obtain, which is a double-precision floating-point number. 196 * @return Returns <b>true</b> if the double-precision number is successfully obtained; returns 197 * <b>false</b> otherwise. 198 * @since 10 199 * @version 1.0 200 */ 201 bool GetDoubleValue(const std::string_view &key, double &value) const; 202 203 /** 204 * @brief Obtains the metadata value of the string type. 205 * 206 * @param key Indicates the metadata key. 207 * @param value Indicates the metadata value to obtain, which is a string. 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 GetStringValue(const std::string_view &key, std::string &value) const; 213 214 /** 215 * @brief Obtains the metadata value of the string type. 216 * 217 * @param key Indicates the metadata key. 218 * @param addr Indicates the metadata addr to obtain, which is a uint8_t **. 219 * @param size Indicates the metadata addr size to obtain, which is a size_t. 220 * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise. 221 * @since 10 222 * @version 1.0 223 */ 224 bool GetBuffer(const std::string_view &key, uint8_t **addr, size_t &size) const; 225 226 /** 227 * @brief Obtains the metadata value of the string type. 228 * 229 * @param key Indicates the metadata key. 230 * @param addr Indicates the metadata addr to obtain, which is a int32_t **. 231 * @param size Indicates the metadata addr size to obtain, which is a size_t. 232 * @return Returns <b>true</b> if the string is successfully obtained; returns <b>false</b> otherwise. 233 * @since 6.0 234 */ 235 bool GetIntBuffer(const std::string_view &key, int32_t **addr, size_t &size) const; 236 237 /** 238 * @brief Obtains the metadata value of the format vector type. 239 * 240 * @param key Indicates the metadata key. 241 * @param value Indicates the metadata value to obtain, which is a format vector. 242 * @return Returns <b>true</b> if the format vector is successfully obtained; returns <b>false</b> otherwise. 243 * @since 10 244 * @version 1.0 245 */ 246 bool GetFormatVector(const std::string_view &key, std::vector<Format> &value) const; 247 248 /** 249 * @brief Query whether the key exists in this Format. 250 * 251 * @param key Indicates the metadata key. 252 * @return true 253 * @return false 254 */ 255 bool ContainKey(const std::string_view &key) const; 256 257 /** 258 * @brief Get the value type for the key if the key exists in this Format. 259 * 260 * @param key Indicates the metadata key. 261 * @return FormatDataType. If the key does not exists, return FORMAT_TYPE_NONE. 262 */ 263 FormatDataType GetValueType(const std::string_view &key) const; 264 265 /** 266 * @brief Remove the key from the Format 267 * 268 * @param keys the key will be removed. 269 */ 270 void RemoveKey(const std::string_view &key); 271 272 /** 273 * @brief A trick to enable the comparision between the std::string and std::string_view for 274 * std::map, the trick called Transparent Comparator. 275 * 276 */ 277 using FormatDataMap = std::map<std::string, FormatData, std::less<>>; 278 279 /** 280 * @brief Obtains the metadata map. 281 * 282 * @return Returns the map object. 283 * @since 10 284 * @version 1.0 285 */ 286 const FormatDataMap &GetFormatMap() const; 287 288 /** 289 * @brief A trick to enable the comparision between the std::string and std::string_view for 290 * std::map, the trick called Transparent Comparator. 291 * 292 */ 293 using FormatVectorMap = std::map<std::string, std::vector<Format>, std::less<>>; 294 295 /** 296 * @brief Obtains the metadata vector map. 297 * 298 * @return Returns the map object. 299 * @since 10 300 * @version 1.0 301 */ 302 const FormatVectorMap &GetFormatVectorMap() const; 303 304 /** 305 * @brief Convert the metadata map to string. 306 * 307 * @return Returns a converted string. 308 * @since 10 309 * @version 1.0 310 */ 311 std::string Stringify() const; 312 313 /** 314 * @brief Get the metadata. 315 * 316 * @return Returns the meta of Format. 317 * @since 10 318 * @version 1.0 319 */ 320 std::shared_ptr<Meta> GetMeta(); 321 322 /** 323 * @brief Set the metadata by copying or translating ownership. 324 * 325 * If the provided metadata is shared (use_count > 1), performs a deep copy to avoid 326 * unintended aliasing. Otherwise shares ownership of the provided shared_ptr. 327 * 328 * @param meta Shared pointer to the metadata. 329 * @return Returns <b>true</b> if metadata is non-null and successfully set; 330 * <b>false</b> otherwise. 331 * @since 10 332 * @version 1.0 333 */ 334 bool SetMeta(std::shared_ptr<Meta> meta); 335 336 /** 337 * @brief Set the metadata reference by taking shared ownership. 338 * 339 * Directly shares ownership of the provided shared_ptr without copying contents. 340 * Used to share the same metadata. 341 * 342 * @param meta Shared pointer to the metadata. 343 * @return Returns <b>true</b> if metadata is non-null and successfully set; 344 * <b>false</b> otherwise. 345 * @since 20 346 * @version 1.0 347 */ 348 bool SetMetaPtr(std::shared_ptr<Meta> meta); 349 350 private: 351 FormatDataMap formatMap_; 352 FormatVectorMap formatVecMap_; 353 std::shared_ptr<Meta> meta_; 354 }; 355 } // namespace Media 356 } // namespace OHOS 357 #endif // FORMAT_H 358