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 : 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 795 : 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__
|
