pickle.h 14 KB

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