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