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 | |
44 | namespace google { |
45 | namespace protobuf { |
46 | |
47 | namespace 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. |
77 | class 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 | |