1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9// * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11// * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15// * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31// Authors: [email protected] (Wink Saville),
32// [email protected] (Kenton Varda)
33// Based on original Protocol Buffers design by
34// Sanjay Ghemawat, Jeff Dean, and others.
35//
36// Defines MessageLite, the abstract interface implemented by all (lite
37// and non-lite) protocol message objects.
38
39#ifndef GOOGLE_PROTOBUF_MESSAGE_LITE_H__
40#define GOOGLE_PROTOBUF_MESSAGE_LITE_H__
41
42#include <climits>
43#include <string>
44
45#include <google/protobuf/stubs/common.h>
46#include <google/protobuf/stubs/logging.h>
47#include <google/protobuf/arena.h>
48#include <google/protobuf/stubs/once.h>
49#include <google/protobuf/port.h>
50#include <google/protobuf/stubs/strutil.h>
51
52
53#include <google/protobuf/port_def.inc>
54
55#ifdef SWIG
56#error "You cannot SWIG proto headers"
57#endif
58
59namespace google {
60namespace protobuf {
61
62template <typename T>
63class RepeatedPtrField;
64
65namespace io {
66
67class CodedInputStream;
68class CodedOutputStream;
69class ZeroCopyInputStream;
70class ZeroCopyOutputStream;
71
72} // namespace io
73namespace internal {
74
75// See parse_context.h for explanation
76class ParseContext;
77
78class RepeatedPtrFieldBase;
79class WireFormatLite;
80class WeakFieldMap;
81
82// We compute sizes as size_t but cache them as int. This function converts a
83// computed size to a cached size. Since we don't proceed with serialization
84// if the total size was > INT_MAX, it is not important what this function
85// returns for inputs > INT_MAX. However this case should not error or
86// GOOGLE_CHECK-fail, because the full size_t resolution is still returned from
87// ByteSizeLong() and checked against INT_MAX; we can catch the overflow
88// there.
89inline int ToCachedSize(size_t size) { return static_cast<int>(size); }
90
91// We mainly calculate sizes in terms of size_t, but some functions that
92// compute sizes return "int". These int sizes are expected to always be
93// positive. This function is more efficient than casting an int to size_t
94// directly on 64-bit platforms because it avoids making the compiler emit a
95// sign extending instruction, which we don't want and don't want to pay for.
96inline size_t FromIntSize(int size) {
97 // Convert to unsigned before widening so sign extension is not necessary.
98 return static_cast<unsigned int>(size);
99}
100
101// For cases where a legacy function returns an integer size. We GOOGLE_DCHECK()
102// that the conversion will fit within an integer; if this is false then we
103// are losing information.
104inline int ToIntSize(size_t size) {
105 GOOGLE_DCHECK_LE(size, static_cast<size_t>(INT_MAX));
106 return static_cast<int>(size);
107}
108
109// This type wraps a variable whose constructor and destructor are explicitly
110// called. It is particularly useful for a global variable, without its
111// constructor and destructor run on start and end of the program lifetime.
112// This circumvents the initial construction order fiasco, while keeping
113// the address of the empty string a compile time constant.
114//
115// Pay special attention to the initialization state of the object.
116// 1. The object is "uninitialized" to begin with.
117// 2. Call Construct() or DefaultConstruct() only if the object is
118// uninitialized. After the call, the object becomes "initialized".
119// 3. Call get() and get_mutable() only if the object is initialized.
120// 4. Call Destruct() only if the object is initialized.
121// After the call, the object becomes uninitialized.
122template <typename T>
123class ExplicitlyConstructed {
124 public:
125 void DefaultConstruct() { new (&union_) T(); }
126
127 template <typename... Args>
128 void Construct(Args&&... args) {
129 new (&union_) T(std::forward<Args>(args)...);
130 }
131
132 void Destruct() { get_mutable()->~T(); }
133
134 constexpr const T& get() const { return reinterpret_cast<const T&>(union_); }
135 T* get_mutable() { return reinterpret_cast<T*>(&union_); }
136
137 private:
138 // Prefer c++14 aligned_storage, but for compatibility this will do.
139 union AlignedUnion {
140 char space[sizeof(T)];
141 int64 align_to_int64;
142 void* align_to_ptr;
143 } union_;
144};
145
146// Default empty string object. Don't use this directly. Instead, call
147// GetEmptyString() to get the reference.
148PROTOBUF_EXPORT extern ExplicitlyConstructed<std::string>
149 fixed_address_empty_string;
150
151
152PROTOBUF_EXPORT inline const std::string& GetEmptyStringAlreadyInited() {
153 return fixed_address_empty_string.get();
154}
155
156PROTOBUF_EXPORT size_t StringSpaceUsedExcludingSelfLong(const std::string& str);
157
158} // namespace internal
159
160// Interface to light weight protocol messages.
161//
162// This interface is implemented by all protocol message objects. Non-lite
163// messages additionally implement the Message interface, which is a
164// subclass of MessageLite. Use MessageLite instead when you only need
165// the subset of features which it supports -- namely, nothing that uses
166// descriptors or reflection. You can instruct the protocol compiler
167// to generate classes which implement only MessageLite, not the full
168// Message interface, by adding the following line to the .proto file:
169//
170// option optimize_for = LITE_RUNTIME;
171//
172// This is particularly useful on resource-constrained systems where
173// the full protocol buffers runtime library is too big.
174//
175// Note that on non-constrained systems (e.g. servers) when you need
176// to link in lots of protocol definitions, a better way to reduce
177// total code footprint is to use optimize_for = CODE_SIZE. This
178// will make the generated code smaller while still supporting all the
179// same features (at the expense of speed). optimize_for = LITE_RUNTIME
180// is best when you only have a small number of message types linked
181// into your binary, in which case the size of the protocol buffers
182// runtime itself is the biggest problem.
183class PROTOBUF_EXPORT MessageLite {
184 public:
185 inline MessageLite() {}
186 virtual ~MessageLite() {}
187
188 // Basic Operations ------------------------------------------------
189
190 // Get the name of this message type, e.g. "foo.bar.BazProto".
191 virtual std::string GetTypeName() const = 0;
192
193 // Construct a new instance of the same type. Ownership is passed to the
194 // caller.
195 virtual MessageLite* New() const = 0;
196
197 // Construct a new instance on the arena. Ownership is passed to the caller
198 // if arena is a NULL. Default implementation for backwards compatibility.
199 virtual MessageLite* New(Arena* arena) const;
200
201 // Get the arena, if any, associated with this message. Virtual method
202 // required for generic operations but most arena-related operations should
203 // use the GetArenaNoVirtual() generated-code method. Default implementation
204 // to reduce code size by avoiding the need for per-type implementations
205 // when types do not implement arena support.
206 virtual Arena* GetArena() const { return NULL; }
207
208 // Get a pointer that may be equal to this message's arena, or may not be.
209 // If the value returned by this method is equal to some arena pointer, then
210 // this message is on that arena; however, if this message is on some arena,
211 // this method may or may not return that arena's pointer. As a tradeoff,
212 // this method may be more efficient than GetArena(). The intent is to allow
213 // underlying representations that use e.g. tagged pointers to sometimes
214 // store the arena pointer directly, and sometimes in a more indirect way,
215 // and allow a fastpath comparison against the arena pointer when it's easy
216 // to obtain.
217 virtual void* GetMaybeArenaPointer() const { return GetArena(); }
218
219 // Clear all fields of the message and set them to their default values.
220 // Clear() avoids freeing memory, assuming that any memory allocated
221 // to hold parts of the message will be needed again to hold the next
222 // message. If you actually want to free the memory used by a Message,
223 // you must delete it.
224 virtual void Clear() = 0;
225
226 // Quickly check if all required fields have values set.
227 virtual bool IsInitialized() const = 0;
228
229 // This is not implemented for Lite messages -- it just returns "(cannot
230 // determine missing fields for lite message)". However, it is implemented
231 // for full messages. See message.h.
232 virtual std::string InitializationErrorString() const;
233
234 // If |other| is the exact same class as this, calls MergeFrom(). Otherwise,
235 // results are undefined (probably crash).
236 virtual void CheckTypeAndMergeFrom(const MessageLite& other) = 0;
237
238 // These methods return a human-readable summary of the message. Note that
239 // since the MessageLite interface does not support reflection, there is very
240 // little information that these methods can provide. They are shadowed by
241 // methods of the same name on the Message interface which provide much more
242 // information. The methods here are intended primarily to facilitate code
243 // reuse for logic that needs to interoperate with both full and lite protos.
244 //
245 // The format of the returned string is subject to change, so please do not
246 // assume it will remain stable over time.
247 std::string DebugString() const;
248 std::string ShortDebugString() const { return DebugString(); }
249 // MessageLite::DebugString is already Utf8 Safe. This is to add compatibility
250 // with Message.
251 std::string Utf8DebugString() const { return DebugString(); }
252
253 // Parsing ---------------------------------------------------------
254 // Methods for parsing in protocol buffer format. Most of these are
255 // just simple wrappers around MergeFromCodedStream(). Clear() will be
256 // called before merging the input.
257
258 // Fill the message with a protocol buffer parsed from the given input
259 // stream. Returns false on a read error or if the input is in the wrong
260 // format. A successful return does not indicate the entire input is
261 // consumed, ensure you call ConsumedEntireMessage() to check that if
262 // applicable.
263 bool ParseFromCodedStream(io::CodedInputStream* input);
264 // Like ParseFromCodedStream(), but accepts messages that are missing
265 // required fields.
266 bool ParsePartialFromCodedStream(io::CodedInputStream* input);
267 // Read a protocol buffer from the given zero-copy input stream. If
268 // successful, the entire input will be consumed.
269 bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);
270 // Like ParseFromZeroCopyStream(), but accepts messages that are missing
271 // required fields.
272 bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input);
273 // Parse a protocol buffer from a file descriptor. If successful, the entire
274 // input will be consumed.
275 bool ParseFromFileDescriptor(int file_descriptor);
276 // Like ParseFromFileDescriptor(), but accepts messages that are missing
277 // required fields.
278 bool ParsePartialFromFileDescriptor(int file_descriptor);
279 // Parse a protocol buffer from a C++ istream. If successful, the entire
280 // input will be consumed.
281 bool ParseFromIstream(std::istream* input);
282 // Like ParseFromIstream(), but accepts messages that are missing
283 // required fields.
284 bool ParsePartialFromIstream(std::istream* input);
285 // Read a protocol buffer from the given zero-copy input stream, expecting
286 // the message to be exactly "size" bytes long. If successful, exactly
287 // this many bytes will have been consumed from the input.
288 bool MergePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
289 int size);
290 // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
291 // missing required fields.
292 bool MergeFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
293 bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
294 // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
295 // missing required fields.
296 bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
297 int size);
298 // Parses a protocol buffer contained in a string. Returns true on success.
299 // This function takes a string in the (non-human-readable) binary wire
300 // format, matching the encoding output by MessageLite::SerializeToString().
301 // If you'd like to convert a human-readable string into a protocol buffer
302 // object, see google::protobuf::TextFormat::ParseFromString().
303 bool ParseFromString(const std::string& data);
304 // Like ParseFromString(), but accepts messages that are missing
305 // required fields.
306 bool ParsePartialFromString(const std::string& data);
307 // Parse a protocol buffer contained in an array of bytes.
308 bool ParseFromArray(const void* data, int size);
309 // Like ParseFromArray(), but accepts messages that are missing
310 // required fields.
311 bool ParsePartialFromArray(const void* data, int size);
312
313
314 // Reads a protocol buffer from the stream and merges it into this
315 // Message. Singular fields read from the what is
316 // already in the Message and repeated fields are appended to those
317 // already present.
318 //
319 // It is the responsibility of the caller to call input->LastTagWas()
320 // (for groups) or input->ConsumedEntireMessage() (for non-groups) after
321 // this returns to verify that the message's end was delimited correctly.
322 //
323 // ParsefromCodedStream() is implemented as Clear() followed by
324 // MergeFromCodedStream().
325 bool MergeFromCodedStream(io::CodedInputStream* input);
326
327 // Like MergeFromCodedStream(), but succeeds even if required fields are
328 // missing in the input.
329 //
330 // MergeFromCodedStream() is just implemented as MergePartialFromCodedStream()
331 // followed by IsInitialized().
332#if GOOGLE_PROTOBUF_ENABLE_EXPERIMENTAL_PARSER
333 bool MergePartialFromCodedStream(io::CodedInputStream* input);
334#else
335 virtual bool MergePartialFromCodedStream(io::CodedInputStream* input) = 0;
336#endif // GOOGLE_PROTOBUF_ENABLE_EXPERIMENTAL_PARSER
337
338 // Merge a protocol buffer contained in a string.
339 bool MergeFromString(const std::string& data);
340
341
342 // Serialization ---------------------------------------------------
343 // Methods for serializing in protocol buffer format. Most of these
344 // are just simple wrappers around ByteSize() and SerializeWithCachedSizes().
345
346 // Write a protocol buffer of this message to the given output. Returns
347 // false on a write error. If the message is missing required fields,
348 // this may GOOGLE_CHECK-fail.
349 bool SerializeToCodedStream(io::CodedOutputStream* output) const;
350 // Like SerializeToCodedStream(), but allows missing required fields.
351 bool SerializePartialToCodedStream(io::CodedOutputStream* output) const;
352 // Write the message to the given zero-copy output stream. All required
353 // fields must be set.
354 bool SerializeToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
355 // Like SerializeToZeroCopyStream(), but allows missing required fields.
356 bool SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
357 // Serialize the message and store it in the given string. All required
358 // fields must be set.
359 bool SerializeToString(std::string* output) const;
360 // Like SerializeToString(), but allows missing required fields.
361 bool SerializePartialToString(std::string* output) const;
362 // Serialize the message and store it in the given byte array. All required
363 // fields must be set.
364 bool SerializeToArray(void* data, int size) const;
365 // Like SerializeToArray(), but allows missing required fields.
366 bool SerializePartialToArray(void* data, int size) const;
367
368 // Make a string encoding the message. Is equivalent to calling
369 // SerializeToString() on a string and using that. Returns the empty
370 // string if SerializeToString() would have returned an error.
371 // Note: If you intend to generate many such strings, you may
372 // reduce heap fragmentation by instead re-using the same string
373 // object with calls to SerializeToString().
374 std::string SerializeAsString() const;
375 // Like SerializeAsString(), but allows missing required fields.
376 std::string SerializePartialAsString() const;
377
378 // Serialize the message and write it to the given file descriptor. All
379 // required fields must be set.
380 bool SerializeToFileDescriptor(int file_descriptor) const;
381 // Like SerializeToFileDescriptor(), but allows missing required fields.
382 bool SerializePartialToFileDescriptor(int file_descriptor) const;
383 // Serialize the message and write it to the given C++ ostream. All
384 // required fields must be set.
385 bool SerializeToOstream(std::ostream* output) const;
386 // Like SerializeToOstream(), but allows missing required fields.
387 bool SerializePartialToOstream(std::ostream* output) const;
388
389 // Like SerializeToString(), but appends to the data to the string's
390 // existing contents. All required fields must be set.
391 bool AppendToString(std::string* output) const;
392 // Like AppendToString(), but allows missing required fields.
393 bool AppendPartialToString(std::string* output) const;
394
395
396 // Computes the serialized size of the message. This recursively calls
397 // ByteSizeLong() on all embedded messages.
398 //
399 // ByteSizeLong() is generally linear in the number of fields defined for the
400 // proto.
401 virtual size_t ByteSizeLong() const = 0;
402
403 // Legacy ByteSize() API.
404 PROTOBUF_DEPRECATED_MSG("Please use ByteSizeLong() instead")
405 int ByteSize() const { return internal::ToIntSize(ByteSizeLong()); }
406
407 // Serializes the message without recomputing the size. The message must not
408 // have changed since the last call to ByteSize(), and the value returned by
409 // ByteSize must be non-negative. Otherwise the results are undefined.
410 virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const;
411
412 // Functions below here are not part of the public interface. It isn't
413 // enforced, but they should be treated as private, and will be private
414 // at some future time. Unfortunately the implementation of the "friend"
415 // keyword in GCC is broken at the moment, but we expect it will be fixed.
416
417 // Like SerializeWithCachedSizes, but writes directly to *target, returning
418 // a pointer to the byte immediately after the last byte written. "target"
419 // must point at a byte array of at least ByteSize() bytes. Whether to use
420 // deterministic serialization, e.g., maps in sorted order, is determined by
421 // CodedOutputStream::IsDefaultSerializationDeterministic().
422 virtual uint8* SerializeWithCachedSizesToArray(uint8* target) const;
423
424 // Returns the result of the last call to ByteSize(). An embedded message's
425 // size is needed both to serialize it (because embedded messages are
426 // length-delimited) and to compute the outer message's size. Caching
427 // the size avoids computing it multiple times.
428 //
429 // ByteSize() does not automatically use the cached size when available
430 // because this would require invalidating it every time the message was
431 // modified, which would be too hard and expensive. (E.g. if a deeply-nested
432 // sub-message is changed, all of its parents' cached sizes would need to be
433 // invalidated, which is too much work for an otherwise inlined setter
434 // method.)
435 virtual int GetCachedSize() const = 0;
436
437#if GOOGLE_PROTOBUF_ENABLE_EXPERIMENTAL_PARSER
438 virtual const char* _InternalParse(const char* ptr,
439 internal::ParseContext* ctx) {
440 return nullptr;
441 }
442#endif // GOOGLE_PROTOBUF_ENABLE_EXPERIMENTAL_PARSER
443
444 protected:
445 // CastToBase allows generated code to cast a RepeatedPtrField<T> to
446 // RepeatedPtrFieldBase. We try to restrict access to RepeatedPtrFieldBase
447 // because it is an implementation detail that user code should not access
448 // directly.
449 template <typename T>
450 static internal::RepeatedPtrFieldBase* CastToBase(
451 RepeatedPtrField<T>* repeated) {
452 return repeated;
453 }
454 template <typename T>
455 static const internal::RepeatedPtrFieldBase& CastToBase(
456 const RepeatedPtrField<T>& repeated) {
457 return repeated;
458 }
459
460 template <typename T>
461 static T* CreateMaybeMessage(Arena* arena) {
462 return Arena::CreateMaybeMessage<T>(arena);
463 }
464
465 public:
466 enum ParseFlags {
467 kMerge = 0,
468 kParse = 1,
469 kMergePartial = 2,
470 kParsePartial = 3,
471 kMergeWithAliasing = 4,
472 kParseWithAliasing = 5,
473 kMergePartialWithAliasing = 6,
474 kParsePartialWithAliasing = 7
475 };
476
477 template <ParseFlags flags, typename T>
478 bool ParseFrom(const T& input);
479
480 private:
481 // TODO(gerbens) make this a pure abstract function
482 virtual const void* InternalGetTable() const { return NULL; }
483
484 // Fast path when conditions match (ie. non-deterministic)
485 public:
486 virtual uint8* InternalSerializeWithCachedSizesToArray(uint8* target) const;
487
488 private:
489 friend class internal::WireFormatLite;
490 friend class Message;
491 friend class internal::WeakFieldMap;
492
493 bool IsInitializedWithErrors() const {
494 if (IsInitialized()) return true;
495 LogInitializationErrorMessage();
496 return false;
497 }
498
499 void LogInitializationErrorMessage() const;
500
501 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageLite);
502};
503
504namespace internal {
505
506template <bool alias>
507bool MergePartialFromImpl(StringPiece input, MessageLite* msg);
508extern template bool MergePartialFromImpl<false>(StringPiece input,
509 MessageLite* msg);
510extern template bool MergePartialFromImpl<true>(StringPiece input,
511 MessageLite* msg);
512
513template <bool alias>
514bool MergePartialFromImpl(io::ZeroCopyInputStream* input, MessageLite* msg);
515extern template bool MergePartialFromImpl<false>(io::ZeroCopyInputStream* input,
516 MessageLite* msg);
517extern template bool MergePartialFromImpl<true>(io::ZeroCopyInputStream* input,
518 MessageLite* msg);
519
520struct BoundedZCIS {
521 io::ZeroCopyInputStream* zcis;
522 int limit;
523};
524
525template <bool alias>
526bool MergePartialFromImpl(BoundedZCIS input, MessageLite* msg);
527extern template bool MergePartialFromImpl<false>(BoundedZCIS input,
528 MessageLite* msg);
529extern template bool MergePartialFromImpl<true>(BoundedZCIS input,
530 MessageLite* msg);
531
532template <typename T>
533struct SourceWrapper;
534
535template <bool alias, typename T>
536bool MergePartialFromImpl(const SourceWrapper<T>& input, MessageLite* msg) {
537 return input.template MergePartialInto<alias>(msg);
538}
539
540} // namespace internal
541
542template <MessageLite::ParseFlags flags, typename T>
543bool MessageLite::ParseFrom(const T& input) {
544 if (flags & kParse) Clear();
545 constexpr bool alias = flags & kMergeWithAliasing;
546 bool res = internal::MergePartialFromImpl<alias>(input, this);
547 return res && ((flags & kMergePartial) || IsInitializedWithErrors());
548}
549
550} // namespace protobuf
551} // namespace google
552
553#include <google/protobuf/port_undef.inc>
554
555#endif // GOOGLE_PROTOBUF_MESSAGE_LITE_H__
556