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