1 /*
2  * Copyright (C) 2016 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 CAMERA_COMMON_1_0_CAMERAMETADATA_H
18 #define CAMERA_COMMON_1_0_CAMERAMETADATA_H
19 
20 #include "system/camera_metadata.h"
21 
22 #include <utils/String8.h>
23 #include <utils/Vector.h>
24 
25 namespace android {
26 namespace hardware {
27 namespace camera {
28 namespace common {
29 namespace V1_0 {
30 namespace helper {
31 
32 class VendorTagDescriptor;
33 
34 /**
35  * A convenience wrapper around the C-based camera_metadata_t library.
36  */
37 class CameraMetadata {
38   public:
39     /** Creates an empty object; best used when expecting to acquire contents
40      * from elsewhere */
41     CameraMetadata();
42     /** Creates an object with space for entryCapacity entries, with
43      * dataCapacity extra storage */
44     CameraMetadata(size_t entryCapacity, size_t dataCapacity = 10);
45 
46     ~CameraMetadata();
47 
48     /** Takes ownership of passed-in buffer */
49     CameraMetadata(camera_metadata_t *buffer);
50     /** Clones the metadata */
51     CameraMetadata(const CameraMetadata &other);
52 
53     /**
54      * Assignment clones metadata buffer.
55      */
56     CameraMetadata &operator=(const CameraMetadata &other);
57     CameraMetadata &operator=(const camera_metadata_t *buffer);
58 
59     /**
60      * Get reference to the underlying metadata buffer. Ownership remains with
61      * the CameraMetadata object, but non-const CameraMetadata methods will not
62      * work until unlock() is called. Note that the lock has nothing to do with
63      * thread-safety, it simply prevents the camera_metadata_t pointer returned
64      * here from being accidentally invalidated by CameraMetadata operations.
65      */
66     const camera_metadata_t* getAndLock() const;
67 
68     /**
69      * Unlock the CameraMetadata for use again. After this unlock, the pointer
70      * given from getAndLock() may no longer be used. The pointer passed out
71      * from getAndLock must be provided to guarantee that the right object is
72      * being unlocked.
73      */
74     status_t unlock(const camera_metadata_t *buffer) const;
75 
76     /**
77      * Release a raw metadata buffer to the caller. After this call,
78      * CameraMetadata no longer references the buffer, and the caller takes
79      * responsibility for freeing the raw metadata buffer (using
80      * free_camera_metadata()), or for handing it to another CameraMetadata
81      * instance.
82      */
83     camera_metadata_t* release();
84 
85     /**
86      * Clear the metadata buffer and free all storage used by it
87      */
88     void clear();
89 
90     /**
91      * Acquire a raw metadata buffer from the caller. After this call,
92      * the caller no longer owns the raw buffer, and must not free or manipulate it.
93      * If CameraMetadata already contains metadata, it is freed.
94      */
95     void acquire(camera_metadata_t* buffer);
96 
97     /**
98      * Acquires raw buffer from other CameraMetadata object. After the call, the argument
99      * object no longer has any metadata.
100      */
101     void acquire(CameraMetadata &other);
102 
103     /**
104      * Append metadata from another CameraMetadata object.
105      */
106     status_t append(const CameraMetadata &other);
107 
108     /**
109      * Append metadata from a raw camera_metadata buffer
110      */
111     status_t append(const camera_metadata* other);
112 
113     /**
114      * Number of metadata entries.
115      */
116     size_t entryCount() const;
117 
118     /**
119      * Is the buffer empty (no entires)
120      */
121     bool isEmpty() const;
122 
123     /**
124      * Sort metadata buffer for faster find
125      */
126     status_t sort();
127 
128     /**
129      * Update metadata entry. Will create entry if it doesn't exist already, and
130      * will reallocate the buffer if insufficient space exists. Overloaded for
131      * the various types of valid data.
132      */
133     status_t update(uint32_t tag,
134             const uint8_t *data, size_t data_count);
135     status_t update(uint32_t tag,
136             const int32_t *data, size_t data_count);
137     status_t update(uint32_t tag,
138             const float *data, size_t data_count);
139     status_t update(uint32_t tag,
140             const int64_t *data, size_t data_count);
141     status_t update(uint32_t tag,
142             const double *data, size_t data_count);
143     status_t update(uint32_t tag,
144             const camera_metadata_rational_t *data, size_t data_count);
145     status_t update(uint32_t tag,
146             const String8 &string);
147     status_t update(const camera_metadata_ro_entry &entry);
148 
149 
150     template<typename T>
update(uint32_t tag,Vector<T> data)151     status_t update(uint32_t tag, Vector<T> data) {
152         return update(tag, data.array(), data.size());
153     }
154 
155     /**
156      * Check if a metadata entry exists for a given tag id
157      *
158      */
159     bool exists(uint32_t tag) const;
160 
161     /**
162      * Get metadata entry by tag id
163      */
164     camera_metadata_entry find(uint32_t tag);
165 
166     /**
167      * Get metadata entry by tag id, with no editing
168      */
169     camera_metadata_ro_entry find(uint32_t tag) const;
170 
171     /**
172      * Delete metadata entry by tag
173      */
174     status_t erase(uint32_t tag);
175 
176     /**
177      * Swap the underlying camera metadata between this and the other
178      * metadata object.
179      */
180     void swap(CameraMetadata &other);
181 
182     /**
183      * Dump contents into FD for debugging. The verbosity levels are
184      * 0: Tag entry information only, no data values
185      * 1: Level 0 plus at most 16 data values per entry
186      * 2: All information
187      *
188      * The indentation parameter sets the number of spaces to add to the start
189      * each line of output.
190      */
191     void dump(int fd, int verbosity = 1, int indentation = 0) const;
192 
193     /**
194      * Find tag id for a given tag name, also checking vendor tags if available.
195      * On success, returns OK and writes the tag id into tag.
196      *
197      * This is a slow method.
198      */
199     static status_t getTagFromName(const char *name,
200             const VendorTagDescriptor* vTags, uint32_t *tag);
201 
202   private:
203     camera_metadata_t *mBuffer;
204     mutable bool       mLocked;
205 
206     /**
207      * Check if tag has a given type
208      */
209     status_t checkType(uint32_t tag, uint8_t expectedType);
210 
211     /**
212      * Base update entry method
213      */
214     status_t updateImpl(uint32_t tag, const void *data, size_t data_count);
215 
216     /**
217      * Resize metadata buffer if needed by reallocating it and copying it over.
218      */
219     status_t resizeIfNeeded(size_t extraEntries, size_t extraData);
220 
221 };
222 
223 } // namespace helper
224 } // namespace V1_0
225 } // namespace common
226 } // namespace camera
227 } // namespace hardware
228 } // namespace android
229 
230 #endif
231