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 5#ifndef BASE_PICKLE_H__ 6#define BASE_PICKLE_H__ 7 8#include <string> 9 10#include "base/base_export.h" 11#include "base/basictypes.h" 12#include "base/compiler_specific.h" 13#include "base/gtest_prod_util.h" 14#include "base/logging.h" 15#include "base/strings/string16.h" 16 17class Pickle; 18 19// PickleIterator reads data from a Pickle. The Pickle object must remain valid 20// while the PickleIterator object is in use. 21class BASE_EXPORT PickleIterator { 22 public: 23 PickleIterator() : payload_(NULL), read_index_(0), end_index_(0) {} 24 explicit PickleIterator(const Pickle& pickle); 25 26 // Methods for reading the payload of the Pickle. To read from the start of 27 // the Pickle, create a PickleIterator from a Pickle. If successful, these 28 // methods return true. Otherwise, false is returned to indicate that the 29 // result could not be extracted. It is not possible to read from iterator 30 // after that. 31 bool ReadBool(bool* result) WARN_UNUSED_RESULT; 32 bool ReadInt(int* result) WARN_UNUSED_RESULT; 33 bool ReadLong(long* result) WARN_UNUSED_RESULT; 34 bool ReadUInt16(uint16* result) WARN_UNUSED_RESULT; 35 bool ReadUInt32(uint32* result) WARN_UNUSED_RESULT; 36 bool ReadInt64(int64* result) WARN_UNUSED_RESULT; 37 bool ReadUInt64(uint64* result) WARN_UNUSED_RESULT; 38 bool ReadFloat(float* result) WARN_UNUSED_RESULT; 39 bool ReadString(std::string* result) WARN_UNUSED_RESULT; 40 bool ReadWString(std::wstring* result) WARN_UNUSED_RESULT; 41 bool ReadString16(base::string16* result) WARN_UNUSED_RESULT; 42 bool ReadData(const char** data, int* length) WARN_UNUSED_RESULT; 43 bool ReadBytes(const char** data, int length) WARN_UNUSED_RESULT; 44 45 // Safer version of ReadInt() checks for the result not being negative. 46 // Use it for reading the object sizes. 47 bool ReadLength(int* result) WARN_UNUSED_RESULT { 48 return ReadInt(result) && *result >= 0; 49 } 50 51 // Skips bytes in the read buffer and returns true if there are at least 52 // num_bytes available. Otherwise, does nothing and returns false. 53 bool SkipBytes(int num_bytes) WARN_UNUSED_RESULT { 54 return !!GetReadPointerAndAdvance(num_bytes); 55 } 56 57 private: 58 // Aligns 'i' by rounding it up to the next multiple of 'alignment' 59 static size_t AlignInt(size_t i, int alignment) { 60 return i + (alignment - (i % alignment)) % alignment; 61 } 62 63 // Read Type from Pickle. 64 template <typename Type> 65 bool ReadBuiltinType(Type* result); 66 67 // Advance read_index_ but do not allow it to exceed end_index_. 68 // Keeps read_index_ aligned. 69 void Advance(size_t size); 70 71 // Get read pointer for Type and advance read pointer. 72 template<typename Type> 73 const char* GetReadPointerAndAdvance(); 74 75 // Get read pointer for |num_bytes| and advance read pointer. This method 76 // checks num_bytes for negativity and wrapping. 77 const char* GetReadPointerAndAdvance(int num_bytes); 78 79 // Get read pointer for (num_elements * size_element) bytes and advance read 80 // pointer. This method checks for int overflow, negativity and wrapping. 81 const char* GetReadPointerAndAdvance(int num_elements, 82 size_t size_element); 83 84 const char* payload_; // Start of our pickle's payload. 85 size_t read_index_; // Offset of the next readable byte in payload. 86 size_t end_index_; // Payload size. 87 88 FRIEND_TEST_ALL_PREFIXES(PickleTest, GetReadPointerAndAdvance); 89}; 90 91// This class provides facilities for basic binary value packing and unpacking. 92// 93// The Pickle class supports appending primitive values (ints, strings, etc.) 94// to a pickle instance. The Pickle instance grows its internal memory buffer 95// dynamically to hold the sequence of primitive values. The internal memory 96// buffer is exposed as the "data" of the Pickle. This "data" can be passed 97// to a Pickle object to initialize it for reading. 98// 99// When reading from a Pickle object, it is important for the consumer to know 100// what value types to read and in what order to read them as the Pickle does 101// not keep track of the type of data written to it. 102// 103// The Pickle's data has a header which contains the size of the Pickle's 104// payload. It can optionally support additional space in the header. That 105// space is controlled by the header_size parameter passed to the Pickle 106// constructor. 107// 108class BASE_EXPORT Pickle { 109 public: 110 // Initialize a Pickle object using the default header size. 111 Pickle(); 112 113 // Initialize a Pickle object with the specified header size in bytes, which 114 // must be greater-than-or-equal-to sizeof(Pickle::Header). The header size 115 // will be rounded up to ensure that the header size is 32bit-aligned. 116 explicit Pickle(int header_size); 117 118 // Initializes a Pickle from a const block of data. The data is not copied; 119 // instead the data is merely referenced by this Pickle. Only const methods 120 // should be used on the Pickle when initialized this way. The header 121 // padding size is deduced from the data length. 122 Pickle(const char* data, int data_len); 123 124 // Initializes a Pickle as a deep copy of another Pickle. 125 Pickle(const Pickle& other); 126 127 // Note: There are no virtual methods in this class. This destructor is 128 // virtual as an element of defensive coding. Other classes have derived from 129 // this class, and there is a *chance* that they will cast into this base 130 // class before destruction. At least one such class does have a virtual 131 // destructor, suggesting at least some need to call more derived destructors. 132 virtual ~Pickle(); 133 134 // Performs a deep copy. 135 Pickle& operator=(const Pickle& other); 136 137 // Returns the size of the Pickle's data. 138 size_t size() const { return header_size_ + header_->payload_size; } 139 140 // Returns the data for this Pickle. 141 const void* data() const { return header_; } 142 143 // For compatibility, these older style read methods pass through to the 144 // PickleIterator methods. 145 // TODO(jbates) Remove these methods. 146 bool ReadBool(PickleIterator* iter, 147 bool* result) const WARN_UNUSED_RESULT { 148 return iter->ReadBool(result); 149 } 150 bool ReadInt(PickleIterator* iter, 151 int* result) const WARN_UNUSED_RESULT { 152 return iter->ReadInt(result); 153 } 154 bool ReadLong(PickleIterator* iter, 155 long* result) const WARN_UNUSED_RESULT { 156 return iter->ReadLong(result); 157 } 158 bool ReadUInt16(PickleIterator* iter, 159 uint16* result) const WARN_UNUSED_RESULT { 160 return iter->ReadUInt16(result); 161 } 162 bool ReadUInt32(PickleIterator* iter, 163 uint32* result) const WARN_UNUSED_RESULT { 164 return iter->ReadUInt32(result); 165 } 166 bool ReadInt64(PickleIterator* iter, 167 int64* result) const WARN_UNUSED_RESULT { 168 return iter->ReadInt64(result); 169 } 170 bool ReadUInt64(PickleIterator* iter, 171 uint64* result) const WARN_UNUSED_RESULT { 172 return iter->ReadUInt64(result); 173 } 174 bool ReadFloat(PickleIterator* iter, 175 float* result) const WARN_UNUSED_RESULT { 176 return iter->ReadFloat(result); 177 } 178 bool ReadString(PickleIterator* iter, 179 std::string* result) const WARN_UNUSED_RESULT { 180 return iter->ReadString(result); 181 } 182 bool ReadWString(PickleIterator* iter, 183 std::wstring* result) const WARN_UNUSED_RESULT { 184 return iter->ReadWString(result); 185 } 186 bool ReadString16(PickleIterator* iter, 187 base::string16* result) const WARN_UNUSED_RESULT { 188 return iter->ReadString16(result); 189 } 190 // A pointer to the data will be placed in *data, and the length will be 191 // placed in *length. This buffer will be into the message's buffer so will 192 // be scoped to the lifetime of the message (or until the message data is 193 // mutated). 194 bool ReadData(PickleIterator* iter, 195 const char** data, 196 int* length) const WARN_UNUSED_RESULT { 197 return iter->ReadData(data, length); 198 } 199 // A pointer to the data will be placed in *data. The caller specifies the 200 // number of bytes to read, and ReadBytes will validate this length. The 201 // returned buffer will be into the message's buffer so will be scoped to the 202 // lifetime of the message (or until the message data is mutated). 203 bool ReadBytes(PickleIterator* iter, 204 const char** data, 205 int length) const WARN_UNUSED_RESULT { 206 return iter->ReadBytes(data, length); 207 } 208 209 // Safer version of ReadInt() checks for the result not being negative. 210 // Use it for reading the object sizes. 211 bool ReadLength(PickleIterator* iter, 212 int* result) const WARN_UNUSED_RESULT { 213 return iter->ReadLength(result); 214 } 215 216 // Methods for adding to the payload of the Pickle. These values are 217 // appended to the end of the Pickle's payload. When reading values from a 218 // Pickle, it is important to read them in the order in which they were added 219 // to the Pickle. 220 bool WriteBool(bool value) { 221 return WriteInt(value ? 1 : 0); 222 } 223 bool WriteInt(int value) { 224 return WritePOD(value); 225 } 226 // WARNING: DO NOT USE THIS METHOD IF PICKLES ARE PERSISTED IN ANY WAY. 227 // It will write whatever a "long" is on this architecture. On 32-bit 228 // platforms, it is 32 bits. On 64-bit platforms, it is 64 bits. If persisted 229 // pickles are still around after upgrading to 64-bit, or if they are copied 230 // between dissimilar systems, YOUR PICKLES WILL HAVE GONE BAD. 231 bool WriteLongUsingDangerousNonPortableLessPersistableForm(long value) { 232 return WritePOD(value); 233 } 234 bool WriteUInt16(uint16 value) { 235 return WritePOD(value); 236 } 237 bool WriteUInt32(uint32 value) { 238 return WritePOD(value); 239 } 240 bool WriteInt64(int64 value) { 241 return WritePOD(value); 242 } 243 bool WriteUInt64(uint64 value) { 244 return WritePOD(value); 245 } 246 bool WriteFloat(float value) { 247 return WritePOD(value); 248 } 249 bool WriteString(const std::string& value); 250 bool WriteWString(const std::wstring& value); 251 bool WriteString16(const base::string16& value); 252 // "Data" is a blob with a length. When you read it out you will be given the 253 // length. See also WriteBytes. 254 bool WriteData(const char* data, int length); 255 // "Bytes" is a blob with no length. The caller must specify the length both 256 // when reading and writing. It is normally used to serialize PoD types of a 257 // known size. See also WriteData. 258 bool WriteBytes(const void* data, int length); 259 260 // Reserves space for upcoming writes when multiple writes will be made and 261 // their sizes are computed in advance. It can be significantly faster to call 262 // Reserve() before calling WriteFoo() multiple times. 263 void Reserve(size_t additional_capacity); 264 265 // Payload follows after allocation of Header (header size is customizable). 266 struct Header { 267 uint32 payload_size; // Specifies the size of the payload. 268 }; 269 270 // Returns the header, cast to a user-specified type T. The type T must be a 271 // subclass of Header and its size must correspond to the header_size passed 272 // to the Pickle constructor. 273 template <class T> 274 T* headerT() { 275 DCHECK_EQ(header_size_, sizeof(T)); 276 return static_cast<T*>(header_); 277 } 278 template <class T> 279 const T* headerT() const { 280 DCHECK_EQ(header_size_, sizeof(T)); 281 return static_cast<const T*>(header_); 282 } 283 284 // The payload is the pickle data immediately following the header. 285 size_t payload_size() const { 286 return header_ ? header_->payload_size : 0; 287 } 288 289 const char* payload() const { 290 return reinterpret_cast<const char*>(header_) + header_size_; 291 } 292 293 // Returns the address of the byte immediately following the currently valid 294 // header + payload. 295 const char* end_of_payload() const { 296 // This object may be invalid. 297 return header_ ? payload() + payload_size() : NULL; 298 } 299 300 protected: 301 char* mutable_payload() { 302 return reinterpret_cast<char*>(header_) + header_size_; 303 } 304 305 size_t capacity_after_header() const { 306 return capacity_after_header_; 307 } 308 309 // Resize the capacity, note that the input value should not include the size 310 // of the header. 311 void Resize(size_t new_capacity); 312 313 // Aligns 'i' by rounding it up to the next multiple of 'alignment' 314 static size_t AlignInt(size_t i, int alignment) { 315 return i + (alignment - (i % alignment)) % alignment; 316 } 317 318 // Find the end of the pickled data that starts at range_start. Returns NULL 319 // if the entire Pickle is not found in the given data range. 320 static const char* FindNext(size_t header_size, 321 const char* range_start, 322 const char* range_end); 323 324 // The allocation granularity of the payload. 325 static const int kPayloadUnit; 326 327 private: 328 friend class PickleIterator; 329 330 Header* header_; 331 size_t header_size_; // Supports extra data between header and payload. 332 // Allocation size of payload (or -1 if allocation is const). Note: this 333 // doesn't count the header. 334 size_t capacity_after_header_; 335 // The offset at which we will write the next field. Note: this doesn't count 336 // the header. 337 size_t write_offset_; 338 339 // Just like WriteBytes, but with a compile-time size, for performance. 340 template<size_t length> void BASE_EXPORT WriteBytesStatic(const void* data); 341 342 // Writes a POD by copying its bytes. 343 template <typename T> bool WritePOD(const T& data) { 344 WriteBytesStatic<sizeof(data)>(&data); 345 return true; 346 } 347 inline void WriteBytesCommon(const void* data, size_t length); 348 349 FRIEND_TEST_ALL_PREFIXES(PickleTest, Resize); 350 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNext); 351 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextWithIncompleteHeader); 352 FRIEND_TEST_ALL_PREFIXES(PickleTest, FindNextOverflow); 353}; 354 355#endif // BASE_PICKLE_H__ 356