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 | // Author: [email protected] (Kenton Varda) |
32 | // Based on original Protocol Buffers design by |
33 | // Sanjay Ghemawat, Jeff Dean, and others. |
34 | // |
35 | // Defines Message, the abstract interface implemented by non-lite |
36 | // protocol message objects. Although it's possible to implement this |
37 | // interface manually, most users will use the protocol compiler to |
38 | // generate implementations. |
39 | // |
40 | // Example usage: |
41 | // |
42 | // Say you have a message defined as: |
43 | // |
44 | // message Foo { |
45 | // optional string text = 1; |
46 | // repeated int32 numbers = 2; |
47 | // } |
48 | // |
49 | // Then, if you used the protocol compiler to generate a class from the above |
50 | // definition, you could use it like so: |
51 | // |
52 | // string data; // Will store a serialized version of the message. |
53 | // |
54 | // { |
55 | // // Create a message and serialize it. |
56 | // Foo foo; |
57 | // foo.set_text("Hello World!"); |
58 | // foo.add_numbers(1); |
59 | // foo.add_numbers(5); |
60 | // foo.add_numbers(42); |
61 | // |
62 | // foo.SerializeToString(&data); |
63 | // } |
64 | // |
65 | // { |
66 | // // Parse the serialized message and check that it contains the |
67 | // // correct data. |
68 | // Foo foo; |
69 | // foo.ParseFromString(data); |
70 | // |
71 | // assert(foo.text() == "Hello World!"); |
72 | // assert(foo.numbers_size() == 3); |
73 | // assert(foo.numbers(0) == 1); |
74 | // assert(foo.numbers(1) == 5); |
75 | // assert(foo.numbers(2) == 42); |
76 | // } |
77 | // |
78 | // { |
79 | // // Same as the last block, but do it dynamically via the Message |
80 | // // reflection interface. |
81 | // Message* foo = new Foo; |
82 | // const Descriptor* descriptor = foo->GetDescriptor(); |
83 | // |
84 | // // Get the descriptors for the fields we're interested in and verify |
85 | // // their types. |
86 | // const FieldDescriptor* text_field = descriptor->FindFieldByName("text"); |
87 | // assert(text_field != NULL); |
88 | // assert(text_field->type() == FieldDescriptor::TYPE_STRING); |
89 | // assert(text_field->label() == FieldDescriptor::LABEL_OPTIONAL); |
90 | // const FieldDescriptor* numbers_field = descriptor-> |
91 | // FindFieldByName("numbers"); |
92 | // assert(numbers_field != NULL); |
93 | // assert(numbers_field->type() == FieldDescriptor::TYPE_INT32); |
94 | // assert(numbers_field->label() == FieldDescriptor::LABEL_REPEATED); |
95 | // |
96 | // // Parse the message. |
97 | // foo->ParseFromString(data); |
98 | // |
99 | // // Use the reflection interface to examine the contents. |
100 | // const Reflection* reflection = foo->GetReflection(); |
101 | // assert(reflection->GetString(foo, text_field) == "Hello World!"); |
102 | // assert(reflection->FieldSize(foo, numbers_field) == 3); |
103 | // assert(reflection->GetRepeatedInt32(foo, numbers_field, 0) == 1); |
104 | // assert(reflection->GetRepeatedInt32(foo, numbers_field, 1) == 5); |
105 | // assert(reflection->GetRepeatedInt32(foo, numbers_field, 2) == 42); |
106 | // |
107 | // delete foo; |
108 | // } |
109 | |
110 | #ifndef GOOGLE_PROTOBUF_MESSAGE_H__ |
111 | #define GOOGLE_PROTOBUF_MESSAGE_H__ |
112 | |
113 | #include <iosfwd> |
114 | #include <string> |
115 | #include <vector> |
116 | |
117 | #include <google/protobuf/message_lite.h> |
118 | |
119 | #include <google/protobuf/stubs/common.h> |
120 | #include <google/protobuf/descriptor.h> |
121 | |
122 | |
123 | #define GOOGLE_PROTOBUF_HAS_ONEOF |
124 | |
125 | namespace google { |
126 | namespace protobuf { |
127 | |
128 | // Defined in this file. |
129 | class Message; |
130 | class Reflection; |
131 | class MessageFactory; |
132 | |
133 | // Defined in other files. |
134 | class UnknownFieldSet; // unknown_field_set.h |
135 | namespace io { |
136 | class ZeroCopyInputStream; // zero_copy_stream.h |
137 | class ZeroCopyOutputStream; // zero_copy_stream.h |
138 | class CodedInputStream; // coded_stream.h |
139 | class CodedOutputStream; // coded_stream.h |
140 | } |
141 | |
142 | |
143 | template<typename T> |
144 | class RepeatedField; // repeated_field.h |
145 | |
146 | template<typename T> |
147 | class RepeatedPtrField; // repeated_field.h |
148 | |
149 | // A container to hold message metadata. |
150 | struct Metadata { |
151 | const Descriptor* descriptor; |
152 | const Reflection* reflection; |
153 | }; |
154 | |
155 | // Abstract interface for protocol messages. |
156 | // |
157 | // See also MessageLite, which contains most every-day operations. Message |
158 | // adds descriptors and reflection on top of that. |
159 | // |
160 | // The methods of this class that are virtual but not pure-virtual have |
161 | // default implementations based on reflection. Message classes which are |
162 | // optimized for speed will want to override these with faster implementations, |
163 | // but classes optimized for code size may be happy with keeping them. See |
164 | // the optimize_for option in descriptor.proto. |
165 | class LIBPROTOBUF_EXPORT Message : public MessageLite { |
166 | public: |
167 | inline Message() {} |
168 | virtual ~Message(); |
169 | |
170 | // Basic Operations ------------------------------------------------ |
171 | |
172 | // Construct a new instance of the same type. Ownership is passed to the |
173 | // caller. (This is also defined in MessageLite, but is defined again here |
174 | // for return-type covariance.) |
175 | virtual Message* New() const = 0; |
176 | |
177 | // Make this message into a copy of the given message. The given message |
178 | // must have the same descriptor, but need not necessarily be the same class. |
179 | // By default this is just implemented as "Clear(); MergeFrom(from);". |
180 | virtual void CopyFrom(const Message& from); |
181 | |
182 | // Merge the fields from the given message into this message. Singular |
183 | // fields will be overwritten, if specified in from, except for embedded |
184 | // messages which will be merged. Repeated fields will be concatenated. |
185 | // The given message must be of the same type as this message (i.e. the |
186 | // exact same class). |
187 | virtual void MergeFrom(const Message& from); |
188 | |
189 | // Verifies that IsInitialized() returns true. GOOGLE_CHECK-fails otherwise, with |
190 | // a nice error message. |
191 | void CheckInitialized() const; |
192 | |
193 | // Slowly build a list of all required fields that are not set. |
194 | // This is much, much slower than IsInitialized() as it is implemented |
195 | // purely via reflection. Generally, you should not call this unless you |
196 | // have already determined that an error exists by calling IsInitialized(). |
197 | void FindInitializationErrors(vector<string>* errors) const; |
198 | |
199 | // Like FindInitializationErrors, but joins all the strings, delimited by |
200 | // commas, and returns them. |
201 | string InitializationErrorString() const; |
202 | |
203 | // Clears all unknown fields from this message and all embedded messages. |
204 | // Normally, if unknown tag numbers are encountered when parsing a message, |
205 | // the tag and value are stored in the message's UnknownFieldSet and |
206 | // then written back out when the message is serialized. This allows servers |
207 | // which simply route messages to other servers to pass through messages |
208 | // that have new field definitions which they don't yet know about. However, |
209 | // this behavior can have security implications. To avoid it, call this |
210 | // method after parsing. |
211 | // |
212 | // See Reflection::GetUnknownFields() for more on unknown fields. |
213 | virtual void DiscardUnknownFields(); |
214 | |
215 | // Computes (an estimate of) the total number of bytes currently used for |
216 | // storing the message in memory. The default implementation calls the |
217 | // Reflection object's SpaceUsed() method. |
218 | virtual int SpaceUsed() const; |
219 | |
220 | // Debugging & Testing---------------------------------------------- |
221 | |
222 | // Generates a human readable form of this message, useful for debugging |
223 | // and other purposes. |
224 | string DebugString() const; |
225 | // Like DebugString(), but with less whitespace. |
226 | string ShortDebugString() const; |
227 | // Like DebugString(), but do not escape UTF-8 byte sequences. |
228 | string Utf8DebugString() const; |
229 | // Convenience function useful in GDB. Prints DebugString() to stdout. |
230 | void PrintDebugString() const; |
231 | |
232 | // Heavy I/O ------------------------------------------------------- |
233 | // Additional parsing and serialization methods not implemented by |
234 | // MessageLite because they are not supported by the lite library. |
235 | |
236 | // Parse a protocol buffer from a file descriptor. If successful, the entire |
237 | // input will be consumed. |
238 | bool ParseFromFileDescriptor(int file_descriptor); |
239 | // Like ParseFromFileDescriptor(), but accepts messages that are missing |
240 | // required fields. |
241 | bool ParsePartialFromFileDescriptor(int file_descriptor); |
242 | // Parse a protocol buffer from a C++ istream. If successful, the entire |
243 | // input will be consumed. |
244 | bool ParseFromIstream(istream* input); |
245 | // Like ParseFromIstream(), but accepts messages that are missing |
246 | // required fields. |
247 | bool ParsePartialFromIstream(istream* input); |
248 | |
249 | // Serialize the message and write it to the given file descriptor. All |
250 | // required fields must be set. |
251 | bool SerializeToFileDescriptor(int file_descriptor) const; |
252 | // Like SerializeToFileDescriptor(), but allows missing required fields. |
253 | bool SerializePartialToFileDescriptor(int file_descriptor) const; |
254 | // Serialize the message and write it to the given C++ ostream. All |
255 | // required fields must be set. |
256 | bool SerializeToOstream(ostream* output) const; |
257 | // Like SerializeToOstream(), but allows missing required fields. |
258 | bool SerializePartialToOstream(ostream* output) const; |
259 | |
260 | |
261 | // Reflection-based methods ---------------------------------------- |
262 | // These methods are pure-virtual in MessageLite, but Message provides |
263 | // reflection-based default implementations. |
264 | |
265 | virtual string GetTypeName() const; |
266 | virtual void Clear(); |
267 | virtual bool IsInitialized() const; |
268 | virtual void CheckTypeAndMergeFrom(const MessageLite& other); |
269 | virtual bool MergePartialFromCodedStream(io::CodedInputStream* input); |
270 | virtual int ByteSize() const; |
271 | virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const; |
272 | |
273 | private: |
274 | // This is called only by the default implementation of ByteSize(), to |
275 | // update the cached size. If you override ByteSize(), you do not need |
276 | // to override this. If you do not override ByteSize(), you MUST override |
277 | // this; the default implementation will crash. |
278 | // |
279 | // The method is private because subclasses should never call it; only |
280 | // override it. Yes, C++ lets you do that. Crazy, huh? |
281 | virtual void SetCachedSize(int size) const; |
282 | |
283 | public: |
284 | |
285 | // Introspection --------------------------------------------------- |
286 | |
287 | // Typedef for backwards-compatibility. |
288 | typedef google::protobuf::Reflection Reflection; |
289 | |
290 | // Get a Descriptor for this message's type. This describes what |
291 | // fields the message contains, the types of those fields, etc. |
292 | const Descriptor* GetDescriptor() const { return GetMetadata().descriptor; } |
293 | |
294 | // Get the Reflection interface for this Message, which can be used to |
295 | // read and modify the fields of the Message dynamically (in other words, |
296 | // without knowing the message type at compile time). This object remains |
297 | // property of the Message. |
298 | // |
299 | // This method remains virtual in case a subclass does not implement |
300 | // reflection and wants to override the default behavior. |
301 | virtual const Reflection* GetReflection() const { |
302 | return GetMetadata().reflection; |
303 | } |
304 | |
305 | protected: |
306 | // Get a struct containing the metadata for the Message. Most subclasses only |
307 | // need to implement this method, rather than the GetDescriptor() and |
308 | // GetReflection() wrappers. |
309 | virtual Metadata GetMetadata() const = 0; |
310 | |
311 | |
312 | private: |
313 | GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Message); |
314 | }; |
315 | |
316 | // This interface contains methods that can be used to dynamically access |
317 | // and modify the fields of a protocol message. Their semantics are |
318 | // similar to the accessors the protocol compiler generates. |
319 | // |
320 | // To get the Reflection for a given Message, call Message::GetReflection(). |
321 | // |
322 | // This interface is separate from Message only for efficiency reasons; |
323 | // the vast majority of implementations of Message will share the same |
324 | // implementation of Reflection (GeneratedMessageReflection, |
325 | // defined in generated_message.h), and all Messages of a particular class |
326 | // should share the same Reflection object (though you should not rely on |
327 | // the latter fact). |
328 | // |
329 | // There are several ways that these methods can be used incorrectly. For |
330 | // example, any of the following conditions will lead to undefined |
331 | // results (probably assertion failures): |
332 | // - The FieldDescriptor is not a field of this message type. |
333 | // - The method called is not appropriate for the field's type. For |
334 | // each field type in FieldDescriptor::TYPE_*, there is only one |
335 | // Get*() method, one Set*() method, and one Add*() method that is |
336 | // valid for that type. It should be obvious which (except maybe |
337 | // for TYPE_BYTES, which are represented using strings in C++). |
338 | // - A Get*() or Set*() method for singular fields is called on a repeated |
339 | // field. |
340 | // - GetRepeated*(), SetRepeated*(), or Add*() is called on a non-repeated |
341 | // field. |
342 | // - The Message object passed to any method is not of the right type for |
343 | // this Reflection object (i.e. message.GetReflection() != reflection). |
344 | // |
345 | // You might wonder why there is not any abstract representation for a field |
346 | // of arbitrary type. E.g., why isn't there just a "GetField()" method that |
347 | // returns "const Field&", where "Field" is some class with accessors like |
348 | // "GetInt32Value()". The problem is that someone would have to deal with |
349 | // allocating these Field objects. For generated message classes, having to |
350 | // allocate space for an additional object to wrap every field would at least |
351 | // double the message's memory footprint, probably worse. Allocating the |
352 | // objects on-demand, on the other hand, would be expensive and prone to |
353 | // memory leaks. So, instead we ended up with this flat interface. |
354 | // |
355 | // TODO(kenton): Create a utility class which callers can use to read and |
356 | // write fields from a Reflection without paying attention to the type. |
357 | class LIBPROTOBUF_EXPORT Reflection { |
358 | public: |
359 | inline Reflection() {} |
360 | virtual ~Reflection(); |
361 | |
362 | // Get the UnknownFieldSet for the message. This contains fields which |
363 | // were seen when the Message was parsed but were not recognized according |
364 | // to the Message's definition. |
365 | virtual const UnknownFieldSet& GetUnknownFields( |
366 | const Message& message) const = 0; |
367 | // Get a mutable pointer to the UnknownFieldSet for the message. This |
368 | // contains fields which were seen when the Message was parsed but were not |
369 | // recognized according to the Message's definition. |
370 | virtual UnknownFieldSet* MutableUnknownFields(Message* message) const = 0; |
371 | |
372 | // Estimate the amount of memory used by the message object. |
373 | virtual int SpaceUsed(const Message& message) const = 0; |
374 | |
375 | // Check if the given non-repeated field is set. |
376 | virtual bool HasField(const Message& message, |
377 | const FieldDescriptor* field) const = 0; |
378 | |
379 | // Get the number of elements of a repeated field. |
380 | virtual int FieldSize(const Message& message, |
381 | const FieldDescriptor* field) const = 0; |
382 | |
383 | // Clear the value of a field, so that HasField() returns false or |
384 | // FieldSize() returns zero. |
385 | virtual void ClearField(Message* message, |
386 | const FieldDescriptor* field) const = 0; |
387 | |
388 | // Check if the oneof is set. Returns ture if any field in oneof |
389 | // is set, false otherwise. |
390 | // TODO(jieluo) - make it pure virtual after updating all |
391 | // the subclasses. |
392 | virtual bool HasOneof(const Message& message, |
393 | const OneofDescriptor* oneof_descriptor) const { |
394 | return false; |
395 | } |
396 | |
397 | virtual void ClearOneof(Message* message, |
398 | const OneofDescriptor* oneof_descriptor) const {} |
399 | |
400 | // Returns the field descriptor if the oneof is set. NULL otherwise. |
401 | // TODO(jieluo) - make it pure virtual. |
402 | virtual const FieldDescriptor* GetOneofFieldDescriptor( |
403 | const Message& message, |
404 | const OneofDescriptor* oneof_descriptor) const { |
405 | return NULL; |
406 | } |
407 | |
408 | // Removes the last element of a repeated field. |
409 | // We don't provide a way to remove any element other than the last |
410 | // because it invites inefficient use, such as O(n^2) filtering loops |
411 | // that should have been O(n). If you want to remove an element other |
412 | // than the last, the best way to do it is to re-arrange the elements |
413 | // (using Swap()) so that the one you want removed is at the end, then |
414 | // call RemoveLast(). |
415 | virtual void RemoveLast(Message* message, |
416 | const FieldDescriptor* field) const = 0; |
417 | // Removes the last element of a repeated message field, and returns the |
418 | // pointer to the caller. Caller takes ownership of the returned pointer. |
419 | virtual Message* ReleaseLast(Message* message, |
420 | const FieldDescriptor* field) const = 0; |
421 | |
422 | // Swap the complete contents of two messages. |
423 | virtual void Swap(Message* message1, Message* message2) const = 0; |
424 | |
425 | // Swap fields listed in fields vector of two messages. |
426 | virtual void SwapFields(Message* message1, |
427 | Message* message2, |
428 | const vector<const FieldDescriptor*>& fields) |
429 | const = 0; |
430 | |
431 | // Swap two elements of a repeated field. |
432 | virtual void SwapElements(Message* message, |
433 | const FieldDescriptor* field, |
434 | int index1, |
435 | int index2) const = 0; |
436 | |
437 | // List all fields of the message which are currently set. This includes |
438 | // extensions. Singular fields will only be listed if HasField(field) would |
439 | // return true and repeated fields will only be listed if FieldSize(field) |
440 | // would return non-zero. Fields (both normal fields and extension fields) |
441 | // will be listed ordered by field number. |
442 | virtual void ListFields(const Message& message, |
443 | vector<const FieldDescriptor*>* output) const = 0; |
444 | |
445 | // Singular field getters ------------------------------------------ |
446 | // These get the value of a non-repeated field. They return the default |
447 | // value for fields that aren't set. |
448 | |
449 | virtual int32 GetInt32 (const Message& message, |
450 | const FieldDescriptor* field) const = 0; |
451 | virtual int64 GetInt64 (const Message& message, |
452 | const FieldDescriptor* field) const = 0; |
453 | virtual uint32 GetUInt32(const Message& message, |
454 | const FieldDescriptor* field) const = 0; |
455 | virtual uint64 GetUInt64(const Message& message, |
456 | const FieldDescriptor* field) const = 0; |
457 | virtual float GetFloat (const Message& message, |
458 | const FieldDescriptor* field) const = 0; |
459 | virtual double GetDouble(const Message& message, |
460 | const FieldDescriptor* field) const = 0; |
461 | virtual bool GetBool (const Message& message, |
462 | const FieldDescriptor* field) const = 0; |
463 | virtual string GetString(const Message& message, |
464 | const FieldDescriptor* field) const = 0; |
465 | virtual const EnumValueDescriptor* GetEnum( |
466 | const Message& message, const FieldDescriptor* field) const = 0; |
467 | // See MutableMessage() for the meaning of the "factory" parameter. |
468 | virtual const Message& GetMessage(const Message& message, |
469 | const FieldDescriptor* field, |
470 | MessageFactory* factory = NULL) const = 0; |
471 | |
472 | // Get a string value without copying, if possible. |
473 | // |
474 | // GetString() necessarily returns a copy of the string. This can be |
475 | // inefficient when the string is already stored in a string object in the |
476 | // underlying message. GetStringReference() will return a reference to the |
477 | // underlying string in this case. Otherwise, it will copy the string into |
478 | // *scratch and return that. |
479 | // |
480 | // Note: It is perfectly reasonable and useful to write code like: |
481 | // str = reflection->GetStringReference(field, &str); |
482 | // This line would ensure that only one copy of the string is made |
483 | // regardless of the field's underlying representation. When initializing |
484 | // a newly-constructed string, though, it's just as fast and more readable |
485 | // to use code like: |
486 | // string str = reflection->GetString(field); |
487 | virtual const string& GetStringReference(const Message& message, |
488 | const FieldDescriptor* field, |
489 | string* scratch) const = 0; |
490 | |
491 | |
492 | // Singular field mutators ----------------------------------------- |
493 | // These mutate the value of a non-repeated field. |
494 | |
495 | virtual void SetInt32 (Message* message, |
496 | const FieldDescriptor* field, int32 value) const = 0; |
497 | virtual void SetInt64 (Message* message, |
498 | const FieldDescriptor* field, int64 value) const = 0; |
499 | virtual void SetUInt32(Message* message, |
500 | const FieldDescriptor* field, uint32 value) const = 0; |
501 | virtual void SetUInt64(Message* message, |
502 | const FieldDescriptor* field, uint64 value) const = 0; |
503 | virtual void SetFloat (Message* message, |
504 | const FieldDescriptor* field, float value) const = 0; |
505 | virtual void SetDouble(Message* message, |
506 | const FieldDescriptor* field, double value) const = 0; |
507 | virtual void SetBool (Message* message, |
508 | const FieldDescriptor* field, bool value) const = 0; |
509 | virtual void SetString(Message* message, |
510 | const FieldDescriptor* field, |
511 | const string& value) const = 0; |
512 | virtual void SetEnum (Message* message, |
513 | const FieldDescriptor* field, |
514 | const EnumValueDescriptor* value) const = 0; |
515 | // Get a mutable pointer to a field with a message type. If a MessageFactory |
516 | // is provided, it will be used to construct instances of the sub-message; |
517 | // otherwise, the default factory is used. If the field is an extension that |
518 | // does not live in the same pool as the containing message's descriptor (e.g. |
519 | // it lives in an overlay pool), then a MessageFactory must be provided. |
520 | // If you have no idea what that meant, then you probably don't need to worry |
521 | // about it (don't provide a MessageFactory). WARNING: If the |
522 | // FieldDescriptor is for a compiled-in extension, then |
523 | // factory->GetPrototype(field->message_type() MUST return an instance of the |
524 | // compiled-in class for this type, NOT DynamicMessage. |
525 | virtual Message* MutableMessage(Message* message, |
526 | const FieldDescriptor* field, |
527 | MessageFactory* factory = NULL) const = 0; |
528 | // Replaces the message specified by 'field' with the already-allocated object |
529 | // sub_message, passing ownership to the message. If the field contained a |
530 | // message, that message is deleted. If sub_message is NULL, the field is |
531 | // cleared. |
532 | virtual void SetAllocatedMessage(Message* message, |
533 | Message* sub_message, |
534 | const FieldDescriptor* field) const = 0; |
535 | // Releases the message specified by 'field' and returns the pointer, |
536 | // ReleaseMessage() will return the message the message object if it exists. |
537 | // Otherwise, it may or may not return NULL. In any case, if the return value |
538 | // is non-NULL, the caller takes ownership of the pointer. |
539 | // If the field existed (HasField() is true), then the returned pointer will |
540 | // be the same as the pointer returned by MutableMessage(). |
541 | // This function has the same effect as ClearField(). |
542 | virtual Message* ReleaseMessage(Message* message, |
543 | const FieldDescriptor* field, |
544 | MessageFactory* factory = NULL) const = 0; |
545 | |
546 | |
547 | // Repeated field getters ------------------------------------------ |
548 | // These get the value of one element of a repeated field. |
549 | |
550 | virtual int32 GetRepeatedInt32 (const Message& message, |
551 | const FieldDescriptor* field, |
552 | int index) const = 0; |
553 | virtual int64 GetRepeatedInt64 (const Message& message, |
554 | const FieldDescriptor* field, |
555 | int index) const = 0; |
556 | virtual uint32 GetRepeatedUInt32(const Message& message, |
557 | const FieldDescriptor* field, |
558 | int index) const = 0; |
559 | virtual uint64 GetRepeatedUInt64(const Message& message, |
560 | const FieldDescriptor* field, |
561 | int index) const = 0; |
562 | virtual float GetRepeatedFloat (const Message& message, |
563 | const FieldDescriptor* field, |
564 | int index) const = 0; |
565 | virtual double GetRepeatedDouble(const Message& message, |
566 | const FieldDescriptor* field, |
567 | int index) const = 0; |
568 | virtual bool GetRepeatedBool (const Message& message, |
569 | const FieldDescriptor* field, |
570 | int index) const = 0; |
571 | virtual string GetRepeatedString(const Message& message, |
572 | const FieldDescriptor* field, |
573 | int index) const = 0; |
574 | virtual const EnumValueDescriptor* GetRepeatedEnum( |
575 | const Message& message, |
576 | const FieldDescriptor* field, int index) const = 0; |
577 | virtual const Message& GetRepeatedMessage( |
578 | const Message& message, |
579 | const FieldDescriptor* field, int index) const = 0; |
580 | |
581 | // See GetStringReference(), above. |
582 | virtual const string& GetRepeatedStringReference( |
583 | const Message& message, const FieldDescriptor* field, |
584 | int index, string* scratch) const = 0; |
585 | |
586 | |
587 | // Repeated field mutators ----------------------------------------- |
588 | // These mutate the value of one element of a repeated field. |
589 | |
590 | virtual void SetRepeatedInt32 (Message* message, |
591 | const FieldDescriptor* field, |
592 | int index, int32 value) const = 0; |
593 | virtual void SetRepeatedInt64 (Message* message, |
594 | const FieldDescriptor* field, |
595 | int index, int64 value) const = 0; |
596 | virtual void SetRepeatedUInt32(Message* message, |
597 | const FieldDescriptor* field, |
598 | int index, uint32 value) const = 0; |
599 | virtual void SetRepeatedUInt64(Message* message, |
600 | const FieldDescriptor* field, |
601 | int index, uint64 value) const = 0; |
602 | virtual void SetRepeatedFloat (Message* message, |
603 | const FieldDescriptor* field, |
604 | int index, float value) const = 0; |
605 | virtual void SetRepeatedDouble(Message* message, |
606 | const FieldDescriptor* field, |
607 | int index, double value) const = 0; |
608 | virtual void SetRepeatedBool (Message* message, |
609 | const FieldDescriptor* field, |
610 | int index, bool value) const = 0; |
611 | virtual void SetRepeatedString(Message* message, |
612 | const FieldDescriptor* field, |
613 | int index, const string& value) const = 0; |
614 | virtual void SetRepeatedEnum(Message* message, |
615 | const FieldDescriptor* field, int index, |
616 | const EnumValueDescriptor* value) const = 0; |
617 | // Get a mutable pointer to an element of a repeated field with a message |
618 | // type. |
619 | virtual Message* MutableRepeatedMessage( |
620 | Message* message, const FieldDescriptor* field, int index) const = 0; |
621 | |
622 | |
623 | // Repeated field adders ------------------------------------------- |
624 | // These add an element to a repeated field. |
625 | |
626 | virtual void AddInt32 (Message* message, |
627 | const FieldDescriptor* field, int32 value) const = 0; |
628 | virtual void AddInt64 (Message* message, |
629 | const FieldDescriptor* field, int64 value) const = 0; |
630 | virtual void AddUInt32(Message* message, |
631 | const FieldDescriptor* field, uint32 value) const = 0; |
632 | virtual void AddUInt64(Message* message, |
633 | const FieldDescriptor* field, uint64 value) const = 0; |
634 | virtual void AddFloat (Message* message, |
635 | const FieldDescriptor* field, float value) const = 0; |
636 | virtual void AddDouble(Message* message, |
637 | const FieldDescriptor* field, double value) const = 0; |
638 | virtual void AddBool (Message* message, |
639 | const FieldDescriptor* field, bool value) const = 0; |
640 | virtual void AddString(Message* message, |
641 | const FieldDescriptor* field, |
642 | const string& value) const = 0; |
643 | virtual void AddEnum (Message* message, |
644 | const FieldDescriptor* field, |
645 | const EnumValueDescriptor* value) const = 0; |
646 | // See MutableMessage() for comments on the "factory" parameter. |
647 | virtual Message* AddMessage(Message* message, |
648 | const FieldDescriptor* field, |
649 | MessageFactory* factory = NULL) const = 0; |
650 | |
651 | |
652 | // Repeated field accessors ------------------------------------------------- |
653 | // The methods above, e.g. GetRepeatedInt32(msg, fd, index), provide singular |
654 | // access to the data in a RepeatedField. The methods below provide aggregate |
655 | // access by exposing the RepeatedField object itself with the Message. |
656 | // Applying these templates to inappropriate types will lead to an undefined |
657 | // reference at link time (e.g. GetRepeatedField<***double>), or possibly a |
658 | // template matching error at compile time (e.g. GetRepeatedPtrField<File>). |
659 | // |
660 | // Usage example: my_doubs = refl->GetRepeatedField<double>(msg, fd); |
661 | |
662 | // for T = Cord and all protobuf scalar types except enums. |
663 | template<typename T> |
664 | const RepeatedField<T>& GetRepeatedField( |
665 | const Message&, const FieldDescriptor*) const; |
666 | |
667 | // for T = Cord and all protobuf scalar types except enums. |
668 | template<typename T> |
669 | RepeatedField<T>* MutableRepeatedField( |
670 | Message*, const FieldDescriptor*) const; |
671 | |
672 | // for T = string, google::protobuf::internal::StringPieceField |
673 | // google::protobuf::Message & descendants. |
674 | template<typename T> |
675 | const RepeatedPtrField<T>& GetRepeatedPtrField( |
676 | const Message&, const FieldDescriptor*) const; |
677 | |
678 | // for T = string, google::protobuf::internal::StringPieceField |
679 | // google::protobuf::Message & descendants. |
680 | template<typename T> |
681 | RepeatedPtrField<T>* MutableRepeatedPtrField( |
682 | Message*, const FieldDescriptor*) const; |
683 | |
684 | // Extensions ---------------------------------------------------------------- |
685 | |
686 | // Try to find an extension of this message type by fully-qualified field |
687 | // name. Returns NULL if no extension is known for this name or number. |
688 | virtual const FieldDescriptor* FindKnownExtensionByName( |
689 | const string& name) const = 0; |
690 | |
691 | // Try to find an extension of this message type by field number. |
692 | // Returns NULL if no extension is known for this name or number. |
693 | virtual const FieldDescriptor* FindKnownExtensionByNumber( |
694 | int number) const = 0; |
695 | |
696 | // --------------------------------------------------------------------------- |
697 | |
698 | protected: |
699 | // Obtain a pointer to a Repeated Field Structure and do some type checking: |
700 | // on field->cpp_type(), |
701 | // on field->field_option().ctype() (if ctype >= 0) |
702 | // of field->message_type() (if message_type != NULL). |
703 | // We use 1 routine rather than 4 (const vs mutable) x (scalar vs pointer). |
704 | virtual void* MutableRawRepeatedField( |
705 | Message* message, const FieldDescriptor* field, FieldDescriptor::CppType, |
706 | int ctype, const Descriptor* message_type) const = 0; |
707 | |
708 | private: |
709 | // Special version for specialized implementations of string. We can't call |
710 | // MutableRawRepeatedField directly here because we don't have access to |
711 | // FieldOptions::* which are defined in descriptor.pb.h. Including that |
712 | // file here is not possible because it would cause a circular include cycle. |
713 | void* MutableRawRepeatedString( |
714 | Message* message, const FieldDescriptor* field, bool is_string) const; |
715 | |
716 | GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Reflection); |
717 | }; |
718 | |
719 | // Abstract interface for a factory for message objects. |
720 | class LIBPROTOBUF_EXPORT MessageFactory { |
721 | public: |
722 | inline MessageFactory() {} |
723 | virtual ~MessageFactory(); |
724 | |
725 | // Given a Descriptor, gets or constructs the default (prototype) Message |
726 | // of that type. You can then call that message's New() method to construct |
727 | // a mutable message of that type. |
728 | // |
729 | // Calling this method twice with the same Descriptor returns the same |
730 | // object. The returned object remains property of the factory. Also, any |
731 | // objects created by calling the prototype's New() method share some data |
732 | // with the prototype, so these must be destroyed before the MessageFactory |
733 | // is destroyed. |
734 | // |
735 | // The given descriptor must outlive the returned message, and hence must |
736 | // outlive the MessageFactory. |
737 | // |
738 | // Some implementations do not support all types. GetPrototype() will |
739 | // return NULL if the descriptor passed in is not supported. |
740 | // |
741 | // This method may or may not be thread-safe depending on the implementation. |
742 | // Each implementation should document its own degree thread-safety. |
743 | virtual const Message* GetPrototype(const Descriptor* type) = 0; |
744 | |
745 | // Gets a MessageFactory which supports all generated, compiled-in messages. |
746 | // In other words, for any compiled-in type FooMessage, the following is true: |
747 | // MessageFactory::generated_factory()->GetPrototype( |
748 | // FooMessage::descriptor()) == FooMessage::default_instance() |
749 | // This factory supports all types which are found in |
750 | // DescriptorPool::generated_pool(). If given a descriptor from any other |
751 | // pool, GetPrototype() will return NULL. (You can also check if a |
752 | // descriptor is for a generated message by checking if |
753 | // descriptor->file()->pool() == DescriptorPool::generated_pool().) |
754 | // |
755 | // This factory is 100% thread-safe; calling GetPrototype() does not modify |
756 | // any shared data. |
757 | // |
758 | // This factory is a singleton. The caller must not delete the object. |
759 | static MessageFactory* generated_factory(); |
760 | |
761 | // For internal use only: Registers a .proto file at static initialization |
762 | // time, to be placed in generated_factory. The first time GetPrototype() |
763 | // is called with a descriptor from this file, |register_messages| will be |
764 | // called, with the file name as the parameter. It must call |
765 | // InternalRegisterGeneratedMessage() (below) to register each message type |
766 | // in the file. This strange mechanism is necessary because descriptors are |
767 | // built lazily, so we can't register types by their descriptor until we |
768 | // know that the descriptor exists. |filename| must be a permanent string. |
769 | static void InternalRegisterGeneratedFile( |
770 | const char* filename, void (*register_messages)(const string&)); |
771 | |
772 | // For internal use only: Registers a message type. Called only by the |
773 | // functions which are registered with InternalRegisterGeneratedFile(), |
774 | // above. |
775 | static void InternalRegisterGeneratedMessage(const Descriptor* descriptor, |
776 | const Message* prototype); |
777 | |
778 | |
779 | private: |
780 | GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageFactory); |
781 | }; |
782 | |
783 | #define DECLARE_GET_REPEATED_FIELD(TYPE) \ |
784 | template<> \ |
785 | LIBPROTOBUF_EXPORT \ |
786 | const RepeatedField<TYPE>& Reflection::GetRepeatedField<TYPE>( \ |
787 | const Message& message, const FieldDescriptor* field) const; \ |
788 | \ |
789 | template<> \ |
790 | RepeatedField<TYPE>* Reflection::MutableRepeatedField<TYPE>( \ |
791 | Message* message, const FieldDescriptor* field) const; |
792 | |
793 | DECLARE_GET_REPEATED_FIELD(int32) |
794 | DECLARE_GET_REPEATED_FIELD(int64) |
795 | DECLARE_GET_REPEATED_FIELD(uint32) |
796 | DECLARE_GET_REPEATED_FIELD(uint64) |
797 | DECLARE_GET_REPEATED_FIELD(float) |
798 | DECLARE_GET_REPEATED_FIELD(double) |
799 | DECLARE_GET_REPEATED_FIELD(bool) |
800 | |
801 | #undef DECLARE_GET_REPEATED_FIELD |
802 | |
803 | // ============================================================================= |
804 | // Implementation details for {Get,Mutable}RawRepeatedPtrField. We provide |
805 | // specializations for <string>, <StringPieceField> and <Message> and handle |
806 | // everything else with the default template which will match any type having |
807 | // a method with signature "static const google::protobuf::Descriptor* descriptor()". |
808 | // Such a type presumably is a descendant of google::protobuf::Message. |
809 | |
810 | template<> |
811 | inline const RepeatedPtrField<string>& Reflection::GetRepeatedPtrField<string>( |
812 | const Message& message, const FieldDescriptor* field) const { |
813 | return *static_cast<RepeatedPtrField<string>* >( |
814 | MutableRawRepeatedString(const_cast<Message*>(&message), field, true)); |
815 | } |
816 | |
817 | template<> |
818 | inline RepeatedPtrField<string>* Reflection::MutableRepeatedPtrField<string>( |
819 | Message* message, const FieldDescriptor* field) const { |
820 | return static_cast<RepeatedPtrField<string>* >( |
821 | MutableRawRepeatedString(message, field, true)); |
822 | } |
823 | |
824 | |
825 | // ----- |
826 | |
827 | template<> |
828 | inline const RepeatedPtrField<Message>& Reflection::GetRepeatedPtrField( |
829 | const Message& message, const FieldDescriptor* field) const { |
830 | return *static_cast<RepeatedPtrField<Message>* >( |
831 | MutableRawRepeatedField(const_cast<Message*>(&message), field, |
832 | FieldDescriptor::CPPTYPE_MESSAGE, -1, |
833 | NULL)); |
834 | } |
835 | |
836 | template<> |
837 | inline RepeatedPtrField<Message>* Reflection::MutableRepeatedPtrField( |
838 | Message* message, const FieldDescriptor* field) const { |
839 | return static_cast<RepeatedPtrField<Message>* >( |
840 | MutableRawRepeatedField(message, field, |
841 | FieldDescriptor::CPPTYPE_MESSAGE, -1, |
842 | NULL)); |
843 | } |
844 | |
845 | template<typename PB> |
846 | inline const RepeatedPtrField<PB>& Reflection::GetRepeatedPtrField( |
847 | const Message& message, const FieldDescriptor* field) const { |
848 | return *static_cast<RepeatedPtrField<PB>* >( |
849 | MutableRawRepeatedField(const_cast<Message*>(&message), field, |
850 | FieldDescriptor::CPPTYPE_MESSAGE, -1, |
851 | PB::default_instance().GetDescriptor())); |
852 | } |
853 | |
854 | template<typename PB> |
855 | inline RepeatedPtrField<PB>* Reflection::MutableRepeatedPtrField( |
856 | Message* message, const FieldDescriptor* field) const { |
857 | return static_cast<RepeatedPtrField<PB>* >( |
858 | MutableRawRepeatedField(message, field, |
859 | FieldDescriptor::CPPTYPE_MESSAGE, -1, |
860 | PB::default_instance().GetDescriptor())); |
861 | } |
862 | |
863 | } // namespace protobuf |
864 | |
865 | } // namespace google |
866 | #endif // GOOGLE_PROTOBUF_MESSAGE_H__ |
867 | |