PageRenderTime 58ms CodeModel.GetById 14ms app.highlight 35ms RepoModel.GetById 1ms app.codeStats 1ms

/thirdparty/breakpad/third_party/protobuf/protobuf/src/google/protobuf/message.h

http://github.com/tomahawk-player/tomahawk
C++ Header | 692 lines | 255 code | 78 blank | 359 comment | 0 complexity | 5282982d871a979fd1d8f4f24259644b MD5 | raw file
  1// Protocol Buffers - Google's data interchange format
  2// Copyright 2008 Google Inc.  All rights reserved.
  3// http://code.google.com/p/protobuf/
  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: kenton@google.com (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//     Descriptor* descriptor = foo->GetDescriptor();
 83//
 84//     // Get the descriptors for the fields we're interested in and verify
 85//     // their types.
 86//     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::TYPE_OPTIONAL);
 90//     FieldDescriptor* numbers_field = descriptor->FindFieldByName("numbers");
 91//     assert(numbers_field != NULL);
 92//     assert(numbers_field->type() == FieldDescriptor::TYPE_INT32);
 93//     assert(numbers_field->label() == FieldDescriptor::TYPE_REPEATED);
 94//
 95//     // Parse the message.
 96//     foo->ParseFromString(data);
 97//
 98//     // Use the reflection interface to examine the contents.
 99//     const Reflection* reflection = foo->GetReflection();
100//     assert(reflection->GetString(foo, text_field) == "Hello World!");
101//     assert(reflection->FieldSize(foo, numbers_field) == 3);
102//     assert(reflection->GetRepeatedInt32(foo, numbers_field, 0) == 1);
103//     assert(reflection->GetRepeatedInt32(foo, numbers_field, 1) == 5);
104//     assert(reflection->GetRepeatedInt32(foo, numbers_field, 2) == 42);
105//
106//     delete foo;
107//   }
108
109#ifndef GOOGLE_PROTOBUF_MESSAGE_H__
110#define GOOGLE_PROTOBUF_MESSAGE_H__
111
112#include <vector>
113#include <string>
114
115#ifdef __DECCXX
116// HP C++'s iosfwd doesn't work.
117#include <iostream>
118#else
119#include <iosfwd>
120#endif
121
122#include <google/protobuf/message_lite.h>
123
124#include <google/protobuf/stubs/common.h>
125
126
127namespace google {
128namespace protobuf {
129
130// Defined in this file.
131class Message;
132class Reflection;
133class MessageFactory;
134
135// Defined in other files.
136class Descriptor;            // descriptor.h
137class FieldDescriptor;       // descriptor.h
138class EnumDescriptor;        // descriptor.h
139class EnumValueDescriptor;   // descriptor.h
140namespace io {
141  class ZeroCopyInputStream;   // zero_copy_stream.h
142  class ZeroCopyOutputStream;  // zero_copy_stream.h
143  class CodedInputStream;      // coded_stream.h
144  class CodedOutputStream;     // coded_stream.h
145}
146class UnknownFieldSet;       // unknown_field_set.h
147
148// A container to hold message metadata.
149struct Metadata {
150  const Descriptor* descriptor;
151  const Reflection* reflection;
152};
153
154// Returns the EnumDescriptor for enum type E, which must be a
155// proto-declared enum type.  Code generated by the protocol compiler
156// will include specializations of this template for each enum type declared.
157template <typename E>
158const EnumDescriptor* GetEnumDescriptor();
159
160// Abstract interface for protocol messages.
161//
162// See also MessageLite, which contains most every-day operations.  Message
163// adds descriptors and reflection on top of that.
164//
165// The methods of this class that are virtual but not pure-virtual have
166// default implementations based on reflection.  Message classes which are
167// optimized for speed will want to override these with faster implementations,
168// but classes optimized for code size may be happy with keeping them.  See
169// the optimize_for option in descriptor.proto.
170class LIBPROTOBUF_EXPORT Message : public MessageLite {
171 public:
172  inline Message() {}
173  virtual ~Message();
174
175  // Basic Operations ------------------------------------------------
176
177  // Construct a new instance of the same type.  Ownership is passed to the
178  // caller.  (This is also defined in MessageLite, but is defined again here
179  // for return-type covariance.)
180  virtual Message* New() const = 0;
181
182  // Make this message into a copy of the given message.  The given message
183  // must have the same descriptor, but need not necessarily be the same class.
184  // By default this is just implemented as "Clear(); MergeFrom(from);".
185  virtual void CopyFrom(const Message& from);
186
187  // Merge the fields from the given message into this message.  Singular
188  // fields will be overwritten, except for embedded messages which will
189  // be merged.  Repeated fields will be concatenated.  The given message
190  // must be of the same type as this message (i.e. the exact same class).
191  virtual void MergeFrom(const Message& from);
192
193  // Verifies that IsInitialized() returns true.  GOOGLE_CHECK-fails otherwise, with
194  // a nice error message.
195  void CheckInitialized() const;
196
197  // Slowly build a list of all required fields that are not set.
198  // This is much, much slower than IsInitialized() as it is implemented
199  // purely via reflection.  Generally, you should not call this unless you
200  // have already determined that an error exists by calling IsInitialized().
201  void FindInitializationErrors(vector<string>* errors) const;
202
203  // Like FindInitializationErrors, but joins all the strings, delimited by
204  // commas, and returns them.
205  string InitializationErrorString() const;
206
207  // Clears all unknown fields from this message and all embedded messages.
208  // Normally, if unknown tag numbers are encountered when parsing a message,
209  // the tag and value are stored in the message's UnknownFieldSet and
210  // then written back out when the message is serialized.  This allows servers
211  // which simply route messages to other servers to pass through messages
212  // that have new field definitions which they don't yet know about.  However,
213  // this behavior can have security implications.  To avoid it, call this
214  // method after parsing.
215  //
216  // See Reflection::GetUnknownFields() for more on unknown fields.
217  virtual void DiscardUnknownFields();
218
219  // Computes (an estimate of) the total number of bytes currently used for
220  // storing the message in memory.  The default implementation calls the
221  // Reflection object's SpaceUsed() method.
222  virtual int SpaceUsed() const;
223
224  // Debugging & Testing----------------------------------------------
225
226  // Generates a human readable form of this message, useful for debugging
227  // and other purposes.
228  string DebugString() const;
229  // Like DebugString(), but with less whitespace.
230  string ShortDebugString() const;
231  // Like DebugString(), but do not escape UTF-8 byte sequences.
232  string Utf8DebugString() const;
233  // Convenience function useful in GDB.  Prints DebugString() to stdout.
234  void PrintDebugString() const;
235
236  // Heavy I/O -------------------------------------------------------
237  // Additional parsing and serialization methods not implemented by
238  // MessageLite because they are not supported by the lite library.
239
240  // Parse a protocol buffer from a file descriptor.  If successful, the entire
241  // input will be consumed.
242  bool ParseFromFileDescriptor(int file_descriptor);
243  // Like ParseFromFileDescriptor(), but accepts messages that are missing
244  // required fields.
245  bool ParsePartialFromFileDescriptor(int file_descriptor);
246  // Parse a protocol buffer from a C++ istream.  If successful, the entire
247  // input will be consumed.
248  bool ParseFromIstream(istream* input);
249  // Like ParseFromIstream(), but accepts messages that are missing
250  // required fields.
251  bool ParsePartialFromIstream(istream* input);
252
253  // Serialize the message and write it to the given file descriptor.  All
254  // required fields must be set.
255  bool SerializeToFileDescriptor(int file_descriptor) const;
256  // Like SerializeToFileDescriptor(), but allows missing required fields.
257  bool SerializePartialToFileDescriptor(int file_descriptor) const;
258  // Serialize the message and write it to the given C++ ostream.  All
259  // required fields must be set.
260  bool SerializeToOstream(ostream* output) const;
261  // Like SerializeToOstream(), but allows missing required fields.
262  bool SerializePartialToOstream(ostream* output) const;
263
264
265  // Reflection-based methods ----------------------------------------
266  // These methods are pure-virtual in MessageLite, but Message provides
267  // reflection-based default implementations.
268
269  virtual string GetTypeName() const;
270  virtual void Clear();
271  virtual bool IsInitialized() const;
272  virtual void CheckTypeAndMergeFrom(const MessageLite& other);
273  virtual bool MergePartialFromCodedStream(io::CodedInputStream* input);
274  virtual int ByteSize() const;
275  virtual void SerializeWithCachedSizes(io::CodedOutputStream* output) const;
276
277 private:
278  // This is called only by the default implementation of ByteSize(), to
279  // update the cached size.  If you override ByteSize(), you do not need
280  // to override this.  If you do not override ByteSize(), you MUST override
281  // this; the default implementation will crash.
282  //
283  // The method is private because subclasses should never call it; only
284  // override it.  Yes, C++ lets you do that.  Crazy, huh?
285  virtual void SetCachedSize(int size) const;
286
287 public:
288
289  // Introspection ---------------------------------------------------
290
291  // Typedef for backwards-compatibility.
292  typedef google::protobuf::Reflection Reflection;
293
294  // Get a Descriptor for this message's type.  This describes what
295  // fields the message contains, the types of those fields, etc.
296  const Descriptor* GetDescriptor() const { return GetMetadata().descriptor; }
297
298  // Get the Reflection interface for this Message, which can be used to
299  // read and modify the fields of the Message dynamically (in other words,
300  // without knowing the message type at compile time).  This object remains
301  // property of the Message.
302  //
303  // This method remains virtual in case a subclass does not implement
304  // reflection and wants to override the default behavior.
305  virtual const Reflection* GetReflection() const {
306    return GetMetadata().reflection;
307  }
308
309 protected:
310  // Get a struct containing the metadata for the Message. Most subclasses only
311  // need to implement this method, rather than the GetDescriptor() and
312  // GetReflection() wrappers.
313  virtual Metadata GetMetadata() const  = 0;
314
315
316 private:
317  GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Message);
318};
319
320// This interface contains methods that can be used to dynamically access
321// and modify the fields of a protocol message.  Their semantics are
322// similar to the accessors the protocol compiler generates.
323//
324// To get the Reflection for a given Message, call Message::GetReflection().
325//
326// This interface is separate from Message only for efficiency reasons;
327// the vast majority of implementations of Message will share the same
328// implementation of Reflection (GeneratedMessageReflection,
329// defined in generated_message.h), and all Messages of a particular class
330// should share the same Reflection object (though you should not rely on
331// the latter fact).
332//
333// There are several ways that these methods can be used incorrectly.  For
334// example, any of the following conditions will lead to undefined
335// results (probably assertion failures):
336// - The FieldDescriptor is not a field of this message type.
337// - The method called is not appropriate for the field's type.  For
338//   each field type in FieldDescriptor::TYPE_*, there is only one
339//   Get*() method, one Set*() method, and one Add*() method that is
340//   valid for that type.  It should be obvious which (except maybe
341//   for TYPE_BYTES, which are represented using strings in C++).
342// - A Get*() or Set*() method for singular fields is called on a repeated
343//   field.
344// - GetRepeated*(), SetRepeated*(), or Add*() is called on a non-repeated
345//   field.
346// - The Message object passed to any method is not of the right type for
347//   this Reflection object (i.e. message.GetReflection() != reflection).
348//
349// You might wonder why there is not any abstract representation for a field
350// of arbitrary type.  E.g., why isn't there just a "GetField()" method that
351// returns "const Field&", where "Field" is some class with accessors like
352// "GetInt32Value()".  The problem is that someone would have to deal with
353// allocating these Field objects.  For generated message classes, having to
354// allocate space for an additional object to wrap every field would at least
355// double the message's memory footprint, probably worse.  Allocating the
356// objects on-demand, on the other hand, would be expensive and prone to
357// memory leaks.  So, instead we ended up with this flat interface.
358//
359// TODO(kenton):  Create a utility class which callers can use to read and
360//   write fields from a Reflection without paying attention to the type.
361class LIBPROTOBUF_EXPORT Reflection {
362 public:
363  // TODO(kenton):  Remove parameter.
364  inline Reflection() {}
365  virtual ~Reflection();
366
367  // Get the UnknownFieldSet for the message.  This contains fields which
368  // were seen when the Message was parsed but were not recognized according
369  // to the Message's definition.
370  virtual const UnknownFieldSet& GetUnknownFields(
371      const Message& message) const = 0;
372  // Get a mutable pointer to the UnknownFieldSet for the message.  This
373  // contains fields which were seen when the Message was parsed but were not
374  // recognized according to the Message's definition.
375  virtual UnknownFieldSet* MutableUnknownFields(Message* message) const = 0;
376
377  // Estimate the amount of memory used by the message object.
378  virtual int SpaceUsed(const Message& message) const = 0;
379
380  // Check if the given non-repeated field is set.
381  virtual bool HasField(const Message& message,
382                        const FieldDescriptor* field) const = 0;
383
384  // Get the number of elements of a repeated field.
385  virtual int FieldSize(const Message& message,
386                        const FieldDescriptor* field) const = 0;
387
388  // Clear the value of a field, so that HasField() returns false or
389  // FieldSize() returns zero.
390  virtual void ClearField(Message* message,
391                          const FieldDescriptor* field) const = 0;
392
393  // Remove the last element of a repeated field.
394  // We don't provide a way to remove any element other than the last
395  // because it invites inefficient use, such as O(n^2) filtering loops
396  // that should have been O(n).  If you want to remove an element other
397  // than the last, the best way to do it is to re-arrange the elements
398  // (using Swap()) so that the one you want removed is at the end, then
399  // call RemoveLast().
400  virtual void RemoveLast(Message* message,
401                          const FieldDescriptor* field) const = 0;
402
403  // Swap the complete contents of two messages.
404  virtual void Swap(Message* message1, Message* message2) const = 0;
405
406  // Swap two elements of a repeated field.
407  virtual void SwapElements(Message* message,
408                    const FieldDescriptor* field,
409                    int index1,
410                    int index2) const = 0;
411
412  // List all fields of the message which are currently set.  This includes
413  // extensions.  Singular fields will only be listed if HasField(field) would
414  // return true and repeated fields will only be listed if FieldSize(field)
415  // would return non-zero.  Fields (both normal fields and extension fields)
416  // will be listed ordered by field number.
417  virtual void ListFields(const Message& message,
418                          vector<const FieldDescriptor*>* output) const = 0;
419
420  // Singular field getters ------------------------------------------
421  // These get the value of a non-repeated field.  They return the default
422  // value for fields that aren't set.
423
424  virtual int32  GetInt32 (const Message& message,
425                           const FieldDescriptor* field) const = 0;
426  virtual int64  GetInt64 (const Message& message,
427                           const FieldDescriptor* field) const = 0;
428  virtual uint32 GetUInt32(const Message& message,
429                           const FieldDescriptor* field) const = 0;
430  virtual uint64 GetUInt64(const Message& message,
431                           const FieldDescriptor* field) const = 0;
432  virtual float  GetFloat (const Message& message,
433                           const FieldDescriptor* field) const = 0;
434  virtual double GetDouble(const Message& message,
435                           const FieldDescriptor* field) const = 0;
436  virtual bool   GetBool  (const Message& message,
437                           const FieldDescriptor* field) const = 0;
438  virtual string GetString(const Message& message,
439                           const FieldDescriptor* field) const = 0;
440  virtual const EnumValueDescriptor* GetEnum(
441      const Message& message, const FieldDescriptor* field) const = 0;
442  // See MutableMessage() for the meaning of the "factory" parameter.
443  virtual const Message& GetMessage(const Message& message,
444                                    const FieldDescriptor* field,
445                                    MessageFactory* factory = NULL) const = 0;
446
447  // Get a string value without copying, if possible.
448  //
449  // GetString() necessarily returns a copy of the string.  This can be
450  // inefficient when the string is already stored in a string object in the
451  // underlying message.  GetStringReference() will return a reference to the
452  // underlying string in this case.  Otherwise, it will copy the string into
453  // *scratch and return that.
454  //
455  // Note:  It is perfectly reasonable and useful to write code like:
456  //     str = reflection->GetStringReference(field, &str);
457  //   This line would ensure that only one copy of the string is made
458  //   regardless of the field's underlying representation.  When initializing
459  //   a newly-constructed string, though, it's just as fast and more readable
460  //   to use code like:
461  //     string str = reflection->GetString(field);
462  virtual const string& GetStringReference(const Message& message,
463                                           const FieldDescriptor* field,
464                                           string* scratch) const = 0;
465
466
467  // Singular field mutators -----------------------------------------
468  // These mutate the value of a non-repeated field.
469
470  virtual void SetInt32 (Message* message,
471                         const FieldDescriptor* field, int32  value) const = 0;
472  virtual void SetInt64 (Message* message,
473                         const FieldDescriptor* field, int64  value) const = 0;
474  virtual void SetUInt32(Message* message,
475                         const FieldDescriptor* field, uint32 value) const = 0;
476  virtual void SetUInt64(Message* message,
477                         const FieldDescriptor* field, uint64 value) const = 0;
478  virtual void SetFloat (Message* message,
479                         const FieldDescriptor* field, float  value) const = 0;
480  virtual void SetDouble(Message* message,
481                         const FieldDescriptor* field, double value) const = 0;
482  virtual void SetBool  (Message* message,
483                         const FieldDescriptor* field, bool   value) const = 0;
484  virtual void SetString(Message* message,
485                         const FieldDescriptor* field,
486                         const string& value) const = 0;
487  virtual void SetEnum  (Message* message,
488                         const FieldDescriptor* field,
489                         const EnumValueDescriptor* value) const = 0;
490  // Get a mutable pointer to a field with a message type.  If a MessageFactory
491  // is provided, it will be used to construct instances of the sub-message;
492  // otherwise, the default factory is used.  If the field is an extension that
493  // does not live in the same pool as the containing message's descriptor (e.g.
494  // it lives in an overlay pool), then a MessageFactory must be provided.
495  // If you have no idea what that meant, then you probably don't need to worry
496  // about it (don't provide a MessageFactory).  WARNING:  If the
497  // FieldDescriptor is for a compiled-in extension, then
498  // factory->GetPrototype(field->message_type() MUST return an instance of the
499  // compiled-in class for this type, NOT DynamicMessage.
500  virtual Message* MutableMessage(Message* message,
501                                  const FieldDescriptor* field,
502                                  MessageFactory* factory = NULL) const = 0;
503
504
505  // Repeated field getters ------------------------------------------
506  // These get the value of one element of a repeated field.
507
508  virtual int32  GetRepeatedInt32 (const Message& message,
509                                   const FieldDescriptor* field,
510                                   int index) const = 0;
511  virtual int64  GetRepeatedInt64 (const Message& message,
512                                   const FieldDescriptor* field,
513                                   int index) const = 0;
514  virtual uint32 GetRepeatedUInt32(const Message& message,
515                                   const FieldDescriptor* field,
516                                   int index) const = 0;
517  virtual uint64 GetRepeatedUInt64(const Message& message,
518                                   const FieldDescriptor* field,
519                                   int index) const = 0;
520  virtual float  GetRepeatedFloat (const Message& message,
521                                   const FieldDescriptor* field,
522                                   int index) const = 0;
523  virtual double GetRepeatedDouble(const Message& message,
524                                   const FieldDescriptor* field,
525                                   int index) const = 0;
526  virtual bool   GetRepeatedBool  (const Message& message,
527                                   const FieldDescriptor* field,
528                                   int index) const = 0;
529  virtual string GetRepeatedString(const Message& message,
530                                   const FieldDescriptor* field,
531                                   int index) const = 0;
532  virtual const EnumValueDescriptor* GetRepeatedEnum(
533      const Message& message,
534      const FieldDescriptor* field, int index) const = 0;
535  virtual const Message& GetRepeatedMessage(
536      const Message& message,
537      const FieldDescriptor* field, int index) const = 0;
538
539  // See GetStringReference(), above.
540  virtual const string& GetRepeatedStringReference(
541      const Message& message, const FieldDescriptor* field,
542      int index, string* scratch) const = 0;
543
544
545  // Repeated field mutators -----------------------------------------
546  // These mutate the value of one element of a repeated field.
547
548  virtual void SetRepeatedInt32 (Message* message,
549                                 const FieldDescriptor* field,
550                                 int index, int32  value) const = 0;
551  virtual void SetRepeatedInt64 (Message* message,
552                                 const FieldDescriptor* field,
553                                 int index, int64  value) const = 0;
554  virtual void SetRepeatedUInt32(Message* message,
555                                 const FieldDescriptor* field,
556                                 int index, uint32 value) const = 0;
557  virtual void SetRepeatedUInt64(Message* message,
558                                 const FieldDescriptor* field,
559                                 int index, uint64 value) const = 0;
560  virtual void SetRepeatedFloat (Message* message,
561                                 const FieldDescriptor* field,
562                                 int index, float  value) const = 0;
563  virtual void SetRepeatedDouble(Message* message,
564                                 const FieldDescriptor* field,
565                                 int index, double value) const = 0;
566  virtual void SetRepeatedBool  (Message* message,
567                                 const FieldDescriptor* field,
568                                 int index, bool   value) const = 0;
569  virtual void SetRepeatedString(Message* message,
570                                 const FieldDescriptor* field,
571                                 int index, const string& value) const = 0;
572  virtual void SetRepeatedEnum(Message* message,
573                               const FieldDescriptor* field, int index,
574                               const EnumValueDescriptor* value) const = 0;
575  // Get a mutable pointer to an element of a repeated field with a message
576  // type.
577  virtual Message* MutableRepeatedMessage(
578      Message* message, const FieldDescriptor* field, int index) const = 0;
579
580
581  // Repeated field adders -------------------------------------------
582  // These add an element to a repeated field.
583
584  virtual void AddInt32 (Message* message,
585                         const FieldDescriptor* field, int32  value) const = 0;
586  virtual void AddInt64 (Message* message,
587                         const FieldDescriptor* field, int64  value) const = 0;
588  virtual void AddUInt32(Message* message,
589                         const FieldDescriptor* field, uint32 value) const = 0;
590  virtual void AddUInt64(Message* message,
591                         const FieldDescriptor* field, uint64 value) const = 0;
592  virtual void AddFloat (Message* message,
593                         const FieldDescriptor* field, float  value) const = 0;
594  virtual void AddDouble(Message* message,
595                         const FieldDescriptor* field, double value) const = 0;
596  virtual void AddBool  (Message* message,
597                         const FieldDescriptor* field, bool   value) const = 0;
598  virtual void AddString(Message* message,
599                         const FieldDescriptor* field,
600                         const string& value) const = 0;
601  virtual void AddEnum  (Message* message,
602                         const FieldDescriptor* field,
603                         const EnumValueDescriptor* value) const = 0;
604  // See MutableMessage() for comments on the "factory" parameter.
605  virtual Message* AddMessage(Message* message,
606                              const FieldDescriptor* field,
607                              MessageFactory* factory = NULL) const = 0;
608
609
610  // Extensions ------------------------------------------------------
611
612  // Try to find an extension of this message type by fully-qualified field
613  // name.  Returns NULL if no extension is known for this name or number.
614  virtual const FieldDescriptor* FindKnownExtensionByName(
615      const string& name) const = 0;
616
617  // Try to find an extension of this message type by field number.
618  // Returns NULL if no extension is known for this name or number.
619  virtual const FieldDescriptor* FindKnownExtensionByNumber(
620      int number) const = 0;
621
622 private:
623  GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Reflection);
624};
625
626// Abstract interface for a factory for message objects.
627class LIBPROTOBUF_EXPORT MessageFactory {
628 public:
629  inline MessageFactory() {}
630  virtual ~MessageFactory();
631
632  // Given a Descriptor, gets or constructs the default (prototype) Message
633  // of that type.  You can then call that message's New() method to construct
634  // a mutable message of that type.
635  //
636  // Calling this method twice with the same Descriptor returns the same
637  // object.  The returned object remains property of the factory.  Also, any
638  // objects created by calling the prototype's New() method share some data
639  // with the prototype, so these must be destoyed before the MessageFactory
640  // is destroyed.
641  //
642  // The given descriptor must outlive the returned message, and hence must
643  // outlive the MessageFactory.
644  //
645  // Some implementations do not support all types.  GetPrototype() will
646  // return NULL if the descriptor passed in is not supported.
647  //
648  // This method may or may not be thread-safe depending on the implementation.
649  // Each implementation should document its own degree thread-safety.
650  virtual const Message* GetPrototype(const Descriptor* type) = 0;
651
652  // Gets a MessageFactory which supports all generated, compiled-in messages.
653  // In other words, for any compiled-in type FooMessage, the following is true:
654  //   MessageFactory::generated_factory()->GetPrototype(
655  //     FooMessage::descriptor()) == FooMessage::default_instance()
656  // This factory supports all types which are found in
657  // DescriptorPool::generated_pool().  If given a descriptor from any other
658  // pool, GetPrototype() will return NULL.  (You can also check if a
659  // descriptor is for a generated message by checking if
660  // descriptor->file()->pool() == DescriptorPool::generated_pool().)
661  //
662  // This factory is 100% thread-safe; calling GetPrototype() does not modify
663  // any shared data.
664  //
665  // This factory is a singleton.  The caller must not delete the object.
666  static MessageFactory* generated_factory();
667
668  // For internal use only:  Registers a .proto file at static initialization
669  // time, to be placed in generated_factory.  The first time GetPrototype()
670  // is called with a descriptor from this file, |register_messages| will be
671  // called, with the file name as the parameter.  It must call
672  // InternalRegisterGeneratedMessage() (below) to register each message type
673  // in the file.  This strange mechanism is necessary because descriptors are
674  // built lazily, so we can't register types by their descriptor until we
675  // know that the descriptor exists.  |filename| must be a permanent string.
676  static void InternalRegisterGeneratedFile(
677      const char* filename, void (*register_messages)(const string&));
678
679  // For internal use only:  Registers a message type.  Called only by the
680  // functions which are registered with InternalRegisterGeneratedFile(),
681  // above.
682  static void InternalRegisterGeneratedMessage(const Descriptor* descriptor,
683                                               const Message* prototype);
684
685 private:
686  GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MessageFactory);
687};
688
689}  // namespace protobuf
690
691}  // namespace google
692#endif  // GOOGLE_PROTOBUF_MESSAGE_H__