1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
13 #include "base/base_export.h"
14 #include "base/check_op.h"
15 #include "base/containers/span.h"
16 #include "base/gtest_prod_util.h"
17 #include "base/memory/raw_ptr_exclusion.h"
18 #include "base/memory/ref_counted.h"
19 #include "base/strings/string_piece.h"
20 #include "third_party/abseil-cpp/absl/types/optional.h"
26 // PickleIterator reads data from a Pickle. The Pickle object must remain valid
27 // while the PickleIterator object is in use.
28 class BASE_EXPORT PickleIterator {
30 PickleIterator() : payload_(nullptr), read_index_(0), end_index_(0) {}
31 explicit PickleIterator(const Pickle& pickle);
33 // Methods for reading the payload of the Pickle. To read from the start of
34 // the Pickle, create a PickleIterator from a Pickle. If successful, these
35 // methods return true. Otherwise, false is returned to indicate that the
36 // result could not be extracted. It is not possible to read from the iterator
38 [[nodiscard]] bool ReadBool(bool* result);
39 [[nodiscard]] bool ReadInt(int* result);
40 [[nodiscard]] bool ReadLong(long* result);
41 [[nodiscard]] bool ReadUInt16(uint16_t* result);
42 [[nodiscard]] bool ReadUInt32(uint32_t* result);
43 [[nodiscard]] bool ReadInt64(int64_t* result);
44 [[nodiscard]] bool ReadUInt64(uint64_t* result);
45 [[nodiscard]] bool ReadFloat(float* result);
46 [[nodiscard]] bool ReadDouble(double* result);
47 [[nodiscard]] bool ReadString(std::string* result);
48 // The StringPiece data will only be valid for the lifetime of the message.
49 [[nodiscard]] bool ReadStringPiece(StringPiece* result);
50 [[nodiscard]] bool ReadString16(std::u16string* result);
51 // The StringPiece16 data will only be valid for the lifetime of the message.
52 [[nodiscard]] bool ReadStringPiece16(StringPiece16* result);
54 // A pointer to the data will be placed in |*data|, and the length will be
55 // placed in |*length|. The pointer placed into |*data| points into the
56 // message's buffer so it will be scoped to the lifetime of the message (or
57 // until the message data is mutated). Do not keep the pointer around!
58 [[nodiscard]] bool ReadData(const char** data, size_t* length);
60 // Similar, but using base::span for convenience.
61 [[nodiscard]] absl::optional<base::span<const uint8_t>> ReadData();
63 // A pointer to the data will be placed in |*data|. The caller specifies the
64 // number of bytes to read, and ReadBytes will validate this length. The
65 // pointer placed into |*data| points into the message's buffer so it will be
66 // scoped to the lifetime of the message (or until the message data is
67 // mutated). Do not keep the pointer around!
68 [[nodiscard]] bool ReadBytes(const char** data, size_t length);
70 // A version of ReadInt() that checks for the result not being negative. Use
71 // it for reading the object sizes.
72 [[nodiscard]] bool ReadLength(size_t* result) {
74 if (!ReadInt(&result_int) || result_int < 0)
76 *result = static_cast<size_t>(result_int);
80 // Skips bytes in the read buffer and returns true if there are at least
81 // num_bytes available. Otherwise, does nothing and returns false.
82 [[nodiscard]] bool SkipBytes(size_t num_bytes) {
83 return !!GetReadPointerAndAdvance(num_bytes);
86 bool ReachedEnd() const { return read_index_ == end_index_; }
89 // Read Type from Pickle.
90 template <typename Type>
91 bool ReadBuiltinType(Type* result);
93 // Advance read_index_ but do not allow it to exceed end_index_.
94 // Keeps read_index_ aligned.
95 void Advance(size_t size);
97 // Get read pointer for Type and advance read pointer.
98 template<typename Type>
99 const char* GetReadPointerAndAdvance();
101 // Get read pointer for |num_bytes| and advance read pointer. This method
102 // checks num_bytes for wrapping.
103 const char* GetReadPointerAndAdvance(size_t num_bytes);
105 // Get read pointer for (num_elements * size_element) bytes and advance read
106 // pointer. This method checks for overflow and wrapping.
107 const char* GetReadPointerAndAdvance(size_t num_elements,
108 size_t size_element);
110 const char* payload_; // Start of our pickle's payload.
111 size_t read_index_; // Offset of the next readable byte in payload.
112 size_t end_index_; // Payload size.
114 FRIEND_TEST_ALL_PREFIXES(PickleTest, GetReadPointerAndAdvance);
117 // This class provides facilities for basic binary value packing and unpacking.
119 // The Pickle class supports appending primitive values (ints, strings, etc.)
120 // to a pickle instance. The Pickle instance grows its internal memory buffer
121 // dynamically to hold the sequence of primitive values. The internal memory
122 // buffer is exposed as the "data" of the Pickle. This "data" can be passed
123 // to a Pickle object to initialize it for reading.
125 // When reading from a Pickle object, it is important for the consumer to know
126 // what value types to read and in what order to read them as the Pickle does
127 // not keep track of the type of data written to it.
129 // The Pickle's data has a header which contains the size of the Pickle's
130 // payload. It can optionally support additional space in the header. That
131 // space is controlled by the header_size parameter passed to the Pickle
134 class BASE_EXPORT Pickle {
136 // Auxiliary data attached to a Pickle. Pickle must be subclassed along with
137 // this interface in order to provide a concrete implementation of support
138 // for attachments. The base Pickle implementation does not accept
140 class BASE_EXPORT Attachment : public RefCountedThreadSafe<Attachment> {
143 Attachment(const Attachment&) = delete;
144 Attachment& operator=(const Attachment&) = delete;
147 friend class RefCountedThreadSafe<Attachment>;
148 virtual ~Attachment();
151 // Initialize a Pickle object using the default header size.
154 // Initialize a Pickle object with the specified header size in bytes, which
155 // must be greater-than-or-equal-to sizeof(Pickle::Header). The header size
156 // will be rounded up to ensure that the header size is 32bit-aligned.
157 explicit Pickle(size_t header_size);
159 // Initializes a Pickle from a const block of data. The data is not copied;
160 // instead the data is merely referenced by this Pickle. Only const methods
161 // should be used on the Pickle when initialized this way. The header
162 // padding size is deduced from the data length.
163 explicit Pickle(span<const uint8_t> data);
164 // TODO(crbug.com/1490484): Migrate callers of this overload to the span
166 Pickle(const char* data, size_t data_len);
168 // Initializes a Pickle as a deep copy of another Pickle.
169 Pickle(const Pickle& other);
171 // Note: There are no virtual methods in this class. This destructor is
172 // virtual as an element of defensive coding. Other classes have derived from
173 // this class, and there is a *chance* that they will cast into this base
174 // class before destruction. At least one such class does have a virtual
175 // destructor, suggesting at least some need to call more derived destructors.
178 // Performs a deep copy.
179 Pickle& operator=(const Pickle& other);
181 // Returns the number of bytes written in the Pickle, including the header.
182 size_t size() const {
183 return header_ ? header_size_ + header_->payload_size : 0;
186 // Returns the data for this Pickle.
187 const uint8_t* data() const {
188 return reinterpret_cast<const uint8_t*>(header_);
191 // Handy method to simplify calling data() with a reinterpret_cast.
192 const char* data_as_char() const {
193 return reinterpret_cast<const char*>(data());
196 // Returns the effective memory capacity of this Pickle, that is, the total
197 // number of bytes currently dynamically allocated or 0 in the case of a
198 // read-only Pickle. This should be used only for diagnostic / profiling
200 size_t GetTotalAllocatedSize() const;
202 // Methods for adding to the payload of the Pickle. These values are
203 // appended to the end of the Pickle's payload. When reading values from a
204 // Pickle, it is important to read them in the order in which they were added
207 void WriteBool(bool value) { WriteInt(value ? 1 : 0); }
208 void WriteInt(int value) { WritePOD(value); }
209 void WriteLong(long value) {
210 // Always write long as a 64-bit value to ensure compatibility between
211 // 32-bit and 64-bit processes.
212 WritePOD(static_cast<int64_t>(value));
214 void WriteUInt16(uint16_t value) { WritePOD(value); }
215 void WriteUInt32(uint32_t value) { WritePOD(value); }
216 void WriteInt64(int64_t value) { WritePOD(value); }
217 void WriteUInt64(uint64_t value) { WritePOD(value); }
218 void WriteFloat(float value) { WritePOD(value); }
219 void WriteDouble(double value) { WritePOD(value); }
220 void WriteString(const StringPiece& value);
221 void WriteString16(const StringPiece16& value);
222 // "Data" is a blob with a length. When you read it out you will be given the
223 // length. See also WriteBytes.
224 void WriteData(const char* data, size_t length);
225 // "Bytes" is a blob with no length. The caller must specify the length both
226 // when reading and writing. It is normally used to serialize PoD types of a
227 // known size. See also WriteData.
228 void WriteBytes(const void* data, size_t length);
230 // WriteAttachment appends |attachment| to the pickle. It returns
231 // false iff the set is full or if the Pickle implementation does not support
233 virtual bool WriteAttachment(scoped_refptr<Attachment> attachment);
235 // ReadAttachment parses an attachment given the parsing state |iter| and
236 // writes it to |*attachment|. It returns true on success.
237 virtual bool ReadAttachment(base::PickleIterator* iter,
238 scoped_refptr<Attachment>* attachment) const;
240 // Indicates whether the pickle has any attachments.
241 virtual bool HasAttachments() const;
243 // Reserves space for upcoming writes when multiple writes will be made and
244 // their sizes are computed in advance. It can be significantly faster to call
245 // Reserve() before calling WriteFoo() multiple times.
246 void Reserve(size_t additional_capacity);
248 // Payload follows after allocation of Header (header size is customizable).
250 uint32_t payload_size; // Specifies the size of the payload.
253 // Returns the header, cast to a user-specified type T. The type T must be a
254 // subclass of Header and its size must correspond to the header_size passed
255 // to the Pickle constructor.
258 DCHECK_EQ(header_size_, sizeof(T));
259 return static_cast<T*>(header_);
262 const T* headerT() const {
263 DCHECK_EQ(header_size_, sizeof(T));
264 return static_cast<const T*>(header_);
267 // The payload is the pickle data immediately following the header.
268 size_t payload_size() const {
269 return header_ ? header_->payload_size : 0;
272 const char* payload() const {
273 return reinterpret_cast<const char*>(header_) + header_size_;
276 // Returns the address of the byte immediately following the currently valid
278 const char* end_of_payload() const {
279 // This object may be invalid.
280 return header_ ? payload() + payload_size() : NULL;
284 // Returns size of the header, which can have default value, set by user or
285 // calculated by passed raw data.
286 size_t header_size() const { return header_size_; }
288 char* mutable_payload() {
289 return reinterpret_cast<char*>(header_) + header_size_;
292 size_t capacity_after_header() const {
293 return capacity_after_header_;
296 // Resize the capacity, note that the input value should not include the size
298 void Resize(size_t new_capacity);
300 // Claims |num_bytes| bytes of payload. This is similar to Reserve() in that
301 // it may grow the capacity, but it also advances the write offset of the
302 // pickle by |num_bytes|. Claimed memory, including padding, is zeroed.
304 // Returns the address of the first byte claimed.
305 void* ClaimBytes(size_t num_bytes);
307 // Find the end of the pickled data that starts at range_start. Returns NULL
308 // if the entire Pickle is not found in the given data range.
309 static const char* FindNext(size_t header_size,
310 const char* range_start,
311 const char* range_end);
313 // Parse pickle header and return total size of the pickle. Data range
314 // doesn't need to contain entire pickle.
315 // Returns true if pickle header was found and parsed. Callers must check
316 // returned |pickle_size| for sanity (against maximum message size, etc).
317 // NOTE: when function successfully parses a header, but encounters an
318 // overflow during pickle size calculation, it sets |pickle_size| to the
319 // maximum size_t value and returns true.
320 static bool PeekNext(size_t header_size,
321 const char* range_start,
322 const char* range_end,
323 size_t* pickle_size);
325 // The allocation granularity of the payload.
326 static const size_t kPayloadUnit;
329 friend class PickleIterator;
331 // `header_` is not a raw_ptr<...> for performance reasons (based on analysis
332 // of sampling profiler data).
333 RAW_PTR_EXCLUSION Header* header_;
334 size_t header_size_; // Supports extra data between header and payload.
335 // Allocation size of payload (or -1 if allocation is const). Note: this
336 // doesn't count the header.
337 size_t capacity_after_header_;
338 // The offset at which we will write the next field. Note: this doesn't count
340 size_t write_offset_;
342 // Just like WriteBytes, but with a compile-time size, for performance.
343 template<size_t length> void BASE_EXPORT WriteBytesStatic(const void* data);
345 // Writes a POD by copying its bytes.
346 template <typename T> bool WritePOD(const T& data) {
347 WriteBytesStatic<sizeof(data)>(&data);
351 inline void* ClaimUninitializedBytesInternal(size_t num_bytes);
352 inline void WriteBytesCommon(const void* data, size_t length);
354 FRIEND_TEST_ALL_PREFIXES(PickleTest, DeepCopyResize);
355 FRIEND_TEST_ALL_PREFIXES(PickleTest, Resize);
356 FRIEND_TEST_ALL_PREFIXES(PickleTest, PeekNext);
357 FRIEND_TEST_ALL_PREFIXES(PickleTest, PeekNextOverflow);
358 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNext);
359 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextWithIncompleteHeader);
360 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextOverflow);
365 #endif // BASE_PICKLE_H_