Home | History | Annotate | Download | only in system
      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 
    157 /**
    158  * Allocate a new camera_metadata structure, with some initial space for entries
    159  * and extra data. The entry_capacity is measured in entry counts, and
    160  * data_capacity in bytes. The resulting structure is all contiguous in memory,
    161  * and can be freed with free_camera_metadata().
    162  */
    163 ANDROID_API
    164 camera_metadata_t *allocate_camera_metadata(size_t entry_capacity,
    165         size_t data_capacity);
    166 
    167 /**
    168  * Allocate a new camera_metadata structure of size src_size. Copy the data,
    169  * ignoring alignment, and then attempt validation. If validation
    170  * fails, free the memory and return NULL. Otherwise return the pointer.
    171  *
    172  * The resulting pointer can be freed with free_camera_metadata().
    173  */
    174 ANDROID_API
    175 camera_metadata_t *allocate_copy_camera_metadata_checked(
    176         const camera_metadata_t *src,
    177         size_t src_size);
    178 
    179 /**
    180  * Place a camera metadata structure into an existing buffer. Returns NULL if
    181  * the buffer is too small for the requested number of reserved entries and
    182  * bytes of data. The entry_capacity is measured in entry counts, and
    183  * data_capacity in bytes. If the buffer is larger than the required space,
    184  * unused space will be left at the end. If successful, returns a pointer to the
    185  * metadata header placed at the start of the buffer. It is the caller's
    186  * responsibility to free the original buffer; do not call
    187  * free_camera_metadata() with the returned pointer.
    188  */
    189 ANDROID_API
    190 camera_metadata_t *place_camera_metadata(void *dst, size_t dst_size,
    191         size_t entry_capacity,
    192         size_t data_capacity);
    193 
    194 /**
    195  * Free a camera_metadata structure. Should only be used with structures
    196  * allocated with allocate_camera_metadata().
    197  */
    198 ANDROID_API
    199 void free_camera_metadata(camera_metadata_t *metadata);
    200 
    201 /**
    202  * Calculate the buffer size needed for a metadata structure of entry_count
    203  * metadata entries, needing a total of data_count bytes of extra data storage.
    204  */
    205 ANDROID_API
    206 size_t calculate_camera_metadata_size(size_t entry_count,
    207         size_t data_count);
    208 
    209 /**
    210  * Get current size of entire metadata structure in bytes, including reserved
    211  * but unused space.
    212  */
    213 ANDROID_API
    214 size_t get_camera_metadata_size(const camera_metadata_t *metadata);
    215 
    216 /**
    217  * Get size of entire metadata buffer in bytes, not including reserved but
    218  * unused space. This is the amount of space needed by copy_camera_metadata for
    219  * its dst buffer.
    220  */
    221 ANDROID_API
    222 size_t get_camera_metadata_compact_size(const camera_metadata_t *metadata);
    223 
    224 /**
    225  * Get the current number of entries in the metadata packet.
    226  */
    227 ANDROID_API
    228 size_t get_camera_metadata_entry_count(const camera_metadata_t *metadata);
    229 
    230 /**
    231  * Get the maximum number of entries that could fit in the metadata packet.
    232  */
    233 ANDROID_API
    234 size_t get_camera_metadata_entry_capacity(const camera_metadata_t *metadata);
    235 
    236 /**
    237  * Get the current count of bytes used for value storage in the metadata packet.
    238  */
    239 ANDROID_API
    240 size_t get_camera_metadata_data_count(const camera_metadata_t *metadata);
    241 
    242 /**
    243  * Get the maximum count of bytes that could be used for value storage in the
    244  * metadata packet.
    245  */
    246 ANDROID_API
    247 size_t get_camera_metadata_data_capacity(const camera_metadata_t *metadata);
    248 
    249 /**
    250  * Copy a metadata structure to a memory buffer, compacting it along the
    251  * way. That is, in the copied structure, entry_count == entry_capacity, and
    252  * data_count == data_capacity.
    253  *
    254  * If dst_size > get_camera_metadata_compact_size(), the unused bytes are at the
    255  * end of the buffer. If dst_size < get_camera_metadata_compact_size(), returns
    256  * NULL. Otherwise returns a pointer to the metadata structure header placed at
    257  * the start of dst.
    258  *
    259  * Since the buffer was not allocated by allocate_camera_metadata, the caller is
    260  * responsible for freeing the underlying buffer when needed; do not call
    261  * free_camera_metadata.
    262  */
    263 ANDROID_API
    264 camera_metadata_t *copy_camera_metadata(void *dst, size_t dst_size,
    265         const camera_metadata_t *src);
    266 
    267 /**
    268  * Validate that a metadata is structurally sane. That is, its internal
    269  * state is such that we won't get buffer overflows or run into other
    270  * 'impossible' issues when calling the other API functions.
    271  *
    272  * This is useful in particular after copying the binary metadata blob
    273  * from an untrusted source, since passing this check means the data is at least
    274  * consistent.
    275  *
    276  * The expected_size argument is optional.
    277  *
    278  * Returns 0 on success. A non-0 value is returned on error.
    279  */
    280 ANDROID_API
    281 int validate_camera_metadata_structure(const camera_metadata_t *metadata,
    282                                        const size_t *expected_size);
    283 
    284 /**
    285  * Append camera metadata in src to an existing metadata structure in dst.  This
    286  * does not resize the destination structure, so if it is too small, a non-zero
    287  * value is returned. On success, 0 is returned. Appending onto a sorted
    288  * structure results in a non-sorted combined structure.
    289  */
    290 ANDROID_API
    291 int append_camera_metadata(camera_metadata_t *dst, const camera_metadata_t *src);
    292 
    293 /**
    294  * Clone an existing metadata buffer, compacting along the way. This is
    295  * equivalent to allocating a new buffer of the minimum needed size, then
    296  * appending the buffer to be cloned into the new buffer. The resulting buffer
    297  * can be freed with free_camera_metadata(). Returns NULL if cloning failed.
    298  */
    299 ANDROID_API
    300 camera_metadata_t *clone_camera_metadata(const camera_metadata_t *src);
    301 
    302 /**
    303  * Calculate the number of bytes of extra data a given metadata entry will take
    304  * up. That is, if entry of 'type' with a payload of 'data_count' values is
    305  * added, how much will the value returned by get_camera_metadata_data_count()
    306  * be increased? This value may be zero, if no extra data storage is needed.
    307  */
    308 ANDROID_API
    309 size_t calculate_camera_metadata_entry_data_size(uint8_t type,
    310         size_t data_count);
    311 
    312 /**
    313  * Add a metadata entry to a metadata structure. Returns 0 if the addition
    314  * succeeded. Returns a non-zero value if there is insufficient reserved space
    315  * left to add the entry, or if the tag is unknown.  data_count is the number of
    316  * entries in the data array of the tag's type, not a count of
    317  * bytes. Vendor-defined tags can not be added using this method, unless
    318  * set_vendor_tag_query_ops() has been called first. Entries are always added to
    319  * the end of the structure (highest index), so after addition, a
    320  * previously-sorted array will be marked as unsorted.
    321  */
    322 ANDROID_API
    323 int add_camera_metadata_entry(camera_metadata_t *dst,
    324         uint32_t tag,
    325         const void *data,
    326         size_t data_count);
    327 
    328 /**
    329  * Sort the metadata buffer for fast searching. If already marked as sorted,
    330  * does nothing. Adding or appending entries to the buffer will place the buffer
    331  * back into an unsorted state.
    332  */
    333 ANDROID_API
    334 int sort_camera_metadata(camera_metadata_t *dst);
    335 
    336 /**
    337  * Get metadata entry at position index in the metadata buffer.
    338  *
    339  * src and index are inputs; the passed-in entry is updated with the details of
    340  * the entry. The data pointer points to the real data in the buffer, and can be
    341  * updated as long as the data count does not change.
    342  */
    343 ANDROID_API
    344 int get_camera_metadata_entry(camera_metadata_t *src,
    345         size_t index,
    346         camera_metadata_entry_t *entry);
    347 
    348 /**
    349  * Find an entry with given tag value. If not found, returns -ENOENT. Otherwise,
    350  * returns entry contents like get_camera_metadata_entry.
    351  *
    352  * If multiple entries with the same tag exist, does not have any guarantees on
    353  * which is returned. To speed up searching for tags, sort the metadata
    354  * structure first by calling sort_camera_metadata().
    355  */
    356 ANDROID_API
    357 int find_camera_metadata_entry(camera_metadata_t *src,
    358         uint32_t tag,
    359         camera_metadata_entry_t *entry);
    360 
    361 /**
    362  * Find an entry with given tag value, but disallow editing the data
    363  */
    364 ANDROID_API
    365 int find_camera_metadata_ro_entry(const camera_metadata_t *src,
    366         uint32_t tag,
    367         camera_metadata_ro_entry_t *entry);
    368 
    369 /**
    370  * Delete an entry at given index. This is an expensive operation, since it
    371  * requires repacking entries and possibly entry data. This also invalidates any
    372  * existing camera_metadata_entry.data pointers to this buffer. Sorting is
    373  * maintained.
    374  */
    375 ANDROID_API
    376 int delete_camera_metadata_entry(camera_metadata_t *dst,
    377         size_t index);
    378 
    379 /**
    380  * Updates a metadata entry with new data. If the data size is changing, may
    381  * need to adjust the data array, making this an O(N) operation. If the data
    382  * size is the same or still fits in the entry space, this is O(1). Maintains
    383  * sorting, but invalidates camera_metadata_entry instances that point to the
    384  * updated entry. If a non-NULL value is passed in to entry, the entry structure
    385  * is updated to match the new buffer state.  Returns a non-zero value if there
    386  * is no room for the new data in the buffer.
    387  */
    388 ANDROID_API
    389 int update_camera_metadata_entry(camera_metadata_t *dst,
    390         size_t index,
    391         const void *data,
    392         size_t data_count,
    393         camera_metadata_entry_t *updated_entry);
    394 
    395 /**
    396  * Set user pointer in buffer. This can be used for linking the metadata buffer
    397  * with other associated data. This user pointer is not copied with
    398  * copy_camera_metadata, and is unaffected by append or any other methods.
    399  */
    400 ANDROID_API
    401 int set_camera_metadata_user_pointer(camera_metadata_t *dst, void* user);
    402 
    403 /**
    404  * Retrieve user pointer in buffer. Returns NULL in user if
    405  * set_camera_metadata_user_pointer has not been called with this buffer.
    406  */
    407 ANDROID_API
    408 int get_camera_metadata_user_pointer(camera_metadata_t *dst, void** user);
    409 
    410 /**
    411  * Retrieve human-readable name of section the tag is in. Returns NULL if
    412  * no such tag is defined. Returns NULL for tags in the vendor section, unless
    413  * set_vendor_tag_query_ops() has been used.
    414  */
    415 ANDROID_API
    416 const char *get_camera_metadata_section_name(uint32_t tag);
    417 
    418 /**
    419  * Retrieve human-readable name of tag (not including section). Returns NULL if
    420  * no such tag is defined. Returns NULL for tags in the vendor section, unless
    421  * set_vendor_tag_query_ops() has been used.
    422  */
    423 ANDROID_API
    424 const char *get_camera_metadata_tag_name(uint32_t tag);
    425 
    426 /**
    427  * Retrieve the type of a tag. Returns -1 if no such tag is defined. Returns -1
    428  * for tags in the vendor section, unless set_vendor_tag_query_ops() has been
    429  * used.
    430  */
    431 ANDROID_API
    432 int get_camera_metadata_tag_type(uint32_t tag);
    433 
    434 /**
    435  * Set up vendor-specific tag query methods. These are needed to properly add
    436  * entries with vendor-specified tags and to use the
    437  * get_camera_metadata_section_name, _tag_name, and _tag_type methods with
    438  * vendor tags. Returns 0 on success.
    439  */
    440 typedef struct vendor_tag_query_ops vendor_tag_query_ops_t;
    441 struct vendor_tag_query_ops {
    442     /**
    443      * Get vendor section name for a vendor-specified entry tag. Only called for
    444      * tags >= 0x80000000. The section name must start with the name of the
    445      * vendor in the Java package style. For example, CameraZoom inc must prefix
    446      * their sections with "com.camerazoom." Must return NULL if the tag is
    447      * outside the bounds of vendor-defined sections.
    448      */
    449     const char *(*get_camera_vendor_section_name)(
    450         const vendor_tag_query_ops_t *v,
    451         uint32_t tag);
    452     /**
    453      * Get tag name for a vendor-specified entry tag. Only called for tags >=
    454      * 0x80000000. Must return NULL if the tag is outside the bounds of
    455      * vendor-defined sections.
    456      */
    457     const char *(*get_camera_vendor_tag_name)(
    458         const vendor_tag_query_ops_t *v,
    459         uint32_t tag);
    460     /**
    461      * Get tag type for a vendor-specified entry tag. Only called for tags >=
    462      * 0x80000000. Must return -1 if the tag is outside the bounds of
    463      * vendor-defined sections.
    464      */
    465     int (*get_camera_vendor_tag_type)(
    466         const vendor_tag_query_ops_t *v,
    467         uint32_t tag);
    468     /**
    469      * Get the number of vendor tags supported on this platform. Used to
    470      * calculate the size of buffer needed for holding the array of all tags
    471      * returned by get_camera_vendor_tags().
    472      */
    473     int (*get_camera_vendor_tag_count)(
    474         const vendor_tag_query_ops_t *v);
    475     /**
    476      * Fill an array with all the supported vendor tags on this platform.
    477      * get_camera_vendor_tag_count() returns the number of tags supported, and
    478      * tag_array should be allocated with enough space to hold all of the tags.
    479      */
    480     void (*get_camera_vendor_tags)(
    481         const vendor_tag_query_ops_t *v,
    482         uint32_t *tag_array);
    483 };
    484 
    485 ANDROID_API
    486 int set_camera_metadata_vendor_tag_ops(const vendor_tag_query_ops_t *query_ops);
    487 
    488 /**
    489  * Print fields in the metadata to the log.
    490  * verbosity = 0: Only tag entry information
    491  * verbosity = 1: Tag entry information plus at most 16 data values
    492  * verbosity = 2: All information
    493  */
    494 ANDROID_API
    495 void dump_camera_metadata(const camera_metadata_t *metadata,
    496         int fd,
    497         int verbosity);
    498 
    499 /**
    500  * Print fields in the metadata to the log; adds indentation parameter, which
    501  * specifies the number of spaces to insert before each line of the dump
    502  */
    503 ANDROID_API
    504 void dump_indented_camera_metadata(const camera_metadata_t *metadata,
    505         int fd,
    506         int verbosity,
    507         int indentation);
    508 
    509 /**
    510  * Prints the specified tag value as a string. Only works for enum tags.
    511  * Returns 0 on success, -1 on failure.
    512  */
    513 ANDROID_API
    514 int camera_metadata_enum_snprint(uint32_t tag,
    515                                  uint32_t value,
    516                                  char *dst,
    517                                  size_t size);
    518 
    519 #ifdef __cplusplus
    520 }
    521 #endif
    522 
    523 #endif
    524