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 <google/protobuf/stubs/common.h>
43 :
44 :
45 : namespace google {
46 : namespace protobuf {
47 : class Arena;
48 : namespace io {
49 : class CodedInputStream;
50 : class CodedOutputStream;
51 : class ZeroCopyInputStream;
52 : class ZeroCopyOutputStream;
53 : }
54 :
55 : // Interface to light weight protocol messages.
56 : //
57 : // This interface is implemented by all protocol message objects. Non-lite
58 : // messages additionally implement the Message interface, which is a
59 : // subclass of MessageLite. Use MessageLite instead when you only need
60 : // the subset of features which it supports -- namely, nothing that uses
61 : // descriptors or reflection. You can instruct the protocol compiler
62 : // to generate classes which implement only MessageLite, not the full
63 : // Message interface, by adding the following line to the .proto file:
64 : //
65 : // option optimize_for = LITE_RUNTIME;
66 : //
67 : // This is particularly useful on resource-constrained systems where
68 : // the full protocol buffers runtime library is too big.
69 : //
70 : // Note that on non-constrained systems (e.g. servers) when you need
71 : // to link in lots of protocol definitions, a better way to reduce
72 : // total code footprint is to use optimize_for = CODE_SIZE. This
73 : // will make the generated code smaller while still supporting all the
74 : // same features (at the expense of speed). optimize_for = LITE_RUNTIME
75 : // is best when you only have a small number of message types linked
76 : // into your binary, in which case the size of the protocol buffers
77 : // runtime itself is the biggest problem.
78 : class LIBPROTOBUF_EXPORT MessageLite {
79 : public:
80 7687710 : inline MessageLite() {}
81 : virtual ~MessageLite();
82 :
83 : // Basic Operations ------------------------------------------------
84 :
85 : // Get the name of this message type, e.g. "foo.bar.BazProto".
86 : virtual string GetTypeName() const = 0;
87 :
88 : // Construct a new instance of the same type. Ownership is passed to the
89 : // caller.
90 : virtual MessageLite* New() const = 0;
91 :
92 : // Construct a new instance on the arena. Ownership is passed to the caller
93 : // if arena is a NULL. Default implementation for backwards compatibility.
94 : virtual MessageLite* New(::google::protobuf::Arena* arena) const;
95 :
96 : // Get the arena, if any, associated with this message. Virtual method
97 : // required for generic operations but most arena-related operations should
98 : // use the GetArenaNoVirtual() generated-code method. Default implementation
99 : // to reduce code size by avoiding the need for per-type implementations when
100 : // types do not implement arena support.
101 405 : virtual ::google::protobuf::Arena* GetArena() const { return NULL; }
102 :
103 : // Get a pointer that may be equal to this message's arena, or may not be. If
104 : // the value returned by this method is equal to some arena pointer, then this
105 : // message is on that arena; however, if this message is on some arena, this
106 : // method may or may not return that arena's pointer. As a tradeoff, this
107 : // method may be more efficient than GetArena(). The intent is to allow
108 : // underlying representations that use e.g. tagged pointers to sometimes store
109 : // the arena pointer directly, and sometimes in a more indirect way, and allow
110 : // a fastpath comparison against the arena pointer when it's easy to obtain.
111 0 : virtual void* GetMaybeArenaPointer() const { return GetArena(); }
112 :
113 : // Clear all fields of the message and set them to their default values.
114 : // Clear() avoids freeing memory, assuming that any memory allocated
115 : // to hold parts of the message will be needed again to hold the next
116 : // message. If you actually want to free the memory used by a Message,
117 : // you must delete it.
118 : virtual void Clear() = 0;
119 :
120 : // Quickly check if all required fields have values set.
121 : virtual bool IsInitialized() const = 0;
122 :
123 : // This is not implemented for Lite messages -- it just returns "(cannot
124 : // determine missing fields for lite message)". However, it is implemented
125 : // for full messages. See message.h.
126 : virtual string InitializationErrorString() const;
127 :
128 : // If |other| is the exact same class as this, calls MergeFrom(). Otherwise,
129 : // results are undefined (probably crash).
130 : virtual void CheckTypeAndMergeFrom(const MessageLite& other) = 0;
131 :
132 : // Parsing ---------------------------------------------------------
133 : // Methods for parsing in protocol buffer format. Most of these are
134 : // just simple wrappers around MergeFromCodedStream(). Clear() will be called
135 : // before merging the input.
136 :
137 : // Fill the message with a protocol buffer parsed from the given input stream.
138 : // Returns false on a read error or if the input is in the wrong format. A
139 : // successful return does not indicate the entire input is consumed, ensure
140 : // you call ConsumedEntireMessage() to check that if applicable.
141 : bool ParseFromCodedStream(io::CodedInputStream* input);
142 : // Like ParseFromCodedStream(), but accepts messages that are missing
143 : // required fields.
144 : bool ParsePartialFromCodedStream(io::CodedInputStream* input);
145 : // Read a protocol buffer from the given zero-copy input stream. If
146 : // successful, the entire input will be consumed.
147 : bool ParseFromZeroCopyStream(io::ZeroCopyInputStream* input);
148 : // Like ParseFromZeroCopyStream(), but accepts messages that are missing
149 : // required fields.
150 : bool ParsePartialFromZeroCopyStream(io::ZeroCopyInputStream* input);
151 : // Read a protocol buffer from the given zero-copy input stream, expecting
152 : // the message to be exactly "size" bytes long. If successful, exactly
153 : // this many bytes will have been consumed from the input.
154 : bool ParseFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input, int size);
155 : // Like ParseFromBoundedZeroCopyStream(), but accepts messages that are
156 : // missing required fields.
157 : bool ParsePartialFromBoundedZeroCopyStream(io::ZeroCopyInputStream* input,
158 : int size);
159 : // Parses a protocol buffer contained in a string. Returns true on success.
160 : // This function takes a string in the (non-human-readable) binary wire
161 : // format, matching the encoding output by MessageLite::SerializeToString().
162 : // If you'd like to convert a human-readable string into a protocol buffer
163 : // object, see google::protobuf::TextFormat::ParseFromString().
164 : bool ParseFromString(const string& data);
165 : // Like ParseFromString(), but accepts messages that are missing
166 : // required fields.
167 : bool ParsePartialFromString(const string& data);
168 : // Parse a protocol buffer contained in an array of bytes.
169 : bool ParseFromArray(const void* data, int size);
170 : // Like ParseFromArray(), but accepts messages that are missing
171 : // required fields.
172 : bool ParsePartialFromArray(const void* data, int size);
173 :
174 :
175 : // Reads a protocol buffer from the stream and merges it into this
176 : // Message. Singular fields read from the input overwrite what is
177 : // already in the Message and repeated fields are appended to those
178 : // already present.
179 : //
180 : // It is the responsibility of the caller to call input->LastTagWas()
181 : // (for groups) or input->ConsumedEntireMessage() (for non-groups) after
182 : // this returns to verify that the message's end was delimited correctly.
183 : //
184 : // ParsefromCodedStream() is implemented as Clear() followed by
185 : // MergeFromCodedStream().
186 : bool MergeFromCodedStream(io::CodedInputStream* input);
187 :
188 : // Like MergeFromCodedStream(), but succeeds even if required fields are
189 : // missing in the input.
190 : //
191 : // MergeFromCodedStream() is just implemented as MergePartialFromCodedStream()
192 : // followed by IsInitialized().
193 : virtual bool MergePartialFromCodedStream(io::CodedInputStream* input) = 0;
194 :
195 :
196 : // Serialization ---------------------------------------------------
197 : // Methods for serializing in protocol buffer format. Most of these
198 : // are just simple wrappers around ByteSize() and SerializeWithCachedSizes().
199 :
200 : // Write a protocol buffer of this message to the given output. Returns
201 : // false on a write error. If the message is missing required fields,
202 : // this may GOOGLE_CHECK-fail.
203 : bool SerializeToCodedStream(io::CodedOutputStream* output) const;
204 : // Like SerializeToCodedStream(), but allows missing required fields.
205 : bool SerializePartialToCodedStream(io::CodedOutputStream* output) const;
206 : // Write the message to the given zero-copy output stream. All required
207 : // fields must be set.
208 : bool SerializeToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
209 : // Like SerializeToZeroCopyStream(), but allows missing required fields.
210 : bool SerializePartialToZeroCopyStream(io::ZeroCopyOutputStream* output) const;
211 : // Serialize the message and store it in the given string. All required
212 : // fields must be set.
213 : bool SerializeToString(string* output) const;
214 : // Like SerializeToString(), but allows missing required fields.
215 : bool SerializePartialToString(string* output) const;
216 : // Serialize the message and store it in the given byte array. All required
217 : // fields must be set.
218 : bool SerializeToArray(void* data, int size) const;
219 : // Like SerializeToArray(), but allows missing required fields.
220 : bool SerializePartialToArray(void* data, int size) const;
221 :
222 : // Make a string encoding the message. Is equivalent to calling
223 : // SerializeToString() on a string and using that. Returns the empty
224 : // string if SerializeToString() would have returned an error.
225 : // Note: If you intend to generate many such strings, you may
226 : // reduce heap fragmentation by instead re-using the same string
227 : // object with calls to SerializeToString().
228 : string SerializeAsString() const;
229 : // Like SerializeAsString(), but allows missing required fields.
230 : string SerializePartialAsString() const;
231 :
232 : // Like SerializeToString(), but appends to the data to the string's existing
233 : // contents. All required fields must be set.
234 : bool AppendToString(string* output) const;
235 : // Like AppendToString(), but allows missing required fields.
236 : bool AppendPartialToString(string* output) const;
237 :
238 : // Computes the serialized size of the message. This recursively calls
239 : // ByteSize() on all embedded messages. If a subclass does not override
240 : // this, it MUST override SetCachedSize().
241 : //
242 : // ByteSize() is generally linear in the number of fields defined for the
243 : // proto.
244 : virtual int ByteSize() const = 0;
245 :
246 : // Serializes the message without recomputing the size. The message must
247 : // not have changed since the last call to ByteSize(); if it has, the results
248 : // are undefined.
249 : virtual void SerializeWithCachedSizes(
250 : io::CodedOutputStream* output) const = 0;
251 :
252 : // Like SerializeWithCachedSizes, but writes directly to *target, returning
253 : // a pointer to the byte immediately after the last byte written. "target"
254 : // must point at a byte array of at least ByteSize() bytes.
255 : virtual uint8* SerializeWithCachedSizesToArray(uint8* target) const;
256 :
257 : // Returns the result of the last call to ByteSize(). An embedded message's
258 : // size is needed both to serialize it (because embedded messages are
259 : // length-delimited) and to compute the outer message's size. Caching
260 : // the size avoids computing it multiple times.
261 : //
262 : // ByteSize() does not automatically use the cached size when available
263 : // because this would require invalidating it every time the message was
264 : // modified, which would be too hard and expensive. (E.g. if a deeply-nested
265 : // sub-message is changed, all of its parents' cached sizes would need to be
266 : // invalidated, which is too much work for an otherwise inlined setter
267 : // method.)
268 : virtual int GetCachedSize() const = 0;
269 :
270 : private:
271 : GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageLite);
272 : };
273 :
274 : } // namespace protobuf
275 :
276 : } // namespace google
277 : #endif // GOOGLE_PROTOBUF_MESSAGE_LITE_H__
|
