1 /* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef SYSTEM_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H 18 #define SYSTEM_MEDIA_INCLUDE_ANDROID_CAMERA_METADATA_H 19 20 #include <string.h> 21 #include <stdint.h> 22 #include <cutils/compiler.h> 23 #include <system/camera_vendor_tags.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * Tag hierarchy and enum definitions for camera_metadata_entry 31 * ============================================================================= 32 */ 33 34 /** 35 * Main enum definitions are in a separate file to make it easy to 36 * maintain 37 */ 38 #include "camera_metadata_tags.h" 39 40 /** 41 * Enum range for each top-level category 42 */ 43 ANDROID_API 44 extern unsigned int camera_metadata_section_bounds[ANDROID_SECTION_COUNT][2]; 45 ANDROID_API 46 extern const char *camera_metadata_section_names[ANDROID_SECTION_COUNT]; 47 48 /** 49 * Type definitions for camera_metadata_entry 50 * ============================================================================= 51 */ 52 enum { 53 // Unsigned 8-bit integer (uint8_t) 54 TYPE_BYTE = 0, 55 // Signed 32-bit integer (int32_t) 56 TYPE_INT32 = 1, 57 // 32-bit float (float) 58 TYPE_FLOAT = 2, 59 // Signed 64-bit integer (int64_t) 60 TYPE_INT64 = 3, 61 // 64-bit float (double) 62 TYPE_DOUBLE = 4, 63 // A 64-bit fraction (camera_metadata_rational_t) 64 TYPE_RATIONAL = 5, 65 // Number of type fields 66 NUM_TYPES 67 }; 68 69 typedef struct camera_metadata_rational { 70 int32_t numerator; 71 int32_t denominator; 72 } camera_metadata_rational_t; 73 74 /** 75 * A reference to a metadata entry in a buffer. 76 * 77 * The data union pointers point to the real data in the buffer, and can be 78 * modified in-place if the count does not need to change. The count is the 79 * number of entries in data of the entry's type, not a count of bytes. 80 */ 81 typedef struct camera_metadata_entry { 82 size_t index; 83 uint32_t tag; 84 uint8_t type; 85 size_t count; 86 union { 87 uint8_t *u8; 88 int32_t *i32; 89 float *f; 90 int64_t *i64; 91 double *d; 92 camera_metadata_rational_t *r; 93 } data; 94 } camera_metadata_entry_t; 95 96 /** 97 * A read-only reference to a metadata entry in a buffer. Identical to 98 * camera_metadata_entry in layout 99 */ 100 typedef struct camera_metadata_ro_entry { 101 size_t index; 102 uint32_t tag; 103 uint8_t type; 104 size_t count; 105 union { 106 const uint8_t *u8; 107 const int32_t *i32; 108 const float *f; 109 const int64_t *i64; 110 const double *d; 111 const camera_metadata_rational_t *r; 112 } data; 113 } camera_metadata_ro_entry_t; 114 115 /** 116 * Size in bytes of each entry type 117 */ 118 ANDROID_API 119 extern const size_t camera_metadata_type_size[NUM_TYPES]; 120 121 /** 122 * Human-readable name of each entry type 123 */ 124 ANDROID_API 125 extern const char* camera_metadata_type_names[NUM_TYPES]; 126 127 /** 128 * Main definitions for the metadata entry and array structures 129 * ============================================================================= 130 */ 131 132 /** 133 * A packet of metadata. This is a list of metadata entries, each of which has 134 * an integer tag to identify its meaning, 'type' and 'count' field, and the 135 * data, which contains a 'count' number of entries of type 'type'. The packet 136 * has a fixed capacity for entries and for extra data. A new entry uses up one 137 * entry slot, and possibly some amount of data capacity; the function 138 * calculate_camera_metadata_entry_data_size() provides the amount of data 139 * capacity that would be used up by an entry. 140 * 141 * Entries are not sorted by default, and are not forced to be unique - multiple 142 * entries with the same tag are allowed. The packet will not dynamically resize 143 * when full. 144 * 145 * The packet is contiguous in memory, with size in bytes given by 146 * get_camera_metadata_size(). Therefore, it can be copied safely with memcpy() 147 * to a buffer of sufficient size. The copy_camera_metadata() function is 148 * intended for eliminating unused capacity in the destination packet. 149 */ 150 struct camera_metadata; 151 typedef struct camera_metadata camera_metadata_t; 152 153 /** 154 * Functions for manipulating camera metadata 155 * ============================================================================= 156 * 157 * NOTE: Unless otherwise specified, functions that return type "int" 158 * return 0 on success, and non-0 value on error. 159 */ 160 161 /** 162 * Allocate a new camera_metadata structure, with some initial space for entries 163 * and extra data. The entry_capacity is measured in entry counts, and 164 * data_capacity in bytes. The resulting structure is all contiguous in memory, 165 * and can be freed with free_camera_metadata(). 166 */ 167 ANDROID_API 168 camera_metadata_t *allocate_camera_metadata(size_t entry_capacity, 169 size_t data_capacity); 170 171 /** 172 * Get the required alignment of a packet of camera metadata, which is the 173 * maximal alignment of the embedded camera_metadata, camera_metadata_buffer_entry, 174 * and camera_metadata_data. 175 */ 176 ANDROID_API 177 size_t get_camera_metadata_alignment(); 178 179 /** 180 * Allocate a new camera_metadata structure of size src_size. Copy the data, 181 * ignoring alignment, and then attempt validation. If validation 182 * fails, free the memory and return NULL. Otherwise return the pointer. 183 * 184 * The resulting pointer can be freed with free_camera_metadata(). 185 */ 186 ANDROID_API 187 camera_metadata_t *allocate_copy_camera_metadata_checked( 188 const camera_metadata_t *src, 189 size_t src_size); 190 191 /** 192 * Place a camera metadata structure into an existing buffer. Returns NULL if 193 * the buffer is too small for the requested number of reserved entries and 194 * bytes of data. The entry_capacity is measured in entry counts, and 195 * data_capacity in bytes. If the buffer is larger than the required space, 196 * unused space will be left at the end. If successful, returns a pointer to the 197 * metadata header placed at the start of the buffer. It is the caller's 198 * responsibility to free the original buffer; do not call 199 * free_camera_metadata() with the returned pointer. 200 */ 201 ANDROID_API 202 camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size, 203 size_t entry_capacity, 204 size_t data_capacity); 205 206 /** 207 * Free a camera_metadata structure. Should only be used with structures 208 * allocated with allocate_camera_metadata(). 209 */ 210 ANDROID_API 211 void free_camera_metadata(camera_metadata_t *metadata); 212 213 /** 214 * Calculate the buffer size needed for a metadata structure of entry_count 215 * metadata entries, needing a total of data_count bytes of extra data storage. 216 */ 217 ANDROID_API 218 size_t calculate_camera_metadata_size(size_t entry_count, 219 size_t data_count); 220 221 /** 222 * Get current size of entire metadata structure in bytes, including reserved 223 * but unused space. 224 */ 225 ANDROID_API 226 size_t get_camera_metadata_size(const camera_metadata_t *metadata); 227 228 /** 229 * Get size of entire metadata buffer in bytes, not including reserved but 230 * unused space. This is the amount of space needed by copy_camera_metadata for 231 * its dst buffer. 232 */ 233 ANDROID_API 234 size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata); 235 236 /** 237 * Get the current number of entries in the metadata packet. 238 * 239 * metadata packet must be valid, which can be checked before the call with 240 * validate_camera_metadata_structure(). 241 */ 242 ANDROID_API 243 size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata); 244 245 /** 246 * Get the maximum number of entries that could fit in the metadata packet. 247 */ 248 ANDROID_API 249 size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata); 250 251 /** 252 * Get the current count of bytes used for value storage in the metadata packet. 253 */ 254 ANDROID_API 255 size_t get_camera_metadata_data_count(const camera_metadata_t *metadata); 256 257 /** 258 * Get the maximum count of bytes that could be used for value storage in the 259 * metadata packet. 260 */ 261 ANDROID_API 262 size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata); 263 264 /** 265 * Copy a metadata structure to a memory buffer, compacting it along the 266 * way. That is, in the copied structure, entry_count == entry_capacity, and 267 * data_count == data_capacity. 268 * 269 * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the 270 * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns 271 * NULL. Otherwise returns a pointer to the metadata structure header placed at 272 * the start of dst. 273 * 274 * Since the buffer was not allocated by allocate_camera_metadata, the caller is 275 * responsible for freeing the underlying buffer when needed; do not call 276 * free_camera_metadata. 277 */ 278 ANDROID_API 279 camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size, 280 const camera_metadata_t *src); 281 282 /** 283 * Validate that a metadata is structurally sane. That is, its internal 284 * state is such that we won't get buffer overflows or run into other 285 * 'impossible' issues when calling the other API functions. 286 * 287 * This is useful in particular after copying the binary metadata blob 288 * from an untrusted source, since passing this check means the data is at least 289 * consistent. 290 * 291 * The expected_size argument is optional. 292 * 293 * Returns 0 on success. A non-0 value is returned on error. 294 */ 295 ANDROID_API 296 int validate_camera_metadata_structure(const camera_metadata_t *metadata, 297 const size_t *expected_size); 298 299 /** 300 * Append camera metadata in src to an existing metadata structure in dst. This 301 * does not resize the destination structure, so if it is too small, a non-zero 302 * value is returned. On success, 0 is returned. Appending onto a sorted 303 * structure results in a non-sorted combined structure. 304 */ 305 ANDROID_API 306 int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src); 307 308 /** 309 * Clone an existing metadata buffer, compacting along the way. This is 310 * equivalent to allocating a new buffer of the minimum needed size, then 311 * appending the buffer to be cloned into the new buffer. The resulting buffer 312 * can be freed with free_camera_metadata(). Returns NULL if cloning failed. 313 */ 314 ANDROID_API 315 camera_metadata_t *clone_camera_metadata(const camera_metadata_t *src); 316 317 /** 318 * Calculate the number of bytes of extra data a given metadata entry will take 319 * up. That is, if entry of 'type' with a payload of 'data_count' values is 320 * added, how much will the value returned by get_camera_metadata_data_count() 321 * be increased? This value may be zero, if no extra data storage is needed. 322 */ 323 ANDROID_API 324 size_t calculate_camera_metadata_entry_data_size(uint8_t type, 325 size_t data_count); 326 327 /** 328 * Add a metadata entry to a metadata structure. Returns 0 if the addition 329 * succeeded. Returns a non-zero value if there is insufficient reserved space 330 * left to add the entry, or if the tag is unknown. data_count is the number of 331 * entries in the data array of the tag's type, not a count of 332 * bytes. Vendor-defined tags can not be added using this method, unless 333 * set_vendor_tag_query_ops() has been called first. Entries are always added to 334 * the end of the structure (highest index), so after addition, a 335 * previously-sorted array will be marked as unsorted. 336 * 337 * Returns 0 on success. A non-0 value is returned on error. 338 */ 339 ANDROID_API 340 int add_camera_metadata_entry(camera_metadata_t *dst, 341 uint32_t tag, 342 const void *data, 343 size_t data_count); 344 345 /** 346 * Sort the metadata buffer for fast searching. If already marked as sorted, 347 * does nothing. Adding or appending entries to the buffer will place the buffer 348 * back into an unsorted state. 349 * 350 * Returns 0 on success. A non-0 value is returned on error. 351 */ 352 ANDROID_API 353 int sort_camera_metadata(camera_metadata_t *dst); 354 355 /** 356 * Get metadata entry at position index in the metadata buffer. 357 * Index must be less than entry count, which is returned by 358 * get_camera_metadata_entry_count(). 359 * 360 * src and index are inputs; the passed-in entry is updated with the details of 361 * the entry. The data pointer points to the real data in the buffer, and can be 362 * updated as long as the data count does not change. 363 * 364 * Returns 0 on success. A non-0 value is returned on error. 365 */ 366 ANDROID_API 367 int get_camera_metadata_entry(camera_metadata_t *src, 368 size_t index, 369 camera_metadata_entry_t *entry); 370 371 /** 372 * Get metadata entry at position index, but disallow editing the data. 373 */ 374 ANDROID_API 375 int get_camera_metadata_ro_entry(const camera_metadata_t *src, 376 size_t index, 377 camera_metadata_ro_entry_t *entry); 378 379 /** 380 * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise, 381 * returns entry contents like get_camera_metadata_entry. 382 * 383 * If multiple entries with the same tag exist, does not have any guarantees on 384 * which is returned. To speed up searching for tags, sort the metadata 385 * structure first by calling sort_camera_metadata(). 386 */ 387 ANDROID_API 388 int find_camera_metadata_entry(camera_metadata_t *src, 389 uint32_t tag, 390 camera_metadata_entry_t *entry); 391 392 /** 393 * Find an entry with given tag value, but disallow editing the data 394 */ 395 ANDROID_API 396 int find_camera_metadata_ro_entry(const camera_metadata_t *src, 397 uint32_t tag, 398 camera_metadata_ro_entry_t *entry); 399 400 /** 401 * Delete an entry at given index. This is an expensive operation, since it 402 * requires repacking entries and possibly entry data. This also invalidates any 403 * existing camera_metadata_entry.data pointers to this buffer. Sorting is 404 * maintained. 405 */ 406 ANDROID_API 407 int delete_camera_metadata_entry(camera_metadata_t *dst, 408 size_t index); 409 410 /** 411 * Updates a metadata entry with new data. If the data size is changing, may 412 * need to adjust the data array, making this an O(N) operation. If the data 413 * size is the same or still fits in the entry space, this is O(1). Maintains 414 * sorting, but invalidates camera_metadata_entry instances that point to the 415 * updated entry. If a non-NULL value is passed in to entry, the entry structure 416 * is updated to match the new buffer state. Returns a non-zero value if there 417 * is no room for the new data in the buffer. 418 */ 419 ANDROID_API 420 int update_camera_metadata_entry(camera_metadata_t *dst, 421 size_t index, 422 const void *data, 423 size_t data_count, 424 camera_metadata_entry_t *updated_entry); 425 426 /** 427 * Retrieve human-readable name of section the tag is in. Returns NULL if 428 * no such tag is defined. Returns NULL for tags in the vendor section, unless 429 * set_vendor_tag_query_ops() has been used. 430 */ 431 ANDROID_API 432 const char *get_camera_metadata_section_name(uint32_t tag); 433 434 /** 435 * Retrieve human-readable name of tag (not including section). Returns NULL if 436 * no such tag is defined. Returns NULL for tags in the vendor section, unless 437 * set_vendor_tag_query_ops() has been used. 438 */ 439 ANDROID_API 440 const char *get_camera_metadata_tag_name(uint32_t tag); 441 442 /** 443 * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1 444 * for tags in the vendor section, unless set_vendor_tag_query_ops() has been 445 * used. 446 */ 447 ANDROID_API 448 int get_camera_metadata_tag_type(uint32_t tag); 449 450 /** 451 * Set up vendor-specific tag query methods. These are needed to properly add 452 * entries with vendor-specified tags and to use the 453 * get_camera_metadata_section_name, _tag_name, and _tag_type methods with 454 * vendor tags. Returns 0 on success. 455 * 456 * **DEPRECATED** - Please use vendor_tag_ops defined in camera_vendor_tags.h 457 * instead. 458 */ 459 typedef struct vendor_tag_query_ops vendor_tag_query_ops_t; 460 struct vendor_tag_query_ops { 461 /** 462 * Get vendor section name for a vendor-specified entry tag. Only called for 463 * tags >= 0x80000000. The section name must start with the name of the 464 * vendor in the Java package style. For example, CameraZoom inc must prefix 465 * their sections with "com.camerazoom." Must return NULL if the tag is 466 * outside the bounds of vendor-defined sections. 467 */ 468 const char *(*get_camera_vendor_section_name)( 469 const vendor_tag_query_ops_t *v, 470 uint32_t tag); 471 /** 472 * Get tag name for a vendor-specified entry tag. Only called for tags >= 473 * 0x80000000. Must return NULL if the tag is outside the bounds of 474 * vendor-defined sections. 475 */ 476 const char *(*get_camera_vendor_tag_name)( 477 const vendor_tag_query_ops_t *v, 478 uint32_t tag); 479 /** 480 * Get tag type for a vendor-specified entry tag. Only called for tags >= 481 * 0x80000000. Must return -1 if the tag is outside the bounds of 482 * vendor-defined sections. 483 */ 484 int (*get_camera_vendor_tag_type)( 485 const vendor_tag_query_ops_t *v, 486 uint32_t tag); 487 /** 488 * Get the number of vendor tags supported on this platform. Used to 489 * calculate the size of buffer needed for holding the array of all tags 490 * returned by get_camera_vendor_tags(). 491 */ 492 int (*get_camera_vendor_tag_count)( 493 const vendor_tag_query_ops_t *v); 494 /** 495 * Fill an array with all the supported vendor tags on this platform. 496 * get_camera_vendor_tag_count() returns the number of tags supported, and 497 * tag_array should be allocated with enough space to hold all of the tags. 498 */ 499 void (*get_camera_vendor_tags)( 500 const vendor_tag_query_ops_t *v, 501 uint32_t *tag_array); 502 }; 503 504 /** 505 * **DEPRECATED** - This should only be used by the camera framework. Camera 506 * metadata will transition to using vendor_tag_ops defined in 507 * camera_vendor_tags.h instead. 508 */ 509 ANDROID_API 510 int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops); 511 512 /** 513 * Print fields in the metadata to the log. 514 * verbosity = 0: Only tag entry information 515 * verbosity = 1: Tag entry information plus at most 16 data values 516 * verbosity = 2: All information 517 */ 518 ANDROID_API 519 void dump_camera_metadata(const camera_metadata_t *metadata, 520 int fd, 521 int verbosity); 522 523 /** 524 * Print fields in the metadata to the log; adds indentation parameter, which 525 * specifies the number of spaces to insert before each line of the dump 526 */ 527 ANDROID_API 528 void dump_indented_camera_metadata(const camera_metadata_t *metadata, 529 int fd, 530 int verbosity, 531 int indentation); 532 533 /** 534 * Prints the specified tag value as a string. Only works for enum tags. 535 * Returns 0 on success, -1 on failure. 536 */ 537 ANDROID_API 538 int camera_metadata_enum_snprint(uint32_t tag, 539 uint32_t value, 540 char *dst, 541 size_t size); 542 543 #ifdef __cplusplus 544 } 545 #endif 546 547 #endif 548