Line data Source code
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: wink@google.com (Wink Saville),
32 : // kenton@google.com (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 <google/protobuf/stubs/common.h>
44 : #include <google/protobuf/stubs/logging.h>
45 : #include <google/protobuf/stubs/once.h>
46 : #include <google/protobuf/arena.h>
47 : #include <google/protobuf/stubs/port.h>
48 :
49 : namespace google {
50 : namespace protobuf {
51 : template <typename T>
52 : class RepeatedPtrField;
53 : namespace io {
54 : class CodedInputStream;
55 : class CodedOutputStream;
56 : class ZeroCopyInputStream;
57 : class ZeroCopyOutputStream;
58 : }
59 : namespace internal {
60 :
61 : class RepeatedPtrFieldBase;
62 : class WireFormatLite;
63 : class WeakFieldMap;
64 :
65 : #ifndef SWIG
66 : // We compute sizes as size_t but cache them as int. This function converts a
67 : // computed size to a cached size. Since we don't proceed with serialization
68 : // if the total size was > INT_MAX, it is not important what this function
69 : // returns for inputs > INT_MAX. However this case should not error or
70 : // GOOGLE_CHECK-fail, because the full size_t resolution is still returned from
71 : // ByteSizeLong() and checked against INT_MAX; we can catch the overflow
72 : // there.
73 0 : inline int ToCachedSize(size_t size) { return static_cast<int>(size); }
74 :
75 : // We mainly calculate sizes in terms of size_t, but some functions that
76 : // compute sizes return "int". These int sizes are expected to always be
77 : // positive. This function is more efficient than casting an int to size_t
78 : // directly on 64-bit platforms because it avoids making the compiler emit a
79 : // sign extending instruction, which we don't want and don't want to pay for.
80 0 : inline size_t FromIntSize(int size) {
81 : // Convert to unsigned before widening so sign extension is not necessary.
82 0 : return static_cast<unsigned int>(size);
83 : }
84 :
85 : // For cases where a legacy function returns an integer size. We GOOGLE_DCHECK()
86 : // that the conversion will fit within an integer; if this is false then we
87 : // are losing information.
88 0 : inline int ToIntSize(size_t size) {
89 0 : GOOGLE_DCHECK_LE(size, static_cast<size_t>(INT_MAX));
90 0 : return static_cast<int>(size);
91 : }
92 :
93 : // This type wraps a variable whose constructor and destructor are explicitly
94 : // called. It is particularly useful for a global variable, without its
95 : // constructor and destructor run on start and end of the program lifetime.
96 : // This circumvents the initial construction order fiasco, while keeping
97 : // the address of the empty string a compile time constant.
98 : //
99 : // Pay special attention to the initialization state of the object.
100 : // 1. The object is "uninitialized" to begin with.
101 : // 2. Call DefaultConstruct() only if the object is uninitialized.
102 : // After the call, the object becomes "initialized".
103 : // 3. Call get() and get_mutable() only if the object is initialized.
104 : // 4. Call Destruct() only if the object is initialized.
105 : // After the call, the object becomes uninitialized.
106 : template <typename T>
107 : class ExplicitlyConstructed {
108 : public:
109 : void DefaultConstruct() {
110 : new (&union_) T();
111 : }
112 :
113 : void Destruct() {
114 : get_mutable()->~T();
115 : }
116 :
117 49 : constexpr const T& get() const { return reinterpret_cast<const T&>(union_); }
118 30 : T* get_mutable() { return reinterpret_cast<T*>(&union_); }
119 :
120 : private:
121 : // Prefer c++14 aligned_storage, but for compatibility this will do.
122 : union AlignedUnion {
123 : char space[sizeof(T)];
124 : int64 align_to_int64;
125 : void* align_to_ptr;
126 : } union_;
127 : };
128 :
129 : // Default empty string object. Don't use this directly. Instead, call
130 : // GetEmptyString() to get the reference.
131 : LIBPROTOBUF_EXPORT extern ExplicitlyConstructed<::std::string> fixed_address_empty_string;
132 :
133 49 : LIBPROTOBUF_EXPORT inline const ::std::string& GetEmptyStringAlreadyInited() {
134 49 : return fixed_address_empty_string.get();
135 : }
136 :
137 : LIBPROTOBUF_EXPORT size_t StringSpaceUsedExcludingSelfLong(const string& str);
138 : #endif // SWIG
139 : } // namespace internal
140 :
141 : // Interface to light weight protocol messages.
142 : //
143 : // This interface is implemented by all protocol message objects. Non-lite
144 : // messages additionally implement the Message interface, which is a
145 : // subclass of MessageLite. Use MessageLite instead when you only need
146 : // the subset of features which it supports -- namely, nothing that uses
147 : // descriptors or reflection. You can instruct the protocol compiler
148 : // to generate classes which implement only MessageLite, not the full
149 : // Message interface, by adding the following line to the .proto file:
150 : //
151 : // option optimize_for = LITE_RUNTIME;
152 : //
153 : // This is particularly useful on resource-constrained systems where
154 : // the full protocol buffers runtime library is too big.
155 : //
156 : // Note that on non-constrained systems (e.g. servers) when you need
157 : // to link in lots of protocol definitions, a better way to reduce
158 : // total code footprint is to use optimize_for = CODE_SIZE. This
159 : // will make the generated code smaller while still supporting all the
160 : // same features (at the expense of speed). optimize_for = LITE_RUNTIME
161 : // is best when you only have a small number of message types linked
162 : // into your binary, in which case the size of the protocol buffers
163 : // runtime itself is the biggest problem.
164 : class LIBPROTOBUF_EXPORT MessageLite {
165 : public:
166 42 : inline MessageLite() {}
167 0 : virtual ~MessageLite() {}
168 :
169 : // Basic Operations ------------------------------------------------
170 :
171 : // Get the name of this message type, e.g. "foo.bar.BazProto".
172 : virtual string GetTypeName() const = 0;
173 :
174 : // Construct a new instance of the same type. Ownership is passed to the
175 : // caller.
176 : virtual MessageLite* New() const = 0;
177 :
178 : // Construct a new instance on the arena. Ownership is passed to the caller
179 : // if arena is a NULL. Default implementation for backwards compatibility.
180 : virtual MessageLite* New(::google::protobuf::Arena* arena) const;
181 :
182 : // Get the arena, if any, associated with this message. Virtual method
183 : // required for generic operations but most arena-related operations should
184 : // use the GetArenaNoVirtual() generated-code method. Default implementation
185 : // to reduce code size by avoiding the need for per-type implementations
186 : // when types do not implement arena support.
187 0 : virtual ::google::protobuf::Arena* GetArena() const { return NULL; }
188 :
189 : // Get a pointer that may be equal to this message's arena, or may not be.
190 : // If the value returned by this method is equal to some arena pointer, then
191 : // this message is on that arena; however, if this message is on some arena,
192 : // this method may or may not return that arena's pointer. As a tradeoff,
193 : // this method may be more efficient than GetArena(). The intent is to allow
194 : // underlying representations that use e.g. tagged pointers to sometimes
195 : // store the arena pointer directly, and sometimes in a more indirect way,
196 : // and allow a fastpath comparison against the arena pointer when it's easy
197 : // to obtain.
198 0 : virtual void* GetMaybeArenaPointer() const { return GetArena(); }
199 :
200 : // Clear all fields of the message and set them to their default values.
201 : // Clear() avoids freeing memory, assuming that any memory allocated
202 : // to hold parts of the message will be needed again to hold the next
203 : // message. If you actually want to free the memory used by a Message,
204 : // you must delete it.
205 : virtual void Clear() = 0;
206 :
207 : // Quickly check if all required fields have values set.
208 : virtual bool IsInitialized() const = 0;
209 :
210 : // This is not implemented for Lite messages -- it just returns "(cannot
211 : // determine missing fields for lite message)". However, it is implemented
212 : // for full messages. See message.h.
213 : virtual string InitializationErrorString() const;
214 :
215 : // If |other| is the exact same class as this, calls MergeFrom(). Otherwise,
216 : // results are undefined (probably crash).
217 : virtual void CheckTypeAndMergeFrom(const MessageLite& other) = 0;
218 :
219 : // Parsing ---------------------------------------------------------
220 : // Methods for parsing in protocol buffer format. Most of these are
221 : // just simple wrappers around MergeFromCodedStream(). Clear() will be
222 : // called before merging the input.
223 :
224 : // Fill the message with a protocol buffer parsed from the given input
225 : // stream. Returns false on a read error or if the input is in the wrong
226 : // format. A successful return does not indicate the entire input is
227 : // consumed, ensure you call ConsumedEntireMessage() to check that if
228 : // applicable.
229 : bool ParseFromCodedStream(io::CodedInputStream* input);
230 : // Like ParseFromCodedStream(), but accepts messages that are missing
231 : // required fields.
232 : bool ParsePartialFromCodedStream(io::CodedInputStream* input);
233 : // Read a protocol buffer from the given zero-copy input stream. If
234 : // successful, the entire input will be consumed.
235 : bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);
236 : // Like ParseFromZeroCopyStream(), but accepts messages that are missing
237 : // required fields.
238 : bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input);
239 : // Read a protocol buffer from the given zero-copy input stream, expecting
240 : // the message to be exactly "size" bytes long. If successful, exactly
241 : // this many bytes will have been consumed from the input.
242 : bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
243 : // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
244 : // missing required fields.
245 : bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
246 : int size);
247 : // Parses a protocol buffer contained in a string. Returns true on success.
248 : // This function takes a string in the (non-human-readable) binary wire
249 : // format, matching the encoding output by MessageLite::SerializeToString().
250 : // If you'd like to convert a human-readable string into a protocol buffer
251 : // object, see google::protobuf::TextFormat::ParseFromString().
252 : bool ParseFromString(const string& data);
253 : // Like ParseFromString(), but accepts messages that are missing
254 : // required fields.
255 : bool ParsePartialFromString(const string& data);
256 : // Parse a protocol buffer contained in an array of bytes.
257 : bool ParseFromArray(const void* data, int size);
258 : // Like ParseFromArray(), but accepts messages that are missing
259 : // required fields.
260 : bool ParsePartialFromArray(const void* data, int size);
261 :
262 :
263 : // Reads a protocol buffer from the stream and merges it into this
264 : // Message. Singular fields read from the what is
265 : // already in the Message and repeated fields are appended to those
266 : // already present.
267 : //
268 : // It is the responsibility of the caller to call input->LastTagWas()
269 : // (for groups) or input->ConsumedEntireMessage() (for non-groups) after
270 : // this returns to verify that the message's end was delimited correctly.
271 : //
272 : // ParsefromCodedStream() is implemented as Clear() followed by
273 : // MergeFromCodedStream().
274 : bool MergeFromCodedStream(io::CodedInputStream* input);
275 :
276 : // Like MergeFromCodedStream(), but succeeds even if required fields are
277 : // missing in the input.
278 : //
279 : // MergeFromCodedStream() is just implemented as MergePartialFromCodedStream()
280 : // followed by IsInitialized().
281 : virtual bool MergePartialFromCodedStream(io::CodedInputStream* input) = 0;
282 :
283 :
284 : // Serialization ---------------------------------------------------
285 : // Methods for serializing in protocol buffer format. Most of these
286 : // are just simple wrappers around ByteSize() and SerializeWithCachedSizes().
287 :
288 : // Write a protocol buffer of this message to the given output. Returns
289 : // false on a write error. If the message is missing required fields,
290 : // this may GOOGLE_CHECK-fail.
291 : bool SerializeToCodedStream(io::CodedOutputStream* output) const;
292 : // Like SerializeToCodedStream(), but allows missing required fields.
293 : bool SerializePartialToCodedStream(io::CodedOutputStream* output) const;
294 : // Write the message to the given zero-copy output stream. All required
295 : // fields must be set.
296 : bool SerializeToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
297 : // Like SerializeToZeroCopyStream(), but allows missing required fields.
298 : bool SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
299 : // Serialize the message and store it in the given string. All required
300 : // fields must be set.
301 : bool SerializeToString(string* output) const;
302 : // Like SerializeToString(), but allows missing required fields.
303 : bool SerializePartialToString(string* output) const;
304 : // Serialize the message and store it in the given byte array. All required
305 : // fields must be set.
306 : bool SerializeToArray(void* data, int size) const;
307 : // Like SerializeToArray(), but allows missing required fields.
308 : bool SerializePartialToArray(void* data, int size) const;
309 :
310 : // Make a string encoding the message. Is equivalent to calling
311 : // SerializeToString() on a string and using that. Returns the empty
312 : // string if SerializeToString() would have returned an error.
313 : // Note: If you intend to generate many such strings, you may
314 : // reduce heap fragmentation by instead re-using the same string
315 : // object with calls to SerializeToString().
316 : string SerializeAsString() const;
317 : // Like SerializeAsString(), but allows missing required fields.
318 : string SerializePartialAsString() const;
319 :
320 : // Like SerializeToString(), but appends to the data to the string's existing
321 : // contents. All required fields must be set.
322 : bool AppendToString(string* output) const;
323 : // Like AppendToString(), but allows missing required fields.
324 : bool AppendPartialToString(string* output) const;
325 :
326 : // Computes the serialized size of the message. This recursively calls
327 : // ByteSizeLong() on all embedded messages.
328 : //
329 : // ByteSizeLong() is generally linear in the number of fields defined for the
330 : // proto.
331 : virtual size_t ByteSizeLong() const = 0;
332 :
333 : // Legacy ByteSize() API.
334 : PROTOBUF_RUNTIME_DEPRECATED("Please use ByteSizeLong() instead")
335 0 : int ByteSize() const {
336 0 : return internal::ToIntSize(ByteSizeLong());
337 : }
338 :
339 : // Serializes the message without recomputing the size. The message must not
340 : // have changed since the last call to ByteSize(), and the value returned by
341 : // ByteSize must be non-negative. Otherwise the results are undefined.
342 : virtual void SerializeWithCachedSizes(
343 : io::CodedOutputStream* output) const;
344 :
345 : // Functions below here are not part of the public interface. It isn't
346 : // enforced, but they should be treated as private, and will be private
347 : // at some future time. Unfortunately the implementation of the "friend"
348 : // keyword in GCC is broken at the moment, but we expect it will be fixed.
349 :
350 : // Like SerializeWithCachedSizes, but writes directly to *target, returning
351 : // a pointer to the byte immediately after the last byte written. "target"
352 : // must point at a byte array of at least ByteSize() bytes. Whether to use
353 : // deterministic serialization, e.g., maps in sorted order, is determined by
354 : // CodedOutputStream::IsDefaultSerializationDeterministic().
355 : virtual uint8* SerializeWithCachedSizesToArray(uint8* target) const;
356 :
357 : // Returns the result of the last call to ByteSize(). An embedded message's
358 : // size is needed both to serialize it (because embedded messages are
359 : // length-delimited) and to compute the outer message's size. Caching
360 : // the size avoids computing it multiple times.
361 : //
362 : // ByteSize() does not automatically use the cached size when available
363 : // because this would require invalidating it every time the message was
364 : // modified, which would be too hard and expensive. (E.g. if a deeply-nested
365 : // sub-message is changed, all of its parents' cached sizes would need to be
366 : // invalidated, which is too much work for an otherwise inlined setter
367 : // method.)
368 : virtual int GetCachedSize() const = 0;
369 :
370 : virtual uint8* InternalSerializeWithCachedSizesToArray(bool deterministic,
371 : uint8* target) const;
372 :
373 : protected:
374 : // CastToBase allows generated code to cast a RepeatedPtrField<T> to
375 : // RepeatedPtrFieldBase. We try to restrict access to RepeatedPtrFieldBase
376 : // because it is an implementation detail that user code should not access
377 : // directly.
378 : template <typename T>
379 0 : static ::google::protobuf::internal::RepeatedPtrFieldBase* CastToBase(
380 : ::google::protobuf::RepeatedPtrField<T>* repeated) {
381 0 : return repeated;
382 : }
383 : template <typename T>
384 : static const ::google::protobuf::internal::RepeatedPtrFieldBase& CastToBase(
385 : const ::google::protobuf::RepeatedPtrField<T>& repeated) {
386 : return repeated;
387 : }
388 :
389 : template <typename T>
390 0 : static T* CreateMaybeMessage(Arena* arena) {
391 0 : return Arena::CreateMaybeMessage<T>(arena);
392 : }
393 :
394 : private:
395 : // TODO(gerbens) make this a pure abstract function
396 0 : virtual const void* InternalGetTable() const { return NULL; }
397 :
398 : friend class internal::WireFormatLite;
399 : friend class Message;
400 : friend class internal::WeakFieldMap;
401 :
402 : GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageLite);
403 : };
404 :
405 : namespace internal {
406 :
407 : extern bool LIBPROTOBUF_EXPORT proto3_preserve_unknown_;
408 :
409 : // DO NOT USE: For migration only. Will be removed when Proto3 defaults to
410 : // preserve unknowns.
411 0 : inline bool GetProto3PreserveUnknownsDefault() {
412 0 : return proto3_preserve_unknown_;
413 : }
414 :
415 : // DO NOT USE: For migration only. Will be removed when Proto3 defaults to
416 : // preserve unknowns.
417 : void LIBPROTOBUF_EXPORT SetProto3PreserveUnknownsDefault(bool preserve);
418 : } // namespace internal
419 :
420 :
421 : } // namespace protobuf
422 :
423 : } // namespace google
424 : #endif // GOOGLE_PROTOBUF_MESSAGE_LITE_H__
|
